Master pytest: Essential Command-Line Options for Efficient Testing

1. Basic Usage

The fundamental pytest command is:

pytest [options] [file_or_dir] ...

2. Common Command-Line Options

2.1 Specify test file or directory

Run a single file: pytest test_example.py Run multiple files: pytest test_example1.py test_example2.py Run an entire directory:

pytest tests/

2.2 Show detailed information

Verbose output (one level): pytest -v More verbose (debug) output:

pytest -vv

2.3 Capture output

Show standard output during tests: pytest -s Capture standard error as well:

pytest -s --capture=sys

2.4 Ignore certain tests

Ignore a single file: pytest --ignore=test_ignore.py Ignore multiple files:

pytest --ignore=test_ignore1.py --ignore=test_ignore2.py

2.5 Select specific test cases

Run a single test function: pytest test_example.py::test_add Run several test functions:

pytest test_example.py::test_add test_example.py::test_subtract

2.6 Select tests by marker

Run tests marked with slow: pytest -m slow Run tests matching a marker expression:

pytest -m "slow or long"

2.7 Control output format

HTML report:

pip install pytest-html
pytest --html=test_report.html

XML report:

pip install pytest-xunitxml
pytest --junitxml=test_report.xml

JSON report:

pip install pytest-json
pytest --json=test_report.json

2.8 Repeat failing tests

Install the rerun plugin and repeat failures three times:

pip install pytest-rerunfailures
pytest --reruns 3

2.9 Parallel test execution

Install the xdist plugin and run tests with four parallel workers:

pip install pytest-xdist
pytest -n 4

2.10 Coverage report

Install the coverage plugin and generate a coverage report for the mylib module:

pip install pytest-cov
pytest --cov=mylib

2.11 Stop after first failure

Exit on the first failing test:

pytest -x

2.12 Show help

Display all available options and commands:

pytest --help

3. Example: Combining Multiple Options

Assume a file test_example.py containing two simple tests. To see verbose output and generate an HTML report, run:

# Install required plugins
pip install pytest pytest-html
# Execute tests with verbosity and HTML report
pytest -v --html=test_report.html test_example.py

This command prints detailed test results and creates test_report.html in the current directory.

4. Summary

The article covered the most frequently used pytest command-line arguments, including how to specify files or directories, increase verbosity, capture output, ignore tests, select individual cases or markers, format reports (HTML, XML, JSON), repeat failures, run tests in parallel, generate coverage data, stop on the first failure, and view the built‑in help.