From ab3de8a911beac7b671f8a6681bc0b63711c11e7 Mon Sep 17 00:00:00 2001
From: Elena ``of Valhalla'' Grandi <valhalla@trueelena.org>
Date: Mon, 1 Aug 2022 17:06:17 +0200
Subject: Document the testing helpers
---
docs/source/examples/greeter.py | 23 ++++++++++++++++
docs/source/index.rst | 1 +
docs/source/testing.rst | 61 +++++++++++++++++++++++++++++++++++++++++
3 files changed, 85 insertions(+)
create mode 100644 docs/source/testing.rst
(limited to 'docs/source')
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]),
+ )
--
cgit v1.2.3