# `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
- `--full`: Show everything a report shortens
- `--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`](/docs/errors/cli.test_arguments.md): A `jadpo test` command names a path that isn't there, or a seed, a kind or a `--name` it can't use
- [`test.assertion_failed`](/docs/errors/test.assertion_failed.md): A test's `assert` doesn't hold: its condition is false, or a call checked with `assert … fails` returned or failed differently
- [`test.unexpected_failure`](/docs/errors/test.unexpected_failure.md): Test ended in a failure it did not expect
- [`test.fault`](/docs/errors/test.fault.md): Test stopped on a fault
- [`test.subscriber_failed`](/docs/errors/test.subscriber_failed.md): Subscriber failed for good during a test
- [`test.failed`](/docs/errors/test.failed.md): A test failed under `jadpo test`, or among a package's own tests under `jadpo package check`
- [`test.no_tests`](/docs/errors/test.no_tests.md): A `jadpo test` command found no test to run: the project has none, or none matches the path, line, name, kind or `--failed` it gives
- [`test.runtime_start_failed`](/docs/errors/test.runtime_start_failed.md): The tests couldn't start, because the machine couldn't give `jadpo test` the thread with a large stack they run on, usually for lack of memory
- [`test.database_unavailable`](/docs/errors/test.database_unavailable.md): The tests that need a database couldn't run, because PostgreSQL for the tests couldn't be started or reached
- [`migration.apply_failed`](/docs/errors/migration.apply_failed.md): Applying the project's migrations to a database stopped at a step that failed
- [`migration.extension_missing`](/docs/errors/migration.extension_missing.md): The project's migrations need a PostgreSQL extension, such as pgvector, that the database server doesn't offer or that the role applying them can't create
- [`migration.extension_outdated`](/docs/errors/migration.extension_outdated.md): The database server's PostgreSQL extension, such as pgvector, is older than the project's migrations and queries need
- [`toolchain.not_built_yet`](/docs/errors/toolchain.not_built_yet.md): Operation is declared but not built yet
- [`toolchain.project_not_found`](/docs/errors/toolchain.project_not_found.md): You ran a command that works on a project in a folder with no `app.jadpo`, in it or in any folder above it