# `mix surfex.test`
[🔗](https://github.com/dcoai/surfex/blob/v0.10.0/lib/mix/tasks/surfex.test.ex#L1)

Runs a requirement's tests as surfex reads them (`Surfex.Select`, §11): every test whose
`verifies:` declarations resolve to the unit, a list's members included.

    mix surfex.test cart-add                 # the tests declaring it
    mix surfex.test spec.md#carts --within   # and those of the units inside it
    mix surfex.test cart-add --list          # name them; run nothing
    mix surfex.test cart-add -- --trace      # what follows `--` goes to mix test
    mix surfex.test --deviations             # every deviation test, skips included
    mix surfex.test plat-3 --checks          # and the checks verifying it

`mix test --only verifies:cart-add` selects a test tagged `["cart-add", "carts"]` by
neither id: ExUnit compares a list tag as one string. This task selects by declaration
and runs `mix test FILE:LINE …` in a child process, which ExUnit's location filter
selects exactly, then exits with that run's status. The run records its evidence as any
run does. Each unit is any reference a tag may use. A unit that is unknown, ambiguous,
or that no test declares is an error before anything runs.

`--deviations` runs every test that declares a deviation (`@tag deviation: "#119"`,
`Surfex.Select.deviations/1`) instead of a unit's, each by `--only location:FILE:LINE`
and its skip reason by `--include skip:REASON` (`Surfex.Select.deviation_args/1`), so
the skip beside the tag doesn't keep it from running and no other test runs. Its
evidence then says whether any passes: `mix surfex.status --evidence` fails a passing
one as a stale deviation. It takes no unit. None to run, another test in their files
skipped for a deviation test's reason, or a skip reason that isn't a literal, is an
error before anything runs.

A unit may also be verified by declared checks (`checks:`, §11.4). `--list` names them
after the tests, and a run says which there are. `--checks` runs them too, after the
tests, recording their evidence as `mix surfex.check` does (§17.1); the task fails if
either the tests or a check fail. With `--checks`, a unit only checks verify is no
error.

---

*Consult [api-reference.md](api-reference.md) for complete listing*