# `jadpo test`

Run tests.

Run the project's tests in the interpreter, in an order a seed decides, and report each failure with the values in its assertion, what happened instead and the command that reruns it. Without a path, the project is found by walking up to app.jadpo and every test runs; a file runs its tests, a folder the tests under it, and <file>:<line> the test at that line. The project must check without errors first. With --watch, it keeps running: each save reruns the tests the change reaches, through the compiler's graph, within the path, name and kind given. Every recording of the app's own integrations in shared/providers/ is read by its operation's decoders as a test of its own.

```text
jadpo test [path]
```

## Arguments

- `path` (optional): A test file, <file>:<line>, or a folder

## Flags

- `--name <text>`: Run tests whose names contain this text
- `--kind <kind>`: Run one kind, such as pure or recording
- `--failed`: Rerun the tests that failed last time
- `--seed <n>`: Run in the order this seed gives
- `--watch`: Rerun the tests each save reaches
- `--keep-failed`: Keep a failed test's database to inspect

## On every command

- `--json`: Print data for tools instead of text
- `--help`: Show every flag, with examples
- `--color <when>`: Choose when to use colour

`jadpo test --json` writes one JSON document to standard output instead of text, with the same exit code. The document has `schemaVersion`, `command` (`"test"`), `ok`, `data` (what the command produced, `null` when it failed) and `diagnostics` (each error with its `rule`, `reason`, `next` and `help`). A command that needs a terminal refuses `--json` and names the flags that do the same job.

## Examples

```text
# Run every test in the project you are in
jadpo test
# Run the test at line 12 of a file, in the order seed 48213 gives
jadpo test domains/planning/libraries/dates.test.jadpo:12 --seed 48213
# Rerun the tests that failed last time
jadpo test --failed
# Rerun the tests each save reaches, until ctrl-c
jadpo test --watch
# Print the results as data for tools
jadpo test --json
```

## Errors

- [`cli.test_arguments`](../errors/cli.test_arguments.md): Test command has invalid arguments
- [`test.assertion_failed`](../errors/test.assertion_failed.md): Test assertion does not hold
- [`test.unexpected_failure`](../errors/test.unexpected_failure.md): Test ended in a failure it did not expect
- [`test.fault`](../errors/test.fault.md): Test stopped on a fault
- [`test.subscriber_failed`](../errors/test.subscriber_failed.md): Subscriber failed for good during a test
- [`test.failed`](../errors/test.failed.md): Test run failed
- [`test.no_tests`](../errors/test.no_tests.md): No tests to run
- [`test.runtime_start_failed`](../errors/test.runtime_start_failed.md): Test runtime could not start
- [`toolchain.not_built_yet`](../errors/toolchain.not_built_yet.md): Operation is declared but not built yet
- [`toolchain.project_not_found`](../errors/toolchain.project_not_found.md): Project could not be found