### Example Context Names in Coverage.py Source: https://github.com/pytest-dev/pytest-cov/blob/master/docs/contexts.md Illustrates the format of context names recorded by coverage.py, which include the test ID and the execution phase (setup, run, or teardown). Parameterized tests include their parameter values in the test ID. ```text test_functions.py::test_addition|run test_fancy.py::test_parametrized[1-101]|setup test_oldschool.py::RegressionTests::test_error|run ``` -------------------------------- ### Install pytest-cov and pytest-xdist Source: https://context7.com/pytest-dev/pytest-cov/llms.txt Install the pytest-cov plugin for coverage measurement. Optionally, install pytest-xdist for distributed testing support. ```bash pip install pytest-cov # Optional: distributed testing support pip install pytest-xdist ``` -------------------------------- ### Install pytest-cov Source: https://github.com/pytest-dev/pytest-cov/blob/master/README.rst Install pytest-cov using pip. For distributed testing support, also install pytest-xdist. ```bash pip install pytest-cov ``` ```bash pip install pytest-xdist ``` -------------------------------- ### Coverage report example in 'each' mode Source: https://github.com/pytest-dev/pytest-cov/blob/master/docs/xdist.md This is an example of the terminal coverage report generated when running distributed tests in 'each' mode, showing combined coverage across different Python versions and platforms. ```text ---------------------------------------- coverage ---------------------------------------- platform linux2, python 2.6.5-final-0 platform linux2, python 2.7.0-final-0 Name Stmts Miss Cover ---------------------------------------- myproj/__init__ 2 0 100% myproj/myproj 257 13 94% myproj/feature4286 94 7 92% ---------------------------------------- TOTAL 353 20 94% ``` -------------------------------- ### Install pytest-cov Source: https://github.com/pytest-dev/pytest-cov/blob/master/docs/readme.md Install pytest-cov using pip. This command is used to add the package to your Python environment. ```default pip install pytest-cov ``` -------------------------------- ### Coverage report example in 'load' mode Source: https://github.com/pytest-dev/pytest-cov/blob/master/docs/xdist.md This is an example of the terminal coverage report generated when running pytest with the '--cov' option in 'load' mode. ```text -------------------- coverage: platform linux2, python 2.6.4-final-0 --------------------- Name Stmts Miss Cover ---------------------------------------- myproj/__init__ 2 0 100% myproj/myproj 257 13 94% myproj/feature4286 94 7 92% ---------------------------------------- TOTAL 353 20 94% ``` -------------------------------- ### Coverage report example Source: https://github.com/pytest-dev/pytest-cov/blob/master/README.rst An example of a coverage report generated by pytest-cov, showing statements, misses, and coverage percentage for different modules. ```text -------------------- coverage: ... --------------------- Name Stmts Miss Cover ---------------------------------------- myproj/__init__ 2 0 100% myproj/myproj 257 13 94% myproj/feature4286 94 7 92% ---------------------------------------- TOTAL 353 20 94% ``` -------------------------------- ### Install pytest-xdist for distributed testing Source: https://github.com/pytest-dev/pytest-cov/blob/master/docs/readme.md To enable distributed testing support with pytest-cov, install the pytest-xdist package. This allows for parallel test execution across multiple processes or machines. ```default pip install pytest-xdist ``` -------------------------------- ### Distributed Testing with pytest-xdist Source: https://context7.com/pytest-dev/pytest-cov/llms.txt Run tests across multiple environments using pytest-xdist in 'each' mode for combined multi-environment coverage reports. Ensure pytest-cov and coverage.py are installed in each environment. ```bash pytest --cov=myproj --dist each \ --tx "popen//chdir=/tmp/testenv3//python=/usr/local/bin/python3.11" \ --tx "ssh=user@host2//chdir=/tmp/testenv4//python=/tmp/env2/bin/python3.12" \ --rsyncdir myproj --rsyncdir tests \ tests/ # Output includes platform rows for each environment: # platform linux, python 3.11.0 # platform linux, python 3.12.0 # TOTAL 353 20 94% ``` -------------------------------- ### Clone pytest-cov Repository Source: https://github.com/pytest-dev/pytest-cov/blob/master/CONTRIBUTING.rst Clone your forked repository locally to start development. Replace YOURGITHUBNAME with your GitHub username. ```bash git clone git@github.com:YOURGITHUBNAME/pytest-cov.git ``` -------------------------------- ### Append coverage data rather than overwrite Source: https://context7.com/pytest-dev/pytest-cov/llms.txt Prevents pytest-cov from erasing the `.coverage` file at session start. This is essential when aggregating results across multiple tox environments or test runs. ```bash # Run two separate test suites and combine results pytest --cov=myproj --cov-append tests/unit/ pytest --cov=myproj --cov-append tests/integration/ # Or within tox across Python versions (see tox section below) pytest --cov --cov-append --cov-report=term-missing ``` -------------------------------- ### Run All Checks and Build Docs Source: https://github.com/pytest-dev/pytest-cov/blob/master/CONTRIBUTING.rst Execute the tox command to run all defined test environments and build documentation. This is a comprehensive check before committing. ```bash tox ``` -------------------------------- ### Upload Distributions Source: https://github.com/pytest-dev/pytest-cov/blob/master/docs/releasing.md Upload the built sdist and wheel archives to PyPI using the 'twine' utility. ```bash twine upload dist/* ``` -------------------------------- ### Build Distributions Source: https://github.com/pytest-dev/pytest-cov/blob/master/docs/releasing.md Build the source distribution (sdist) and wheel distributions using the 'build' package. ```bash python -m build ``` -------------------------------- ### Configure pytest-cov via setup.cfg Source: https://github.com/pytest-dev/pytest-cov/blob/master/docs/config.md Use the `addopts` setting in `setup.cfg` to automatically include pytest-cov options when running pytest. ```default [tool:pytest] addopts = --cov= --cov-report html ``` -------------------------------- ### Run All Test Environments in Parallel Source: https://github.com/pytest-dev/pytest-cov/blob/master/CONTRIBUTING.rst Execute all configured test environments in parallel using tox with the 'auto' option for faster testing. ```bash tox -p auto ``` -------------------------------- ### Distributed testing with 'load' mode across hosts Source: https://github.com/pytest-dev/pytest-cov/blob/master/docs/xdist.md Configure distributed testing with 'load' mode across different hosts and directories. Use '--tx' to specify remote execution details like SSH connection, target directory, and Python interpreter path. '--rsyncdir' is used to synchronize project files. ```bash pytest --cov=myproj --dist load --tx ssh=memedough@host1//chdir=testenv1 --tx ssh=memedough@host2//chdir=/tmp/testenv2//python=/tmp/env1/bin/python --rsyncdir myproj --rsyncdir tests --rsync examples tests/ ``` -------------------------------- ### Commit and Push Changes Source: https://github.com/pytest-dev/pytest-cov/blob/master/CONTRIBUTING.rst Stage all changes, commit them with a descriptive message, and push the branch to your GitHub fork. This prepares your changes for a pull request. ```bash git add . git commit -m "Your detailed description of your changes." git push origin name-of-your-bugfix-or-feature ``` -------------------------------- ### Measuring Plugin Coverage with `coverage run` Source: https://context7.com/pytest-dev/pytest-cov/llms.txt For pytest plugin projects, use `coverage run` directly instead of `pytest --cov` to measure coverage of the plugins themselves. This bypasses setuptools entry-point load ordering issues. ```bash # Instead of: pytest --cov=my_pytest_plugin tests/ # Use: coverage run -m pytest tests/ coverage report coverage html ``` -------------------------------- ### Basic Tox Configuration Source: https://github.com/pytest-dev/pytest-cov/blob/master/docs/tox.md A minimal tox.ini configuration for setting up environments and specifying pytest and coverage options. ```ini [tox] envlist = ... [tool:pytest] ... [coverage:paths] ... [coverage:run] ... [coverage:report] .. [testenv] commands = ... ``` -------------------------------- ### Tox Configuration for Parallel Runs with Coverage Append Source: https://github.com/pytest-dev/pytest-cov/blob/master/docs/tox.md Set up tox.ini for parallel runs, ensuring coverage data is appended and a separate report environment is configured. Dependencies and environment dependencies are specified for proper execution order. ```ini [tox] envlist = clean,py27,py36,report [testenv] commands = pytest --cov --cov-append --cov-report=term-missing deps = pytest pytest-cov depends = {py27,py36}: clean report: py27,py36 [testenv:report] deps = coverage skip_install = true commands = coverage report coverage html [testenv:clean] deps = coverage skip_install = true commands = coverage erase ``` -------------------------------- ### Tox Configuration for Sequential Runs with Coverage Append Source: https://github.com/pytest-dev/pytest-cov/blob/master/docs/tox.md Configure tox.ini for sequential runs to prevent coverage data loss by using `--cov-append`. Includes a 'clean' environment to erase previous coverage data before each run. ```ini [tox] envlist = clean,py27,py36,... [testenv] commands = pytest --cov --cov-append --cov-report=term-missing ... deps = pytest pytest-cov [testenv:clean] deps = coverage skip_install = true commands = coverage erase ``` -------------------------------- ### Push Changes and Tags Source: https://github.com/pytest-dev/pytest-cov/blob/master/docs/releasing.md After updating the changelog and bumping the version, push all local changes and tags to the remote repository. ```bash git push git push --tags ``` -------------------------------- ### Run pytest with coverage in 'each' mode Source: https://github.com/pytest-dev/pytest-cov/blob/master/docs/xdist.md Execute tests in 'each' mode for combined coverage reports across multiple environments. This command specifies different Python environments on remote hosts using '--tx' and synchronizes project files with '--rsyncdir'. ```bash pytest --cov=myproj --dist each --tx popen//chdir=/tmp/testenv3//python=/usr/local/python27/bin/python --tx ssh=memedough@host2//chdir=/tmp/testenv4//python=/tmp/env2/bin/python --rsyncdir myproj --rsyncdir tests --rsync examples tests/ ``` -------------------------------- ### Specifying Output Paths for Reports Source: https://github.com/pytest-dev/pytest-cov/blob/master/docs/reporting.md Generates various coverage reports and specifies output file or directory paths for each. This allows for organized storage of report artifacts. ```bash pytest --cov-report html:cov_html --cov-report xml:cov.xml --cov-report json:cov.json --cov-report markdown:cov.md --cov-report markdown-append:cov-append.md --cov-report lcov:cov.info --cov-report annotate:cov_annotate --cov=myproj tests/ ``` -------------------------------- ### Configure pytest-cov via pyproject.toml Source: https://github.com/pytest-dev/pytest-cov/blob/master/docs/config.md Use the `addopts` setting within the `[tool.pytest.ini_options]` section of `pyproject.toml` to automatically include pytest-cov options. ```toml [tool.pytest.ini_options] addopts = "--cov= --cov-report html" ``` -------------------------------- ### Run a Subset of Tests with Tox Source: https://github.com/pytest-dev/pytest-cov/blob/master/CONTRIBUTING.rst Use tox with specific environment names and pytest's -k flag to run a targeted subset of tests. Replace envname with the desired environment. ```bash tox -e envname -- pytest -k test_myfeature ``` -------------------------------- ### Measure coverage for a source path Source: https://context7.com/pytest-dev/pytest-cov/llms.txt Activates coverage measurement for a specified source path or importable package name. The option can be repeated for multiple packages. Pass an empty value to record all executed code without source filtering. ```bash # Measure a single package pytest --cov=myproj tests/ # Multiple packages pytest --cov=myproj --cov=mylib tests/ # Record all executed code (no source filter) pytest --cov= tests/ ``` ```text # Expected terminal output: # -------------------- coverage: ... -------------------- # Name Stmts Miss Cover # ----------------------------------------------- # myproj/__init__ 2 0 100% # myproj/myproj 257 13 94% # myproj/feature4286 94 7 92% # ----------------------------------------------- # TOTAL 353 20 94% ``` -------------------------------- ### Configure HTML Report to Show Contexts Source: https://github.com/pytest-dev/pytest-cov/blob/master/docs/contexts.md Add this configuration to your .coveragerc file to enable the display of contexts in the HTML coverage report. This annotation indicates how many contexts executed each covered line. ```ini [html] show_contexts = True ``` -------------------------------- ### Run pytest with coverage Source: https://github.com/pytest-dev/pytest-cov/blob/master/README.rst Execute pytest with the --cov option to enable coverage measurement for a specified module. This will produce a coverage report. ```bash pytest --cov=myproj tests/ ``` -------------------------------- ### Create a New Branch for Development Source: https://github.com/pytest-dev/pytest-cov/blob/master/CONTRIBUTING.rst Create a new branch for your bugfix or feature development. This isolates your changes. ```bash git checkout -b name-of-your-bugfix-or-feature ``` -------------------------------- ### Configure Subprocess Patch in pyproject.toml Source: https://github.com/pytest-dev/pytest-cov/blob/master/docs/subprocess-support.md Alternatively, configure coverage's subprocess patching using `pyproject.toml`. This also automatically enables parallel mode. ```toml [tool.coverage.run] patch = ["subprocess"] ``` -------------------------------- ### Tox Integration for Multi-Environment Coverage Source: https://context7.com/pytest-dev/pytest-cov/llms.txt Use tox with a 'clean' environment to erase stale data and a 'report' environment for a final combined coverage report. This pattern works for both sequential and parallel tox runs. ```ini # tox.ini (parallel tox run covering py311 + py312) [tox] envlist = clean,py311,py312,report [tool:pytest] addopts = --cov-report=term-missing [testenv] commands = pytest --cov --cov-append {posargs:-vv} deps = pytest pytest-cov coverage depends = {py311,py312}: clean report: py311,py312 [testenv:clean] skip_install = true deps = coverage commands = coverage erase [testenv:report] skip_install = true deps = coverage commands = coverage report --fail-under=100 coverage html [coverage:run] branch = True source = myproj [coverage:report] show_missing = True ``` -------------------------------- ### Per-Test Dynamic Coverage Contexts Source: https://context7.com/pytest-dev/pytest-cov/llms.txt Records which individual test (including parametrize variants) executed each line. Requires coverage>=5.0. Context names follow the pattern |. ```bash pytest --cov=myproj --cov-context=test --cov-report=html tests/ ``` -------------------------------- ### Clean Temporary Build Files Source: https://github.com/pytest-dev/pytest-cov/blob/master/docs/releasing.md Manually remove temporary build and distribution files that are ignored by git. This ensures a clean build of the sdist and wheel. ```bash rm -rf dist build src/*.egg-info ``` -------------------------------- ### Run pytest with coverage in 'load' mode Source: https://github.com/pytest-dev/pytest-cov/blob/master/docs/xdist.md Use this command to run tests distributed across multiple workers with coverage reporting enabled. The '--cov' flag specifies the package to measure, and '-n 2' indicates the number of workers. ```bash pytest --cov=myproj -n 2 tests/ ``` -------------------------------- ### Persistent addopts Configuration in pyproject.toml Source: https://context7.com/pytest-dev/pytest-cov/llms.txt Add pytest-cov options to pyproject.toml so they apply to every pytest invocation automatically. ```toml # pyproject.toml [tool.pytest.ini_options] addopts = "--cov=myproj --cov-report=html --cov-fail-under=80" ``` -------------------------------- ### Distributed Testing with pytest-xdist (load mode) Source: https://context7.com/pytest-dev/pytest-cov/llms.txt Runs tests across multiple workers; coverage is measured on every worker and combined automatically into a single report. ```bash # 2 local workers pytest --cov=myproj -n 2 tests/ ``` ```bash # Workers on remote hosts via execnet pytest --cov=myproj --dist load \ --tx "ssh=user@host1//chdir=testenv1" \ --tx "ssh=user@host2//chdir=/tmp/testenv2//python=/tmp/env1/bin/python" \ --rsyncdir myproj --rsyncdir tests \ tests/ ``` ```bash # Output: combined report across all workers # TOTAL 353 20 94% ``` -------------------------------- ### Markdown Append for GitHub Actions Source: https://github.com/pytest-dev/pytest-cov/blob/master/docs/reporting.md Configures the Markdown report to append to the GitHub Actions step summary. This is useful for displaying coverage results directly in GitHub Actions logs. ```bash pytest --cov-report markdown-append:$GITHUB_STEP_SUMMARY --cov=myproj tests/ ``` -------------------------------- ### Specify Coverage Configuration File Source: https://context7.com/pytest-dev/pytest-cov/llms.txt Overrides the default .coveragerc lookup. Useful when configuration lives in tox.ini, pyproject.toml, or a non-standard path. ```bash pytest --cov=myproj --cov-config=tox.ini tests/ ``` ```bash pytest --cov=myproj --cov-config=pyproject.toml tests/ ``` -------------------------------- ### Disable Coverage via Fixture Injection Source: https://context7.com/pytest-dev/pytest-cov/llms.txt Equivalent to the marker but expressed as a fixture parameter, allowing conditional disabling or use in fixture chains. ```python def test_low_level_io(no_cover): """Coverage is paused for this test via fixture.""" with open("/dev/null", "w") as f: f.write("test") ``` -------------------------------- ### Select coverage report formats Source: https://context7.com/pytest-dev/pytest-cov/llms.txt Controls which reports are generated and where they are written. Multiple `--cov-report` flags can be combined. Terminal reports support `:skip-covered`, and file-based reports support a `:DEST` output path. Use `--cov-report=` to suppress all output. ```bash # Terminal with missing line numbers pytest --cov-report=term-missing --cov=myproj tests/ # Terminal, skipping 100%-covered files pytest --cov-report=term:skip-covered --cov=myproj tests/ # Multiple simultaneous reports with custom destinations pytest \ --cov-report=html:htmlcov \ --cov-report=xml:coverage.xml \ --cov-report=json:coverage.json \ --cov-report=lcov:coverage.info \ --cov-report=markdown:coverage.md \ --cov=myproj tests/ # Suppress terminal output; only write the .coverage file (e.g. for Coveralls on CI) pytest --cov-report= --cov=myproj tests/ # Append coverage summary to GitHub Actions step summary pytest --cov-report="markdown-append:$GITHUB_STEP_SUMMARY" --cov=myproj tests/ ``` -------------------------------- ### Enable branch coverage measurement Source: https://context7.com/pytest-dev/pytest-cov/llms.txt Enables branch (arc) coverage measurement, equivalent to setting `branch = True` in `.coveragerc`. When active, the report shows both statement and branch misses. ```bash pytest --cov-branch --cov=myproj tests/ # Alternatively, set permanently in .coveragerc: # [run] # branch = True ``` -------------------------------- ### Access Coverage Instance with `cov` Fixture Source: https://github.com/pytest-dev/pytest-cov/blob/master/docs/markers-fixtures.md Inject the `cov` fixture into a test function to gain access to the underlying Coverage instance. Use with caution as it may be a 'foot-gun'. ```python def test_with_cov_fixture(cov): # Access the Coverage instance here ``` -------------------------------- ### Uninstall pytest-cov Source: https://github.com/pytest-dev/pytest-cov/blob/master/README.rst Uninstall pytest-cov using pip. Be aware of potential stray .pth files left from older versions. ```bash pip uninstall pytest-cov ``` -------------------------------- ### Terminal Report with Skip Covered Source: https://github.com/pytest-dev/pytest-cov/blob/master/docs/reporting.md Generates a terminal coverage report that skips files or modules that are completely covered. This can simplify the report output by hiding fully covered components. ```bash pytest --cov-report term:skip-covered --cov=myproj tests/ ``` -------------------------------- ### Append coverage data Source: https://github.com/pytest-dev/pytest-cov/blob/master/README.rst Use the --cov-append option to combine coverage data from the current test run with data from previous runs. ```bash pytest --cov-append --cov=myproj tests/ ``` -------------------------------- ### Generating Multiple Report Types Source: https://github.com/pytest-dev/pytest-cov/blob/master/docs/reporting.md Generates HTML, XML, JSON, Markdown, and LCOV reports without the default terminal output. When specific reporting options are used, the default terminal report is not automatically included. ```bash pytest --cov-report html --cov-report xml --cov-report json --cov-report markdown --cov-report markdown-append:cov-append.md --cov-report lcov --cov-report annotate --cov=myproj tests/ ``` -------------------------------- ### Reset Accumulated Coverage Sources Source: https://context7.com/pytest-dev/pytest-cov/llms.txt Clears all --cov sources accumulated so far in the argument list. Useful in addopts configurations that need to be overridden from the command line. ```bash # In pyproject.toml: addopts = "--cov=myproj" # Override at CLI: pytest --cov-reset --cov=otherproj tests/ ``` -------------------------------- ### Configure Subprocess Patch in pytest.ini Source: https://github.com/pytest-dev/pytest-cov/blob/master/docs/subprocess-support.md To enable coverage's subprocess patching, add this to your `pytest.ini` file. This setting automatically enables parallel mode. ```ini [run] patch = subprocess ``` -------------------------------- ### Enabling Subprocess Coverage Patch Source: https://context7.com/pytest-dev/pytest-cov/llms.txt Migrate from pytest-cov 6.x subprocess measurement by enabling coverage's built-in subprocess patch. This automatically enables `parallel = true`. ```ini # .coveragerc [run] patch = subprocess ``` ```toml # pyproject.toml [tool.coverage.run] patch = ["subprocess"] ``` -------------------------------- ### Combined Terminal Reports Source: https://github.com/pytest-dev/pytest-cov/blob/master/docs/reporting.md Combines the 'term-missing' and 'skip-covered' options for a terminal report. This provides detailed missing line information while still skipping fully covered files. ```bash pytest --cov-report term-missing:skip-covered --cov=myproj tests/ ``` -------------------------------- ### Configure pytest to ignore common coverage warnings Source: https://github.com/pytest-dev/pytest-cov/blob/master/CHANGELOG.rst This pytest configuration snippet sets up filters to ignore specific warnings, including SQLite ResourceWarnings and pytest-cov's own warnings. This prevents them from being raised as errors, especially when using `filterwarnings=error`. ```ini filterwarnings = [ "error", "ignore:unclosed database in 0 ``` -------------------------------- ### Terminal Report with Line Numbers Source: https://github.com/pytest-dev/pytest-cov/blob/master/docs/reporting.md Generates a terminal coverage report that includes missing line numbers. Use this to identify specific lines of code that are not covered by tests. ```bash pytest --cov-report=term-missing --cov=myproj tests/ ``` -------------------------------- ### Debugger Warning Message Source: https://github.com/pytest-dev/pytest-cov/blob/master/docs/debuggers.md This warning indicates a conflict between the debugger and coverage, as both use sys.settrace. Ensure only one tracer is active. ```default PYDEV DEBUGGER WARNING: sys.settrace() should not be used when the debugger is being used. This may cause the debugger to stop working correctly. ``` -------------------------------- ### Enforce a minimum coverage threshold Source: https://context7.com/pytest-dev/pytest-cov/llms.txt Causes pytest to exit with a non-zero status when total coverage falls below a specified minimum. The threshold can also be read from `.coveragerc`. ```bash pytest --cov=myproj --cov-fail-under=90 tests/ # On failure, pytest prints: # FAIL Required test coverage of 90% not reached. Total coverage: 87.50% # On success: # Required test coverage of 90% reached. Total coverage: 94.00% ``` -------------------------------- ### Coverage Disabled Message Source: https://github.com/pytest-dev/pytest-cov/blob/master/docs/debuggers.md This message appears when coverage has been successfully disabled using the --no-cov switch. ```default Coverage disabled via --no-cov switch! ``` -------------------------------- ### Disable Coverage with `no_cover` Fixture Source: https://github.com/pytest-dev/pytest-cov/blob/master/docs/markers-fixtures.md Inject the `no_cover` fixture into a test function to disable coverage collection for that test. This provides the same functionality as the marker. ```python def test_foobar(no_cover): # same as the marker ... ``` -------------------------------- ### Disable Coverage with --no-cov Source: https://github.com/pytest-dev/pytest-cov/blob/master/docs/debuggers.md Use the --no-cov flag to completely disable coverage when debugging is required. This prevents conflicts with debuggers. ```bash --no-cov ``` -------------------------------- ### Disable Coverage Entirely Source: https://context7.com/pytest-dev/pytest-cov/llms.txt Completely disables coverage measurement. Use this when running tests under a debugger to avoid sys.settrace conflicts. A warning is printed in the terminal summary. ```bash pytest --no-cov tests/ ``` -------------------------------- ### Ignore SQLite ResourceWarning in pytest Source: https://github.com/pytest-dev/pytest-cov/blob/master/CHANGELOG.rst Use this command-line option to suppress SQLite ResourceWarnings when running pytest. This is useful for managing common warnings that might otherwise be raised as errors. ```bash pytest -W "ignore:unclosed database in