1# Framework fixtures
 2
 3Representative project shapes for exercising live mode against different framework conventions. Each fixture is a small directory tree that the test harness copies into a temp git repo, then drives `live-inject.mjs`, `live-wrap.mjs`, `live-accept.mjs`, and `is-generated.mjs` against.
 4
 5Fixtures can also opt into a **runtime E2E** pass that actually installs dependencies, boots the framework dev server, and drives a Playwright browser to verify the live handshake. See the `runtime` block below.
 6
 7## Layout
 8
 9```
10<fixture>/
11  files/              project tree the test copies into tmp
12  gitignore.txt       becomes .gitignore in tmp (so we can commit the real files here)
13  fixture.json        config + expected results the test consumes
14```
15
16`fixture.json` schema:
17
18```json
19{
20  "name": "human-readable label",
21  "config": { ...contents for .impeccable/live/config.json ... },
22  "sourceFiles": ["paths that is-generated should classify as source (false)"],
23  "generatedFiles": ["paths that is-generated should classify as generated (true)"],
24  "wrapCases": [
25    {
26      "name": "description",
27      "args": { "classes": "...", "tag": "...", "elementId": "..." },
28      "expectedFile": "where wrap should land (relative to fixture root)",
29      "expectsError": "optional error code, e.g. element_not_in_source"
30    }
31  ],
32  "csp": {
33    "shape": "shared-helper | inline-headers | middleware | meta-tag | null",
34    "signals": ["diagnostic hints — paths where CSP was detected"],
35    "patchTarget": "which file the agent should modify",
36    "expectedAfter": "filename of the reference post-patch output inside this fixture"
37  },
38  "runtime": {
39    "styling": "plain-css | tailwind-v4 | styled-components | ...",
40    "install": ["npm", "install"],
41    "devCommand": ["npm", "run", "dev"],
42    "scheme": "http",
43    "ignoreHTTPSErrors": false,
44    "readyPattern": "Local:\\s+https?://[^:]+:(\\d+)",
45    "readyTimeoutMs": 120000,
46    "pickSelector": "h1.hero-title",
47    "preActions": [
48      { "type": "click", "selector": "[data-testid='open-modal']" },
49      { "type": "goto",  "path": "/about" }
50    ],
51    "reloadProbe": {
52      "preActions": [{ "type": "click", "selector": "[data-testid='open-modal']" }],
53      "expectSelector": "h1.hero-title"
54    },
55    "probe": {
56      "expectLiveInit": true,
57      "expectConsoleClean": true
58    }
59  }
60}
61```
62
63The `expectedAfter` file lives alongside `fixture.json` (not inside `files/`) and is a human/agent-review reference — tests don't auto-apply the patch.
64
65The `runtime` block is optional. Fixtures without it only run the static unit checks (is-generated, inject, wrap, csp-detect). Fixtures *with* it additionally run the E2E suite in `tests/live-e2e.test.mjs` (`bun run test:live-e2e`), which:
66
671. Stages the fixture into a tmp repo.
682. Runs `runtime.install` to install real deps.
693. Starts `live-server.mjs --background` and runs `live-inject.mjs --port` against it.
704. Spawns `runtime.devCommand` and scrapes the port from stdout using `runtime.readyPattern` (the first capture group must be the port).
715. Opens Playwright Chromium at the dev URL and asserts `window.__IMPECCABLE_LIVE_INIT__ === true` (the browser-side handshake oracle) within `runtime.readyTimeoutMs`.
726. Tears everything down (Playwright close, dev server SIGTERM, live-server stop, tmp rm).
73
74## Current fixtures
75
76| Fixture | Shape |
77|---|---|
78| `vite-react/` | Tracked `index.html` shell + `src/App.jsx`. Inject into the shell. |
79| `nextjs-app/` | `app/layout.tsx` as JSX inject target (commentSyntax `jsx`). |
80| `astro/` | `src/layouts/Layout.astro` as inject target. HTML comments. |
81| `sveltekit/` | `src/app.html` shell + `src/routes/+page.svelte`. |
82| `multipage-with-generator/` | `src/` tracked, `dist/` gitignored. Exercises the is-generated guard and `element_not_in_source` fallback. |
83| `nextjs-turborepo/` | Monorepo with shared CSP helper (`createBaseNextConfig`). CSP shape `append-arrays`. |
84| `nextjs-inline-csp/` | App-level `next.config.js` with a literal CSP string. CSP shape `append-string`. |
85| `sveltekit-csp/` | SvelteKit `kit.csp.directives` in `svelte.config.js`. CSP shape `append-arrays`. |
86| `nuxt-csp/` | Nuxt `routeRules` with literal CSP header in `nuxt.config.ts`. CSP shape `append-string`. |
87
88Add new fixtures by cloning a directory, swapping files, and updating `fixture.json`.