|
| 1 | +# Browser E2E (Playwright) |
| 2 | + |
| 3 | +Real-browser tests, driving the actual client + server + a real database — not |
| 4 | +mocks, not jsdom. Deliberately narrow: three flows chosen for what only a real |
| 5 | +browser + server + database can catch, not for breadth (the jsdom-based |
| 6 | +`entities.test.js` smoke tests already cover every resource page cheaply — |
| 7 | +see "What this catches that jsdom smoke tests don't" below). Wired into CI |
| 8 | +as the `e2e-tests` job in `.github/workflows/run-tests.yml`, which stands up |
| 9 | +a real MySQL service container, runs migrations, boots server + client, then |
| 10 | +runs this suite against them. |
| 11 | + |
| 12 | +## Why Playwright, and which browser it launches |
| 13 | + |
| 14 | +Some dev sandboxes this pilot runs in ship a pre-installed Chromium under |
| 15 | +`$PLAYWRIGHT_BROWSERS_PATH` (`/opt/pw-browsers`), so there's no download step |
| 16 | +there — `playwright.config.ts` points `launchOptions.executablePath` at |
| 17 | +`/opt/pw-browsers/chromium` (a stable symlink to the current versioned |
| 18 | +build) when that path exists, which avoids both a network fetch that may |
| 19 | +not be reachable in a sandbox and a redundant download of a browser that's |
| 20 | +already there. Override with `PLAYWRIGHT_CHROMIUM_PATH` if your environment |
| 21 | +installs it elsewhere. |
| 22 | + |
| 23 | +CI (and most other environments) doesn't have that path — there, |
| 24 | +`executablePath` is left unset and Playwright falls back to its own managed |
| 25 | +browser, installed by the `Install E2E deps` step's `npx playwright install |
| 26 | +--with-deps chromium`. Run that same command locally first if your |
| 27 | +environment has neither a pre-installed Chromium nor one Playwright has |
| 28 | +already downloaded. |
| 29 | + |
| 30 | +## Prerequisites: a live stack |
| 31 | + |
| 32 | +Playwright needs the client and server actually running against a real |
| 33 | +database — see the `run-without-docker` skill (`multi-repo-codespace/.github/skills/`) |
| 34 | +for the full walkthrough if you don't have Docker. Short version: |
| 35 | + |
| 36 | +```bash |
| 37 | +# 1. MySQL, once |
| 38 | +apt-get install -y mysql-server-8.0 && service mysql start |
| 39 | +mysql -u root -e " |
| 40 | + CREATE DATABASE mysql_database CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci; |
| 41 | + CREATE USER 'mysql_user'@'localhost' IDENTIFIED BY 'mysql_password'; |
| 42 | + GRANT ALL PRIVILEGES ON mysql_database.* TO 'mysql_user'@'localhost'; |
| 43 | + GRANT SYSTEM_USER ON *.* TO 'mysql_user'@'localhost'; |
| 44 | + FLUSH PRIVILEGES; |
| 45 | +" |
| 46 | + |
| 47 | +# 2. Load the schema checkpoint + remaining migrations (fast path — see |
| 48 | +# run-without-docker for the full-replay alternative) |
| 49 | +mysql -u root mysql_database < db/data.sql |
| 50 | +cd server && NODE_ENV=development yarn typeorm:run |
| 51 | + |
| 52 | +# 3. Start server and client — NODE_ENV=development is required, not optional: |
| 53 | +# server/shared/utils/bootstrap.util.ts only allows the browser's |
| 54 | +# localhost origin through CORS when NODE_ENV === 'development'. Without |
| 55 | +# it every request from the client to the API fails as a silent CORS |
| 56 | +# error in the browser (curl/supertest calls don't hit this — they don't |
| 57 | +# send an Origin header — so this is easy to miss when smoke-testing the |
| 58 | +# API directly). |
| 59 | +NODE_ENV=development MYSQL_HOST=localhost MYSQL_PORT=3306 \ |
| 60 | + MYSQL_USER=mysql_user MYSQL_PASSWORD=mysql_password MYSQL_DATABASE=mysql_database \ |
| 61 | + JWT_SECRET=jwt_secret PORT=3001 yarn start:dev # server, separate shell |
| 62 | + |
| 63 | +cd client && yarn start # client, separate shell — picks 3000, falls back if taken |
| 64 | +``` |
| 65 | + |
| 66 | +Default API URL resolution in the client (`constantsProvider.js`) is |
| 67 | +`http://<hostname>:<client-port + 1>`, so client on 3000 + server on 3001 |
| 68 | +just works with no extra client-side config. |
| 69 | + |
| 70 | +## Running |
| 71 | + |
| 72 | +```bash |
| 73 | +cd e2e |
| 74 | +yarn install |
| 75 | +yarn test # against http://localhost:3000 |
| 76 | +E2E_BASE_URL=... E2E_API_URL=... yarn test # against a different stack |
| 77 | +``` |
| 78 | + |
| 79 | +## What's covered |
| 80 | + |
| 81 | +All three specs share `tests/helpers.ts`'s `registerTestUser()` — registers a |
| 82 | +fresh user via the API (same pattern as `server/test/*-crud.e2e-spec.ts`, not |
| 83 | +seeded DB fixtures — the checkpoint dump's password hashes aren't real bcrypt |
| 84 | +hashes of any known password) — and `loginThroughUi()`, which logs that user |
| 85 | +in through the actual UI form. |
| 86 | + |
| 87 | +- `tests/login-dashboard.spec.ts` — confirms the dashboard loads after login |
| 88 | + (sidebar renders, no leftover login form, no error page). |
| 89 | +- `tests/crud-roundtrip.spec.ts` — creates, edits, and deletes a `klass_type` |
| 90 | + through the real UI, checking after each step that the change actually |
| 91 | + round-tripped through the server and database (not just that the request |
| 92 | + didn't throw). `klass_type` is used because, as a non-admin user, it only |
| 93 | + needs two plain fields (no reference-picker dropdown to drive). |
| 94 | +- `tests/export-download.spec.ts` — downloads a real Excel export and checks |
| 95 | + the file is non-empty. Exporting is gated on the user's `isPaid` flag, which |
| 96 | + nothing in the app itself can set for a fresh registration, so |
| 97 | + `tests/helpers.ts`'s `markUserAsPaid()` reaches directly into the database — |
| 98 | + setup for the flow under test, same reasoning as `registerTestUser()` |
| 99 | + reaching around the UI via the API. |
| 100 | + |
| 101 | +## What this catches that jsdom smoke tests don't |
| 102 | + |
| 103 | +Real browser rendering, real CORS/cookie/auth wiring end to end, an actual |
| 104 | +multi-page flow (form submit → redirect → authenticated data fetch → |
| 105 | +render), a create/edit/delete that really persists through the server and |
| 106 | +database instead of a mocked `dataProvider`, and a real server-generated |
| 107 | +file (the export test) — none of which a jsdom test with a mocked |
| 108 | +`dataProvider` can exercise, since there's no real server or file on the |
| 109 | +other end of the call. `entities.test.js`'s smoke tests are cheaper and |
| 110 | +catch a different, much larger class of bug (any resource crashing on |
| 111 | +mount) across every resource in the app — see that file's comments for the |
| 112 | +trade-off between the two. |
0 commit comments