UnitTest support

Tortoise ORM includes its own helper utilities to assist in unit tests.


from tortoise.contrib import test

class TestSomething(test.TestCase):
    def test_something(self):

    async def test_something_async(self):

    @test.skip('Skip this')
    def test_skip(self):

    def test_something(self):

To get test.TestCase to work as expected, you need to configure your test environment setup and teardown to call the following:

from tortoise.contrib.test import initializer, finalizer

# In setup
initializer(['module.a', 'module.b.c'])
# With optional db_url, app_label and loop parameters
initializer(['module.a', 'module.b.c'], db_url='...', app_label="someapp", loop=loop)
# Or env-var driven → See Green test runner section below.

# In teardown

On the DB_URL it should follow the following standard:

TORTOISE_TEST_DB=sqlite:///tmp/test-{}.sqlite TORTOISE_TEST_DB=postgres://postgres:@{}

The {} is a string-replacement parameter, that will create a randomized database name. This is currently required for test.IsolatedTestCase to function. If you don’t use test.IsolatedTestCase then you can give an absolute address. The SQLite in-memory :memory: database will always work, and is the default.

Test Runners


In your .green file:

initializer = tortoise.contrib.test.env_initializer
finalizer = tortoise.contrib.test.finalizer

And then define the TORTOISE_TEST_MODULES environment variable with a comma separated list of module paths.

Furthermore, you may set the database configuration parameter as an environment variable (defaults to sqlite://:memory:):

TORTOISE_TEST_DB=sqlite:///tmp/test-{}.sqlite TORTOISE_TEST_DB=postgres://postgres:@{}



pytest 5.4.0 & 5.4.1 has a bug that stops it from working with async test cases. You may have to install pytest>=5.4.2 to get it to work.

Run the initializer and finalizer in your conftest.py file:

import os
import pytest
from tortoise.contrib.test import finalizer, initializer

@pytest.fixture(scope="session", autouse=True)
def initialize_tests(request):
    db_url = os.environ.get("TORTOISE_TEST_DB", "sqlite://:memory:")
    initializer(["tests.testmodels"], db_url=db_url, app_label="models")


Load the plugin tortoise.contrib.test.nose2 either via command line:

nose2 --plugin tortoise.contrib.test.nose2 --db-module tortoise.tests.testmodels

Or via the config file:

plugins = tortoise.contrib.test.nose2

# Must specify at least one module path
db-module =
# You can optionally override the db_url here
db-url = sqlite://testdb-{}.sqlite