Hand-back U2 en Build and Test-documentatie

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-07 01:27:11 +01:00
co-authored by Claude Sonnet 5.5
parent 3b3f132558
commit 8cc9666b62
9 changed files with 110 additions and 1 deletions
@@ -0,0 +1,20 @@
# Build and Test Summary - andreaslop-site-hosting (U1 + U2)
## Build Status
- **Backend**: `dotnet build SlpModularCms.sln` succeeded (0 errors). **Frontend**: default and `VITE_THEME=asf` builds succeeded; `VITE_THEME=nope` fails as intended.
- **Artifacts**: none published here (CI publishes `app-asf-test`).
## Test Execution Summary (local, 2026-11-07)
### Unit tests
- Core 351, Modules.Identity 57, Availability 82, Master 57, Offerings 57, ASF host configuration 5, frontend 293: **all passed**, 0 failed. ESLint and `tsc -b` clean.
### Integration tests
- In-memory integration (website routing, headers, proxy awareness, setup token controller): passed (inside Core/Identity counts).
- **Not run locally**: `Api.Tests` and `Api.AndreaSlopFotografie.Tests/HostPipelineTests` (10 tests) need MariaDB, which is not available on this machine. They run in CI `backend-test`; result to be reported after the first push and CI run.
### Performance
- Local 0.72 ms/request (in-memory). Pi measurement pending the first test deploy.
### Additional
- **Security / dependency scan: FAIL (pre-existing).** `dotnet list package --vulnerable` reports `System.Security.Cryptography.Xml 10.0.10` and transitive `Pkcs 10.0.10` (high; patched in 10.0.12+, 10.0.14 available) in `Core` and four test projects; `pnpm audit --prod` reports 6 findings (seroval, zod; patched versions exist). Not caused by this feature, but the CI `vulnerability-scan` gate will fail and block publishing. Decision needed.
- Contract/E2E: the curl checks in manual-steps 14-18 act as the E2E check on the test host after the first deploy.
## Overall Status
- **Build**: Success. **All locally runnable tests**: Pass. **Ready for Operations**: Yes for the code; CI is blocked by the dependency advisories until resolved or overridden, and the database-backed tests are unproven until CI runs.
@@ -0,0 +1,16 @@
# Build Instructions
## Prerequisites
- **Build tools**: .NET SDK 10 (`10.0.x`), Node 20+ with pnpm (CI uses Node 20, pnpm 9; local pnpm 12 works, lockfile format unchanged).
- **Dependencies**: NuGet and npm registries reachable. New frontend packages: `@fontsource/jost@5.3.0`, `@fontsource/marcellus@5.3.0` (only bundled when `VITE_THEME=asf`).
- **Environment variables** (admin build only, all optional): `VITE_THEME` (`asf`), `VITE_DEFAULT_LANGUAGE` (`nl`|`en`), `VITE_APP_TITLE`, `VITE_APP_ENV`, `VITE_SENTRY_DSN`.
## Build steps
1. Backend, all projects: `dotnet build SlpModularCms.sln` (from the repo root). Expected: 0 errors; warnings NU1903/NU1902/NU1510 about packages are known (see summary).
2. Admin, default look: `cd frontend && pnpm install --frozen-lockfile && pnpm build`.
3. Admin, ASF look: `VITE_THEME=asf VITE_DEFAULT_LANGUAGE=nl VITE_APP_TITLE="Andrea Slop Fotografie" pnpm build`. Expect `dist/favicon-theme.png`, four `*.woff2` files and `index.html` linking `/admin/favicon-theme.png`. An unknown `VITE_THEME` must fail the build.
4. Publish as CI does: copy `frontend/dist/.` to `src/SlpModularCms.Api.AndreaSlopFotografie/wwwroot/admin/`, then `dotnet publish -c Release -r linux-arm64 --self-contained false` in that project.
## Troubleshooting
- `Unknown VITE_THEME "x"`: the name must be a folder under `frontend/themes/` containing `theme.css` (available: `asf`).
- Lockfile mismatch in CI: run `pnpm install` locally with the same major lockfile format and commit `pnpm-lock.yaml`.
@@ -0,0 +1,12 @@
# Integration Test Instructions
## Scenarios
1. **Real host with database** (`Api.Tests`, `Api.AndreaSlopFotografie.Tests/HostPipelineTests`): `WebApplicationFactory` boots the composed pipeline in `Development`; checks `/health`, `/api/v1/System/capabilities` (Identity and Availability present; Offerings and Master absent), `Setup/status` (`tokenRequired:false` without token), the unknown website path (404 with `StrictSite` CSP and `X-Robots-Tag: noindex, nofollow`), and `/robots.txt` (`Disallow: /`). The startup migration needs a reachable MariaDB.
2. **Proxy awareness** (`Core.Tests/Hosting/Proxy`, in-memory, no database): untrusted peers cannot spoof `X-Forwarded-For`; a trusted proxy yields the real address/scheme and separate limiter buckets; no configuration keeps the old shared bucket.
3. **Prerendered website** (`Core.Tests/Hosting/Website`, in-memory): routing parity, headers on every response, 404 page, 301 including the percent-encoded `Location`.
## Environment for scenario 1
Local MariaDB matching `appsettings.Development.json`, or override `ConnectionStrings__DefaultConnection`. CI (`backend-test`) starts `mariadb:11` on port 3307 and runs `dotnet test SlpModularCms.sln -c Release`.
## Run
`dotnet test SlpModularCms.sln -c Release` (with the database available). Cleanup: stop the container.
@@ -0,0 +1,5 @@
# Performance Test Instructions
Requirement (NFR-PF): website responses must not add noticeable latency; per-request file lookup, no cache.
- **Local (done)**: 500 `GET /over-mij` on an in-memory server = 0.72 ms per request (U1).
- **On the Pi (after the first test deploy, optional, cheap)**: `for i in $(seq 1 200); do curl -s -o /dev/null -w "%{time_total}\n" http://127.0.0.1:5200/over-mij; done | sort -n | awk '{a[NR]=$1} END{print "median",a[int(NR/2)],"p95",a[int(NR*0.95)]}'`; repeat with the website folder on `/mnt/storage1`. Report the numbers in the hand-back; no load test is planned (single small site).
@@ -0,0 +1,6 @@
# Security Test Instructions
- **Dependency scan**: `dotnet list SlpModularCms.sln package --vulnerable --include-transitive` (CI gate `vulnerability-scan` fails when it prints "has the following vulnerable packages") and `cd frontend && pnpm audit --prod`.
- **Setup token**: unit tests cover only-exact-token-passes (PBT), uniform 401, no token in logs, whitespace-only token rejected at startup, limiter on both endpoints (configuration). Manual after the first deploy (manual-steps 16-17): wrong token gives the Dutch error and a `setup_token_rejected` log line, right token creates the owner, then remove the token from `shared/env`.
- **Forwarded headers**: tests prove an untrusted peer cannot spoof; wildcard/unparsable proxy entries fail at startup. Manual: after the first deploy the visitor address (not 192.168.1.102) should be what the limiter/logs see.
- **Headers**: CSP byte-identical to nginx (asserted); verify with `curl -I https://test.andreaslop.nl/` (manual-steps 14).
@@ -0,0 +1,12 @@
# Unit Test Execution
## Run
- Backend, suites that need no database (run each from the repo root):
`dotnet test src/SlpModularCms.Core.Tests`, `...Modules.Identity.Tests`, `...Modules.Availability.Tests`, `...Modules.Master.Tests`, `...Modules.Offerings.Tests`, and `dotnet test src/SlpModularCms.Api.AndreaSlopFotografie.Tests --filter "FullyQualifiedName~HostConfigurationTests"`.
- Frontend: `cd frontend && pnpm test` (Vitest, includes `themes/*.test.ts`), plus `pnpm lint` and `npx tsc -b`.
## Expected (2026-11-07, local)
Core 351, Identity 57, Availability 82, Master 57, Offerings 57, ASF host configuration 5, frontend 293; 0 failures. Property-based tests (FsCheck, random seed per run) are part of Core and Identity; on failure the replay seed is printed in the message; pin the shrunk counterexample as an example test.
## If a test fails
Read the failure and seed, reproduce, fix the code (not the test) unless the test is wrong, rerun several times for property tests (a failure may appear in only 1 of ~15 runs: this is how the U1 `Location` encoding defect was found).