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 handling

  • E3_ENABLE_FEATURE="" to discard any specific features supported by e3

  • E3_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):
    ...