a new example for doing non-python extensions

--HG--
branch : trunk

doc/example/nonpython.txt

@@ -0,0 +1,64 @@
+
+Working with non-python tests
+====================================================
+
+a basic example for specifying tests in Yaml files
+--------------------------------------------------------------
+
+.. _`pytest-yamlwsgi`: http://bitbucket.org/aafshar/pytest-yamlwsgi/src/tip/pytest_yamlwsgi.py
+
+Here is an example ``conftest.py`` (extracted from Ali Afshnars special purpose `pytest-yamlwsgi`_ plugin).   This ``conftest.py`` will  collect ``test*.yml`` files and will execute the yaml-formatted content as custom tests:
+
+.. include:: nonpython/conftest.py
+    :literal:
+
+You can create a simple example file:
+
+.. include:: nonpython/test_simple.yml
+    :literal:
+
+and then execute the yaml - test specification::
+
+    nonpython $ py.test
+    =========================== test session starts ============================
+    platform linux2 -- Python 2.6.5 -- pytest-2.0.0.dev10
+    test path 1: /home/hpk/p/pytest/doc/example/nonpython
+    
+    test_simple.yml .F
+    
+    ================================= FAILURES =================================
+    ______________________________ usecase: hello ______________________________
+    usecase execution failed
+       spec failed: 'some': 'other'
+       no further details known at this point.
+    ==================== 1 failed, 1 passed in 0.06 seconds ====================
+
+You get one dot for the passing ``sub1: sub1`` check and one failure.
+Obviously in the above ``conftest.py`` you'll want to implement a more
+interesting interpretation of the yaml-values.  Note that ``reportinfo()``
+is used for representing the test location and is also consulted for
+reporting in ``verbose`` mode::
+
+    nonpython $ py.test -v
+    =========================== test session starts ============================
+    platform linux2 -- Python 2.6.5 -- pytest-2.0.0.dev10 -- /home/hpk/venv/0/bin/python
+    test path 1: /home/hpk/p/pytest/doc/example/nonpython
+    
+    test_simple.yml:1: usecase: ok PASSED
+    test_simple.yml:1: usecase: hello FAILED
+    
+    ================================= FAILURES =================================
+    ______________________________ usecase: hello ______________________________
+    usecase execution failed
+       spec failed: 'some': 'other'
+       no further details known at this point.
+    ==================== 1 failed, 1 passed in 0.06 seconds ====================
+
+While developing your custom test collection and execution it's also
+interesting to just look at the collection tree::
+
+    nonpython $ py.test --collectonly
+    <Directory 'nonpython'>
+      <YamlFile 'test_simple.yml'>
+        <UsecaseItem 'ok'>
+        <UsecaseItem 'hello'>

doc/example/nonpython/conftest.py

@@ -0,0 +1,40 @@
+# content of conftest.py
+
+import py
+
+def pytest_collect_file(path, parent):
+    if path.ext == ".yml" and path.basename.startswith("test"):
+        return YamlFile(path, parent)
+            
+class YamlFile(py.test.collect.File):
+    def collect(self):
+        import yaml # we need a yaml parser, e.g. PyYAML
+        raw = yaml.load(self.fspath.open())
+        for name, spec in raw.items():
+            yield UsecaseItem(name, self, spec)
+
+class UsecaseItem(py.test.collect.Item):
+    def __init__(self, name, parent, spec):
+        super(UsecaseItem, self).__init__(name, parent)
+        self.spec = spec
+    
+    def runtest(self):
+        for name, value in self.spec.items():
+            # some custom test execution (dumb example follows)
+            if name != value:
+                raise UsecaseException(self, name, value)
+
+    def repr_failure(self, excinfo):
+        """ called when self.runtest() raises an exception. """
+        if excinfo.errisinstance(UsecaseException):
+            return "\n".join([
+                "usecase execution failed",
+                "   spec failed: %r: %r" % excinfo.value.args[1:3],
+                "   no further details known at this point."
+            ])
+
+    def reportinfo(self):
+        return self.fspath, 0, "usecase: %s" % self.name
+
+class UsecaseException(Exception):
+    """ custom exception for error reporting. """

doc/example/nonpython/test_simple.yml

@@ -0,0 +1,7 @@
+# test_simple.yml
+ok:
+    sub1: sub1
+
+hello:
+    world: world
+    some: other

doc/examples.txt

@@ -10,3 +10,4 @@ Usages and Examples
    example/marking.txt
    example/mysetup.txt
    example/misc.txt
+   example/nonpython.txt