Document the testing helpers

3 files changed, 85 insertions, 0 deletions

diff --git a/docs/source/examples/greeter.py b/docs/source/examples/greeter.py
index 5a978f4..32d739f 100755
--- a/docs/source/examples/greeter.py
+++ b/docs/source/examples/greeter.py
@@ -1,5 +1,6 @@
 #!/usr/bin/env python3
 import hazwaz
+import hazwaz.unittest
 
 
 class World(hazwaz.Command):
@@ -26,6 +27,27 @@ class Individual(hazwaz.Command):
         print("Hello {}".format(self.args.gretee))
 
 
+class TestGreeter(hazwaz.unittest.HazwazTestCase):
+    def test_greet_world(self):
+        cmd = Greet()
+        stream = self.run_with_argv(cmd, [
+            "./greeter.py",
+            "world",
+        ])
+
+        self.assertEqual(stream["stdout"].getvalue(), "Hello world!\n")
+
+    def test_greet_individual(self):
+        cmd = Greet()
+        stream = self.run_with_argv(cmd, [
+            "./greeter.py",
+            "individual",
+            "Bob",
+        ])
+
+        self.assertEqual(stream["stdout"].getvalue(), "Hello Bob\n")
+
+
 class Greet(hazwaz.MainCommand):
     """
     Greet people in different ways.
@@ -33,6 +55,7 @@ class Greet(hazwaz.MainCommand):
     commands = (
         World(),
         Individual(),
+        hazwaz.unittest.TestCommand([TestGreeter]),
     )
 
 
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 3440917..9e93a88 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -16,6 +16,7 @@ Contents
    :caption: Contents:
 
    tutorial
+   testing
    reference/modules
 
 Indices and tables
diff --git a/docs/source/testing.rst b/docs/source/testing.rst
new file mode 100644
index 0000000..1ddf5e5
--- /dev/null
+++ b/docs/source/testing.rst
@@ -0,0 +1,61 @@
+*********
+ Testing
+*********
+
+Hazwaz provides the module :py:mod:`hazwaz.unittest` with helpers based
+on :py:mod:`unittest` to write unit tests for command line behaviour.
+
+The class :py:class:`hazwaz.unittest.HazwazTestCase` can be used instead
+of :py:class:`unittest.TestCase` and works just as its parent: methods
+whose name start with ``test`` are run as individual tests, and you can
+use all the usual `unittest assert methods
+<https://docs.python.org/3/library/unittest.html#assert-methods>`_.
+
+To write a test that runs the command as if from the command line, with
+certain parameters, you can use the method
+:py:meth:`hazwaz.unittest.HazwazTestCase.run_with_argv` as in the
+following example::
+
+   import hazwaz.unittest
+
+   import greeter
+
+
+   class testGreeter(hazwaz.unittest.HazwazTestCase):
+       def test_greet_world(self):
+	   cmd = greeter.Greet()
+	   stream = self.run_with_argv(cmd, [
+	       "./greeter.py",
+	       "world",
+	   ])
+	   
+	   self.assertEqual(
+               stream["stdout"].getvalue(),
+               "Hello world!\n"
+           )
+
+
+
+The first parameter should be the name of the command itself, as if this
+was the full command line.
+
+If the tests are in their own module, there is a convienence function
+:py:func:`hazwaz.unittest.main` that runs :py:func:`unittest.main`,
+to be used e.g.::
+
+   if __name__ == "__main__":
+       hazwaz.unittest.main()
+
+However, if you're writing a self-contained script you can use the
+command :py:class:`hazwaz.unittest.TestCommand` to add a subcommand called
+``test`` which runs all tests from a list of :py:class:`unittest.TestCase`::
+
+   class Greet(hazwaz.MainCommand):
+       """
+       Greet people in different ways.
+       """
+       commands = (
+           World(),
+           Individual(),
+           hazwaz.unittest.TestCommand([TestGreeter]),
+       )