Added Sphinx (reST-style) conversion of Evennia documentation to docs/. This is an auto-generated conversion directly from the Wiki, so it's not custom-written in any way (will also make it easy to update). You need Sphinx to compile the sources into fancy pages. Supporting sphinx is to make documentation easier to print and view offline. Currently no sphinx src-code viewing is activated by default, it gives too many spurious errors (the converters are in the repo though if you're interested in experimenting). So for offline autodocs, doxygen is still to recommend.

docs/sphinx/source/wiki/UnitTesting.rst

@@ -0,0 +1,103 @@
+Using and writing unit tests for Evennia.
+
+Unit Testing
+============
+
+*This topic is mainly of interest to people interested in helping to
+develop Evennia itself.*
+
+Unit testing means testing components of a program in isolation from
+each other to make sure every part works on its own before using it with
+others. Extensive testing helps avoid new updates causing unexpected
+side effects as well as alleviates general code rot (a more
+comprehensive wikipedia article on unit testing can be found
+`here <http://en.wikipedia.org/wiki/Unit_test>`_).
+
+A typical unit test calls some component of Evennia with a given input,
+looks at the result and makes sure that this result looks as expected.
+Rather than having lots of stand-alone test programs, Evennia makes use
+of a central *test runner*. This is a program that gathers all available
+tests all over the Evennia source code (called *test suites*) and runs
+them all in one go. Errors and tracebacks are reported.
+
+Running the test suite
+----------------------
+
+To run the Evennia test suite, go to the ``game/`` folder and issue the
+command
+
+``python manage.py test``
+
+A temporary database will be instantiated to manage the tests. If
+everything works out you will see how many tests were run and how long
+it took. If something went wrong you will get error messages.
+
+Writing new tests
+-----------------
+
+Evennia's test suite makes use of Django unit test system, which in turn
+relies on Python's *unittest* module. Evennia's test modules are always
+named ``tests.py`` and should be located in different sub folders of
+``src/`` depending on which system they are testing. You can find an
+example of a testing module in ``src/objects/tests.py``.
+
+Inside the ``tests.py`` module you create classes inheriting from
+``django.test.TestCase`` (later versions of Django will use
+``django.utils.unittest.TestCase`` instead). A ``TestCase`` class is
+used to test a single aspect or component in various ways. Each test
+case contains one ore more *test methods* - these define the actual
+tests to run. You can name the test methods anything you want as long as
+the name starts with "``test_``". Your ``TestCase`` class can also have
+a method !SetUp(). This is run before each test, setting up whatever
+preparations the test methods need.
+
+To test the results, you use special methods of the ``TestCase`` class.
+Many of those start with "``assert``", such as ``assertEqual`` or
+``assertTrue``.
+
+Example of a ``TestCase`` class (inside a file ``tests.py``):
+
+::
+
+    # testing a simple funciontry:    # this is an optimized version only available in later Django versions    from django.utils.unittest import TestCase except ImportError:    # if the first fail, we use the old version    from django.test import TestCase# the function we want to test from mypath import myfuncTestObj(unittest.TestCase):    "This tests a function myfunc."   def test_return_value(self):        "test method. Makes sure return value is as expected."          expected_return = "This is me being nice."        actual_return = myfunc()        # test         self.assertEqual(expected_return, actual_return)    def test_alternative_call(self):        "test method. Calls with a keyword argument."        expected_return = "This is me being baaaad."        actual_return = myfunc(bad=True)        # test        self.assertEqual(expected_return, actual_return)
+
+The above example is very simplistic, but you should get the idea. Look
+at ``src/objects/tests.py`` for more realistic examples of tests. You
+might also want to read the `documentation for the unittest
+module <http://docs.python.org/library/unittest.html>`_.
+
+Testing in-game Commands
+------------------------
+
+In-game Commands are a special case. Tests for the default commands are
+put in ``src/commands/default/tests.py``. This test suite is executed as
+part of running the ``objects`` test suite (since it lies outside
+Django's normal "app" structure). It also supplies a few convenience
+functions for executing commands (notably creating a "fake" player
+session so as to mimic an actual command call). It also makes several
+test characters and objects available. For example ``char1`` is a
+"logged in" Character object that acts as the one calling the command.
+
+Each command tested should have its own ``TestCase`` class. Inherit this
+class from the ``CommandTest`` class in the same module to get access to
+the command-specific utilities mentioned.
+
+::
+
+    class TestSet(CommandTest):
+        "tests the @set command by simple call"
+        def test_call(self):
+            self.execute_command("@set self/testval = mytestvalue")
+            # knowing what @set does, our test character (char1) should
+            # by now have a new attribute 'testval' with the value 'mytestvalue'.
+            self.assertEqual("mytestvalue", self.char1.db.testval)
+
+A note on adding new tests
+--------------------------
+
+Having an extensive tests suite is very important for avoiding code
+degradation as Evennia is developed. Only a small fraction of the
+Evennia codebase is covered by test suites at this point. Writing new
+tests is not hard, it's more a matter of finding the time to do so. So
+adding new tests is really an area where everyone can contribute, also
+with only limited Python skills.