Reviewing failures¶
A pytest run records every failed expect call under .xpt/. The xpt command reads that record, so you can review and accept without running the tests again.
Call sites and ids¶
Failures are grouped by call site, the expect call in the source. A call inside a loop or a parametrized test is one call site that ran several times.
Each call site has a short id such as b211. The id is a hash of the file, the function, and the call's position among the expect calls in that function, so it stays the same across runs when lines move. It gets longer, like a git short hash, when two ids collide.
Statuses¶
| Status | Meaning | Acceptable |
|---|---|---|
missing |
expect(actual) with no expected value |
yes |
mismatch |
The values differ | yes |
conflict |
The call ran more than once with different values, or the file changed during the run | no |
unsupported |
The value has a type xpt can't record, or is over 1 MB | no |
unlocatable |
xpt can't find the call in the source | no |
A conflict usually means the call needs one expect per case. A call site that you rejected also shows rejected after its status.
xpt failures¶
Lists every failed call site of the latest run with its diff, and ends with the next command.
b211 tests/test_demo.py:18 mismatch 1 test
value.items[1]: added "pear"
1 changed, 3 unchanged
ee17 tests/test_demo.py:22 missing 1 test
actual: {"status": "ok", "count": 3}
2 failures in run 20261119T150648-5031 (1 mismatch, 1 missing), 2 acceptable. Next: xpt accept b211 ee17
Plain assert failures appear in the pytest report but not here, because xpt can't write them.
xpt show ID¶
Shows one call site with its function and the tests that hit it. --full lifts the limits on how many changes and how much of each value it prints, and adds both whole values.
b211 tests/test_demo.py:18 mismatch 1 test
function: test_order
test: tests/test_demo.py::test_order
value.items[1]: added "pear"
1 changed, 3 unchanged
Next: xpt accept b211
xpt accept¶
Writes each call site's actual value into the source as its expected value.
xpt accept b211 ee17 # these call sites
xpt accept --missing # only empty expectations
xpt accept --all # every acceptable call site that was not rejected
xpt accept --dry-run b211 # report what would change, write nothing
xpt accept with no ids and no flag does nothing and says so.
Accept is careful about what it writes.
- It checks that the expected argument's text still matches the run, and refuses with
staleif you edited it since. Run the tests again to record a fresh value. - Lines added or removed elsewhere in the file don't matter.
- A second accept of the same value is a no-op and reports
already_accepted. - It rewrites each file once, through a temporary file, under
.xpt/accept.lock. The new text must compile before it is written. - It reprints the call the way
ruff formatwould at line width 100, and leaves the rest of the file byte for byte. A call with a comment inside it keeps the comment, and only the expected argument is replaced. - It refuses files that aren't UTF-8.
xpt reject¶
Use it when the diff shows a bug rather than a new expectation. It records the call site and a hash of the actual value in .xpt/decisions.jsonl. From then on, xpt failures and the pytest footer mark that call site rejected and stop suggesting xpt accept for it. --all and --missing skip it.
A rejection stops matching as soon as a run records a different value at that call site. The test keeps failing until the code is fixed. Accepting a rejected call site by its id still works.
pytest --expect-create¶
Runs the tests, then fills every missing expectation the way xpt accept --missing does. It writes after the session ends, never during it, and never replaces an existing expected value. The run still fails, because the expectations were empty when their tests ran. Run again to see them pass.
Other commands¶
xpt runslists the recorded runs, newest first. xpt keeps the last five.xpt cleandeletes.xpt/and every recorded value.--run IDonfailures,show,accept, andrejectreads an older run.
See the CLI reference for every option and exit code.