Test¶

This page describes the invoke_tasklib.test module, which provides tasks to run doctests, unit/integration/functional tests, and benchmarks with pytest.

Overview¶

Task	Behavior
`test.doctest`	Runs doctests on source code and markdown files
`test.doctest-src`	Runs doctests on source code
`test.doctest-markdown`	Runs doctests on Python examples in markdown files
`test.unit`	Runs unit tests
`test.integration`	Runs integration tests
`test.functional`	Runs functional tests
`test.all`	Runs all tests (unit, integration, and functional)
`test.coverage-report`	Generates an HTML/terminal report from existing coverage data
`test.benchmark`	Runs performance benchmarks

All test tasks (except test.benchmark, test.doctest, and test.doctest-markdown) run pytest with --xdoctest enabled, so doctests embedded in the code under test are also collected.

Running Doctests¶

invoke test.doctest

Runs both test.doctest-src and test.doctest-markdown.

invoke test.doctest-src

Runs doctests against paths.src from the resolved config.

invoke test.doctest-markdown

Recursively finds every *.md file in the project (skipping .venv, .pytest_cache, .git, and node_modules) and runs, for each one:

python -m doctest -o NORMALIZE_WHITESPACE -o ELLIPSIS -o REPORT_NDIFF <file>.md

so Python code examples embedded in markdown files (README, docs, ...) stay correct and up to date. NORMALIZE_WHITESPACE and ELLIPSIS make output comparisons more forgiving (whitespace differences are ignored, and ... in expected output matches any text), and REPORT_NDIFF gives a readable diff when an example's output doesn't match. A markdown file with no >>> doctest blocks is still visited but simply reports zero tests, so it always "passes".

Running Tests by Scope¶

invoke test.unit
invoke test.integration
invoke test.functional

Each targets its own path (paths.unit_tests, paths.integration_tests, paths.functional_tests), with a longer timeout (60s vs 10s) for integration and functional tests, since they typically exercise more of the system.

invoke test.all

Runs everything in paths.tests in a single pytest invocation, with a 10s timeout.

Coverage¶

Pass --cov to test.unit, test.integration, test.functional, or test.all to generate coverage reports in HTML, XML, and terminal formats:

invoke test.unit --cov

test.integration --cov and test.functional --cov append to any existing coverage data (--cov-append), so they compose with a prior test.unit --cov run to build up combined coverage across scopes:

invoke test.unit --cov
invoke test.integration --cov
invoke test.functional --cov

invoke test.coverage-report

Regenerates the HTML report and prints the terminal summary from whatever coverage data (.coverage) is currently on disk — the data produced by an earlier --cov run — without re-running the tests. Pass --open-browser to also open htmlcov/index.html in your default browser:

invoke test.coverage-report --open-browser

Benchmarks¶

invoke test.benchmark

Runs pytest --benchmark-only against paths.benchmarks. This requires pytest-benchmark to be installed.