Quickstart
Installation
Load up your VirtualEnvironment of choice and run:
pip install django-expanded-test-cases
Alternatively, add django-expanded-test-cases
to your respective project
requirements file, and then follow the standard package installation method
for your project
(requirements.txt,
pipenv, etc).
Currently, this package also assumes use of some kind of User model
implementation, which requires Django’s sessions
app.
Double check that the following is added to your INSTALLED_APPS project settings
definition:
INSTALLED_APPS = (
...
'django.contrib.sessions',
)
Optional Packages
Django ETC comes with support for the following optional packages.
For colorized debug output, install the colorama
package.
pip install colorama
For basic selenium support, install the selenium
and webdriver-manager
packages.
pip install selenium webdriver-manager
Note
As of Chrome version 115 and higher, the official chromedriver API has been modified, and the traditional release
repository is no longer supported. Chromedriver releases can now only be discovered programmatically. To support
that, selenium
package version 4.11.2 or higher is now required.
See https://bonigarcia.dev/webdrivermanager/#support-for-chromedriver-115 and https://chromedriver.chromium.org/downloads/version-selection for more information.
For full Django Channels selenium support, install the channels and daphne packages.
pip install channels daphne
Or alternatively see the official channels installation guide for additional methods.
Testing Environments
The functionality provided by Django-Expanded-Test-Cases will work with both the default Django Manage.py testing framework and PyTest. However, one of the most useful features of the Django-Expanded-Test-Cases package is that it automatically displays debug page response output to the console on test failure. This feature works best when running tests via PyTest and thus is the recommend way to run tests. For a complete explanation as to why, see the “important” note below.
Please refer to the PyTest Configuration QuickStart section for setting up PyTest to work with this package. Refer to the Manage.py Test QuickStart section for setting up Manage.py to work with this package.
Important
When running tests, manage.py
’s base functionality is to assume all
testing console output is meaningful, and display it to the console
unconditionally.
Because of this behavior, when using this package in a project with a decent amount of tests, output results in an unwieldy amount of unhelpful text being sent to the console. This happens regardless of whether all tests pass or there are failures to review. Any useful information that might have occurred quickly becomes near impossible to find and gain knowledge from.
Thus, when using this package, we strongly recommend switching to running tests via PyTest. PyTest only sends extra output to the console on test failure. So, when there is extra output, you know that all of it is relevant to the failing test(s).
If you really don’t want to use PyTest, but still want to use this package,
you can also consider using the --buffer
flag with manage.py, which will
hide output for passing tests, but failing test output won’t be formatted
as neatly as in PyTest. Ex: manage.py test --buffer
If you would like further explanation of “manage.py vs pytest”, as well as why we DON’T try to change this manage.py behavior in our project, see https://adamj.eu/tech/2020/09/05/what-happens-when-you-run-manage.py-test/#no-composition.
PyTest Configuration QuickStart
See https://docs.pytest.org/en/stable/ for official documentation.
PyTest can be fairly trivial to set up for a project.
To start, install the base PyTest package, plus any additional sub-packages that apply to your project:
pytest # Base Pytest package.
pytest-asyncio # Additional Pytest logic for asyncio support.
pytest-django # Additional Pytest logic for Django support.
pytest-xdist # Additional Pytest features, such as multithreading and looping.
Next, define a pytest.ini
file at project root. A minimal, default
configuration is provided below. Otherwise see
https://docs.pytest.org/en/stable/reference/customize.html for official Pytest
customization documentation.
[pytest]
DJANGO_SETTINGS_MODULE = path.example.to.project.settings
python_files = tests.py test_*.py
log_level = NOTSET
Note
For the above snippet, be sure to replace the DJANGO_SETTINGS_MODULE
value with the path to the project’s settings file, starting from the
project root.
Ex: If your settings file is defined at
<project_root>/configuration/settings.py
, then the value for this
setting should be configuration.settings
.
From this point, UnitTests can be invoked through Pytest, at project root with the following commands:
pytest # Run pytest on all files that match ini definition.
pytest path/to/check # Run PyTest on a specific folder.
pytest -n auto # Run PyTest parallel, if pytest-xdist is installed.
For additional details about configuration and setup, see the General Setting Configuration page.
For information on how to use this package, see the General Usage page.
Manage.py Test QuickStart
Warning
While this project can function with manage.py test
, the debug output
functionality will send content to the console on every test regardless of
pass or fail leading to an overwhelming amount of output. Instead, we
strongly recommend that you consider using PyTest to run tests as
PyTest will only output debug info on test failure.
If you really don’t want to use PyTest, but still want to use this package,
you can also consider using the --buffer
flag with manage.py, which will
hide output for passing tests, but failing test output won’t be formatted
as neatly as in PyTest. Ex: manage.py test --buffer
Nothing extra needs to be done in order for the provided TestCase classes to
work with Django’s default manage.py test
command.
However, since you will get debug output on every test that uses the additional asserts provided by the TestCases, it is recommended that you disable the debug output so that console output is manageable.
To do so, add the following line to your settings.py
file:
DJANGO_EXPANDED_TESTCASES_DEBUG_PRINT = False
For more details about available settings, see the General Setting Configuration page.
For information on how to use this package, see the General Usage page.