Surfex's process (spec §18) assumes new work: a test is written, fails, and passes once the code exists, and that red→green is the evidence a relation rests on. An established project's tests already pass. They can't honestly go red, so without help every relation would need a review before Surfex reports anything useful, and again after each refactor.
adoption: in .surfex.exs decides how much of the existing suite is taken on trust
(spec §18.1).
Trust or re-evaluate
| Setting | Use it when |
|---|---|
:reevaluate (the default) | the suite is new, small, or nobody can vouch for it; or the project wants every relation earned |
:trust | the suite has been kept honest for a long time: written test-first, reviewed, run in CI on every change |
[trust: globs, reevaluate: globs] | a well-kept core beside tests nobody has read in a while |
Per area, the globs lie within tests: and don't overlap. A test matched by neither is
re-evaluated:
adoption: [trust: ["test/core/**/*_test.exs"], reevaluate: ["test/legacy/**/*_test.exs"]]Trust is a statement about the tests, so make it where you'd defend it. Re-evaluating a test later is always possible. Trusting more later is not.
The baseline
Under trust, adoption is: tag, run green, take the baseline.
# 1. Write @tag verifies: on the tests that verify each spec unit: the review work.
mix test
mix surfex.baseline --note "test-first since 2023, reviewed in every MR"
mix surfex.confirm --evidenceTag first. The baseline adopts the verifies: tags already written; it doesn't create
them, and it is one-shot. A tag added afterwards is an ordinary claim, proposed until its
test fails and passes or someone reviews it, one at a time. So the tags decide what the
baseline is worth. With none, mix surfex.baseline refuses, unless --no-tags says
you mean to baseline test versions alone and tag later at that per-tag cost. It ends by
reporting what it adopted: the trusted test versions, the verifies relations, and the
spec units left without one.
What it is. A record, per trusted test version, that the version counts as if it had
discriminated, plus that test's verifies: tags as relations with basis baseline.
confirm --evidence then carries the code each baselined test exercises (implements,
basis baseline). The note says why the suite is trusted; it stays in the log.
What it isn't.
- It isn't evidence: reports count baseline relations separately, naming the mode.
- It isn't repeatable: it is one-shot, so widening
adoption:later trusts nothing new. - It doesn't vouch for tests that aren't green at the time it is taken. Surfex refuses until they are.
From trust to evidence
The baseline only shrinks. Each relation leaves it the first time its test
discriminates for real: a run that fails and then passes against different code, at the
same test version. confirm --evidence records that red→green, and the relation moves to
basis evidence. Ordinary bug-fix work does this over time. Nothing has to be scheduled.
When the backlog should end, mix surfex.status --no-baseline (or baseline: :fail in
.surfex.exs) fails while any relation still rests on the baseline.
What changes cost afterwards
| Change | Trusted test | Re-evaluated test |
|---|---|---|
| Refactor the code, tests still green | confirm --evidence re-confirms it as baseline; no review | it needs a red→green, or a review (mix surfex.validate) |
| Edit the test | the new version isn't baselined: a red→green, or a review | the same |
| Change the spec unit | review the test against the new text, as always | the same |
| A test's first red→green | its relations move to evidence | the same |
Narrow adoption: | its baseline relations are reported unvalidated: the backlog to review | — |
| Add a test | the normal process: fails first, then passes | the same |
Trust only saves work on the most common change, a refactor under green tests. Everything else costs what it would without adoption.