<h1>Unit Testing<aclass="headerlink"href="#unit-testing"title="Permalink to this headline">¶</a></h1>
<p><em>Unit testing</em> 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 <aclass="reference external"href="https://en.wikipedia.org/wiki/Unit_test">here</a>).</p>
<p>A typical unit test set calls some function or method 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 <em>test runner</em>. This is a program that gathers all available tests all over the Evennia source code (called <em>test suites</em>) and runs them all in one go. Errors and tracebacks are reported.</p>
<p>By default Evennia only tests itself. But you can also add your own tests to your game code and have Evennia run those for you.</p>
<sectionid="running-the-evennia-test-suite">
<h2>Running the Evennia test suite<aclass="headerlink"href="#running-the-evennia-test-suite"title="Permalink to this headline">¶</a></h2>
<p>To run the full Evennia test suite, go to your game folder and issue the command</p>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span>evennia test evennia
<p>This will run all the evennia tests using the default settings. You could also run only a subset of all tests by specifying a subpackage of the library:</p>
<p>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. If you contribute to Evennia, this is a useful sanity check to see you haven’t introduced an unexpected bug.</p>
<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>An important thing to note is that those tests will all be run using the <em>default Evennia settings</em>. 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>
<p>Evennia’s test suite makes use of Django unit test system, which in turn relies on Python’s <em>unittest</em> module.</p>
<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 the module you need to put a class inheriting (at any distance) from <codeclass="docutils literal notranslate"><spanclass="pre">unittest.TestCase</span></code>. Each method on that class that starts with <codeclass="docutils literal notranslate"><spanclass="pre">test_</span></code> will be run separately as a unit test. There are two special, optional methods <codeclass="docutils literal notranslate"><spanclass="pre">setUp</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">tearDown</span></code> that will (if you define them) respectively run before and after <em>every</em> test. This can be useful for creating, configuring and cleaning up things that every test in the class needs.</p>
<p>To actually test things, you use special <codeclass="docutils literal notranslate"><spanclass="pre">assert...</span></code> methods on the class. Most common on is <codeclass="docutils literal notranslate"><spanclass="pre">assertEqual</span></code>, which makes sure a result is what you expect it to be.</p>
<p>Here’s an example of the principle. Let’s assume you put this in <codeclass="docutils literal notranslate"><spanclass="pre">mygame/world/tests.py</span></code>
and want to test a function in <codeclass="docutils literal notranslate"><spanclass="pre">mygame/world/myfunctions.py</span></code></p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># in a module tests.py somewhere i your game dir</span>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span>evennia test --settings settings.py world.tests.TestObj.test_alternative_call
</pre></div>
</div>
<p>You might also want to read the <aclass="reference external"href="https://docs.python.org/library/unittest.html">Python documentation for the unittest module</a>.</p>
<sectionid="using-the-evennia-testing-classes">
<h3>Using the Evennia testing classes<aclass="headerlink"href="#using-the-evennia-testing-classes"title="Permalink to this headline">¶</a></h3>
<p>Evennia offers many custom testing classes that helps with testing Evennia features. They are all found in <aclass="reference internal"href="../api/evennia.utils.test_resources.html#evennia-utils-test-resources"><spanclass="std std-ref">evennia.utils.test_resources</span></a>.</p>
<divclass="admonition important">
<pclass="admonition-title">Important</p>
<p>Note that these base classes implement the <codeclass="docutils literal notranslate"><spanclass="pre">setUp</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">tearDown</span></code> already, so if you want to add stuff in them yourself you should remember to use e.g. <codeclass="docutils literal notranslate"><spanclass="pre">super().setUp()</span></code> in your code.</p>
<h4>Classes for testing your game dir<aclass="headerlink"href="#classes-for-testing-your-game-dir"title="Permalink to this headline">¶</a></h4>
<p>These all use whatever setting you pass to them and works well for testing code in your game dir.</p>
<ulclass="simple">
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">EvenniaTest</span></code> - this sets up a full object environment for your test. All the created entities
can be accesses as properties on the class:</p>
<ul>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">.account</span></code> - A fake <aclass="reference internal"href="../api/evennia.accounts.accounts.html#evennia.accounts.accounts.DefaultAccount"title="evennia.accounts.accounts.DefaultAccount"><spanclass="xref myst py py-class">Account</span></a> named “TestAccount”.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">.room1</span></code> - A <aclass="reference internal"href="../api/evennia.objects.objects.html#evennia.objects.objects.DefaultRoom"title="evennia.objects.objects.DefaultRoom"><spanclass="xref myst py py-class">Room</span></a> named “Room”. Both characters and both
objects are located inside this room. It has a description of “room_desc”.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">.room2</span></code> - Another <aclass="reference internal"href="../api/evennia.objects.objects.html#evennia.objects.objects.DefaultRoom"title="evennia.objects.objects.DefaultRoom"><spanclass="xref myst py py-class">Room</span></a> named “Room2”. It is empty and has no set description.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">.exit</span></code> - An exit named “out” that leads from <codeclass="docutils literal notranslate"><spanclass="pre">.room1</span></code> to <codeclass="docutils literal notranslate"><spanclass="pre">.room2</span></code>.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">.script</span></code> - A <aclass="reference internal"href="../api/evennia.scripts.scripts.html#evennia.scripts.scripts.DefaultScript"title="evennia.scripts.scripts.DefaultScript"><spanclass="xref myst py py-class">Script</span></a> named “Script”. It’s an inert script
without a timing component.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">.session</span></code> - A fake <aclass="reference internal"href="../api/evennia.server.serversession.html#evennia.server.serversession.ServerSession"title="evennia.server.serversession.ServerSession"><spanclass="xref myst py py-class">Session</span></a> that mimics a player
connecting to the game. It is used by <codeclass="docutils literal notranslate"><spanclass="pre">.account1</span></code> and has a sessid of 1.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">EvenniaCommandTest</span></code> - has the same environment like <codeclass="docutils literal notranslate"><spanclass="pre">EvenniaTest</span></code> but also adds a special <aclass="reference internal"href="../api/evennia.utils.test_resources.html#evennia.utils.test_resources.EvenniaCommandTestMixin.call"title="evennia.utils.test_resources.EvenniaCommandTestMixin.call"><spanclass="xref myst py py-meth">.call()</span></a> method specifically for testing Evennia <aclass="reference internal"href="../Components/Commands.html"><spanclass="doc std std-doc">Commands</span></a>. It allows you to compare what the command <em>actually</em> returns to the player with what you expect. Read the <codeclass="docutils literal notranslate"><spanclass="pre">call</span></code> api doc for more info.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">EvenniaTestCase</span></code> - This is identical to the regular Python <codeclass="docutils literal notranslate"><spanclass="pre">TestCase</span></code> class, it’s
just there for naming symmetry with <codeclass="docutils literal notranslate"><spanclass="pre">BaseEvenniaTestCase</span></code> below.</p></li>
</ul>
<p>Here’s an example of using <codeclass="docutils literal notranslate"><spanclass="pre">EvenniaTest</span></code></p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># in a test module</span>
<spanclass="w"></span><spanclass="sd">"""Remember that the testing class creates char1 and char2 inside room1 ..."""</span>
<p>When using <codeclass="docutils literal notranslate"><spanclass="pre">.call</span></code>, you don’t need to specify the entire string; you can just give the beginning of it and if it matches, that’s enough. Use <codeclass="docutils literal notranslate"><spanclass="pre">\n</span></code> to denote line breaks and (this is a special for the <codeclass="docutils literal notranslate"><spanclass="pre">.call</span></code> helper), <codeclass="docutils literal notranslate"><spanclass="pre">||</span></code> to indicate multiple uses of <codeclass="docutils literal notranslate"><spanclass="pre">.msg()</span></code> in the Command. The <codeclass="docutils literal notranslate"><spanclass="pre">.call</span></code> helper has a lot of arguments for mimicing different ways of calling a Command, so make sure to <aclass="reference internal"href="../api/evennia.utils.test_resources.html#evennia.utils.test_resources.EvenniaCommandTestMixin.call"title="evennia.utils.test_resources.EvenniaCommandTestMixin.call"><spanclass="xref myst py py-meth">read the API docs for .call()</span></a>.</p>
above but enforce Evennias default settings found in <codeclass="docutils literal notranslate"><spanclass="pre">evennia/settings_default.py</span></code>, ignoring any settings changes in your game dir.</p>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">BaseEvenniaTest</span></code> - all the default objects above but with enforced default settings</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">BaseEvenniaCommandTest</span></code> - for testing Commands, but with enforced default settings</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">BaseEvenniaTestCase</span></code> - no default objects, only enforced default settings</p></li>
</ul>
<p>There are also two special ‘mixin’ classes. These are uses in the classes above, but may also
be useful if you want to mix your own testing classes:</p>
<ulclass="simple">
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">EvenniaTestMixin</span></code> - A class mixin that creates all test environment objects.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">EvenniaCommandMixin</span></code> - A class mixin that adds the <codeclass="docutils literal notranslate"><spanclass="pre">.call()</span></code> Command-tester helper.</p></li>
</ul>
<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
<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="../Concepts/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 <codeclass="docutils literal notranslate"><spanclass="pre">evennia</span><spanclass="pre">test</span><spanclass="pre">evennia</span></code>.</p>
<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>
<blockquote>
<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>
</div></blockquote>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># a file contrib/mycontrib/tests.py</span>
<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>If you have custom models with a large number of migrations, creating the test database can take a very long time. If you don’t require migrations to run for your tests, you can disable them with the django-test-without-migrations package. To install it, simply:</p>
<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>
