Guides

Databases, network and secrets

Postgres and Redis in tests, tests that need the internet, secrets, build steps and generated-file checks.

Databases and services

A test that needs Postgres starts it the way you would on a laptop. Install it in .land/setup.sh, and start a fresh copy inside the test command. There is no services file to write.

#!/bin/sh
# .land/setup.sh: install Postgres once, with the network on
set -e
apt-get update -qq
DEBIAN_FRONTEND=noninteractive apt-get install -y -qq postgresql
ln -sf "$(ls -d /usr/lib/postgresql/*/bin | tail -1)" /opt/pgbin
#!/bin/sh
# scripts/with-pg.sh: a fresh Postgres for one test command, then the command, then stop
set -e
PG=/opt/pgbin; DATA="$TMPDIR/pg"
$PG/initdb -D "$DATA" -A trust -U app >/dev/null
$PG/pg_ctl -D "$DATA" -o "-k $TMPDIR -c listen_addresses=''" -w -s start
trap '$PG/pg_ctl -D "$DATA" -m fast -w -s stop' EXIT
export PGHOST="$TMPDIR" PGUSER=app PGDATABASE=postgres PATH="$PG:$PATH"
"$@"
# .land/tests
# name   folder  files               command
orders   .       -                   scripts/with-pg.sh pytest -q tests/test_orders.py
api      .       tests/api/test_*.py scripts/with-pg.sh pytest -q {file}
  • Every test command gets its own fresh database, in its own process and network namespace, so two commands running side by side never see each other's data or ports.
  • The database runs inside the command, so land records what it reads too. A change to one migration reruns only the tests whose database read that migration, and the rest are carried.
  • Commands run as an unprivileged user, which Postgres requires anyway. Keep the data directory and socket in $TMPDIR, which is empty for every command.

Redis and others

Any service that runs as a normal process works the same way: install it in setup.sh, start it in the command.

# setup.sh
apt-get install -y -qq redis-server

# in the test command
redis-server --port 0 --unixsocket "$TMPDIR/redis.sock" --daemonize yes
REDIS_URL="unix://$TMPDIR/redis.sock" pytest -q tests/cache

Tests that need the internet

Commands run offline by default, which is what lets land carry them. A command that has to reach the internet says network after ;; on its line. It runs on every merge, because land can't record what it read from outside, and the verdict marks it as run online.

# .land/tests
contract  .  -  pytest -q tests/contract   ;; network
staging   .  -  npm run e2e                ;; secrets=STAGING_URL,STAGING_TOKEN

Secrets

secrets=A,B gives a command those secrets as environment variables (it implies network). The owner sets each one once. A secret is stored encrypted, given only to the lines that name it, and masked in output.

printf %s "$TOKEN" | land secret set STAGING_TOKEN   # the value on stdin, never an argument
land secret set < .env.staging                         # every NAME=value line of a .env file (land 0.3.5+)

Code an agent pushes into a command that names a secret can read that secret, exactly as in any CI. Name secrets only on the lines that need them.

Shared build steps

A line marked keep is a build step: what it writes is kept, and lines marked after=NAME see it. It is recorded and carried like a test, so the build reruns only when something it read changed.

# .land/tests
build   .         -                  pnpm run build                ;; keep
web     apps/web  src/**/*.test.ts   pnpm exec vitest run {files}  ;; after=build

Generated files are up to date

Generated code (API clients, protobufs, ORM models) drifts when someone edits the source and forgets to regenerate. Add the check as one more line. land reruns it only when something the generator read changed.

# .land/tests: fails when someone changed the schema but not the generated code
generated  .  -  make generate && git diff --exit-code

What isn't supported

Docker inside a test command, docker compose and testcontainers don't work yet. Install the service in setup.sh and start it in the command instead, as above. See Limits.