repremium/mokosh
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(01-11): wave-2 — Puppeteer harness scaffolding + A0 GREEN, popup-bridge architecture

Browse Source 
Task 3 of Plan 01-11 (Puppeteer UAT harness).

Harness file tree (tests/uat/):
- harness.test.ts: tsx-runnable top-to-bottom harness entry point.
  Runs A0 inline (filesystem grep gate, abort-on-fail T-1-11-01),
  then launches Chrome + opens popup bridge + queries manifest, then
  iterates A1-A13 stubs. Each stub throws "NOT YET IMPLEMENTED —
  Plan 01-11 Task N wires this assertion". Exit code = 0 on full
  pass, 1 otherwise. Final line: "UAT harness: N/14 assertions passed".
- lib/launch.ts: launchHarnessBrowser() — wraps puppeteer.launch with
  enableExtensions:[dist-test/], headless default (HEADLESS=0
  override), --no-sandbox + --auto-select-desktop-capture-source flags.
  Polls browser.extensions() until the extension registers (empirically
  ~100ms but the first call right after launch returns Map(0)).
  Opens both a blank page (for triggerExtensionAction) AND the popup
  page (the bridge surface). Returns { browser, extension, extensionId,
  sw, downloadsDir, page, popup }.
- lib/extension.ts: waitForOffscreenTarget + attachToOffscreen +
  countOffscreenTargets. Offscreen attach uses target.type() ===
  'background_page' + .asPage() (NOT .page() — RESEARCH §4 Pitfall 1).
- lib/sw.ts: chrome.* state queries via the POPUP page handle (NOT
  the WebWorker handle — see architecture note below). getBadgeText,
  getPopup, getManifest, getIconSize, getIsRecording (side-channeled
  through badge text), fireOnStartup (via __mokoshTestQuery bridge),
  sendSyntheticRecordingError, getNotificationSnapshot (via bridge),
  keepalivePing (no-op message to wake SW for ~30s).
- lib/offscreen.ts: getDisplaySurface, simulateUserStop (the
  dispatchEvent('ended') path per RESEARCH §7 BLOCKER — DO NOT REFACTOR
  to track.stop()), getSegmentCount.
- lib/assertions.ts: runAssertion(idx, name, buffers, fn) wrapper —
  records pass/fail/duration; on failure dumps last 30 lines of SW
  + offscreen console buffers to stderr before rethrowing. assertEqual
  / assertMatch / assertTrue / assertGte / waitFor polling helper.
- lib/zip.ts: jszip-based assertArchiveShape + extractEntryToFile for
  assertions 12 + 13.
- README.md: runtime + local-debug + CI semantics + locale gotcha
  + dev-dep size note + assertion catalog table.
- tsconfig.json: per-tree type-check config (mirrors root tsconfig.json
  compiler options but includes the harness tree explicitly).

Architecture refinement (DEVIATION from RESEARCH §1 — Rule 1+3 inline fix):
- RESEARCH §1 sketched `sw.evaluate(() => chrome.action.getBadgeText({}))`
  as the chrome.* query path. Empirical probes during Task 3 execution
  against Puppeteer 25.0.2 + Chrome 148 + --headless=true revealed two
  blockers:
    1. Puppeteer's WebWorker.evaluate runs in an ISOLATED WORLD that
       carries SW globals (clients, registration, ...) but NOT the
       extension's full chrome.* API surface. Object.keys(chrome) inside
       sw.evaluate returns ["loadTimes","csi"] — the public webpage
       chrome, not the extension chrome.
    2. Chrome 148's headless mode aggressively suspends MV3 service
       workers; subsequent swTarget.worker() calls return
       "Protocol error: No target with given id found".
- WORKAROUND: open the popup page (chrome-extension://<id>/src/popup/
  index.html) as a separate Puppeteer Page. The popup has full
  chrome.* access (it's an extension context with same privileges as
  the SW) AND stable Puppeteer lifetime. For SW-globalThis state
  (__mokoshTest in the SW isolate, NOT in the popup), bridge via
  chrome.runtime.sendMessage. The popup sends
  { type: '__mokoshTestQuery', op: 'snapshot' | 'fire-on-startup' |
  'handler-types' }; the SW hook's onMessage handler responds.
- Bridge implementation added to src/test-hooks/sw-hooks.ts — registers
  AFTER the production listeners so it never intercepts production
  messages (__mokoshTest* type is unambiguously test-only). Tier-1
  grep gate (no-test-hooks-in-prod-bundle.test.ts) continues to enforce
  ZERO __mokoshTest occurrences in dist/ — the bridge handler is
  tree-shaken alongside the rest of the hook module via the
  __MOKOSH_UAT__ gate.

