repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

docs: plan aggregate browser e2e

b739a534f9b54de715c36cc2689eefcd422bb50e

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (2)

docs/super/plans/2026-07-12-mise-task-architecture-phase-2-existing-e2e-and-aggregate.md

Added
new file mode 100644
1 +# Mise Task Architecture Phase 2 Implementation Plan
3 +> **For agentic workers:** REQUIRED SUB-SKILL: Use /skill:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
5 +**Goal:** Move existing diff-review and UI browser suites into extension-local mise tasks, run both in Chromium and Firefox, and replace extension-specific root commands with one aggregate `e2e` task.
7 +**Architecture:** Each browser-owning extension controls its Playwright configuration and local `e2e` command. Root mise installs both browser engines once, then dispatches extension-local suites sequentially through monorepo task syntax.
9 +**Tech Stack:** mise monorepo tasks, Playwright 1.61, Chromium, Firefox, npm workspaces, TypeScript.
11 +**Roadmap:** [`docs/super/roadmaps/2026-07-12-mise-task-architecture-roadmap.md`](../roadmaps/2026-07-12-mise-task-architecture-roadmap.md)
13 +**Phase:** Phase 2: Existing E2E Suites And Aggregate Command
15 +---
17 +## File Structure
19 +**Create:**
21 +- `extensions/diff-review/mise.toml`: diff-review E2E ownership.
22 +- `extensions/ui/mise.toml`: UI E2E ownership.
24 +**Modify:**
26 +- `extensions/diff-review/playwright.config.ts`: Chromium and Firefox projects.
27 +- `extensions/ui/playwright.config.ts`: Chromium and Firefox projects without a Windows-only executable override.
28 +- `extensions/diff-review/package.json`: remove duplicate `test:e2e` script ownership.
29 +- `extensions/ui/package.json`: remove duplicate `test:e2e` script ownership.
30 +- `mise.toml`: replace public browser-install and diff-review-specific tasks with aggregate `e2e`.
31 +- `AGENTS.md`: document the aggregate root task and qualified local tasks.
32 +- `extensions/diff-review/README.md`: document local and root-qualified E2E usage.
33 +- `extensions/ui/README.md`: document local and root-qualified E2E usage.
35 +**Unchanged:**
37 +- Existing Playwright specs remain behaviorally unchanged.
38 +- Root `test` remains Vitest-only.
39 +- Root `ci` remains lint, test, and check until Phase 4.
40 +- The-system and tune E2E coverage remain deferred to Phases 3 and 4.
42 +### Task 1: Normalize Existing Playwright Browser Matrices
44 +**Files:**
46 +- Modify: `extensions/diff-review/playwright.config.ts`
47 +- Modify: `extensions/ui/playwright.config.ts`
49 +- [ ] **Step 1: Record unrelated work before editing**
51 +Run:
53 +```bash
54 +git status --short
55 +git diff -- extensions/diff-review/playwright.config.ts extensions/ui/playwright.config.ts
56 +```
58 +Expected: neither Playwright config has pre-existing worktree changes.
59 +Preserve every unrelated dirty path shown by status.
61 +- [ ] **Step 2: Verify the current single-browser behavior**
63 +Run:
65 +```bash
66 +npm exec --workspace extensions/diff-review -- playwright test --config playwright.config.ts --list
67 +npm --workspace extensions/ui exec -- node --import tsx ../../node_modules/@playwright/test/cli.js test --config playwright.config.ts --list
68 +```
70 +Expected: diff-review lists Firefox tests only, and UI lists Chromium tests only.
71 +This is the failing baseline for the required two-browser matrix.
73 +- [ ] **Step 3: Configure diff-review for both browsers**
75 +Replace `extensions/diff-review/playwright.config.ts` with:
77 +```ts
78 +import { defineConfig } from "@playwright/test";
80 +export default defineConfig({
81 + testDir: "__e2e__",
82 + testMatch: "*.spec.ts",
83 + timeout: 30_000,
84 + retries: 1,
85 + projects: [
86 + { name: "chromium", use: { browserName: "chromium" } },
87 + { name: "firefox", use: { browserName: "firefox" } },
88 + ],
89 + use: {
90 + headless: true,
91 + },
92 +});
93 +```
95 +Keep existing timeout and retry policy unchanged.
97 +- [ ] **Step 4: Configure UI for both Playwright-managed browsers**
99 +Replace `extensions/ui/playwright.config.ts` with:
101 +```ts
102 +import { defineConfig } from "@playwright/test";
104 +export default defineConfig({
105 + testDir: "./__e2e__",
106 + timeout: 30_000,
107 + expect: { timeout: 5_000 },
108 + projects: [
109 + { name: "chromium", use: { browserName: "chromium" } },
110 + { name: "firefox", use: { browserName: "firefox" } },
111 + ],
112 + use: {
113 + headless: true,
114 + viewport: { width: 900, height: 700 },
115 + },
116 +});
117 +```
119 +Delete the `node:fs` import and hard-coded Windows Chrome path.
120 +Playwright’s installed Chromium must be used consistently on every platform.
122 +- [ ] **Step 5: Verify both projects are discovered**
124 +Run:
126 +```bash
127 +npm exec --workspace extensions/diff-review -- playwright test --config playwright.config.ts --list
128 +npm --workspace extensions/ui exec -- node --import tsx ../../node_modules/@playwright/test/cli.js test --config playwright.config.ts --list
129 +```
131 +Expected:
133 +- Every diff-review spec appears once under `[chromium]` and once under `[firefox]`.
134 +- Both UI specs appear once under `[chromium]` and once under `[firefox]`.
135 +- `real-rpc-smoke.spec.ts` remains listed but runtime-skipped unless explicitly enabled.
137 +- [ ] **Step 6: Install the two browser engines for verification**
139 +Run:
141 +```bash
142 +npm exec -- playwright install chromium firefox
143 +```
145 +Expected: exit 0.
146 +Existing cached engines may be reused.
147 +Do not use `--with-deps`; system-package mutation belongs to CI environment setup, not this cross-platform task.
149 +- [ ] **Step 7: Run both suites directly**
151 +Run:
153 +```bash
154 +npm exec --workspace extensions/diff-review -- playwright test --config playwright.config.ts
155 +npm --workspace extensions/ui exec -- node --import tsx ../../node_modules/@playwright/test/cli.js test --config playwright.config.ts
156 +```
158 +Expected:
160 +- Diff-review passes in Chromium and Firefox.
161 +- UI’s fake-RPC suite passes in Chromium and Firefox.
162 +- UI’s real-RPC smoke is skipped by default in both projects.
163 +- No OS-specific browser executable is required.
165 +- [ ] **Step 8: Commit browser matrix normalization**
167 +Run:
169 +```bash
170 +git add extensions/diff-review/playwright.config.ts extensions/ui/playwright.config.ts
171 +git diff --cached --check
172 +git commit -m "test(e2e): cover chromium and firefox"
173 +```
175 +Expected: only the two Playwright configs are committed.
177 +### Task 2: Move E2E Command Ownership Into Extensions
179 +**Files:**
181 +- Create: `extensions/diff-review/mise.toml`
182 +- Create: `extensions/ui/mise.toml`
183 +- Modify: `extensions/diff-review/package.json`
184 +- Modify: `extensions/ui/package.json`
186 +- [ ] **Step 1: Verify qualified E2E tasks are absent**
188 +Run:
190 +```bash
191 +mise tasks --all --name-only
192 +```
194 +Expected: neither `//extensions/diff-review:e2e` nor `//extensions/ui:e2e` exists.
196 +- [ ] **Step 2: Add diff-review’s local E2E task**
198 +Create `extensions/diff-review/mise.toml`:
200 +```toml
201 +[tasks.e2e]
202 +description = "Run diff-review browser E2E tests"
203 +depends = ["//:install"]
204 +run = "npm exec -- playwright test --config playwright.config.ts"
205 +```
207 +- [ ] **Step 3: Add UI’s local E2E task**
209 +Create `extensions/ui/mise.toml`:
211 +```toml
212 +[tasks.e2e]
213 +description = "Run UI browser E2E tests"
214 +depends = ["//:install"]
215 +run = "node --import tsx ../../node_modules/@playwright/test/cli.js test --config playwright.config.ts"
216 +```
218 +- [ ] **Step 4: Remove duplicate package-script ownership**
220 +Remove only `test:e2e` from both extension `scripts` objects.
222 +`extensions/diff-review/package.json` keeps:
224 +```json
225 +"scripts": {
226 + "dev:smoke": "tsx scripts/dev-server.ts"
228 +```
230 +`extensions/ui/package.json` keeps:
232 +```json
233 +"scripts": {
234 + "test": "vitest run ./__tests__/*.test.ts"
236 +```
238 +Do not change dependencies in this phase.
239 +Playwright remains a declared development dependency of the root and each E2E-owning workspace.
241 +- [ ] **Step 5: Regenerate npm lock metadata**
243 +Run:
245 +```bash
246 +mise run lock
247 +```
249 +Expected: exit 0.
250 +Package scripts normally do not alter `package-lock.json`; if the lockfile changes, inspect and include only metadata caused by these package edits.
252 +- [ ] **Step 6: Verify local task discovery and execution**
254 +Run:
256 +```bash
257 +mise tasks --all --name-only
258 +mise run //extensions/diff-review:e2e
259 +mise run //extensions/ui:e2e
260 +```
262 +Expected: both qualified tasks exist and both browser matrices pass.
264 +- [ ] **Step 7: Commit local E2E ownership**
266 +Run:
268 +```bash
269 +git add extensions/diff-review/mise.toml extensions/ui/mise.toml extensions/diff-review/package.json extensions/ui/package.json package-lock.json
270 +git diff --cached --check
271 +git commit -m "build(e2e): localize browser suites"
272 +```
274 +Expected: two local mise files and removal of duplicate package scripts are committed.
275 +Omit `package-lock.json` if unchanged.
277 +### Task 3: Replace Root E2E Tasks With One Aggregate
279 +**Files:**
281 +- Modify: `mise.toml:59-72`
283 +- [ ] **Step 1: Confirm the obsolete root commands**
285 +Run:
287 +```bash
288 +mise tasks --name-only
289 +```
291 +Expected: `//:install-e2e-browsers` and `//:e2e-diff-review` exist, while `//:e2e` does not.
293 +- [ ] **Step 2: Replace both obsolete task blocks**
295 +Delete the complete `[tasks.install-e2e-browsers]` and `[tasks.e2e-diff-review]` blocks.
296 +Insert this task in their place:
298 +```toml
299 +[tasks.e2e]
300 +description = "Run all extension browser E2E tests"
301 +depends = ["install"]
302 +run = [
303 + "npm exec -- playwright install chromium firefox",
304 + "mise run --jobs 1 //extensions/...:e2e",
306 +```
308 +Browser installation occurs once at root.
309 +Extension execution is sequential to avoid browser/process contention and interleaved reports.
310 +Local qualified tasks assume browsers were installed through root `e2e` or an explicit Playwright install.
312 +- [ ] **Step 3: Verify root and all-task surfaces**
314 +Run:
316 +```bash
317 +mise tasks validate
318 +mise tasks --name-only
319 +mise tasks --all --name-only
320 +mise run --dry-run e2e
321 +```
323 +Expected:
325 +- Task validation exits 0.
326 +- Root contains `//:e2e`.
327 +- Root no longer contains `//:install-e2e-browsers` or `//:e2e-diff-review`.
328 +- All-task output contains both qualified extension E2E tasks.
329 +- The dry run shows one browser install followed by sequential monorepo dispatch.
331 +- [ ] **Step 4: Run the aggregate E2E task**
333 +Run:
335 +```bash
336 +mise run e2e
337 +```
339 +Expected: browser installation succeeds once, then diff-review and UI suites both pass in Chromium and Firefox.
340 +The two extension task headers do not overlap.
342 +- [ ] **Step 5: Confirm Vitest and CI remain unchanged**
344 +Run:
346 +```bash
347 +mise run test
348 +mise run --dry-run ci
349 +```
351 +Expected:
353 +- Vitest does not discover files under `__e2e__`.
354 +- CI resolves lint, test, and check only.
355 +- E2E remains outside CI until Phase 4.
357 +- [ ] **Step 6: Commit root aggregation**
359 +Run:
361 +```bash
362 +git add mise.toml
363 +git diff --cached --check
364 +git commit -m "build(e2e): aggregate browser suites"
365 +```
367 +Expected: the commit contains only replacement of the two legacy E2E tasks with root `e2e`.
369 +### Task 4: Document The Phase 2 Task Surface
371 +**Files:**
373 +- Modify: `AGENTS.md:10-35`
374 +- Modify: `extensions/diff-review/README.md`
375 +- Modify: `extensions/ui/README.md`
377 +- [ ] **Step 1: Replace legacy E2E rows in AGENTS.md**
379 +Remove:
381 +```markdown
382 +| E2E browsers | `mise run install-e2e-browsers` | Install Playwright E2E browsers |
383 +| E2E review | `mise run e2e-diff-review` | Run diff-review headless browser E2E |
384 +```
386 +Add after `Bench`:
388 +```markdown
389 +| E2E | `mise run e2e` | Run extension E2E in Chromium and Firefox |
390 +```
392 +Keep the Phase 2 CI description as `Release gate (lint + test + check)`.
394 +- [ ] **Step 2: Document diff-review E2E usage**
396 +Add this section near diff-review’s development/testing documentation:
398 +```markdown
399 +## E2E
401 +Run root `mise run e2e` first to install browsers and execute every extension suite.
402 +After that bootstrap, run `mise run e2e` here, or `mise //extensions/diff-review:e2e` from the repository root, to test only the browser review flow in Chromium and Firefox.
403 +```
405 +- [ ] **Step 3: Document UI E2E usage**
407 +Add this section near UI’s development/testing documentation:
409 +```markdown
410 +## E2E
412 +Run root `mise run e2e` first to install browsers and execute every extension suite.
413 +After that bootstrap, run `mise run e2e` here, or `mise //extensions/ui:e2e` from the repository root, to test only the browser UI in Chromium and Firefox.
414 +The real Pi RPC smoke remains opt-in through `UI_REAL_RPC_SMOKE=1`.
415 +```
417 +- [ ] **Step 4: Verify obsolete command references are gone from live docs**
419 +Run:
421 +```bash
422 +node -e "const fs=require('node:fs'); for(const p of ['AGENTS.md','extensions/diff-review/README.md','extensions/ui/README.md']) { const s=fs.readFileSync(p,'utf8'); for(const old of ['install-e2e-browsers','e2e-diff-review']) if(s.includes(old)) throw new Error(p+': '+old); }"
423 +```
425 +Expected: exit 0 with no output.
427 +- [ ] **Step 5: Verify changed documentation formatting**
429 +Run:
431 +```bash
432 +git diff --check -- AGENTS.md extensions/diff-review/README.md extensions/ui/README.md
433 +```
435 +Expected: exit 0 with no output.
436 +Do not run repository-wide formatting while unrelated dirty files remain.
437 +The final CI lint check validates Markdown formatting without mutating those files.
439 +- [ ] **Step 6: Commit documentation**
441 +Run:
443 +```bash
444 +git add AGENTS.md extensions/diff-review/README.md extensions/ui/README.md
445 +git diff --cached --check
446 +git commit -m "docs: explain aggregate browser E2E"
447 +```
449 +Expected: only E2E command documentation is committed.
451 +### Task 5: Verify The Phase 2 Boundary
453 +**Files:**
455 +- Verify: `mise.toml`
456 +- Verify: `extensions/diff-review/mise.toml`
457 +- Verify: `extensions/ui/mise.toml`
458 +- Verify: both Playwright configurations and suites
460 +- [ ] **Step 1: Validate final task discovery**
462 +Run:
464 +```bash
465 +mise tasks validate
466 +mise tasks --name-only
467 +mise tasks --all --name-only
468 +```
470 +Expected:
472 +- Exactly one public root E2E task exists: `//:e2e`.
473 +- Qualified diff-review and UI E2E tasks exist.
474 +- Legacy root E2E task names are absent.
475 +- Phase 1 benchmark tasks remain unchanged.
477 +- [ ] **Step 2: Run the complete browser aggregate**
479 +Run:
481 +```bash
482 +mise run e2e
483 +```
485 +Expected:
487 +- Both browser engines are available.
488 +- Diff-review passes in Chromium and Firefox.
489 +- UI fake-RPC passes in Chromium and Firefox.
490 +- UI real-RPC smoke is skipped by default.
492 +- [ ] **Step 3: Run the unchanged release gate**
494 +Run:
496 +```bash
497 +mise run ci
498 +```
500 +Expected: lint, all Vitest tests, typecheck, and static checks pass.
501 +E2E remains a separate manual gate in Phase 2.
503 +- [ ] **Step 4: Inspect final scope**
505 +Run:
507 +```bash
508 +git status --short
509 +git diff --stat
510 +git log -5 --oneline
511 +```
513 +Expected: unrelated pre-existing work remains untouched.
514 +No the-system or tune E2E files were added.
515 +No CI workflow was changed.
516 +No TypeScript import standardization from Phase 5 was started.
518 +- [ ] **Step 5: Report completion evidence**
520 +Report:
522 +- Task validation and root/all task lists.
523 +- Chromium and Firefox results for diff-review and UI.
524 +- `mise run ci` result.
525 +- Commits created.
526 +- Confirmation that E2E is not yet part of CI.
527 +- Confirmation that Phases 3 through 5 remain unimplemented.

docs/super/roadmaps/2026-07-12-mise-task-architecture-roadmap.md

Modified
171 171 - Add a local `e2e` task and Playwright suite for tune’s browser interface.
172 172 - Cover page startup, essential rendering, one primary interaction, and the browser-to-extension result path.
173 173 - Make tune automatically participate in the aggregate E2E command.
174 -- Change root `ci` order to lint, test, e2e, then check.
174 +- Change root `ci` order to check, lint, test, then e2e.
175 175 - Update Git-hook and task documentation for the final command surface.
176 176 - Verify GitHub Actions needs no extension-specific browser logic beyond `mise run ci`.