<h2>Running tests with custom settings file<aclass="headerlink"href="#running-tests-with-custom-settings-file"title="Permalink to this headline">¶</a></h2>
<p>The period (<codeclass="docutils literal notranslate"><spanclass="pre">.</span></code>) means to run all tests found in the current directory and all subdirectories. You
could also specify, say, <codeclass="docutils literal notranslate"><spanclass="pre">typeclasses</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">world</span></code> if you wanted to just run tests in those subdirs.</p>
<p>Those tests will all be run using the default settings. To run the tests with your own settings file
you must use the <codeclass="docutils literal notranslate"><spanclass="pre">--settings</span></code> option:</p>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">--settings</span></code> option of Evennia takes a file name in the <codeclass="docutils literal notranslate"><spanclass="pre">mygame/server/conf</span></code> folder. It is
normally used to swap settings files for testing and development. In combination with <codeclass="docutils literal notranslate"><spanclass="pre">test</span></code>, it
forces Evennia to use this settings file over the default one.</p>
<div><p>If you want to help out writing unittests for Evennia, take a look at Evennia’s <aclass="reference external"href="https://coveralls.io/github/evennia/evennia">coveralls.io page</a>. There you see which modules have any form of
<p>To make the test runner find the tests, they must be put in a module named <codeclass="docutils literal notranslate"><spanclass="pre">test*.py</span></code> (so <codeclass="docutils literal notranslate"><spanclass="pre">test.py</span></code>,
<codeclass="docutils literal notranslate"><spanclass="pre">tests.py</span></code> etc). Such a test module will be found wherever it is in the package. It can be a good
idea to look at some of Evennia’s <codeclass="docutils literal notranslate"><spanclass="pre">tests.py</span></code> modules to see how they look.</p>
<p>Inside a testing file, a <codeclass="docutils literal notranslate"><spanclass="pre">unittest.TestCase</span></code> class is used to test a single aspect or component in
various ways. Each test case contains one or more <em>test methods</em> - these define the actual tests to
run. You can name the test methods anything you want as long as the name starts with “<codeclass="docutils literal notranslate"><spanclass="pre">test_</span></code>”.
Your <codeclass="docutils literal notranslate"><spanclass="pre">TestCase</span></code> class can also have a method <codeclass="docutils literal notranslate"><spanclass="pre">setUp(self):</span></code>. This is run before each test, setting
up and storing whatever preparations the test methods need. Conversely, a <codeclass="docutils literal notranslate"><spanclass="pre">tearDown(self):</span></code> method
can optionally do cleanup after each test.</p>
<p>To test the results, you use special methods of the <codeclass="docutils literal notranslate"><spanclass="pre">TestCase</span></code> class. Many of those start with
“<codeclass="docutils literal notranslate"><spanclass="pre">assert</span></code>”, such as <codeclass="docutils literal notranslate"><spanclass="pre">assertEqual</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">assertTrue</span></code>.</p>
<p>You might also want to read the <aclass="reference external"href="http://docs.python.org/library/unittest.html">documentation for the unittest module</a>.</p>
<p>Evennia offers a custom TestCase, the <codeclass="docutils literal notranslate"><spanclass="pre">evennia.utils.test_resources.EvenniaTest</span></code> class. This class
initiates a range of useful properties on themselves for testing Evennia systems. Examples are
<codeclass="docutils literal notranslate"><spanclass="pre">.account</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">.session</span></code> representing a mock connected Account and its Session and <codeclass="docutils literal notranslate"><spanclass="pre">.char1</span></code> and
<codeclass="docutils literal notranslate"><spanclass="pre">.char2</span></code> representing Characters complete with a location in the test database. These are all useful
when testing Evennia system requiring any of the default Evennia typeclasses as inputs. See the full
definition of the <codeclass="docutils literal notranslate"><spanclass="pre">EvenniaTest</span></code> class in <aclass="reference external"href="https://github.com/evennia/evennia/blob/master/evennia/utils/test_resources.py">evennia/utils/test_resources.py</a>.</p>
<p>In-game Commands are a special case. Tests for the default commands are put in
<codeclass="docutils literal notranslate"><spanclass="pre">evennia/commands/default/tests.py</span></code>. This uses a custom <codeclass="docutils literal notranslate"><spanclass="pre">CommandTest</span></code> class that inherits from
<codeclass="docutils literal notranslate"><spanclass="pre">evennia.utils.test_resources.EvenniaTest</span></code> described above. <codeclass="docutils literal notranslate"><spanclass="pre">CommandTest</span></code> supplies extra convenience
functions for executing commands and check that their return values (calls of <codeclass="docutils literal notranslate"><spanclass="pre">msg()</span></code> returns
expected values. It uses Characters and Sessions generated on the <codeclass="docutils literal notranslate"><spanclass="pre">EvenniaTest</span></code> class to call each
class).</p>
<p>Each command tested should have its own <codeclass="docutils literal notranslate"><spanclass="pre">TestCase</span></code> class. Inherit this class from the <codeclass="docutils literal notranslate"><spanclass="pre">CommandTest</span></code>
class in the same module to get access to the command-specific utilities mentioned.</p>
<h3>Unit testing contribs with custom models<aclass="headerlink"href="#unit-testing-contribs-with-custom-models"title="Permalink to this headline">¶</a></h3>
<p>A special case is if you were to create a contribution to go to the <codeclass="docutils literal notranslate"><spanclass="pre">evennia/contrib</span></code> folder that
uses its <aclass="reference internal"href="New-Models.html"><spanclass="doc std std-doc">own database models</span></a>. The problem with this is that Evennia (and Django) will
only recognize models in <codeclass="docutils literal notranslate"><spanclass="pre">settings.INSTALLED_APPS</span></code>. If a user wants to use your contrib, they will
be required to add your models to their settings file. But since contribs are optional you cannot
add the model to Evennia’s central <codeclass="docutils literal notranslate"><spanclass="pre">settings_default.py</span></code> file - this would always create your
optional models regardless of if the user wants them. But at the same time a contribution is a part
of the Evennia distribution and its unit tests should be run with all other Evennia tests using
<p>The way to do this is to only temporarily add your models to the <codeclass="docutils literal notranslate"><spanclass="pre">INSTALLED_APPS</span></code> directory when the
test runs. here is an example of how to do it.</p>
<div><p>Note that this solution, derived from this <aclass="reference external"href="http://stackoverflow.com/questions/502916/django-how-to-create-a-model-dynamically-just-for-testing#503435">stackexchange answer</a> is currently untested! Please report your findings.</p>
<h3>A note on making the test runner faster<aclass="headerlink"href="#a-note-on-making-the-test-runner-faster"title="Permalink to this headline">¶</a></h3>
<p>Then add it to your <codeclass="docutils literal notranslate"><spanclass="pre">INSTALLED_APPS</span></code> in your <codeclass="docutils literal notranslate"><spanclass="pre">server.conf.settings.py</span></code>:</p>
<p>After doing so, you can then run tests without migrations by adding the <codeclass="docutils literal notranslate"><spanclass="pre">--nomigrations</span></code> argument:</p>
<h2>Testing for Game development (mini-tutorial)<aclass="headerlink"href="#testing-for-game-development-mini-tutorial"title="Permalink to this headline">¶</a></h2>
<p>This command will execute Evennia’s test runner using your own settings file. It will set up a dummy
database of your choice and look into the ‘commands’ package defined in your game directory
(<codeclass="docutils literal notranslate"><spanclass="pre">mygame/commands</span></code> in this example) to find tests. The test module’s name should begin with ‘test’
and contain one or more <codeclass="docutils literal notranslate"><spanclass="pre">TestCase</span></code>. A full example can be found below.</p>
<p>In your game directory, go to <codeclass="docutils literal notranslate"><spanclass="pre">commands</span></code> and create a new file <codeclass="docutils literal notranslate"><spanclass="pre">tests.py</span></code> inside (it could be named
anything starting with <codeclass="docutils literal notranslate"><spanclass="pre">test</span></code>). We will start by making a test that has nothing to do with Commands,
<p>We specified the <codeclass="docutils literal notranslate"><spanclass="pre">commands</span></code> package to the evennia test command since that’s where we put our test
file. In this case we could just as well just said <codeclass="docutils literal notranslate"><spanclass="pre">.</span></code> to search all of <codeclass="docutils literal notranslate"><spanclass="pre">mygame</span></code> for testing files.
If we have a lot of tests it may be useful to test only a single set at a time though. We get an
information text telling us we are using our custom settings file (instead of Evennia’s default
file) and then the test runs. The test passes! Change the “FOO” string to something else in the test
<aclass="reference internal"href="First-Steps-Coding.html"><spanclass="doc std std-doc">First Steps Coding</span></a> page. Follow this tutorial to create the ‘abilities’ command, we
<p>Testing commands in Evennia is a bit more complex than the simple testing example we have seen.
Luckily, Evennia supplies a special test class to do just that … we just need to inherit from it
and use it properly. This class is called ‘CommandTest’ and is defined in the
‘evennia.commands.default.tests’ package. To create a test for our ‘abilities’ command, we just
need to create a class that inherits from ‘CommandTest’ and add methods.</p>
<p>We could create a new test file for this but for now we just append to the <codeclass="docutils literal notranslate"><spanclass="pre">tests.py</span></code> file we
already have in <codeclass="docutils literal notranslate"><spanclass="pre">commands</span></code> from before.</p>
<p>Having read the unit test tutorial on <aclass="reference internal"href="#testing-commands"><spanclass="std std-doc">Testing commands</span></a> we can see
I recommend reading the <codeclass="docutils literal notranslate"><spanclass="pre">Introduction</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">Simple</span><spanclass="pre">Pattern</span></code> sections at
<aclass="reference external"href="https://docs.python.org/3/howto/regex.html">Python regular expressions tutorial</a>. If you do plan on making a complete Evennia
<p>Noticed that we removed the test string from <codeclass="docutils literal notranslate"><spanclass="pre">self.call</span></code>. That method always returns the string it
found from the commands output. If we remove the string to test against, all <codeclass="docutils literal notranslate"><spanclass="pre">self.call</span></code> will do is
return the screen output from the command object passed to it.<br></p>
<p>We are instead using the next line to test our command’s output.
<aclass="reference external"href="https://docs.python.org/3/library/unittest.html#unittest.TestCase.assertRegex">assertRegex</a> is a
method of <codeclass="docutils literal notranslate"><spanclass="pre">unittest.TestCase</span></code> this is inherited to <codeclass="docutils literal notranslate"><spanclass="pre">TestDynamicAbilities</span></code> from <codeclass="docutils literal notranslate"><spanclass="pre">CommandTest</span></code> who
inherited it from <codeclass="docutils literal notranslate"><spanclass="pre">EvenniaTest</span></code>.<br></p>
<p>What we are doing is testing the result of the <codeclass="docutils literal notranslate"><spanclass="pre">CmdAbilities</span></code> method or command against a regular
expression pattern. In this case, <codeclass="docutils literal notranslate"><spanclass="pre">"STR:</span><spanclass="pre">\d+,</span><spanclass="pre">AGI:</span><spanclass="pre">\d+,</span><spanclass="pre">MAG:</span><spanclass="pre">\d+"</span></code>. <codeclass="docutils literal notranslate"><spanclass="pre">\d</span></code> in regular expressions or
regex are digits (numbers), the <codeclass="docutils literal notranslate"><spanclass="pre">+</span></code> is to state we want 1 or more of that pattern. Together <codeclass="docutils literal notranslate"><spanclass="pre">\d+</span></code> is
