<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) run before
<em>every</em> test. This can be useful for setting up and deleting things.</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 .
</pre></div>
</div>
<p>to run the entire test module</p>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span>evennia test --settings setings.py .world.tests
</pre></div>
</div>
<p>or a specific class:</p>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span>evennia test --settings settings.py .world.tests.TestObj
</pre></div>
</div>
<p>You can also run a specific test:</p>
<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>
</section>
<sectionid="using-the-evennia-testing-classes">
<h2>Using the Evennia testing classes<aclass="headerlink"href="#using-the-evennia-testing-classes"title="Permalink to this headline">¶</a></h2>
<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>. Note that
these 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>
<sectionid="classes-for-testing-your-game-dir">
<h3>Classes for testing your game dir<aclass="headerlink"href="#classes-for-testing-your-game-dir"title="Permalink to this headline">¶</a></h3>
<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">.account2</span></code> - Another account named “TestAccount2”</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">char1</span></code> - A <aclass="reference internal"href="../api/evennia.objects.objects.html#evennia.objects.objects.DefaultCharacter"title="evennia.objects.objects.DefaultCharacter"><spanclass="xref myst py py-class">Character</span></a> linked to <codeclass="docutils literal notranslate"><spanclass="pre">.account</span></code>, named <codeclass="docutils literal notranslate"><spanclass="pre">Char</span></code>.
This has ‘Developer’ permissions but is not a superuser.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">.char2</span></code> - Another character linked to <codeclass="docutils literal notranslate"><spanclass="pre">account</span></code>, named <codeclass="docutils literal notranslate"><spanclass="pre">Char2</span></code>. This has base permissions (player).</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">.obj1</span></code> - A regular <aclass="reference internal"href="../api/evennia.objects.objects.html#evennia.objects.objects.DefaultObject"title="evennia.objects.objects.DefaultObject"><spanclass="xref myst py py-class">Object</span></a> named “Obj”.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">.obj2</span></code> - Another object named “Obj2”.</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 room 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>
</ul>
</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>
<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>
</section>
<sectionid="classes-for-testing-evennia-core">
<h3>Classes for testing Evennia core<aclass="headerlink"href="#classes-for-testing-evennia-core"title="Permalink to this headline">¶</a></h3>
<p>These are used for testing Evennia itself. They provide the same resources as the classes
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>
<ulclass="simple">
<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
page</a>. There you see which modules have any form of
test coverage and which does not. All help is appreciated!</p>
<h2>Unit testing contribs with custom models<aclass="headerlink"href="#unit-testing-contribs-with-custom-models"title="Permalink to this headline">¶</a></h2>
<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/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>
<h2>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></h2>
<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>
