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

8.7 KiB

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.

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

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.