Skip to content


"The pytest framework makes it easy to write small tests, yet scales to support complex functional testing for applications and libraries." -

Common args

pytest --help is a bit overwhelming, so here's a smaller reference:

  • --pdb drop to pdb when an exception is raised
  • --maxfail=N quit after this many test failures
  • --ff run previously failed tests first
  • --lf only run tests that previously failed
  • -k searchstring only run tests that have "searchstring' in them (actually more complicated matches can be done with -k)
  • -s alias for --capture=no which basically means "show output of print statements in tests"

Usage Tips

Debug failing test with pdb

This will drop you into a pdb shell when a test failure occurs.

pytest --pdb tests/test_*.py

Override test args

export PYTEST_ADDOPTS='--maxfail=1 -v --pdb'
pytest app/tests/test_*.py

Run only tests that failed on the last run

pytest --lf

Run all tests, but put the last failures first

pytest --ff

Run a specific test case

You can use python expressions to match more than one test. Each given test is substring matched against available tests. The matching logic can get pretty complicated, so see the help docs.

pytest -k 'test_this_specific_thing or that_specific_thing'

Passing args via ENV vars

You can pass args via the PYTEST_ADDOPTS ENV var. This is useful for instance if you're using make to run tests, and the command line does additional things like source files, enter a venv, or whatever.

PYTEST_ADDOPTS="--ff --maxfail=1" make test

Show your fixtures

pytest --fixtures

Show fixture setup and teardown during run

pytest --setup-show