Other configuration changes:
- vitest.config.ts: exclude tests/uat/** from vitest discovery. The
  Puppeteer harness is invoked via `npm run test:uat` (not vitest);
  running it under vitest would try to launch real Chrome inside a
  vitest worker. The .test.ts suffix is retained for editor +
  naming-convention consistency with the rest of the tree.

Verification:
- npx tsc --noEmit (src/): exit 0
- npx tsc --noEmit -p tests/uat: exit 0
- npm run build: exit 0
- grep -rln '__mokoshTest|simulateUserStop|getSegmentCount|setCurrentStream|setSegmentCountGetter|__mokoshTestQuery|__mokoshKeepalive' dist/: ZERO matches
- npm run build:test: exit 0; dist-test/ populated with the new bridge code
- SKIP_BUILD=1 npx vitest run: 89/89 GREEN
- SKIP_PROD_REBUILD=1 npx tsx tests/uat/harness.test.ts:
  → A0 [PASS]: production bundle has no test-hook leaks (19ms)
  → Browser launches; popup opens; manifest read succeeds
  → A1-A13 [FAIL]: NOT YET IMPLEMENTED — Plan 01-11 Task N wires this
  → "UAT harness: 1/14 assertions passed, 13 failed (first failure: A1)"
  → Exit code: 1 (expected — 13 RED stubs intentional)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Mark
2026-05-18 09:14:58 +02:00
parent cb1a729962
commit dbd977c815
11 changed files with 1705 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

314
tests/uat/lib/launch.ts Normal file
View File

@@ -0,0 +1,314 @@
// tests/uat/lib/launch.ts — Plan 01-11 harness launch helper.
//
// Wraps puppeteer.launch with the project's invariants:
// - enableExtensions points at the absolute path to dist-test/ (the
// test bundle that carries the gated test hooks per Plan 01-11
// Task 2). NOT dist/ — that would defeat the harness entirely.
// - headless defaults to true (CI-friendly); HEADLESS=0 env opens a
// real Chrome window for local debugging.
// - --auto-select-desktop-capture-source="Entire screen" auto-accepts
// the screen-share picker so getDisplayMedia resolves without
// operator interaction (RESEARCH §9). The literal string is
// en_US-locale-sensitive; document the fallback in tests/uat/README.md.
// - Downloads land in a fresh per-run temp dir so assertion 5
// (SAVE_ARCHIVE) can poll for session_report_*.zip without
// colliding with operator downloads.
//
// References:
// - puppeteer.launch options: https://pptr.dev/api/puppeteer.launchoptions
// - puppeteer extension API: https://pptr.dev/guides/extensions
// - Chrome --auto-select-desktop-capture-source:
// https://source.chromium.org/chromium/chromium/src/+/main:media/capture/video/chromeos/camera_app_device_provider.cc
// (search for the flag in chrome://flags or the Chromium source tree)
import { execSync } from 'node:child_process';
import { existsSync, mkdtempSync, statSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { dirname, join, resolve as resolvePath } from 'node:path';
import { fileURLToPath } from 'node:url';
import puppeteer, {
type Browser,
type CDPSession,
type Extension,
type Page,
type WebWorker,
} from 'puppeteer';
/// <reference path="./test-hook-contract.d.ts" />
const HARNESS_FILE_DIR = dirname(fileURLToPath(import.meta.url));
const REPO_ROOT = resolvePath(HARNESS_FILE_DIR, '..', '..', '..');
const DIST_TEST_DIR = resolvePath(REPO_ROOT, 'dist-test');
/**
* Handles returned from `launchHarnessBrowser`. All references are
* live for the lifetime of the browser; the caller MUST close the
* browser to release them.
*/
export interface HarnessHandles {
readonly browser: Browser;
readonly extension: Extension;
readonly extensionId: string;
/**
* Service worker handle (for completeness / future use). NOTE: per
* the architecture refinement documented in tests/uat/lib/sw.ts,
* the harness's chrome.* state queries go through the `popup` page
* (which has full extension chrome.* access AND a stable Puppeteer
* lifetime). Direct sw.evaluate is unreliable in Chrome 148 +
* headless + Puppeteer 25 (the SW suspends + worker() returns
* "Protocol error: No target with given id found"). The SW handle
* is kept here for harness wave-3 assertion 11 / 12 (where we may
* need a worker reference for diagnostics).
*/
readonly sw: WebWorker;
readonly downloadsDir: string;
/**
* A pre-opened blank page the harness can use to invoke
* `triggerExtensionAction` (Puppeteer requires a page in the active
* tab for the toolbar-click simulation).
*/
readonly page: Page;
/**
* The extension popup page, opened at
* chrome-extension://<extensionId>/src/popup/index.html. This page
* is the harness's primary chrome.* query surface (see
* tests/uat/lib/sw.ts file header for rationale).
*/
readonly popup: Page;
}
/**
* Optional launch overrides. Defaults are CI-friendly; HEADLESS=0
* environment variable flips to headful for local debugging.
*/
export interface LaunchOptions {
/** Override the dist-test directory (test isolation). */
readonly distTestDir?: string;
/** Override the downloads directory (default: fresh tempdir per call). */
readonly downloadsDir?: string;
/** Force headless / headful regardless of HEADLESS env. */
readonly headless?: boolean;
}
/**
* Create a per-run downloads directory under the OS tmpdir. Caller is
* responsible for cleanup (typically deferred to OS tmpdir GC).
*
* @returns Absolute path to the freshly-created downloads directory.
*/
function makeDownloadsDir(): string {
return mkdtempSync(join(tmpdir(), 'mokosh-uat-downloads-'));
}
/**
* Verify the dist-test directory exists and is a directory. Fails
* loudly with an actionable message — the caller likely forgot to
* run `npm run build:test` before invoking the harness.
*
* @param distTestDir - Absolute path to dist-test.
* @throws If the directory does not exist or is not a directory.
*/
function assertDistTestPresent(distTestDir: string): void {
if (!existsSync(distTestDir)) {
throw new Error(
`dist-test/ missing at ${distTestDir}. ` +
`Run \`npm run build:test\` before launching the harness ` +
`(or invoke via \`npm run test:uat\` which does it for you).`,
);
}
const stat = statSync(distTestDir);
if (!stat.isDirectory()) {
throw new Error(
`dist-test/ exists at ${distTestDir} but is not a directory.`,
);
}
}
/**
* Resolve whether to run headless. HEADLESS=0 forces headful;
* anything else (including undefined) is headless. Explicit
* `options.headless` overrides the env entirely.
*
* @param options - Optional launch overrides.
* @returns true for headless, false for headful.
*/
function resolveHeadless(options: LaunchOptions): boolean {
if (options.headless !== undefined) {
return options.headless;
}
return process.env.HEADLESS !== '0';
}
/**
* Locate the SW target via the extension ID. Polls puppeteer's target
* list because the SW is registered asynchronously after the extension
* loads. Times out at 10s — if the SW is missing after that, either
* dist-test/ is corrupted or the SW bundle threw at module init (which
* would be caught by sw-bundle-import.test.ts BEFORE the harness ever
* runs; but defensively, we surface a clear diagnostic here).
*
* @param browser - Puppeteer Browser handle.
* @param extensionId - The extension's runtime id.
* @returns The SW WebWorker handle.
* @throws If no SW target appears within 10s.
*/
async function waitForSwTarget(
browser: Browser,
extensionId: string,
): Promise<WebWorker> {
const target = await browser.waitForTarget(
(t) =>
t.type() === 'service_worker' &&
t.url().startsWith(`chrome-extension://${extensionId}`),
{ timeout: 10_000 },
);
const sw = await target.worker();
if (sw === null) {
throw new Error(
`Service worker target found for extension ${extensionId} but ` +
`its worker() returned null — the SW likely crashed at init.`,
);
}
return sw;
}
/**
* Configure the per-page download behavior via CDP so files land in
* our temp downloadsDir. Puppeteer 25's high-level downloads API is
* still in flux; the raw CDP call is stable across versions.
*
* @param page - Page whose downloads should be redirected.
* @param downloadsDir - Absolute path to capture downloads.
*/
async function setDownloadBehavior(
page: Page,
downloadsDir: string,
): Promise<void> {
const cdpClient: CDPSession = await page.target().createCDPSession();
await cdpClient.send('Browser.setDownloadBehavior', {
behavior: 'allow',
downloadPath: downloadsDir,
eventsEnabled: true,
});
}
/**
* Launch a Chrome instance with the test bundle loaded as an unpacked
* MV3 extension; wire downloads to a per-run temp dir; return all
* handles the harness needs. Caller MUST `await handles.browser.close()`.
*
* @param options - Optional overrides (mostly for isolation in tests).
* @returns Resolved handles to browser, extension, SW, page, downloadsDir.
* @throws If dist-test/ missing OR SW target never appears.
*/
export async function launchHarnessBrowser(
options: LaunchOptions = {},
): Promise<HarnessHandles> {
const distTestDir = options.distTestDir ?? DIST_TEST_DIR;
assertDistTestPresent(distTestDir);
const downloadsDir = options.downloadsDir ?? makeDownloadsDir();
const headless = resolveHeadless(options);
// Pre-flight: verify the operator's chrome binary supports the
// auto-select picker flag. The string is locale-specific; en_US
// uses "Entire screen". This pre-flight does NOT verify the locale
// matches — it only verifies Puppeteer can find a Chromium binary
// at all (a missing binary fails the launch with a confusing message
// otherwise).
// Suppress noisy `puppeteer --version` check; if it fails, the launch
// itself will surface the same diagnostic.
try {
execSync('node ./node_modules/puppeteer/lib/cjs/puppeteer/node/cli.js --help', {
stdio: 'ignore',
timeout: 5_000,
});
} catch {
// Best-effort. The actual launch will fail loudly if the binary is
// truly missing.
}
const browser = await puppeteer.launch({
enableExtensions: [distTestDir],
headless,
pipe: true,
args: [
'--no-sandbox',
// RESEARCH §9: auto-accept the screen-share picker so
// getDisplayMedia resolves without operator interaction. The
// literal string is en_US-locale-sensitive; tests/uat/README.md
// documents the fallback for other locales.
'--auto-select-desktop-capture-source=Entire screen',
// DO NOT add --use-fake-ui-for-media-stream (RESEARCH §9 Pitfall:
// conflicts with auto-select).
],
});
// Resolve the extension ID. Puppeteer 25's browser.extensions() returns
// a Map<id, Extension> with all enabled extensions — BUT the map is
// populated asynchronously after the extension's manifest loads.
// Empirically: extension appears within ~100ms on local hardware but
// the very first call right after launch returns Map(0). Poll until
// extension registers OR 5s elapses; surface a clear diagnostic on
// timeout (probably means dist-test/ is malformed).
let extensionsMap = await browser.extensions();
const POLL_TIMEOUT_MS = 5_000;
const POLL_INTERVAL_MS = 100;
const pollStart = Date.now();
while (extensionsMap.size === 0 && Date.now() - pollStart < POLL_TIMEOUT_MS) {
await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
extensionsMap = await browser.extensions();
}
const entries = [...extensionsMap];
if (entries.length === 0) {
await browser.close();
throw new Error(
`Puppeteer launched Chrome but no extensions loaded after ${POLL_TIMEOUT_MS}ms — ` +
`verify enableExtensions path points at a valid unpacked extension: ${distTestDir}. ` +
`Common causes: dist-test/ missing the manifest.json, manifest version mismatch ` +
`(Chrome requires MV3 — verify "manifest_version": 3), or chrome binary ` +
`incompatible with the unpacked extension shape.`,
);
}
const [extensionId, extension] = entries[0];
// Wait for the SW target to appear + capture its worker handle.
const sw = await waitForSwTarget(browser, extensionId);
// Give the SW's module init a tick to complete. Empirically the
// service-worker-loader.js → assets/index-*.js dynamic import
// resolves quickly, but `chrome.action.onClicked.addListener` (and
// the gated test-hook addListener monkey-patches) all run inside
// the module body — a brief settle ensures the hook surface is
// installed BEFORE the harness's first `sw.evaluate(() =>
// globalThis.__mokoshTest...)` query.
await new Promise((r) => setTimeout(r, 500));
// Pre-open a blank page; configure downloads. The blank page is
// also the page the harness uses for triggerExtensionAction.
const page = await browser.newPage();
await page.goto('about:blank');
await setDownloadBehavior(page, downloadsDir);
// Open the extension popup as a separate Page. This is the harness's
// primary chrome.* query surface — see tests/uat/lib/sw.ts file
// header for the architecture rationale. The popup page has full
// extension chrome.* access AND a stable Puppeteer lifetime. Loading
// the URL also wakes the SW (chrome-extension:// page load IS a SW
// wake-up event in MV3).
const popup = await browser.newPage();
await popup.goto(
`chrome-extension://${extensionId}/src/popup/index.html`,
{ waitUntil: 'domcontentloaded', timeout: 10_000 },
);
return {
browser,
extension,
extensionId,
sw,
downloadsDir,
page,
popup,
};
}