Write a document on how to add a test to Stem

doc/HACKING/WritingTests.md

@@ -417,18 +417,50 @@ makefile exports them.
 Writing integration tests with Stem
 -----------------------------------
 
-The 'stem' library includes extensive unit tests for the Tor controller
+The 'stem' library includes extensive tests for the Tor controller protocol.
-protocol.
-
-For more information on writing new tests for stem, have a look around
-the `test/*` directory in stem, and find a good example to emulate.  You
-might want to start with
-`https://gitweb.torproject.org/stem.git/tree/test/integ/control/controller.py`
-to improve Tor's test coverage.
-
 You can run stem tests from tor with `make test-stem`, or see
 `https://stem.torproject.org/faq.html#how-do-i-run-the-tests`.
 
+To see what tests are available, have a look around the `test/*` directory in
+stem. The first thing you'll notice is that there are both `unit` and `integ`
+tests. The former are for tests of the facilities provided by stem itself that
+can be tested on their own, without the need to hook up a tor process. These
+are less relevant, unless you want to develop a new stem feature. The latter,
+however, are a very useful tool to write tests for controller features. They
+provide a default environment with a connected tor instance that can be
+modified and queried. Adding more integration tests is a great way to increase
+the test coverage inside Tor, especially for controller features.
+
+Let's assume you actually want to write a test for a previously untested
+controller feature. I'm picking the `exit-policy/*` GETINFO queries. Since
+these are a controller feature that we want to write an integration test for,
+the right file to modify is
+`https://gitweb.torproject.org/stem.git/tree/test/integ/control/controller.py`.
+
+First off we notice that there is an integration test called
+`test_get_exit_policy()` that's already written. This exercises the interaction
+of stem's `Controller.get_exit_policy()` method, and is not relevant for our
+test since there are no stem methods to make use of all `exit-policy/*`
+queries (if there were, likely they'd be tested already. Maybe you want to
+write a stem feature, but I chose to just add tests).
+
+Our test requires a tor controller connection, so we'll use the
+`@require_controller` annotation for our `test_exit_policy()` method. We need a
+controller instance, which we get from
+`test.runner.get_runner().get_tor_controller()`. The attached Tor instance is
+configured as a client, but the exit-policy GETINFO queries need a relay to
+work, so we have to change the config (using `controller.set_options()`). This
+is OK for us to do, we just have to remember to set DisableNetwork so we don't
+actually start an exit relay and also to undo the changes we made (by calling
+`controller.reset_conf()` at the end of our test). Additionally, we have to
+configure a static Address for Tor to use, because it refuses to build a
+descriptor when it can't guess a suitable IP address. Unfortunately, these
+kinds of tripwires are everywhere. Don't forget to file appropriate tickets if
+you notice any strange behaviour that seems totally unreasonable.
+
+Check out the `test_exit_policy()` function in abovementioned file to see the
+final implementation for this test.
+
 System testing with Chutney
 ---------------------------