You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@libcloud.apache.org by to...@apache.org on 2011/11/05 20:23:16 UTC
svn commit: r1198026 - in /libcloud/site/trunk: content/docs/index.mdtext
content/docs/load-balancer-base-api.mdtext
content/docs/writing-tests-and-using-the-fixture-framework.mdtext
templates/blocks/menu_docs.html
Author: tomaz
Date: Sat Nov 5 19:23:15 2011
New Revision: 1198026
URL: http://svn.apache.org/viewvc?rev=1198026&view=rev
Log:
More docs.
Added:
libcloud/site/trunk/content/docs/writing-tests-and-using-the-fixture-framework.mdtext
Modified:
libcloud/site/trunk/content/docs/index.mdtext
libcloud/site/trunk/content/docs/load-balancer-base-api.mdtext
libcloud/site/trunk/templates/blocks/menu_docs.html
Modified: libcloud/site/trunk/content/docs/index.mdtext
URL: http://svn.apache.org/viewvc/libcloud/site/trunk/content/docs/index.mdtext?rev=1198026&r1=1198025&r2=1198026&view=diff
==============================================================================
--- libcloud/site/trunk/content/docs/index.mdtext (original)
+++ libcloud/site/trunk/content/docs/index.mdtext Sat Nov 5 19:23:15 2011
@@ -9,3 +9,7 @@ browsing the documentation, click on the
If you have questions, suggestions or corrections, feel free to
[contact us](/devinfo.html).
+
+Documentation is also freely available in the Markdown format in our SVN
+repository which means anyone can clonethe repository and help us improve
+it.
Modified: libcloud/site/trunk/content/docs/load-balancer-base-api.mdtext
URL: http://svn.apache.org/viewvc/libcloud/site/trunk/content/docs/load-balancer-base-api.mdtext?rev=1198026&r1=1198025&r2=1198026&view=diff
==============================================================================
--- libcloud/site/trunk/content/docs/load-balancer-base-api.mdtext (original)
+++ libcloud/site/trunk/content/docs/load-balancer-base-api.mdtext Sat Nov 5 19:23:15 2011
@@ -52,7 +52,8 @@ members to it.
<h3 id="destroy_balancer">destroy_balancer</h3>
**Method signature**:
-[driver.destroy_balancer(balancer)](/apidocs/current/libcloud.loadbalancer.base.Driver.html#destroy_balancer)
+[driver.destroy_balancer(balancer)](/apidocs/current/libcloud.loadbalancer.base.Driver.html#destroy_balancer),
+[balancer.destroy()](/apidocs/current/libcloud.loadbalancer.base.LoadBalancer.html#destroy)
**Description**: Destroy a load balancer.
<h3 id="balancer_attach_member">balancer_attach_member</h3>
Added: libcloud/site/trunk/content/docs/writing-tests-and-using-the-fixture-framework.mdtext
URL: http://svn.apache.org/viewvc/libcloud/site/trunk/content/docs/writing-tests-and-using-the-fixture-framework.mdtext?rev=1198026&view=auto
==============================================================================
--- libcloud/site/trunk/content/docs/writing-tests-and-using-the-fixture-framework.mdtext (added)
+++ libcloud/site/trunk/content/docs/writing-tests-and-using-the-fixture-framework.mdtext Sat Nov 5 19:23:15 2011
@@ -0,0 +1,95 @@
+title: Writing tests and using the fixture framework
+
+## Writing tests and using the fixture framework ##
+
+This section describes how to write tests for the provider drivers and how to use
+our fixture framework and system for mocking the responses.
+
+Examples in this section refer to the compute API but things described in this
+section are also applicable to other APIs.
+
+* [Creating Fixtures](#creating-fixtures)
+* [Mocking responses and using MockHttp class](#mocking-responses-and-using-mockhttp-class)
+* [MockHttp class example](#mock-http-class-example)
+
+<h3 id="creating-fixtures">Creating Fixtures</h3>
+
+In our test cases fixtures store different responses returned by the provider APIs.
+They are stored and named in the following format:
+`test/<api name>/fixtures/<provider name>/<fixture name>`.
+
+Fixtures are usually generated by "manually" performing (usually using a tool like curl)
+different actions with the provider API and saving responses in the files.
+
+*Note: You are advised against using the examples from the provider API docs because empirical
+evidence has shown that in a lot of cases they are wrong or out of date.*
+
+<h3 id="mocking-responses-and-using-mockhttp-class">Mocking responses and using MockHttp class</h3>
+
+Each provider test file usually contains a class which inherits from the base `MockHttp` class.
+This class is responsible for loading fixtures and returning a mocked response for
+each API call.
+
+Which method is called is primary determined by the requested path. All the forward slashes,
+periods and dashes in the requested path are replaced by an underscore (`_`).
+
+Some examples:
+
+**Requested path**: `/servers/list.all`
+**use_params**: `MockHttp.use_params = None`
+**Name of the method on the Mock class**: `_servers_list_all`
+
+**Requested path**: `/servers/reboot-all`
+**use_params**: `MockHttp.use_params = None`
+**Name of the method on the Mock class**: `_servers_reboot_all`
+
+Some providers use the same path for all the requests and the actual action is determined by
+some parameter in a query string. To overcome this problem, set the `use_param` MockHttp class
+attribute to the name of the query string parameter which specifies the action.
+Good example of a provider API which does this is the Amazon EC2 API
+(`test/compute/test_ec2.py`).
+
+Example:
+
+**Requested path**: `/?Action=RebootInstances&InstanceId=12345`
+**use_params**: `MockHttp.use_params = 'Action'`
+**Name of the method on the Mock class**: `_RebootInstances`
+
+Usually we also want to test different scenarios for a single API call.
+Good example of this is testing a success and different failure scenarios when creating a node.
+Because we are testing a single API call, this means that the request path will in most
+cases be the same. This makes loading a different response fixture for each API call
+without inspecting the request parameters or doing something similar very cumbersome.
+
+This problem can be overcome by setting the `type` attribute on the `MockHttp` class before
+issuing a request. The specified `type` will be automatically appended to the end of the
+constructed method name.
+
+Example:
+
+**Requested path**: `/servers/reboot-all`
+**use_params**: `MockHttp.use_params = None`
+**type**: `MockHttp.type = 'FAILURE'`
+**Name of the method on the Mock class**: `_servers_reboot_all_FAILURE`
+
+<h3 id="mock-http-class-example">MockHttp class example</h3>
+
+Bellow is an example of a MockHttp class from the Amazon EC2 tests with a
+single method.
+
+Return value of a mock method is a tuple -
+**(status_code, response_body, response_headers, response_status_string)**.
+
+* **response_code** (intger) - response status code (httplib.OK, httplib.NOT_FOUND, ...)
+* **response_body** (string) - actual mocked response body which is usually read from a fixture
+* **response_headers** (dictionary) - response headers
+* **response_status_string** (string) - string representation of the response status code (httplib.responses[httplib.OK], httplib.responses[httplib.CONTINUE], ...)
+
+ ::python
+ class EC2MockHttp(MockHttp):
+
+ fixtures = ComputeFileFixtures('ec2')
+
+ def _DescribeInstances(self, method, url, body, headers):
+ body = self.fixtures.load('describe_instances.xml')
+ return (httplib.OK, body, {'Content-Type': 'application/xml'}, httplib.responses[httplib.OK])
Modified: libcloud/site/trunk/templates/blocks/menu_docs.html
URL: http://svn.apache.org/viewvc/libcloud/site/trunk/templates/blocks/menu_docs.html?rev=1198026&r1=1198025&r2=1198026&view=diff
==============================================================================
--- libcloud/site/trunk/templates/blocks/menu_docs.html (original)
+++ libcloud/site/trunk/templates/blocks/menu_docs.html Sat Nov 5 19:23:15 2011
@@ -22,12 +22,14 @@
<li><a href="load-balancer-examples.html">Examples</a></li>
</ul>
</ul>
+ <li>Development</li>
+ <ul>
+ <li><a href="writing-tests-and-using-the-fixture-framework.html">Writing tests and using the fixture framework</a></li>
+ </ul>
<li>Other</li>
<ul>
- <ul>
- <li><a href="debugging.html">Debugging</a></li>
- <li><a href="using-libcloud-in-multi-threaded-and-async-environments.html">Using Libcloud in multi-threaded and async environments</a></li>
- </ul>
+ <li><a href="debugging.html">Debugging</a></li>
+ <li><a href="using-libcloud-in-multi-threaded-and-async-environments.html">Using Libcloud in multi-threaded and async environments</a></li>
</ul>
<li><a href="/apidocs">Generated API docs</a></li>
</ul>