Reference

Everything you might need to look up, in tables.

Command-line options

Option	Default	Effect
`--receptor=human`	✔ default	Unchanged pytest. The plugin registers nothing; output is byte-identical to not having it installed.
`--receptor=llm`		Compact output for a coding agent that can open the on-disk report; holds back only a pathological spread of root causes (>10). See Choosing between `llm` and `ci`.
`--receptor=ci`		The same renderer with build-log defaults: nothing held back, no on-disk report referenced, because a CI log gets one shot and the runner is gone afterwards. See Choosing between `llm` and `ci`.
`--receptor-full`	off	Expand everything: every occurrence, every message in full.
`--receptor-stats`	off	Append what this run cost against pytest as you configured it. Measured in the same run, not estimated.
`--receptor-events=PATH`	off	Stream normalized `pytest-receptor.events@1` JSONL and finalize it with integrity metadata. Requires `llm` or `ci`. See Versioned evidence artifacts.
`--receptor-events-max-bytes=BYTES`	52428800	Set the artifact’s hard total-size ceiling. Minimum 65536. Omitted events are counted and declared in the finalized stream.

What the compact profiles set on pytest

Applied on your behalf; you do not need to pass any of them.

Setting	Equivalent	Why
`verbose = -2`	`-qq`	Suppresses the progress bar and the trailing counts line.
`no_header = True`	`--no-header`	Suppresses the banner, `rootdir`, and plugin list.
`reportchars = ""`	(no flag)	Suppresses `short test summary info` without silencing other plugins.
`color = "no"`	`--color=no`	Overrides `FORCE_COLOR`, `PY_COLORS`, and an explicit `--color=yes`. Not applied while `--receptor-stats` measures a baseline, where the point is to record what pytest would really have emitted.

--tb is deliberately not set, and restricting it yourself degrades the output — see Do not restrict --tb in Usage.

Configuration file

Setting	Type	Purpose
`receptor_normalizers`	line list	`regex -> replacement` rules applied before grouping, so project-specific dynamic values do not split one root cause into many.
`receptor_rerun_command`	string	The runner each `rerun:` line starts with. Default `pytest`. Set it to match how you invoke pytest, or empty to omit the line.

[pytest]
receptor_normalizers =
    device='cuda:\d+' -> device='cuda:N'
    tmp/[a-f0-9]{8}/ -> tmp/HASH/
receptor_rerun_command = uv run pytest

Rules apply to grouping only — the message you read is the raw one. A rule that fails to compile is skipped rather than costing you the run.

receptor_rerun_command replaces only the leading pytest; the receptor still appends the selection and -q, so a configured runner reruns exactly the group it is printed under. The promise that the line works pasted verbatim holds only when this matches your invocation — a project driven by uv run pytest, hatch test, tox, or a wrapper must set it.

Session outcomes

Exactly one of these opens every run. The numeric status is always pytest’s; the label refines statuses that pytest uses for more than one state when the receptor has concrete evidence, rather than inferring success or failure from the absence of reports.

Line	Exit	Meaning
`PASS exit=0`	0	The suite ran and passed.
`FAIL exit=1`	1	Tests failed.
`INTERRUPTED exit=2`	2	The run was interrupted; counts state how much ran.
`COLLECTION_ERROR exit=2`	2	Collection failed before the suite could run.
`ERROR exit=3`	3	An internal pytest error.
`USAGE_ERROR exit=4`	4	pytest was invoked incorrectly.
`USAGE_ERROR exit=5 \| invalid selection`	5	Under xdist, pytest returned its no-tests status for an invocation containing nonexistent filesystem targets; every missing target follows.
`NO_TESTS exit=5`	5	Nothing was collected.
`RECEPTOR_ERROR`	preserved	The receptor itself failed. pytest’s status and the raw evidence follow.

A run stopped early by -x or --maxfail is additionally marked incomplete with executed and collected counts, even when nothing has failed yet.

Result categories

These follow pytest exactly, including the fact that they count phases rather than tests: a test that passes and then fails its teardown is both passed and an error.

Word	Means
`failed`	The call phase failed.
`errors`	Setup or teardown failed.
`passed`	The call phase passed.
`skipped` / `xfailed` / `xpassed`	As pytest reports them.

Anatomy of a failure group

[1] TypeError | 38 tests | setup          ← index, exception, blast radius, phase
    conftest.py:31                        ← crash location, relative to your cwd
    TypeError: 'NoneType' object is not subscriptable
    caused by: KeyError: 'atoms'          ← only when `raise X from Y`
    frames: tests/a.py:12 -> lib/b.py:41 (ext)   ← only when more than one frame
    2 other messages:                     ← variants at this same call site
      ...
    captured stdout (tests/a.py::test_x): ← only when a test printed something
      ...
    tests:                                ← only when more than one occurrence
      tests/a.py::test_x[0]
      +35 more
    rerun: pytest tests/a.py -q           ← always; selects the whole group

Other sections

Each appears only when it has something to say.

Section	Appears when
`warnings: N in M groups`	Any warning was raised. Every distinct group is listed.
`skipped: N in M groups`	Any test was skipped. Grouped by reason; `(no reason declared)` is its own group.
`xfailed: N in M groups`	Any expected failure occurred.
`unexpected passes:`	An `xfail` test passed. Named individually, with its reason.
`invalid selection:`	An xdist invocation returned exit 5 while containing explicit filesystem targets that do not exist. Every missing target is listed.
`full report: <path>`	Detail was held back, and only then.

Progress on stderr

receptor: 20% 106/530 20s
receptor: 40% 212/530 22s
receptor: 100% 530/530 67s

One line as the run crosses each twenty-percent threshold, after a silent twenty-second warm-up, ending at 100% — at most five lines however long the run takes. Thresholds already passed during the warm-up are skipped; later lines are emitted at live crossings with a percentage calculated from the count beside it. Never on stdout. Under xdist, emitted by the controller only.

Exit status

The receptor never changes pytest’s exit status — not on success, not on failure, and not when the receptor itself raises.