Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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"]', {