# The test database

Each test gets its own database at the latest migration, empty except for
what its fixtures create. You write nothing for this; `jadpo test` does
it.

Tests run on PostgreSQL, because every environment runs the same engine:
PostgreSQL, unless the application declares otherwise
([Stores](/docs/stores.md)).

## Where the server comes from

`jadpo test` starts a disposable local PostgreSQL server for the run, from
the PostgreSQL tools on your machine. To use a server of your own, in CI
for example, name it in `JADPO_TEST_DATABASE_URL`.

When the tests need a database and there is none to be had, because
PostgreSQL isn't installed, can't start (a sandbox with no shared memory,
say) or the named server can't be used, no test runs. The run ends in one
error, [`test.database_unavailable`](/docs/errors/test.database_unavailable.md),
marked `(human)`, with the line that says why; `--full` shows all PostgreSQL
said. Nothing in the project is wrong, so no test is reported as failing and
the last run's failures stay what `--failed` reruns. Tests that need no
database still run under `jadpo test --kind pure`.

## A copy for each test

`jadpo test` builds one template database from the migrations, and copies
it for each test (`CREATE DATABASE … TEMPLATE`). A copy takes tens of
milliseconds, and lets tests run in parallel. Copies are prepared in the
background while tests run.

## Real commits

Each test's actions commit for real. So work that runs after a commit,
such as delivering events, and the checks for concurrent changes behave
as in production.

## Keeping a failed test's database: `--keep-failed`

`--keep-failed` keeps a failed test's database, named in the report. Not
built yet: its trace, with `jadpo trace` and the developer console to
inspect exactly what it did.