pytest hook atlas

A visual reference for the order and nesting of pytest's hooks - captured from real pytest runs, not transcribed from prose.

Every diagram is traced with pluggy's hook monitoring, so it shows what pytest actually did: the sequence, what ran inside what, and which plugin supplied each implementation.

Want this for your own project?

These pages show pytest running scenarios chosen to be instructive. For your suite - your plugins, your conftest.py, your layout - use hook-atlas, which traces and draws any pluggy-based application and is what these diagrams are drawn with.

pip install hook-atlas
hook-atlas trace -- pytest -q tests/
hook-atlas draw          # then open hook-flow.html

It works on anything built on pluggy, not only pytest - tox and datasette included.

Scenarios

The flow genuinely changes with your project layout. Each scenario links back to the code it was traced from.

Scenario	What it shows	Releases	Distinct flows
Baseline	A plain test suite with no conftest and no plugins.	52	8
A conftest implementing every hook	What actually happens when a conftest.py implements all 52 declared hooks.	52	8
The hooks other scenarios never reach	Assertion comparison, deselection, string conditions and the debugger.	52	8
A run cut short by Ctrl-C	What pytest does when a test raises KeyboardInterrupt.	52	8
A run that dies during collection	What pytest does when a hook implementation raises.	52	8
Distributed across workers	The controller and its workers, which see completely different runs.	40	7

Every captured release - What changed between releases - Why the diagrams look like this - Changelog