From 4e9ae35e6cbdb60f1da971b082dbee82375e6a68 Mon Sep 17 00:00:00 2001 From: dave Date: Sun, 3 Dec 2017 21:09:31 -0800 Subject: [PATCH] Update docs with testing info --- README.md | 14 +++++++++++--- docs/module_guide/_module_guide.rst | 28 ++++++++++++++++++++++++++++ tests/README.md | 5 +++++ tests/lib.py | 3 +++ 4 files changed, 47 insertions(+), 3 deletions(-) create mode 100644 tests/README.md diff --git a/README.md b/README.md index c1a788e..b4b5036 100644 --- a/README.md +++ b/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 ---- diff --git a/docs/module_guide/_module_guide.rst b/docs/module_guide/_module_guide.rst index d446e9c..761db4d 100644 --- a/docs/module_guide/_module_guide.rst +++ b/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`` diff --git a/tests/README.md b/tests/README.md new file mode 100644 index 0000000..fda25f1 --- /dev/null +++ b/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`. diff --git a/tests/lib.py b/tests/lib.py index 311a2fc..990d994 100644 --- a/tests/lib.py +++ b/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))