Changeset 1685

Timestamp:

09/15/08 20:34:35 (2 months ago)

Author:

nick

Message:

Adding license and docstrings

Files:

• pyamf/sandbox/nick/gae_client.py (modified) (2 diffs)

pyamf/sandbox/nick/gae_client.py

@@ +1 @@
+# -*- encoding: utf8 -*-
+#
+# Copyright (c) 2007 The PyAMF Project. All rights reserved.
+# 
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+# 
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALI
+
+"""
+GAE Client - a unit test runner that operates against a running GAE Instance.
+This script can be used as part of an automated build (e.g. buildbot) to test
+the app whilst it is running on Google's infrastructure.
+"""
+
 import simplejson
 import pycurl
 
-
-
 class GAETestRunner(object):
+    """
+    This class interfaces with the test application running on a GAE Instance.
+
+    The structure of the app is as follows:
+     - /tests/ - Returns a list of tests to run, in json format. There are
+        three keys, 'tests', 'expected', and 'skipped'. 'tests' are a list of
+        all the tests that should be run to complete the test suite. 'expected'
+        is a list of tests that are expected to fail. This means that test
+        suites that were built with more open environments can pass. 'skipped'
+        means tests that were not meant to run at all on the GAE platform.
+     - /run/{module}/{test_case}/{method} - Runs an individual test. The
+        response is a json object that contains the following keys: 'test' -
+        the fully qualified name of the test, 'skipped' - if C{True} then this
+        test was skipped, 'passed' - a boolean if the test password or not,
+        'errors' - a list of errors that occurred when running the test,
+        'failures' - a list of failures that occurred when running the test.
+
+        errors or failures generally contain the formatted traceback that was
+        the problem.
+    """
+
     def __init__(self, url):
+        """
+        @param url: The fully qualified url that gives access to the test app.
+        @type url: C{str}
+        """
         if url[-1] != '/':
             url += '/'
@@ -45 +97 @@
 
     def run_test_suite(self, out):
+        """
+        This is the workhorse function. Call this to iterate through the test
+        suite. It returns a dict containing varions details about the test run.
+
+        @param out: A file type object used to output a formatted version of the
+            test run. Very similar to Twisted's default test runner.
+        @return: A dict containing the following keys:
+         - `errors`: a dict of tests that contained errors, the key being the
+            full qualified test name.
+         - `failures`: Similar to errors.
+         - `skips`: A list of tests that were skipped
+         - `failed`: A boolean determining the outcome of the test run.
+         - `count`: The number of tests that were actually run.
+        """
         # TODO thread this or convert to Twisted ..