Adds the build and test documents of the prerendering feature

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-03 18:12:22 +01:00
co-authored by Claude Opus 5.5
parent 39dc456946
commit 0970c24108
8 changed files with 485 additions and 4 deletions
@@ -0,0 +1,76 @@
# Build and Test Summary
Feature: prerendering. Branch `feature/prerendering`, worktree `AndreaSlopFotografie-prerendering`.
Verified at HEAD `39dc456`. The code is that of `2006fa0` (CI run 599); later commits change only `aidlc-state.md` and `audit.md`.
In this stage no build and no Lighthouse run was made. `pnpm test` was run once (exit 0). The other results come from CI runs 598 and 599, the main session's checks on the test site, and the measurement reports.
## Build Status
- **Build Tool**: pnpm 12.11.2, `tsc && vite build && node config/externalizeInlineScripts.ts` (Node v24.16.0)
- **Build Status**: Success (the `check` job of CI run 599 is green: lint, format, unit tests, build, audits)
- **Build Artifacts**: `web/dist/client/` (12 HTML files, `sitemap.xml`, assets with the moved scripts; deployed) and `web/dist/server/` (not deployed)
- **Main bundle**: 547,302 bytes raw, 155,603 bytes gzip over the wire (test server)
- **Build Time**: not recorded in this stage
## Test Execution Summary
### Unit Tests
- **Total Tests**: 1390 in 132 files (code summary of unit 3; baseline on master 888 in 113 files)
- **Passed**: all; `pnpm test` at HEAD exited 0 in this stage. The "Tests" line was not captured (output read through `tail`), so the count is the code summary's figure.
- **Failed**: 0
- **Coverage** (v8, this stage): statements 96.1%, branches 94.5%, functions 97.36%, lines 96.6%; thresholds met
- **fast-check seed**: printed on every run (`config/testSeed.ts`); replay with `FC_SEED=<seed> pnpm test`
- **Status**: Pass
- **Details**: `unit-test-instructions.md`
### Integration Tests (browser suite, `pnpm e2e`)
- **Test Scenarios**: 7 (hydration, raw HTML, display fallbacks, nginx rules against the build, server redirect against router, deploy scripts, deployed test site)
- **Passed**: 471 of 471 tests in 12 files (CI run 599), including 198 against real nginx 1.24 (`serverRules.e2e.ts`) and 47 deploy-script tests with the real lftp cases (`deployScripts.e2e.ts`)
- **Failed**: 0
- **Local run before CI**: 248 passed, 204 skipped (nginx and lftp suites skipped on the PC), 0 failed
- **Status**: Pass
- **Details**: `integration-test-instructions.md`
### Performance Tests
- **Reference measurement** (author's PC, 3 runs, median, commit `6d4d012`, not re-run): mobile 0.85 to 0.97 on the 12 URLs (master 0.75 to 0.91); desktop 0.99 or 1.00. Every URL meets its target (`/` exactly at 0.85). Accessibility 1, best practices 1.
- **CI run 599** (Pi runner, 1 run): performance mobile 0.47 to 0.66 and desktop 0.71 to 0.81, all warnings, by design (warn-only on the Pi). Accessibility, best practices and SEO assertions pass.
- **Status**: Pass against the reference measurement; CI performance is warn-only and not comparable.
- **Details**: `performance-test-instructions.md`
### Additional Tests
- **Contract Tests**: N/A (no API; static site)
- **Security Tests**: Pass for the production audit, headers, redirects and deploy-script checks. Development audit: advisories in tools only, non-blocking (23 at unit 3 Step 21). IIS and FTPS unverified. Details: `security-test-instructions.md`.
- **E2E Tests**: Automated suite passes (above). Human check V-D4 (no-JS menu in Firefox, Safari, Chrome on Android) is open. Details: `e2e-test-instructions.md`.
## Test site check (run 598, commit `79b1a66`)
Deployed to `test.andreaslop.nl` with the post-deploy check green, after the owner placed the new nginx config first. Curl checks by the main session: pages 200; `/over-mij/`, `/Over-Mij`, `/over-mij.html`, `/index.html` give 301; `/bestaat-niet`, `/404`, `/404.html`, `/%5Cevil.example/` give 404; gzip on HTML and JS; security headers present; no e-mail address in the HTML of `/over-mij`. Pi-Main checked the config on nginx 1.30.6 without root.
## Defects found by the test stages (all fixed)
CI runs 591 to 598 found and fixed: a hydration test race, a case-insensitive nginx `map` key (`/Over-Mij`), an open redirect through `%5C`, harness permissions when nginx runs as root, the PC runner (no `policy.json`, run 597), and a duplicated upload script (run 598). Details are in the code summaries and `audit.md`.
## Extension Compliance
### Property-Based Testing (full enforcement)
| Rule | Status | Note |
|---|---|---|
| PBT-08 (shrinking and reproducibility; applicable at this stage) | Compliant | Seed printed on every run and replayable (`FC_SEED`); no shrink override found; both CI jobs log a seed; PBT is in CI |
| PBT-01 to PBT-07, PBT-09, PBT-10 | Not re-evaluated | Evaluated at Functional Design and Code Generation (properties P1 to P25 and P-HST-01 to 11 are listed in the code summaries); outside this stage's scope |
### Security Baseline
Compliant where applicable: SECURITY-04, 09, 10, 11, 13, 15; others N/A for a static site. Unverified: IIS rules, FTPS against a real host. See `security-test-instructions.md`.
## Overall Status
- **Build**: Success
- **All Tests**: Pass (471 of 471 browser tests in CI, unit suite green)
- **Ready for Operations**: N/A (Include Operations Phase = No, `aidlc-state.md`)
## Open Items
1. **V-D4**: the no-JS menu in Firefox, Safari and Chrome on Android. Human task for the owner, on the test site.
2. **IIS**: the rules are generated text and unverified; there is no host yet. `deploy-production` stays dispatch-only.
3. **FTPS** against a real host is untested; lftp is proven against a local `file:` target only.
4. **nginx 1.30.6 on the Pi**: CI proves 1.24.0; the config was checked on 1.30.6 without root.
5. **Lighthouse**: `/` sits exactly at its 0.85 target with `numberOfRuns: 1`, so a slow local run can fail `pnpm check`. zwangerschap and portret keep a 0.85 target because one run is unreliable at 0.90. Responsive photos are the planned fix for the exceptions.
6. **PC runner**: stopped (missing `policy.json`). Restart with `podman start gitea-runner`; the cause is open.
7. **Repository access**: the repository appears to be anonymously readable from the Pi. To be checked by the owner.
## Next Steps
Build and test passes. Operations is not included, so the workflow completes after this stage once the owner has reviewed the open items above.
@@ -0,0 +1,63 @@
# Build Instructions
Feature: prerendering (branch `feature/prerendering`, worktree `AndreaSlopFotografie-prerendering`).
Verified at HEAD `39dc456`. Only documents changed since `2006fa0`, the commit CI run 599 built (`git diff --stat 2006fa0 HEAD` lists `aidlc-state.md` and `audit.md` only). No build was run in this stage; the build facts come from CI run 599, the test deployment (run 598) and the code summaries.
## Prerequisites
- **Build Tool**: pnpm 12.11.2 (`packageManager` in `web/package.json`), run from `web/`. Vite with TanStack Start (prerender), TypeScript (`tsc` runs first).
- **Runtime**: Node.js v24.16.0 (the version of the measurements and the local runs).
- **Dependencies**: installed from `web/pnpm-lock.yaml` only (`pnpm install --frozen-lockfile`). The `postinstall` hook runs `chakra typegen ./src/theme.ts`. The feature added exact pins for `@tanstack/react-start` 1.169.4 and `@tanstack/react-router` 1.170.46, a pin for `playwright-core` 1.55.0, and a `zod@4` override (`^4.6.6`) in `pnpm-workspace.yaml` (unit 1 code summary, deviations 1 and 2).
- **Environment Variables**:
- `VITE_RELEASE`: set by CI to the commit SHA for Sentry. Not needed locally.
- `FC_SEED=<seed>`: replays a fast-check run (see `unit-test-instructions.md`).
- `CI=true`: makes a missing nginx fail the browser tests instead of skipping the nginx suites (BR-HST-24).
- `LIGHTHOUSE_PERFORMANCE=warn`, `LIGHTHOUSE_CHROME_FLAGS`: Lighthouse only (see `performance-test-instructions.md`).
- **System Requirements**: Windows 11 with Git Bash, or the Ubuntu CI container. The browser tests need Chromium (Playwright 1.55.0). The nginx and lftp suites need `nginx` and `lftp` installed. The CI job installs both; the author's PC has neither, so those suites are skipped there.
## Build Steps
### 1. Install Dependencies
```bash
cd web
pnpm install --frozen-lockfile
```
Expected: lockfile up to date, exit 0. In CI run 599 the install also printed `Lockfile passes supply-chain policies (910 entries)`.
### 2. Configure Environment
No configuration is needed for a local build. Do not create `.env` files.
### 3. Build All Units
```bash
cd web
pnpm build
```
`pnpm build` is `tsc && vite build && node config/externalizeInlineScripts.ts`. The three steps cover all three units together:
- Unit 1 (start migration): Vite builds a client and a server environment and prerenders one HTML file per page.
- Unit 1 (script step): `externalizeInlineScripts.ts` moves every inline executable script into `/assets/inline-<hash>.js` and fails the build if an inline script, an `on*=` attribute or a `javascript:` link remains.
- Units 2 and 3 are code and generated text inside the same build (no extra build step). The generated server files `web/deploy/nginx/andreaslop-test.conf` and `web/deploy/iis/web.config` come from `web/config/serverConfig.ts`; a unit test checks that the committed files equal the generator output.
### 4. Verify Build Success
- **Expected Output**: exit 0. At its Step 31 unit 1 reported "12 pages, 16 scripts moved (28 files written), no violations".
- **Build Artifacts** (gitignored):
- `web/dist/client/`: 12 HTML files (11 pages and `404.html`), `sitemap.xml`, and all assets including the moved scripts. This folder is the CI artifact `dist` and is what gets deployed.
- `web/dist/server/`: a sibling folder, not deployed.
- **Main bundle** (measured on the test server after run 598): 547,302 bytes raw, 155,603 bytes over the wire with gzip.
- **Common Warnings**: Vite's chunk-size warning (main bundle above 500 kB), as on master. Accepted.
## Troubleshooting
### Build Fails with Dependency Errors
- **Cause**: lockfile out of date, or `node_modules` from another branch (this feature changed `package.json` and the lockfile).
- **Solution**: run `pnpm install --frozen-lockfile` again. Do not change the lockfile in this stage; report the failure with its output.
### Build Fails with Compilation Errors
- **Cause**: `tsc` errors. `src/routeTree.gen.ts` is generated by the TanStack plugin.
- **Solution**: read the first `error TS` line. If it is in `routeTree.gen.ts`, run `pnpm exec vite build` once to regenerate it, then `pnpm build`. Do not hand-edit the generated file.
### Build Fails in the Script Step
- **Cause**: `externalizeInlineScripts.ts` found an inline executable script, an `on*=` attribute or a `javascript:` link in a prerendered page.
- **Solution**: the error names the file. Remove the inline code from the component. The CSP (`script-src 'self'` plus Umami) must not be loosened.
### Browser Tests Cannot Find `dist/client`
- **Cause**: `pnpm e2e` runs against the build output.
- **Solution**: run `pnpm build` first.
@@ -0,0 +1,32 @@
# End-to-End Test Instructions
Feature: prerendering. HEAD `39dc456`.
## Purpose
The automated end-to-end suite is `pnpm e2e` (Chromium through Playwright, 12 files, 471 tests); its results and scenarios are in `integration-test-instructions.md`. This file covers what the suite cannot: browsers other than Chrome, and a person looking at the test site. Run it after the deploy-test job (done in run 598).
## Environment
- **Target**: `https://test.andreaslop.nl` (deployed from commit `79b1a66`, run 598).
- **Browsers**: Firefox, Safari, Chrome on Android (the missing ones), plus desktop Chrome or Edge for a quick look.
## Test Steps
### 1. Menu without JavaScript (V-D4) - open, human task for the owner
Why: the menu works through `:target` links when JavaScript is off. Chrome keeps the scroll position when the menu opens (verified in the suite); other browsers may jump.
1. Turn JavaScript off in the browser (Firefox: `about:config`, `javascript.enabled` false; Safari: Develop menu; Chrome on Android: Site settings).
2. Open `https://test.andreaslop.nl/` on a narrow screen (mobile width) and open the menu.
3. Expected: the menu opens, the page does not jump to the top, the sub-links of "Soorten fotoshoots" are reachable, and the menu closes again.
4. Repeat on `/over-mij` and `/soorten-fotoshoots/newborn`.
5. Report the browser and what happened. Status in this stage: **not done** (needs a person).
### 2. Pages look right with JavaScript on
Open `/`, `/over-mij`, `/portfolio`, `/soorten-fotoshoots`, one shoot page and `/contact`. Expected: no empty gaps where photos load, no flash of the light logo when navigating to `/` after the page has loaded, the contact form appears (it is revealed by a moved script), the e-mail address appears in the contact details after load.
### 3. Pages are readable without JavaScript
With JavaScript off, every page above shows its text and photos; the contact form is not usable without JavaScript, which FR-PR-13 allows.
### 4. URLs (spot check; curl already done in run 598)
In a browser: `/over-mij/` and `/Over-Mij` end up on `/over-mij`; `/bestaat-niet` shows the 404 page with the site layout.
## Results in this stage
Steps 2 to 4 are covered by the automated suite and the main session's curl checks (see `integration-test-instructions.md`, scenario 7). Step 1 is the only open human check.
@@ -0,0 +1,118 @@
# 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.
@@ -0,0 +1,90 @@
# Performance Test Instructions
Feature: prerendering. Lighthouse was **not run** in this stage. Two sets of figures exist and they must not be mixed:
- **Reference measurement** (`construction/hosting-and-targets/code/measurement-final.md`): 3 runs per URL, median, on the author's PC, commit `6d4d012`, 2026-11-01. This is where scores can be compared with master.
- **CI run 599** (commit `2006fa0`, Pi runner, 1 run per URL): scores are much lower and only warn. They are not comparable with the reference measurement.
## Purpose
Check the Lighthouse budgets of the 12 URLs with the three units combined. This is a static site: there is no load or stress test, because there is no server-side work to load. The goal of the feature is faster first paint and better SEO by serving prerendered HTML (NFR-PR-P-01 to P-04).
## Performance Requirements
Targets after the owner's decisions of 2026-11-01 (`web/lighthouserc.cjs`, each URL matches exactly one entry):
| URL | Mobile target |
|---|---|
| `/` | 0.85 (raised from 0.8; kept at the current score until responsive photos) |
| `/soorten-fotoshoots/zwangerschap`, `/gezin`, `/loveshoot`, `/portret` | 0.85 |
| All other indexed pages and the not-found page | 0.9 |
- **Desktop** (`lighthouserc.desktop.cjs`): 0.9 on all 12 URLs.
- **Accessibility, best practices**: 1 on every URL. **SEO**: 1 on indexed pages; `/privacyverklaring` and the not-found page deliberately fail `is-crawlable` (noindex).
- `numberOfRuns` is 1.
## Setup Performance Test Environment
### 1. Prepare Test Environment
- Build first (`pnpm build`). Lighthouse runs against the built site through `config/previewServer.ts`, started by Lighthouse CI with `--audit-route` (the not-found page is audited at `/__audit/404`, because Lighthouse refuses a page with status 404 and `/404.html` is a real 404 now).
- Port 4173 must be free (`--strictPort`).
- Chrome must be installed. In the CI container Chrome needs `LIGHTHOUSE_CHROME_FLAGS='--no-sandbox --headless=new --disable-dev-shm-usage'`.
### 2. Configure Test Parameters
- **Strictness**: locally `LIGHTHOUSE_PERFORMANCE` is unset, so a performance miss fails the run. In CI it is `warn`.
- **Reports**: `web/lighthouse-reports/mobile/` and `.../desktop/` (HTML and JSON); the CI job uploads them as artifact `lighthouse-reports` (50 files, 14 days).
## Run Performance Tests
### 1. Execute Lighthouse (mobile and desktop)
```bash
cd web
pnpm build
pnpm lighthouse
```
`pnpm lighthouse` is `lhci autorun && lhci autorun --config=lighthouserc.desktop.cjs`. For a more reliable local reading use 3 runs: `pnpm exec lhci collect --numberOfRuns=3` per preset, and compare medians.
### 2. Execute the Gate
```bash
cd web
pnpm check
```
Runs lint, format, tests, build, browser tests, both audits and Lighthouse. `/` sits exactly at its 0.85 target with one run, so a slow local run can fail `pnpm check`.
### 3. Analyze Performance Results
**Reference measurement** (author's PC, 3 runs, median; master / after unit 1 / final):
| URL | Mobile score master / unit 1 / final | Mobile LCP ms master / final | Target | Status |
|---|---|---|---|---|
| `/` | 0.75 / 0.85 / 0.85 | 4293 / 4357 | 0.85 | pass, exactly at target |
| `/over-mij` | 0.86 / 0.90 / 0.92 | 3535 / 3233 | 0.9 | pass |
| `/portfolio` | 0.90 / 0.94 / 0.93 | 2926 / 3232 | 0.9 | pass |
| `/soorten-fotoshoots` | 0.85 / 0.89 / 0.92 | 3750 / 3306 | 0.9 | pass |
| `.../newborn` | 0.85 / 0.90 / 0.91 | 3525 / 3457 | 0.9 | pass |
| `.../zwangerschap` | 0.84 / 0.88 / 0.90 | 3676 / 3606 | 0.85 | pass |
| `.../gezin` | 0.84 / 0.88 / 0.89 | 3678 / 3681 | 0.85 | pass |
| `.../loveshoot` | 0.82 / 0.86 / 0.88 | 3768 / 3831 | 0.85 | pass |
| `.../portret` | 0.84 / 0.89 / 0.90 | 3673 / 3606 | 0.85 | pass |
| `/contact` | 0.87 / 0.94 / 0.94 | 3345 / 3007 | 0.9 | pass |
| `/privacyverklaring` | 0.90 / 0.96 / 0.96 | 2844 / 2780 | 0.9 | pass |
| Not found | 0.91 / 0.97 / 0.97 | 2603 / 2630 | 0.9 | pass |
- FCP on mobile fell from about 2.5 to 2.7 s (master) to about 1.36 s (final) on every page; TBT from 114 to 293 ms to 61 to 75 ms. CLS stays at 0.021 or lower.
- Desktop: 0.99 or 1.00 on all 12 URLs.
- Accessibility 1 and best practices 1 on every URL, all runs; SEO 1 on the ten indexed pages.
- `lhci assert` on these reports (36 mobile and 36 desktop): all 12 URLs pass in both presets.
- LCP itself did not improve on every page (for example `/` 4293 to 4357 ms, gezin and loveshoot slightly later); the score gain comes from FCP and TBT.
**CI run 599** (Pi runner, 1 run, warnings only, the job succeeded):
- Mobile performance 0.47 to 0.66 on the 12 URLs (`/` 0.49, `/over-mij` 0.53, `/portfolio` 0.61, gezin 0.47, `/privacyverklaring` 0.66, not found 0.59). Every URL warned.
- Desktop performance 0.71 to 0.81 on the 12 URLs (`/` 0.71, `/privacyverklaring` 0.8, not found 0.81). Every URL warned.
- The workflow comment says performance on the Pi is not representative (CPU slowdown on a slow machine); that is the reason it only warns there. These numbers say nothing about the feature and are not a regression against the PC figures. They also cannot show an improvement.
- Accessibility, best practices and SEO assertions: passed (no error reported; the job succeeded).
**Bundle**: main bundle 547,302 bytes raw, 155,603 bytes gzip on the wire (test server, after run 598). Master's figure was not re-measured in this stage.
**Results Location**: `construction/hosting-and-targets/code/measurement-final.md` (and `measurement-baseline.md`, `measurement-gate.md`, `measurement-display.md` in the other units' folders); CI artifact `lighthouse-reports` of run 599.
## Performance Optimization
Open items (owner decisions already recorded; nothing to fix in this stage):
1. `/` is exactly at 0.85 with `numberOfRuns: 1`; responsive photos are the planned way to remove the exceptions of `/`, gezin and loveshoot.
2. zwangerschap and portret score 0.90 and keep a 0.85 target only because one run is unreliable near 0.90.
3. Production compression was not part of the PC measurements (they ran with gzip on the preview server). The test server sends gzip, as the curl checks show.
@@ -0,0 +1,66 @@
# Security Test Instructions
Feature: prerendering. HEAD `39dc456`; CI run 599 on `2006fa0`.
## Purpose
Check the dependencies, the HTTP security headers, the redirect and path handling of the server rules, and the no-inline-script rule of the prerendered HTML. The Security Baseline extension is enabled (`aidlc-state.md`, Extension Configuration: Security Baseline = Yes). The per-rule tables are in `construction/hosting-and-targets/infrastructure-design/infrastructure-design.md` § 15 and the business rules of units 1 and 2.
## Security Test Scope
- **Dependency audit (production)**: `pnpm audit:deps` (`pnpm audit --prod --audit-level high`), blocking. It is a step of the CI `check` job, which was green in run 599.
- **Dependency audit (development tools)**: `pnpm audit:dev`, non-blocking by design (NFR-SEC-05, the script ends with an `echo` fallback).
- **No inline executable script**: `externalizeInlineScripts.ts` fails the build on an inline script, an `on*=` attribute or a `javascript:` link; `e2e/rawHtml.e2e.ts` re-checks the raw HTML. The CSP (`script-src 'self'` plus Umami) is unchanged by this feature.
- **E-mail address not in the output**: the address is in no output file (the script runner checks it); the main session confirmed no address in the HTML of `/over-mij` on the test server.
- **Server rules**: security headers on every response, open redirect, path traversal, directory listing.
- **Deploy scripts**: unsafe target folders, invalid artifact, fail-closed verification.
- **Raw HTML injection**: `grep -rn "dangerouslySetInnerHTML" src config public`.
## Run Security Tests
### 1. Dependency Audits
```bash
cd web
pnpm audit:deps
pnpm audit:dev
```
- **`pnpm audit:deps`**: passed in the `check` job of CI run 599 (the job is green, the step is blocking). No new production dependency was added by unit 3; unit 1 added `@tanstack/react-start` and its tree, with the `zod@4` override against GHSA-mrhx-c7xc-m3w5.
- **`pnpm audit:dev`**: the figures differ by unit and were not re-run in this stage. Unit 1: the same severity counts as master (low 2, moderate 10, high 11, critical 0). Unit 3 Step 21: 23 advisories, non-blocking. Findings are in development tools only and not in the shipped bundle.
- **Result**: production audit pass; development audit reports advisories (non-blocking, as on master).
### 2. Security Headers, Redirects and Paths (real nginx)
```bash
cd web
pnpm e2e
```
In CI run 599, `e2e/serverRules.e2e.ts` (198 tests, real nginx 1.24.0) and `e2e/urls.e2e.ts` (12) passed. They check:
- the five security headers on 200, 301, 404 and the 404 page (SECURITY-04), including the server-level `if` redirects;
- exactly one `Cache-Control` per response;
- an open redirect cannot be built: `//evil.example/` and `/%5Cevil.example/` are tested (BR-HST-06); `/%5Cevil.example/` gives 404 and no `Location` to another host. The `%5C` case was a real defect in the first generator (`Location: /evil.example`), found by this suite in CI and fixed;
- no directory listing, no `index` fallback to the home page, `/assets` is not served as a directory (BR-HST-07);
- the preview server and nginx answer the same on generated paths (P-HST-09).
On the test server (run 598, curl checks by the main session): security headers present, `/%5Cevil.example/` returns 404, no e-mail address in `/over-mij`.
Not verified: the IIS rules (generated text only, no host), and nginx 1.30.6 on the Pi beyond Pi-Main's check of the config without root (`pi-install-instructions.md`). The Pi sends `Server: nginx/<version>`; `server_tokens` is a Pi-level setting outside the generated file.
### 3. Deploy Script Checks
`e2e/deployScripts.e2e.ts` (47 tests, passed in run 599) covers: refusal of unsafe target folders and of an invalid build before anything is uploaded, TLS requirements and no backup files in every lftp session, `verify-deployment.sh` failing on each missing security header and on the old SPA behaviour. Not tested: FTPS against a real host (login, certificate, directory layout).
### 4. Raw HTML Injection Check
```bash
cd web
grep -rn "dangerouslySetInnerHTML" src config public
```
- **Expected**: one code use, the JSON-LD script of `StructuredData`.
- **Verified at HEAD** (this stage): `src/components/StructuredData/StructuredData.tsx:15` (`dangerouslySetInnerHTML={{ __html: jsonLdScript(data) }}`, escaping `<`, `>` and `&`) and the comment on line 8. No other match outside tests.
### 5. Security Baseline Extension
- **Status**: enabled.
- **Compliance** (from the design documents; the implementation proofs are the tests above):
- SECURITY-04 (headers): compliant, proven with real nginx.
- SECURITY-09 (hardening, no listing, no stack traces): compliant by design and by the nginx tests.
- SECURITY-10 (supply chain): compliant for the production audit and the frozen lockfile; the development audit reports non-blocking advisories.
- SECURITY-11 (secure design: path traversal, open redirect, CRLF): compliant, covered by P-HST-01, P-HST-04, P-HST-07.
- SECURITY-13 (integrity): compliant, no external script; the audit route is opt-in and not on production hosts.
- SECURITY-15 (fail-safe): compliant; a prerender error fails the build, the post-deploy script fails closed, the artifact check stops an upload.
- Other rules (data stores, APIs, accounts, logging): N/A, static site.
- **Residual**: IIS rules and FTPS are unverified; the repository appears anonymously readable from the Pi (see the summary, open items).
@@ -0,0 +1,36 @@
# Unit Test Execution
Feature: prerendering. HEAD `39dc456`.
## Run Unit Tests
### 1. Execute All Unit Tests
```bash
cd web
pnpm test
```
`pnpm test` is `vitest run --coverage`. It runs the unit and component tests of all three units together, in jsdom. The browser tests are a separate command (`pnpm e2e`, see `integration-test-instructions.md`).
### 2. Review Test Results
- **Expected**: 1390 tests in 132 files, 0 failures. This is the count of the unit 3 code summary (unit 1 ended at 1179, unit 2 at 1277, master had 888).
- **Confirmed in this stage**: `pnpm test` was run once at HEAD `39dc456` and exited 0. The output was read through `tail`, so the "Tests" line itself was not captured; the count 1390 in 132 files is the code summary's figure. `git diff --stat 2006fa0 HEAD` shows no change outside `aidlc-docs/`, so the code is the code that count was taken on.
- **Test Coverage** (v8, this run): statements 96.1% (1654/1721), branches 94.5% (1152/1219), functions 97.36% (518/532), lines 96.6% (1479/1531). The configured thresholds are met (the run exited 0).
- **Test Report Location**: terminal output and `web/coverage/` (gitignored).
### 3. Property-based tests (PBT-08)
- **Framework**: fast-check, through Vitest.
- **Seed**: `web/config/testSeed.ts` is a Vitest global setup, used by `vite.config.ts` and by `vitest.e2e.config.ts`. It picks one seed per run (`FC_SEED` if set, otherwise random) and always prints it, also when everything passes: `fast-check seed: <n> (opnieuw: FC_SEED=<n> pnpm test)`. `src/test/setup.ts` hands it to `fc.configureGlobal({ seed })`, so every property in the run uses it.
- **Replay**: `FC_SEED=<seed> pnpm test`. Seeds seen in this feature: 1405857762 (unit 1), 2056055883 (unit 2), 511446714 (unit 3), 753602326 (the browser run of CI run 599).
- **Shrinking**: not disabled. A search of `web/src`, `web/config` and `web/e2e` finds no `endOnFailure` and no shrink override (the only "shrink" match is a CSS comment). On a failure fast-check prints the shrunk counterexample and the seed.
- **CI**: the `check` job runs `pnpm test` (the workflow comment says the seed is logged). The `lighthouse` job runs `pnpm e2e`, which prints its own seed. Both runs therefore log a seed on every run.
- **Properties added by this feature**: P1 to P9 (`config/inlineScripts.test.ts`), P10 (`pageFiles`), P11 to P13 (`externalizeInlineScripts`), P14 (`contactChannels`), P15 (`emailAddress`), P16 and P17 (`previewServer`), P18 to P21 (`revealPhase`), P22 (`preloadImage` in `seo.ts`), P24 and P25 (`firstRow`), P-HST-01 to 08 (`canonicalUrls`, `previewServer`, `serverConfig`), P-HST-09 (nginx against the preview server, bounded to 100 runs, in the browser suite), P-HST-11 (`lighthouserc`). P23 is an example test. Hooks and browser flows have example tests only (no property identified).
### 4. Fix Failing Tests
If tests fail:
1. Read the output; copy the printed seed and the shrunk counterexample.
2. Replay with `FC_SEED=<seed> pnpm test` (or one file with `pnpm exec vitest run <file>`).
3. Fix the code, or the test if the design rule changed, and rerun the whole suite.
4. A property that fails once and passes on retry is a defect to investigate (PBT-08), not noise.
## Known messages (not failures)
- jsdom prints `Not implemented: HTMLCanvasElement's getContext()` and `Not implemented: navigation to another Document`.