Update docs with testing info

README.md

@@ -12,7 +12,9 @@ Quick start
 Running in docker
 -----------------
 
-A dockerfile is included at `examples/docker/`. From the *root* of this repository, run `docker build -t pyircbot -f examples/docker/Dockerfile .` to build it. Typical use is mounting a directory from the host onto `/srv/bot`; this dir should contain config.json and any other dirs it references.
+A dockerfile is included at `examples/docker/`. From the *root* of this repository, run
+`docker build -t pyircbot -f examples/docker/Dockerfile .` to build it. Typical use is mounting a directory from the
+host onto `/srv/bot`; this dir should contain config.json and any other dirs it references.
 
 Building Docs
 -------------
@@ -23,14 +25,20 @@ Building Docs
 
 Or, use my pre-built copy [here](http://davepedu.com/files/botdocs/).
 
-Alternatively, use the included Dockerfile to create an environment for
-building the docs. Check `docs/builder/README.md`.
+Alternatively, use the included Dockerfile to create an environment for building the docs. Check
+`docs/builder/README.md`.
 
 Developing Modules
 ------------------
 
 Check *Module Developer’s Guide* in the docs
 
+Tests
+-----
+
+PyIRCBot has great test coverage. After installing the contents of `requirements-test.txt`, the script `./run-tests.sh`
+will run all tests. See the contents of the script for more information. See README.md in `./tests/` for more info.
+
 TODO
 ----
 

docs/module_guide/_module_guide.rst

@@ -185,3 +185,31 @@ one is found.
 modules providing a service should be loaded before modules requiring the
 service. Modules using a service MUST BE unloaded before the service module
 is unloaded.**
+
+Testing
+-------
+
+Good modules should be fully tested. PyIRCBot's test suite provides fixtures
+for testing any module:
+
+- ``fakebot``: a slimmed-down bot backend for light module testing
+- ``livebot``: a fully fledged instance of the bot connected to a real irc server
+
+Except for the most extreme cases, most modules can be tested with ``fakebot``.
+It allows feeding lines and checking internal state. In the test suite,
+``tests/modules/test_calc.py`` is a good example of use.
+
+However, ``livebot`` exists mainly for testing network-level things, like
+reconnecting after a connection drop, etc. If your module deals with this level
+of operations, ``livebot`` might be right. Otherwise. no.
+
+Tests (for modules) should be placed in ``./tests/modules/`` and be named like
+``test_modulename.py``.
+
+To run the test suite, call the helper script in the root of the repository:
+
+- ``./run-tests.sh``
+
+Or an individual test:
+
+- ``PYTHONPATH=. py.test tests/modules/test_mymodule.py -s -k test_function_name``

tests/README.md

@@ -0,0 +1,5 @@
+Tests
+=====
+
+PyIRCBot uses [py.test](https://pytest.org/). Several fixtures are provided to mock various parts of the PyIRCBot
+ecosystem. See them all in `lib.py`.

tests/lib.py

@@ -99,6 +99,9 @@ def ircserver():
 
 @pytest.fixture
 def livebot(ircserver, tmpdir):
+    """
+    A full-fledged bot connected to an irc server.
+    """
     port, server = ircserver
     channel = "#test" + str(randint(100000, 1000000))
     nick = "testbot" + str(randint(100000, 1000000))