Files
AndreaSlopFotografie/aidlc-docs/features/prerendering/construction/build-and-test/integration-test-instructions.md
T

119 lines
8.7 KiB
Markdown

# Integration Test Instructions
Feature: prerendering. HEAD `39dc456`; test results from CI run 599 on `2006fa0` and the test deployment of run 598 on `79b1a66`.
## Purpose
Test the interactions between the three units: the start migration and script step (unit 1, produces `dist/client`), the display fallbacks (unit 2, what the HTML shows without or before JavaScript) and the hosting and targets (unit 3, the rules that serve the files and the scripts that upload and check them). Unit tests cannot show these: they need the real build output, a real browser, a real nginx and a real lftp.
There is no service to start by hand. The browser suite (`pnpm e2e`) starts its own preview server and its own nginx, and cleans them up. In this stage no browser run was made locally; the results below are CI run 599.
```mermaid
graph TD
U1["Unit 1: prerender and script step"]
U2["Unit 2: display fallbacks"]
U3["Unit 3: server rules and deploy scripts"]
DIST["dist/client: 12 HTML files and assets"]
PREV["Preview server"]
NGINX["Real nginx 1.24"]
LFTP["Real lftp 4.9.2"]
BROWSER["Chromium via Playwright"]
TESTHOST["test.andreaslop.nl"]
U1 -->|"produces"| DIST
U2 -->|"changes HTML of"| DIST
U3 -->|"serves"| DIST
DIST --> PREV
DIST --> NGINX
DIST --> LFTP
PREV --> BROWSER
NGINX --> BROWSER
LFTP -->|"upload in CI run 598"| TESTHOST
classDef service fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
classDef client fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
classDef gateway fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
classDef external fill:#e9d5ff,stroke:#6b21a8,stroke-width:1px,color:#000;
classDef database fill:#fbd38d,stroke:#92400e,stroke-width:1px,color:#000;
class U1,U2,U3 service;
class BROWSER client;
class PREV,NGINX gateway;
class LFTP,TESTHOST external;
class DIST database;
```
Text alternative: units 1 to 3 all act on the build output `dist/client`, which the preview server, a real nginx and a real lftp consume; a Chromium browser tests the preview server and nginx, and lftp uploads to the test host.
## Test Scenarios
### Scenario 1: Unit 1 (prerendered HTML) → browser hydration
- **Description**: the prerendered HTML and the client entry must give a hydrated page without console messages or CSP violations, on every page and width, including the `404.html` case (React error #418 race found in unit 1).
- **Setup**: `pnpm build`. The suite starts `config/previewServer.ts`.
- **Test Steps**: Chromium opens every page (hydration at 390 px and other widths), waits for hydration, and records console output and CSP violations.
- **Expected Results**: no console message, no CSP violation, one title per page.
- **Files**: `e2e/hydration.e2e.ts` (48 tests), `e2e/interaction.e2e.ts` (12), `e2e/smoke.e2e.ts` (3).
- **Result (CI run 599)**: all passed.
### Scenario 2: Unit 1 (script step) → raw HTML
- **Description**: the moved scripts must leave no inline executable script, no `on*=` attribute and no `javascript:` link, and the e-mail address must be in no output file.
- **Test Steps**: fetch the raw HTML of each page and scan it.
- **Expected Results**: none of the forbidden items; the CSP stays `script-src 'self'` plus Umami.
- **Files**: `e2e/rawHtml.e2e.ts` (14 tests).
- **Result (CI run 599)**: passed.
### Scenario 3: Unit 1 + unit 2 → what shows without JavaScript and before hydration
- **Description**: with JavaScript off every page is visible, photos show through `<noscript>` twins, the menu works through `:target`, the first row of photos is eager with a preload, and `Reveal` content is visible in the HTML.
- **Test Steps**: load pages with JavaScript disabled and with it enabled at several widths; check visibility, requested images, scroll position after the menu opens, and the light-logo timing (requested once, after `load`, off the home page).
- **Files**: `e2e/displayHtml.e2e.ts` (70), `e2e/noJs.e2e.ts` (24), `e2e/noJsMenu.e2e.ts` (7), `e2e/reveal.e2e.ts` (23), `e2e/images.e2e.ts` (13).
- **Result (CI run 599)**: all passed. Chrome only: V-D4 (the no-JS menu in Firefox, Safari and Chrome on Android) is a human check, still open (see `e2e-test-instructions.md`).
### Scenario 4: Unit 3 (nginx rules) → unit 1 (build output)
- **Description**: the generated `andreaslop-test.conf` must serve the real build: pages from their files, canonical URLs by one 301, real 404 for unknown paths and for `/404` and `/404.html`, no SPA fallback, five security headers on every response including redirects, gzip for text types, and parity with the preview server on generated paths (oracle, P-HST-09).
- **Setup**: CI installs nginx (1.24.0 on the Ubuntu runner) with `policy-rc.d` so the package does not start a service. `CI=true` makes a missing nginx fail the run.
- **Test Steps**: the harness writes the generated config, runs `nginx -t`, starts a private nginx and sends requests against the fixture site and `dist/client`.
- **Files**: `e2e/serverRules.e2e.ts` (198 tests), `e2e/urls.e2e.ts` (12).
- **Result (CI run 599)**: passed. 198 tests ran against real nginx.
- **Defects this scenario found earlier** (CI runs 591 to 598, recorded in the code summaries and `audit.md`): workers as `www-data` could not read the fixture (harness permissions), map keys ignored case so `/Over-Mij` was not redirected, and `/%5Cevil.example/` produced `Location: /evil.example` (open redirect). All three were fixed and are covered by tests.
### Scenario 5: Unit 3 (server redirect) → unit 1 (router)
- **Description**: a URL the server redirects or does not know, which the router might still render, must give one 301 or a 404 with one title and one `noindex`, and `?pakket=` queries must survive the redirect.
- **Files**: `e2e/urls.e2e.ts`, `e2e/hydration.e2e.ts`.
- **Result (CI run 599)**: passed.
### Scenario 6: Unit 1 (artifact) → unit 3 (deploy scripts)
- **Description**: `check-artifact.sh` accepts a valid `dist/client` and refuses an invalid one before anything is uploaded; `upload-production.sh` uploads in rounds (all but HTML, then HTML, then stale files removed) with real lftp, leaves no `~` backup files, and refuses unsafe target folders; `verify-deployment.sh` passes against correct rules and fails against the old SPA behaviour and per missing header.
- **Test Steps**: run the scripts against a local `file:` target with lftp 4.9.2 and against stub servers.
- **Files**: `e2e/deployScripts.e2e.ts` (47 tests).
- **Result (CI run 599)**: passed. Not tested: FTPS against a real host.
- **Defect found earlier**: run 598 showed a stray `web.config` backup. Cause: `upload-production.sh` held its body twice since commit `6d4d012`. Fixed in `2006fa0` (duplicate removed, lftp backups turned off).
### Scenario 7: The deployed test environment
- **Description**: the real chain: CI `check` → artifact → check-artifact → lftp upload → `verify-deployment.sh --test` against `https://test.andreaslop.nl`.
- **Setup**: the owner placed the new nginx config on the Pi first (`construction/hosting-and-targets/infrastructure-design/pi-install-instructions.md`).
- **Result (run 598, commit `79b1a66`)**: deployed to test with the post-deploy check green. The main session's curl checks on `https://test.andreaslop.nl`:
- pages return 200;
- `/over-mij/`, `/Over-Mij`, `/over-mij.html` and `/index.html` return 301;
- `/bestaat-niet`, `/404`, `/404.html` and `/%5Cevil.example/` return 404;
- gzip on HTML and JS (main bundle 547,302 bytes, 155,603 bytes over the wire);
- security headers present;
- no e-mail address in the HTML of `/over-mij`.
- Later commits (`2006fa0` and the document commits) changed only the upload script, tests and documents, so the deployed site is unaffected.
- **Pi nginx version**: the Pi runs nginx 1.30.6; CI proves 1.24.0. Pi-Main checked the config on 1.30.6 without root (`nginx -t` level); see `pi-install-instructions.md`.
## Run Integration Tests
### 1. Execute the Browser Suite
```bash
cd web
pnpm build
pnpm e2e
```
Locally the nginx and lftp suites are skipped when the tools are missing. In CI (`CI=true`) a missing nginx fails the job. To get the CI result, dispatch the workflow; the `lighthouse` job runs `pnpm e2e` after installing nginx and lftp.
### 2. Verify Interactions
- **Expected**: 12 files, 471 tests, 0 failures in CI (run 599: `Test Files 12 passed (12)`, `Tests 471 passed (471)`, 727 s on the Pi runner). Locally without nginx and lftp: 248 passed, 204 skipped (last local full run, unit 3 Step 21).
- **Logs Location**: the CI log of the `lighthouse` job, step "Browsertests"; a local run prints to the terminal.
### 3. Cleanup
The harness stops the preview server and nginx and removes its temporary folders. Nothing is left running. If a run is killed, check for a stray `nginx` process and for port 4173.