Merge pull request #35 from sjagoe/add-some-docstrings

Add some docstrings

haas_rest_test/config.py

@@ -10,6 +10,12 @@
 
 
 class Config(object):
+    """Container for the top-level test configuration.
+
+    This contains all of the top-level configuration, such as the target
+    host and variables to be used in test cases.
+
+    """
 
     def __init__(self, scheme, host, variables, var_loader, test_filename):
         super(Config, self).__init__()

haas_rest_test/discoverer.py

@@ -18,6 +18,15 @@
 
 
 class RestTestDiscoverer(IDiscovererPlugin):
+    """A ``haas`` test discovery plugin to generate Web API test cases from
+    YAML descriptions.
+
+    Parameters
+    ----------
+    loader : haas.loader.Loader
+        The ``haas`` test loader.
+
+    """
 
     def __init__(self, loader, **kwargs):
         super(RestTestDiscoverer, self).__init__(**kwargs)

haas_rest_test/parameter_builder.py

@@ -14,6 +14,9 @@
 
 @contextmanager
 def ParameterBuilder(config, parameter_loaders):
+    """Load all of a test's parameters in a context manager.
+
+    """
     try:
         headers_loader = next(loader for loader in parameter_loaders
                               if isinstance(loader, HeadersTestParameter))

haas_rest_test/web_test.py

@@ -34,6 +34,12 @@ def initialize_test_parameter_loaders(test_parameter_plugins, parameter_specs):
 
 
 class WebTest(object):
+    """The main entry-point into a single web test case.
+
+    The :meth:`WebTest.run() <haas_rest_test.web_test.WebTest.run>`
+    method is executed from within the generated TestCase test method.
+
+    """
 
     def __init__(self, session, config, name, path, assertions,
                  parameter_loaders):
@@ -68,6 +74,9 @@ def test_parameters(self):
     @classmethod
     def from_dict(cls, session, spec, config, assertions_map,
                   test_parameter_plugins):
+        """Create a :class:`~.WebTest` from a test specification.
+
+        """
         spec = spec.copy()
         name = spec.pop('name')
 
@@ -87,6 +96,14 @@ def from_dict(cls, session, spec, config, assertions_map,
         )
 
     def run(self, case):
+        """Execute the web test case, and record results via the ``case``.
+
+        Parameters
+        ----------
+        case : unittest.TestCase
+            The ``TestCase`` instance used to record test results.
+
+        """
         try:
             url = self.url
         except InvalidVariableType as exc:

haas_rest_test/yaml_test_loader.py

@@ -67,6 +67,15 @@ def _create_reused_tests(session, config, assertions_map,
 
 def create_test_case_for_case(filename, config, case, assertions_map,
                               test_parameter_plugins, test_definitions):
+    """Programatically generate ``TestCases`` from a test specification.
+
+    Returns
+    -------
+    test_case_cls : type
+        A subclass of ``unittest.TestCase`` containing all of the
+        generated tests, in the same order as defined in the file.
+
+    """
     session = create_session()
 
     pre_run_cases = _create_reused_tests(
@@ -115,6 +124,15 @@ def __str__(self):
 
 
 class YamlTestLoader(object):
+    """A test case generator, creating ``TestCase`` and ``TestSuite``
+    instances from a single YAML file.
+
+    Parameters
+    ----------
+    loader : haas.loader.Loader
+        The ``haas`` test loader.
+
+    """
 
     def __init__(self, loader):
         super(YamlTestLoader, self).__init__()
@@ -137,11 +155,19 @@ def __init__(self, loader):
         )
 
     def load_tests_from_file(self, filename):
+        """Load the YAML test file and create a ``TestSuite`` containing all
+        test cases contained in the file.
+
+        """
         with open(filename) as fh:
             test_structure = yaml.safe_load(fh)
         return self.load_tests_from_yaml(test_structure, filename)
 
     def load_tests_from_yaml(self, test_structure, filename):
+        """Create a ``TestSuite`` containing all test cases contained in the
+        yaml structure.
+
+        """
         loader = self._loader
         try:
             jsonschema.validate(test_structure, SCHEMA)