How to handle test failures

Dropping to pdb on failures

Python comes with a builtin Python debugger called pdb. pytest allows one to drop into the pdb prompt via a command line option:

pytest --pdb

This will invoke the Python debugger on every failure (or KeyboardInterrupt). Often you might only want to do this for the first failing test to understand a certain failure situation:

pytest -x --pdb   # drop to PDB on first failure, then end test session
pytest --pdb --maxfail=3  # drop to PDB for first three failures

Note that on any failure the exception information is stored on sys.last_value, sys.last_type and sys.last_traceback. In interactive use, this allows one to drop into postmortem debugging with any debug tool. One can also manually access the exception information, for example:

>>> import sys
>>> sys.last_traceback.tb_lineno
42
>>> sys.last_value
AssertionError('assert result == "ok"',)

Dropping to pdb at the start of a test

pytest allows one to drop into the pdb prompt immediately at the start of each test via a command line option:

pytest --trace

This will invoke the Python debugger at the start of every test.

Setting breakpoints

To set a breakpoint in your code use the native Python import pdb;pdb.set_trace() call in your code and pytest automatically disables its output capture for that test:

• Output capture in other tests is not affected.
• Any prior test output that has already been captured and will be processed as such.
• Output capture gets resumed when ending the debugger session (via the continue command).

Using the builtin breakpoint function

Python 3.7 introduces a builtin breakpoint() function. Pytest supports the use of breakpoint() with the following behaviours:

• When breakpoint() is called and PYTHONBREAKPOINT is set to the default value, pytest will use the custom internal PDB trace UI instead of the system default Pdb.
• When tests are complete, the system will default back to the system Pdb trace UI.
• With --pdb passed to pytest, the custom internal Pdb trace UI is used with both breakpoint() and failed tests/unhandled exceptions.
• --pdbcls can be used to specify a custom debugger class.