Testing Guide

This page covers the main automated test entrypoints used during development, with extra focus on the local Playwright end-to-end workflow.

Backend Tests

Run the backend test suite from the repository root with:

cd src/backend
pytest tests/

Frontend Unit Tests

Run the frontend unit tests with:

npm --prefix src/frontend/app run test

End-to-End Tests

The Playwright suite starts the frontend in Vite development mode and drives a real Chromium browser against the backend development stack.

Before the first local run, install the browser once:

npm --prefix src/frontend/app exec playwright install chromium

Run the full local smoke flow with:

npm --prefix src/frontend/app run test:e2e:local

test:e2e:local is the full fresh-stack entrypoint used for local smoke runs. It prepares the Docker-based backend services and then executes the Playwright suite. This mode is headless by default.

Watching the Browser Live

If you want to see what the tests are doing visually, use the fresh-stack headed entrypoint:

npm --prefix src/frontend/app run test:e2e:local:headed

This opens Chromium, resets the e2e stack first, and shows the clicks, page transitions, uploads, and other interactions while the suite runs.

If you already started a clean e2e stack yourself and only want to run the browser suite, you can still use:

npm --prefix src/frontend/app run test:e2e:headed

Use that browser-only command only against a freshly reset e2e database. The suite starts by creating the initial admin account, so reusing an existing dev database will make the first test fail.

Debug Mode

For an interactive debugging session, run:

npm --prefix src/frontend/app run test:e2e -- --debug

This opens the Playwright inspector and lets you step through actions interactively.

Notes

  • test:e2e and test:e2e:headed assume the backend development services are already running.

  • test:e2e:local and test:e2e:local:headed are the safest local entrypoints because they reset the Docker-based e2e stack for you.

  • If you run only the browser suite, MailHog must also be reachable because the e2e tests assert email-delivery flows.

  • When you start the e2e stack with docker-compose.e2e.yml, the MailHog UI is exposed on http://127.0.0.1:18025 by default.