Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
fix(ok): measure the QA-022 dock reveal, not the harness round trip (#4795)
Nick Gomez2b40f4a61fa0
diff --git a/packages/desktop/tests/smoke/_helpers/dock-reveal-latency.test.ts b/packages/desktop/tests/smoke/_helpers/dock-reveal-latency.test.tsnew file mode 100644index 000000000..7dff5fd9a--- /dev/null+++ b/packages/desktop/tests/smoke/_helpers/dock-reveal-latency.test.ts@@ -0,0 +1,346 @@+import { afterEach, describe, expect, test, vi } from 'vitest';+import {+ DOCK_REVEAL_BUDGET_MS,+ DOCK_REVEAL_WATCH_CEILING_MS,+ type DockRevealSample,+ dockRevealProbe,+ measureDockRevealMs,+ readDockRevealElapsed,+ watchForDockReveal,+} from './dock-reveal-latency';++const ARMED_AT = 1_000;+const REVEAL_SPAN_MS = 5;+const SLOW_TRIGGER_MS = 120;+const PANEL_ID = 'terminal-dock-panel';+const COLLAPSED = { width: 1280, height: 0 };+const EXPANDED = { width: 1280, height: 300 };++const sleep = (ms: number): Promise<void> =>+ new Promise((resolve) => {+ setTimeout(resolve, ms);+ });++const armed = (over: Partial<DockRevealSample> = {}): DockRevealSample => ({+ at: ARMED_AT,+ revealed: false,+ ...over,+});++interface FakePanel {+ box: { width: number; height: number };+ visibility: string;+ passesCheckVisibility: boolean;+}++const fakePanel = (over: Partial<FakePanel> = {}): FakePanel => ({+ box: { ...COLLAPSED },+ visibility: 'visible',+ passesCheckVisibility: true,+ ...over,+});++function mountFakeRenderer(panel: FakePanel | null, clock: { now: number }) {+ const element =+ panel === null+ ? null+ : {+ checkVisibility: () => panel.passesCheckVisibility,+ getBoundingClientRect: () => panel.box,+ };+ vi.stubGlobal('document', {+ getElementById: (id: string) => (id === PANEL_ID ? element : null),+ });+ vi.stubGlobal('getComputedStyle', () => ({ visibility: panel?.visibility ?? 'hidden' }));+ vi.stubGlobal('performance', { now: () => clock.now });+}++describe('dock reveal measurement', () => {+ const stubSteps = (over: Partial<Parameters<typeof measureDockRevealMs>[0]> = {}) => ({+ armProbe: () => Promise.resolve(armed()),+ watchForReveal: () => Promise.resolve(ARMED_AT + REVEAL_SPAN_MS),+ triggerReveal: () => Promise.resolve(),+ ...over,+ });++ test('starts watching before the toggle is dispatched', async () => {+ const order: string[] = [];++ await measureDockRevealMs(+ stubSteps({+ watchForReveal: () => {+ order.push('watch');+ return Promise.resolve(ARMED_AT + REVEAL_SPAN_MS);+ },+ triggerReveal: () => {+ order.push('trigger');+ return Promise.resolve();+ },+ }),+ );++ expect(order).toEqual(['watch', 'trigger']);+ });++ test('reports the stamp itself, whatever the trigger costs', async () => {+ const startedAt = Date.now();++ const measured = await measureDockRevealMs(+ stubSteps({+ watchForReveal: () => Promise.resolve(ARMED_AT + REVEAL_SPAN_MS),+ triggerReveal: () => sleep(SLOW_TRIGGER_MS),+ }),+ );++ expect(measured).toBe(REVEAL_SPAN_MS);+ expect(measured).toBeLessThan(Date.now() - startedAt);+ });++ test('reports the same span whether the trigger returns promptly or late', async () => {+ const measureWithTrigger = (triggerMs: number): Promise<number> =>+ measureDockRevealMs(stubSteps({ triggerReveal: () => sleep(triggerMs) }));++ expect(await measureWithTrigger(0)).toBe(await measureWithTrigger(SLOW_TRIGGER_MS));+ });++ test('surfaces a trigger failure as itself, not as a reveal timeout', async () => {+ await expect(+ measureDockRevealMs(+ stubSteps({+ watchForReveal: () => new Promise<number>(() => {}),+ triggerReveal: () => Promise.reject(new Error('View menu is missing the Terminal item')),+ }),+ ),+ ).rejects.toThrow(/View menu is missing the Terminal item/u);+ });++ test('an abandoned watch cannot resurface as an unhandled rejection', async () => {+ await expect(+ measureDockRevealMs(+ stubSteps({+ watchForReveal: () =>+ new Promise<number>((_resolve, reject) => {+ setTimeout(() => reject(new Error('watch abandoned after the trigger failed')), 10);+ }),+ triggerReveal: () => Promise.reject(new Error('View menu item missing')),+ }),+ ),+ ).rejects.toThrow(/View menu item missing/u);++ await sleep(60);+ });++ test('reports the abandoned watch reason without displacing the trigger failure', async () => {+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});++ try {+ await expect(+ measureDockRevealMs(+ stubSteps({+ watchForReveal: () => Promise.reject(new Error('panel never mounted')),+ triggerReveal: () =>+ new Promise<void>((_resolve, reject) => {+ setTimeout(() => reject(new Error('View menu item missing')), 0);+ }),+ }),+ ),+ ).rejects.toThrow(/View menu item missing/u);++ expect(warn).toHaveBeenCalledWith(expect.stringContaining('panel never mounted'));+ } finally {+ warn.mockRestore();+ }+ });++ test('does not report a watch failure the thrown error already carries', async () => {+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});++ try {+ await expect(+ measureDockRevealMs(+ stubSteps({+ watchForReveal: () =>+ Promise.reject(new Error('ended without a stamp inside its ceiling')),+ triggerReveal: () => Promise.resolve(),+ }),+ ),+ ).rejects.toThrow(/ended without a stamp inside its ceiling/u);++ expect(warn).not.toHaveBeenCalled();+ } finally {+ warn.mockRestore();+ }+ });++ test('refuses a vacuous reading before it watches or dispatches anything', async () => {+ let watches = 0;+ let triggers = 0;++ await expect(+ measureDockRevealMs(+ stubSteps({+ armProbe: () => Promise.resolve(armed({ revealed: true })),+ watchForReveal: () => {+ watches += 1;+ return Promise.resolve(ARMED_AT);+ },+ triggerReveal: () => {+ triggers += 1;+ return Promise.resolve();+ },+ }),+ ),+ ).rejects.toThrow(/already revealed when the probe was armed/u);++ expect([watches, triggers]).toEqual([0, 0]);+ });++ test('refuses a non-finite arm mark before it watches or dispatches anything', async () => {+ let watches = 0;+ let triggers = 0;++ await expect(+ measureDockRevealMs(+ stubSteps({+ armProbe: () => Promise.resolve(armed({ at: Number.NaN })),+ watchForReveal: () => {+ watches += 1;+ return Promise.resolve(0);+ },+ triggerReveal: () => {+ triggers += 1;+ return Promise.resolve();+ },+ }),+ ),+ ).rejects.toThrow(/non-finite mark/u);++ expect([watches, triggers]).toEqual([0, 0]);+ });++ test('refuses a reveal stamped before the probe armed', () => {+ const reading = readDockRevealElapsed(ARMED_AT, ARMED_AT - 1);+ expect(reading.revealed === false && reading.reason).toMatch(/before the probe armed/u);+ });++ test('refuses a non-finite stamp rather than reporting NaN as a measurement', () => {+ const reading = readDockRevealElapsed(ARMED_AT, Number.NaN);+ expect(reading.revealed === false && reading.reason).toMatch(/non-finite/u);+ });+});++describe('dock reveal probe reads the panel the way Playwright does', () => {+ afterEach(() => {+ vi.unstubAllGlobals();+ });++ test('a collapsed zero-height panel is not revealed, though it is in the DOM', () => {+ mountFakeRenderer(fakePanel({ box: { ...COLLAPSED } }), { now: ARMED_AT });++ expect(dockRevealProbe(['arm', PANEL_ID])).toEqual({ at: ARMED_AT, revealed: false });+ });++ test('an expanded panel at arm time is reported as already revealed', () => {+ mountFakeRenderer(fakePanel({ box: { ...EXPANDED } }), { now: ARMED_AT });++ expect(dockRevealProbe(['arm', PANEL_ID])).toEqual({ at: ARMED_AT, revealed: true });+ });++ test('a poll against a still-collapsed panel yields no stamp', () => {+ mountFakeRenderer(fakePanel({ box: { ...COLLAPSED } }), { now: ARMED_AT });++ expect(dockRevealProbe(['poll', PANEL_ID])).toBe(false);+ });++ test('a transition-only reveal is stamped, with no DOM mutation anywhere in it', () => {+ const clock = { now: ARMED_AT };+ const panel = fakePanel({ box: { ...COLLAPSED } });+ mountFakeRenderer(panel, clock);++ expect(dockRevealProbe(['poll', PANEL_ID])).toBe(false);++ clock.now = ARMED_AT + REVEAL_SPAN_MS;+ panel.box = { width: 1280, height: 1 };++ expect(dockRevealProbe(['poll', PANEL_ID])).toEqual({+ at: ARMED_AT + REVEAL_SPAN_MS,+ revealed: true,+ });+ });++ test('a sized panel hidden by visibility is not revealed', () => {+ mountFakeRenderer(fakePanel({ box: { ...EXPANDED }, visibility: 'hidden' }), { now: ARMED_AT });++ expect(dockRevealProbe(['poll', PANEL_ID])).toBe(false);+ });++ test('a sized panel that fails checkVisibility is not revealed', () => {+ mountFakeRenderer(fakePanel({ box: { ...EXPANDED }, passesCheckVisibility: false }), {+ now: ARMED_AT,+ });++ expect(dockRevealProbe(['poll', PANEL_ID])).toBe(false);+ });++ test('an absent panel is not revealed', () => {+ mountFakeRenderer(null, { now: ARMED_AT });++ expect(dockRevealProbe(['poll', PANEL_ID])).toBe(false);+ });+});++describe('dock reveal watch budget', () => {+ const pageWithNoWait = {+ waitForFunction: () => Promise.reject(new Error('waitForFunction must not be reached')),+ } as unknown as Parameters<typeof watchForDockReveal>[0];++ test.each([+ ['a negative ceiling', -1],+ ['a zero ceiling', 0],+ ['a NaN ceiling', Number.NaN],+ ])('rejects %s by naming the contract, not an already-elapsed deadline', async (_label, ms) => {+ await expect(watchForDockReveal(pageWithNoWait, PANEL_ID, ms)).rejects.toThrow(+ /positive ceiling/u,+ );+ });++ test('holds the watch ceiling above the asserted budget, so an over-budget reveal is measured rather than timed out', () => {+ expect(DOCK_REVEAL_WATCH_CEILING_MS).toBeGreaterThan(DOCK_REVEAL_BUDGET_MS);+ });++ test('names the ceiling and the panel when the watch ends with no stamp', async () => {+ const pageThatNeverReveals = {+ waitForFunction: () => Promise.reject(new Error('Timeout 2000ms exceeded')),+ } as unknown as Parameters<typeof watchForDockReveal>[0];++ await expect(watchForDockReveal(pageThatNeverReveals, PANEL_ID, 2000)).rejects.toThrow(+ /terminal-dock-panel.*2000 ms ceiling/su,+ );+ });++ test('a read that fails after the stamp exists is not reported as a missing stamp', async () => {+ const destroyed = 'Execution context was destroyed, most likely because of a navigation';+ const pageLosingItsContext = {+ waitForFunction: () =>+ Promise.resolve({ jsonValue: () => Promise.reject(new Error(destroyed)) }),+ } as unknown as Parameters<typeof watchForDockReveal>[0];++ const failure = await watchForDockReveal(pageLosingItsContext, PANEL_ID, 2000).then(+ () => new Error('the watch resolved where it had to reject'),+ (error: unknown) => error,+ );++ expect(failure).toBeInstanceOf(Error);+ expect((failure as Error).message).toBe(destroyed);+ });++ test('refuses a falsy poll sample in its own words rather than as a non-finite mark', async () => {+ const pageResolvingFalse = {+ waitForFunction: () => Promise.resolve({ jsonValue: () => Promise.resolve(false) }),+ } as unknown as Parameters<typeof watchForDockReveal>[0];++ await expect(watchForDockReveal(pageResolvingFalse, PANEL_ID, 2000)).rejects.toThrow(+ /resolved on a falsy sample for #terminal-dock-panel/u,+ );+ });+});diff --git a/packages/desktop/tests/smoke/_helpers/dock-reveal-latency.ts b/packages/desktop/tests/smoke/_helpers/dock-reveal-latency.tsnew file mode 100644index 000000000..c2410ca4a--- /dev/null+++ b/packages/desktop/tests/smoke/_helpers/dock-reveal-latency.ts@@ -0,0 +1,129 @@+import type { Page } from '@playwright/test';++export const DOCK_REVEAL_BUDGET_MS = 2_000;+export const DOCK_REVEAL_WATCH_CEILING_MS = 5_000;++export interface DockRevealSample {+ at: number;+ revealed: boolean;+}++export type DockRevealReading =+ | { readonly revealed: false; readonly reason: string }+ | { readonly revealed: true; readonly elapsedMs: number };++export interface DockRevealSteps {+ armProbe: () => Promise<DockRevealSample>;+ watchForReveal: () => Promise<number>;+ triggerReveal: () => Promise<void>;+}++export function dockRevealProbe(args: readonly ['arm', string]): DockRevealSample;+export function dockRevealProbe(args: readonly ['poll', string]): DockRevealSample | false;+export function dockRevealProbe([mode, panelId]: readonly ['arm' | 'poll', string]):+ | DockRevealSample+ | false {+ const isRevealed = (element: Element | null): boolean => {+ if (element === null) return false;+ if (!element.checkVisibility()) return false;+ if (getComputedStyle(element).visibility !== 'visible') return false;+ const box = element.getBoundingClientRect();+ return box.width > 0 && box.height > 0;+ };+ const revealed = isRevealed(document.getElementById(panelId));+ if (mode === 'poll' && !revealed) return false;+ return { at: performance.now(), revealed };+}++export function readDockRevealElapsed(armedAt: number, stampedAt: number): DockRevealReading {+ const pending = (reason: string): DockRevealReading => ({ revealed: false, reason });+ if (!Number.isFinite(stampedAt)) {+ return pending(`terminal dock reveal stamped a non-finite mark ${stampedAt}`);+ }+ if (stampedAt < armedAt) {+ return pending(+ `terminal dock reveal stamped ${stampedAt}, before the probe armed at ${armedAt}`,+ );+ }+ return { revealed: true, elapsedMs: stampedAt - armedAt };+}++export async function measureDockRevealMs({+ armProbe,+ watchForReveal,+ triggerReveal,+}: DockRevealSteps): Promise<number> {+ const armed = await armProbe();+ if (armed.revealed) {+ throw new Error(+ 'terminal dock was already revealed when the probe was armed, so the toggle revealed nothing',+ );+ }+ if (!Number.isFinite(armed.at)) {+ throw new Error(`dock reveal probe armed at a non-finite mark ${armed.at}`);+ }++ // STOP: the watch has to be polling before the toggle is dispatched. On every platform but darwin the trigger awaits an IPC round trip, and a watch started after it resolves reports that round trip as the reveal, which is the defect this helper exists to remove.+ const settled = watchForReveal().then(+ (stampedAt) => ({ stamped: true, stampedAt }) as const,+ (error: unknown) => ({ stamped: false, error }) as const,+ );+ try {+ await triggerReveal();+ } catch (triggerFailure) {+ void settled.then((abandoned) => {+ if (abandoned.stamped) return;+ const reason =+ abandoned.error instanceof Error ? abandoned.error.message : String(abandoned.error);+ console.warn(`[dock-reveal] terminal dock reveal watch failed: ${reason}`);+ });+ throw triggerFailure;+ }++ const outcome = await settled;+ if (!outcome.stamped) throw outcome.error;+ const reading = readDockRevealElapsed(armed.at, outcome.stampedAt);+ if (!reading.revealed) throw new Error(reading.reason);+ return reading.elapsedMs;+}++export async function armDockRevealProbe(page: Page, panelId: string): Promise<DockRevealSample> {+ const sample = await page.evaluate(dockRevealProbe, ['arm', panelId] as const);+ if (sample === false) {+ throw new Error(+ `dock reveal probe returned no arm sample for #${panelId}; arm mode always returns one, so the renderer ran a different probe than this module ships`,+ );+ }+ return sample;+}++export async function watchForDockReveal(+ page: Page,+ panelId: string,+ ceilingMs: number,+): Promise<number> {+ if (!(ceilingMs > 0)) {+ throw new Error(+ `watchForDockReveal needs a positive ceiling; received ${ceilingMs}. ` ++ `waitForFunction({ timeout: 0 }) waits without a deadline and fails as an unattributable test timeout.`,+ );+ }+ const handle = await page+ .waitForFunction(dockRevealProbe, ['poll', panelId] as const, {+ polling: 'raf',+ timeout: ceilingMs,+ })+ .catch((cause: unknown): never => {+ throw new Error(+ `terminal dock reveal watch on #${panelId} ended without a stamp inside its ${ceilingMs} ms ceiling`,+ { cause },+ );+ });+ const sample = await handle.jsonValue();+ if (sample === false) {+ throw new Error(+ `dock reveal poll resolved on a falsy sample for #${panelId}; waitForFunction resolves only on a truthy result, so the renderer ran a different probe than this module ships`,+ );+ }+ return sample.at;+}diff --git a/packages/desktop/tests/smoke/terminal-dock.e2e.ts b/packages/desktop/tests/smoke/terminal-dock.e2e.tsindex 6c9582b7f..9a3032260 100644--- a/packages/desktop/tests/smoke/terminal-dock.e2e.ts+++ b/packages/desktop/tests/smoke/terminal-dock.e2e.ts@@ -11,6 +11,13 @@ import { tmpdir } from 'node:os';import { basename, join } from 'node:path';import type { ElectronApplication, Locator, Page } from '@playwright/test';import { _electron as electron } from '@playwright/test';+import {+ armDockRevealProbe,+ DOCK_REVEAL_BUDGET_MS,+ DOCK_REVEAL_WATCH_CEILING_MS,+ measureDockRevealMs,+ watchForDockReveal,+} from './_helpers/dock-reveal-latency';import { desktopLaunchOptions, resolveDesktopTarget } from './_helpers/launch-desktop';import { launchDesktopApp, waitForWindowByMode } from './_helpers/launch-readiness';import {@@ -33,6 +40,8 @@ const TARGET = resolveDesktopTarget();const SMOKE_ENABLED = process.env.OK_DESKTOP_E2E_SMOKE === '1';const PRIMARY_MODIFIER = process.platform === 'darwin' ? 'Meta' : 'Control';const SHELL_COMMANDS = terminalSmokeShellCommands();+const TERMINAL_DOCK_PANEL_ID = 'terminal-dock-panel';+const TERMINAL_DOCK_PANEL_SELECTOR = `#${TERMINAL_DOCK_PANEL_ID}`;interface SeedOpts {consent?: boolean;@@ -637,7 +646,7 @@ test.describe('Docked terminal — live Electron', () => {await expectCollapsedRailColumn(page, '#terminal-column');});- test('QA-022 toggle reveals the dock within 2 seconds and mounts within 15 seconds', async ({+ test('QA-022 toggle reveals the dock and mounts the terminal inside their liveness budgets', async ({captureStderrFor,}) => {const s = seed('perf', { consent: true });@@ -649,13 +658,17 @@ test.describe('Docked terminal — live Electron', () => {await waitForRendererResponsive(page);const t0 = await page.evaluate(() => performance.now());- expect(await clickViewTerminalItem(app, page)).toBe('Show Terminal');- await page.waitForSelector('#terminal-dock-panel', {- state: 'visible',- timeout: 5_000,+ const dockElapsed = await measureDockRevealMs({+ armProbe: () => armDockRevealProbe(page, TERMINAL_DOCK_PANEL_ID),+ watchForReveal: () =>+ watchForDockReveal(page, TERMINAL_DOCK_PANEL_ID, DOCK_REVEAL_WATCH_CEILING_MS),+ triggerReveal: async () => {+ expect(await clickViewTerminalItem(app, page)).toBe('Show Terminal');+ },});- const dockElapsed = await page.evaluate((start) => performance.now() - start, t0);- expect(dockElapsed).toBeLessThan(2000);+ console.log(`[dock-reveal] revealMs=${dockElapsed.toFixed(1)}`);+ await expect(page.locator(TERMINAL_DOCK_PANEL_SELECTOR)).toBeVisible();+ expect(dockElapsed).toBeLessThan(DOCK_REVEAL_BUDGET_MS);const mountBudgetMs = 15_000;await page.waitForSelector('section[aria-label="Terminal"]', {