Using the e3 pytest plugin¶
Introduction¶
e3-core
contains a pytest
plugin that is discovered automatically when
installed. The plugin provides several features: it generates a results file
compatible with anod when the environment variable RESULTS_DIR
is defined.
It provides a simple setup for running coverage (on top of the pytest-cov
plugin). And it provides a env_protect fixture that is automatically activated.
Activating e3-core pytest plugins¶
To activate the e3-core pytest plugin, you need to install e3-core and pass
the option --e3
to pytest.
env_protect¶
When activated, the plugin will register the env_protect
feature to ensure
that all tests are run in isolation. All changes to the environment done in
each test won’t impact other tests. Also, each test is run in a separate temp
directory, you won’t have to cleanup the files that the tests create.
env_protect
also sets some environment variables such as:
TZ=UTC
to ensure a consistent timezone handlingE3_ENABLE_FEATURE=""
to discard any specific features supported by e3E3_CONFIG=/dev/null
to avoid having a specific e3 config read by the tests
And the e3 DEBUG log level is activated for each tests.
Coverage¶
When running pytest with --e3
and --cov
options, pytest will
automatically generate an exclude list for lines matching the following
patterns:
all: no cover
if TYPE_CHECKING:
@abstractmethod
# os-specific
defensive code
assert_never(),
And <os>-only
with <os>
different from the local OS, so if you’re
running a test on Linux, windows-only
and darwin-only
will be discared.
The opposite <os>: no cover
is also supported.
Specific test for the windows platform are also detected:
if sys.platform == win32
if sys.platform != win32
unix-only
You can also skip complete files by creating an omit file
in
tests/coverage/omit-file-<os>
. The file should contain a filename per line.
Finally, the option --e3-cov-rewrite <origin> <dest>
changes the paths
reported by coverage. If you run --e3-cov-rewrite
.tox/py311/cov-xdist/lib-site-packages src
instead of seeing reports of files in
.tox/py311-cov-xdist/lib/site-packages/e3/
the report will show files
in the repository src/e3/
.
require_tool
fixture¶
e3.pytest
provides a function require_tool
that generates a fixture
allowing to skip tests if a tool is missing. For instance, to create a fixture
that will skip tests if git
is not installed run:
from e3.pytest import require_tool
git = require_tool("git")
# Use it in a test that will run only if git is installed
def test_git_fixture(git):
...