Run the tests

How each repo is checked locally and in CI.

Every pull request runs the same checks in CI. Run them locally first.

Backend: 104 tests against a real Postgres 17

The tests build throwaway databases with the server’s own migration runner, so a passing run also proves the migrations work. They need a superuser on a local Postgres 17:

cd waterflow/backend
source .venv/bin/activate

# once: a disposable Postgres 17 on port 5499
docker run -d --name pgtest -e POSTGRES_HOST_AUTH_METHOD=trust -p 127.0.0.1:5499:5432 postgres:17
# later sessions: docker start pgtest

export TEST_ADMIN_URL="postgresql+psycopg://postgres@localhost:5499/postgres"
PATH=/usr/lib/postgresql/17/bin:$PATH python -m pytest -q -p no:cacheprovider tests/

Expect 119 passed (0.4.0).

Never point the tests at a database you care about They create and drop databases and logins (api_login, t_api, …) on whatever server TEST_ADMIN_URL names.

File	Covers
`tests/test_schema.py`	The database: ledger rules, RLS, roles, sharing, purge, the lock-down, temp-table tricks
`tests/test_api.py`	The API routes, the own-web-app rule, the web app’s files, timezones
`tests/test_sign_in.py`	Setup, invites, sign-in, two-factor and recovery codes, resets, the admin, rate limits, the migration runner, updates
`tests/test_backup.py`	The backup job, restoring a backup on start, and the documented restore (needs `pg_dump`, `pg_restore`, `psql` 17)

Requirements and tests maps every requirement to the test that proves it. A new requirement gets a row there (docs PR) and a test (code PR).

Web

cd waterflow/web
npm run lint && npm test && npm run build

Expect 181 passed in 34 test files (0.4.0).

npm test includes src/i18n/strings.test.ts, which fails if en.json and vi.json don’t have the same keys. Screens have component tests beside them (*.test.tsx, with Testing Library): src/test/render.tsx renders one with the app’s providers, and src/test/fakeApi.ts answers its API calls from a table and records what it sent. jsdom lays nothing out and doesn’t always behave like a browser, so check a layout or a date field in Chromium too.

The image and the stack

cd waterflow
docker compose down -v && docker compose up -d --build && docker compose logs -f waterflow

A fresh stack must come up healthy, print a setup code, and run the three daily jobs. Do this before a release (Releases).

Docs (this site)

cd waterflow-landing
npm run check && npm run build     # the docs are part of the website

What CI runs

Repo	On	Steps
waterflow	every PR, push to `dev` and `main`; before every release	backend pytest with a Postgres 17 service; web lint, test, build; `docker build` and the compose file’s validity
landing	every PR, push to `dev` and `main`	translation keys, build

Required status checks on protected branches: backend, web, image (waterflow); check (landing).