Skip to main content

E2E Testing (Playwright)

End-to-end (E2E) tests open the real app in a browser and check that important flows work as expected. They complement manual checks and catch regressions early.

This page helps you find documented test flows, run automated tests when you need to, or dig into technical setup if you maintain the project.

How to use this guide​

Choose what you need:

If you want to…Go to…
Follow the same steps as the automated tests (manual walkthrough)Test scenario guides
Run the automated testsRunning the tests
Open the HTML report after a runTest report
Understand where tests run (isolated environment vs dev stack)How the test environment works
Know how we design tests (no hidden dependencies, clean data)Rules our automation follows
Prepare a machine before running testsBefore you run: checklist

Test scenario guides​

Each link opens a dedicated page with the full list of scenarios for that topic. You do not need the summaries below to be complete—open the guide when you need the step-by-step detail.

Topic
Place-related testsView guide
Login-related testsView guide
Product-related testsView guide
Catalog-related testsView guide

On each guide, start with How to read this page (plain directions). For hands-on replay, use sections titled User actions (numbered steps). Maintainers: keep those steps aligned with the automated tests when code changes.

Running the tests​

Automated tests are executed from the unpispas.nx project root. Pick the option that matches your situation.

Use this when you want a self-contained run: its own database (reset when the stack starts), app, API, and browser automation. Good for consistent results and CI-style runs.

npm install
npx playwright install
npm run test:e2e:docker

Against an already running dev stack (nx)​

Use this when nx stack is already up and you only want to point Playwright at that URL (no separate pw stack).

BASE_URL=https://app.nx.unpispas4.mywire.org/unpispas-pos/ npm run test:e2e

Manual run inside the pw stack (pick a file or browser)​

Use this when you are working inside the pw Docker setup and want one file, one browser, or Playwright UI mode.

cd docker/pw
docker compose up -d
docker compose run --rm playwright npx playwright test e2e/tests/smoke.spec.ts
# Chromium only
docker compose run --rm playwright npx playwright test --project=chromium

# Interactive UI mode
docker compose run --rm playwright npx playwright test --ui

Technical reference (paths)​

  • Test files: e2e/tests/ in the monorepo root.
  • Auth reuse: e2e/tests/auth.setup.ts saves e2e/.auth/<browser>.json per browser; main projects load it so catalog/product/place tests skip typing credentials each time. Login UI scenarios stay in login.spec.ts and run under *-login projects (no saved storage). Generated JSON files are gitignored.
  • HTML report (pw flow): under docs/e2e/report/runs/<run-id>/, indexed from docs/e2e/report/index.html when the documentation stack serves that path.

Test report​

Each time you run Playwright, the HTML report is written to a new folder: docs/e2e/report/runs/<run-id>/. Previous runs are not deleted, so you can still open an older report (for example login-only, then place-only) from the hub.

  • Hub (lists all runs): docs/e2e/report/index.html — when the documentation site is up, use View E2E report or /e2e/report/ on the doc host.
  • Latest run only (local): npm run test:e2e:report opens the most recent report in the browser.

Optional: set PLAYWRIGHT_RUN_ID=my-label for a stable folder name for that process (default is a timestamp; a marker file under the report root keeps the same id if Playwright reloads config mid-run). To force the old single-folder behaviour, set PLAYWRIGHT_HTML_REPORT to an explicit path (manifest updates are skipped).

Direct link: View E2E report — also listed under Other Resources.

How the test environment works​

In plain terms: the recommended setup runs everything in an isolated pw environment: a fresh copy of the database on startup, the POS app, the API, and the tool that drives the browser (Playwright). That way tests do not depend on whatever happened on your laptop yesterday.

The app under test talks to the pw API because the frontend loads a small configuration file generated when that stack starts.

Technical reference (pw stack)​

  • Docker setup: docker/pw
  • Typical hostnames: app.pw.* (app), api.pw.* (API) — your DNS or hosts file must resolve them to the machine running Docker.

Rules our automation follows​

These rules keep tests reliable and easy to reason about:

  • Known starting data: Tests assume a preloaded database (seed data). In the pw stack, the database is reset when the stack starts, so tests do not have to undo every change they make.
  • No ordering tricks: Each test must pass on its own, using only seed data or data it creates in that test (or in setup that runs before that test only). Do not rely on another test having run first.
  • Missing data? If the seed does not include something you need, either create it inside the test or add it to the seed so it is always there.

Before you run: checklist​

Everyone running tests should have:

  1. Reverse proxy for local HTTPS routing (docker/proxy on ports 80/443).
  2. POS app built for the stack you target (e.g. build unpispas-pos via nx / nx-dev when using nx).
  3. DNS or hosts so app.pw… and api.pw… resolve when using the pw stack.

Developers aligning backend config with pw:

  • In server/.env, set BUILD_DDBB_HOST=db and use database credentials that match docker/pw/.env.

Example: smoke test​

This is a minimal sanity check: open the app and confirm you see a real screen (login, places, or “no places”), not a blank page or hard error.

Before: The chosen stack is running and the app URL is reachable.

After: The page has a title and at least one of these is visible: login, add-place entry point, or “no places” style message. No data is intentionally changed by this check.

User-facing summary​

Confirms the application loads and shows the first meaningful screen for a user.

Technical reference (automation)​

  • Open path: /unpispas-pos/.
  • Assertions: page title non-empty; one of the main entry controls visible within about 10 seconds (as implemented in e2e/tests/smoke.spec.ts).

Quick glossary​

TermIn short
E2ETest from the user’s perspective, through the real UI.
PlaywrightTool that controls a browser to run those tests.
StackThe set of services (app + API + database, etc.) running together.
pw stackIsolated Docker stack used for E2E (docker/pw).
nx stackMain development stack; tests can target it with BASE_URL.
Seed dataFixed data loaded into the database so tests start from a known state.
User actions (in guides)Numbered steps that match what the automated test does, for manual replay.