Markers

Some broadly useful pytest markers are provided.

Default markers

By default, the following markers are defined for any project consuming modflow-devtools as a pytest plugin:

slow: tests taking more than a few seconds to complete
regression: tests comparing results from different versions of a program

Smoke testing

Smoke testing is a form of integration testing which aims to exercise a substantial subset of the codebase quickly enough to run often during development. This is useful to rapidly determine whether a refactor has broken any expectations before running slower, more extensive tests.

To run smoke tests, use the --smoke (short -S) CLI option. For instance:

pytest -v -S

Conditionally skipping tests

Several pytest markers are provided to conditionally skip tests based on executable availability, Python package environment or operating system.

To skip tests if one or more executables are not available on the path:

from shutil import which
from modflow_devtools.markers import requires_exe

@requires_exe("mf6")
def test_mf6():
    assert which("mf6")

@requires_exe("mf6", "mp7")
def test_mf6_and_mp7():
    assert which("mf6")
    assert which("mp7")

To skip tests if one or more Python packages are not available:

from modflow_devtools.markers import requires_pkg

@requires_pkg("pandas")
def test_needs_pandas():
    import pandas as pd

@requires_pkg("pandas", "shapefile")
def test_needs_pandas():
    import pandas as pd
    from shapefile import Reader

To mark tests requiring or incompatible with particular operating systems:

import os
import platform
from modflow_devtools.markers import requires_platform, excludes_platform

@requires_platform("Windows")
def test_needs_windows():
    assert platform.system() == "Windows"

@excludes_platform("Darwin", ci_only=True)
def test_breaks_osx_ci():
    if "CI" in os.environ:
        assert platform.system() != "Darwin"

Platforms must be specified as returned by platform.system().

Both these markers accept a ci_only flag, which indicates whether the policy should only apply when the test is running on GitHub Actions CI.

Markers are also provided to ping network resources and skip if unavailable:

@requires_github: skips if github.com is unreachable
@requires_spatial_reference: skips if spatialreference.org is unreachable

A marker is also available to skip tests if pytest is running in parallel with pytest-xdist:

from os import environ
from modflow_devtools.markers import no_parallel

@no_parallel
def test_only_serially():
    # https://pytest-xdist.readthedocs.io/en/stable/how-to.html#identifying-the-worker-process-during-a-test.
    assert environ.get("PYTEST_XDIST_WORKER") is None

Aliases

All markers are aliased to imperative mood, e.g. require_github. Some have other aliases as well:

requires_pkg -> require[s]_package requires_exe -> require[s]_program