# Usage and invocations

## Basic usage

When using pytest-django, django-admin.py or manage.py is not used to run tests. This makes it possible to invoke pytest and other plugins with all its different options directly.

Running a test suite is done by invoking the pytest command directly:

    pytest

Specific test files or directories can be selected by specifying the test file names directly on the command line:

    pytest test_something.py a_directory

See the pytest documentation on Usage and invocations for more help on available parameters.

## Additional command line options

### `--fail-on-template-vars` - fail for invalid variables in templates

Fail tests that render templates which make use of invalid template variables.

You can switch it on in pytest.ini:

    [pytest]
    FAIL_INVALID_TEMPLATE_VARS = True

## Additional pytest.ini settings

### `django_debug_mode` - change how DEBUG is set

By default tests run with the DEBUG setting set to `False`. This is to ensure that the observed output of your code matches what will be seen in a production setting.

If you want `DEBUG` to be set:

    [pytest]
    django_debug_mode = true

You can also use `django_debug_mode = keep` to disable the overriding and use whatever is already set in the Django settings.

## Running tests in parallel with pytest-xdist

pytest-django supports running tests on multiple processes to speed up test suite run time. This can lead to significant speed improvements on multi core/multi CPU machines.

This requires the pytest-xdist plugin to be available, it can usually be installed with:

    pip install pytest-xdist

You can then run the tests by running:

    pytest -n <number of processes>

When tests are invoked with xdist, pytest-django will create a separate test database for each process. Each test database will be given a suffix (something like “gw0”, “gw1”) to map to a xdist process. If your database name is set to “foo”, the test database with xdist will be “test_foo_gw0”, “test_foo_gw1” etc.

See the full documentation on pytest-xdist for more information. Among other features, pytest-xdist can distribute/coordinate test execution on remote machines.