@uppercut-labs/electron-qa-measurements 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Uppercut Labs
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,93 @@
1
- # Temporary Holding Version
2
-
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
1
+ # @uppercut-labs/electron-qa-measurements
2
+
3
+ Measures how an Electron window behaves under input: the time from a key event to the frame that shows its effect while typing into a field, the time to open a command palette, launch and first-frame times, and whether typed text survives a kill and relaunch. Every timing is reported with sample count, p50, p95 and max. The package reports numbers and does not decide what is acceptable.
4
+
5
+ The window is passed in, and only a few `BrowserWindow` and `webContents` methods are used, so the statistics and scenarios also run against a stand-in object in tests. Electron is an optional peer dependency and is never imported.
6
+
7
+ ```sh
8
+ npm install @uppercut-labs/electron-qa-measurements
9
+ ```
10
+
11
+ ```ts
12
+ import { app, BrowserWindow, screen } from 'electron';
13
+ import { generateText, measureCommandPalette, measureLaunchMarks, measureTyping, writeJsonReport } from '@uppercut-labs/electron-qa-measurements';
14
+
15
+ const launchedAt = Date.now();
16
+
17
+ async function runQa(win: BrowserWindow) {
18
+ const marks = await measureLaunchMarks(win, {
19
+ launchedAt,
20
+ getDisplay: (bounds) => {
21
+ const d = screen.getDisplayMatching(bounds!);
22
+ return { hz: d.displayFrequency, scale: d.scaleFactor };
23
+ },
24
+ });
25
+ const typing = await measureTyping(win, { field: '#search', text: generateText(220) });
26
+ const palette = await measureCommandPalette(win, { openSelector: '.palette' });
27
+ await writeJsonReport('qa-report.json', { marks, typing, palette });
28
+ app.quit();
29
+ }
30
+ ```
31
+
32
+ ## Statistics and text
33
+
34
+ | Function | Returns |
35
+ | --- | --- |
36
+ | `computeStats(values)` | `{ samples, p50, p95, max }` using nearest-rank percentiles, rounded to 0.1 ms; `{ samples: 0 }` for no data. Values that are not finite are ignored |
37
+ | `generateText(count, kind?)` | Deterministic text of exactly `count` characters; `kind` is `'prose'` (default) or `'digits'` (digits, `.`, `+`, `-`) |
38
+
39
+ ## Scenarios
40
+
41
+ Each scenario takes the window first. All accept `sleep` and `injector` options so they can run without real time or real input.
42
+
43
+ | Function | What it does |
44
+ | --- | --- |
45
+ | `measureTyping(win, options)` | Focuses the field, installs a page-side probe, types `text` and returns `{ latency, typed, fieldLengthAfter, interactionsOverThreshold, worstEventTimingMs, focused }`. `latency` runs from each key event's timestamp to the end of the frame that rendered the change |
46
+ | `measureCommandPalette(win, options)` | Presses the shortcut `runs` times and returns `{ open, samples, runs, missed }`. `open` runs from the key event to the frame in which `openSelector` matches |
47
+ | `measureLaunchMarks(win, options)` | Returns launch-to-load and launch-to-first-frame times, first contentful paint, optional display details and the result of an optional page-side `benchScript` |
48
+ | `typeAndRecord(win, options)` | Types into the field and returns `{ pid, expected, typed, lastKeyAt }` for an outside script to use when it kills the process |
49
+ | `checkRecovery(record, restoredText)` | Compares the text found after relaunch with the record: `exact`, `typedSurvived`, lengths, `commonPrefixLength` and `lostChars` |
50
+ | `readField(win, field)` | The text in the field, or `null` when no element matches |
51
+ | `reloadPage(win)` | Reloads and resolves on `did-finish-load` |
52
+
53
+ Options for `measureTyping`: `field` (CSS selector), `text`, `gapMs` (35), `settleMs` (400), `slowThresholdMs` (16, the platform minimum).
54
+
55
+ Every scenario that types also takes `focusWindow`. The default `sendInputEvent` injector needs the window focused, so without an `injector` the window is focused first; with an injector (such as `createProtocolInjector` with `emulatePageFocus`) it is not, because on macOS focusing the web contents makes the window the key window and takes the user's focus. Set `focusWindow` to override either default. Changed in 0.1.1: 0.1.0 always focused the window.
56
+
57
+ Options for `measureCommandPalette`: `openSelector`, `key` (`k`), `modifier` (`meta` on macOS, `control` elsewhere), `runs` (6), `closeKey` (`Escape`), `settleMs` (300), `closeMs` (250).
58
+
59
+ Options for `measureLaunchMarks`: `launchedAt` (epoch ms, required), `now`, `getDisplay(bounds)`, `benchScript`. Call it from the `did-finish-load` handler; `didFinishLoad` is the time it was called.
60
+
61
+ Options for `typeAndRecord`: `field`, `text`, `pid` (current process), `gapMs` (25), `now`.
62
+
63
+ A kill-and-relaunch check has three steps. In the first run, call `typeAndRecord` and write the record to a file. From outside, terminate the process by its `pid`. In the second run, call `readField` after the app has restored its state and pass the text to `checkRecovery` with the saved record.
64
+
65
+ ## Key injection
66
+
67
+ By default keys go through `webContents.sendInputEvent`. Pass `injector` to use something else.
68
+
69
+ | Function | Meaning |
70
+ | --- | --- |
71
+ | `createInputEventInjector(webContents)` | The default: `keyDown`, `char` and `keyUp` events |
72
+ | `createProtocolInjector(send)` | Keys through the DevTools protocol (`Input.dispatchKeyEvent`), where `send` is `(method, params) => webContents.debugger.sendCommand(method, params)`; the window never needs focus |
73
+ | `emulatePageFocus(send)` | Makes the page behave as focused while its window is not, for use with the protocol injector |
74
+ | `modifierForPlatform(platform?)` | `'meta'` for `darwin` or `macos`, otherwise `'control'` |
75
+
76
+ A `KeyInjector` is `{ press(key, modifiers?) }`, and may be asynchronous.
77
+
78
+ ## Reports and arguments
79
+
80
+ | Function | Meaning |
81
+ | --- | --- |
82
+ | `writeJsonReport(file, value)` | Writes indented JSON, creating folders, and returns the absolute path |
83
+ | `describeWindow(win)` | `{ bounds, visible, focused }` for whatever the window can answer |
84
+ | `readArg(name, argv?)` | The value of `--name=value`, or `null` |
85
+ | `createLatencyProbeScript(field, options?)` and other `*Script` exports | The page-side scripts, if you want to run them yourself |
86
+
87
+ ## Errors
88
+
89
+ `measureTyping` and `typeAndRecord` throw `Error('No element matches <selector>')` when the field is missing. `reloadPage` rejects when the window has no `reload` or `once`. `generateText` throws `RangeError` for a count that is not a non-negative integer. `measureLaunchMarks` does not throw for page errors; it stores them as `paintError` and `benchError`.
90
+
91
+ ## License
92
+
93
+ MIT
@@ -0,0 +1,5 @@
1
+ export type { Bounds, CommonOptions, InputEventLike, KeyInjector, Stats, WebContentsLike, WindowLike } from './types.js';
2
+ export { computeStats, generateText, type SampleKind } from './stats.js';
3
+ export { createInputEventInjector, createProtocolInjector, emulatePageFocus, modifierForPlatform, type ProtocolSend } from './input.js';
4
+ export { armPaletteScript, createLatencyProbeScript, focusFieldScript, paintScript, readFieldScript, readProbeScript, type ProbeOptions } from './probe.js';
5
+ export { checkRecovery, describeWindow, measureCommandPalette, measureLaunchMarks, measureTyping, readArg, readField, reloadPage, typeAndRecord, writeJsonReport, type DisplayInfo, type KillRecord, type KillRecordOptions, type LaunchMarks, type LaunchMarksOptions, type PaletteOptions, type PaletteResult, type RecoveryResult, type TypingOptions, type TypingResult, type WindowDescription, } from './scenarios.js';
package/dist/index.js ADDED
@@ -0,0 +1,4 @@
1
+ export { computeStats, generateText } from './stats.js';
2
+ export { createInputEventInjector, createProtocolInjector, emulatePageFocus, modifierForPlatform } from './input.js';
3
+ export { armPaletteScript, createLatencyProbeScript, focusFieldScript, paintScript, readFieldScript, readProbeScript } from './probe.js';
4
+ export { checkRecovery, describeWindow, measureCommandPalette, measureLaunchMarks, measureTyping, readArg, readField, reloadPage, typeAndRecord, writeJsonReport, } from './scenarios.js';
@@ -0,0 +1,16 @@
1
+ import type { CommonOptions, KeyInjector, WebContentsLike } from './types.js';
2
+ export declare const defaultSleep: (ms: number) => Promise<void>;
3
+ /** Key presses through `webContents.sendInputEvent`, which uses Chromium's input pipeline. */
4
+ export declare function createInputEventInjector(contents: Pick<WebContentsLike, 'sendInputEvent'>): KeyInjector;
5
+ export type ProtocolSend = (method: string, params?: Record<string, unknown>) => Promise<unknown>;
6
+ /**
7
+ * Key presses through the DevTools protocol (`Input.dispatchKeyEvent`). `send` is
8
+ * `(method, params) => webContents.debugger.sendCommand(method, params)`. Nothing
9
+ * is sent to the operating system, so the window never needs focus.
10
+ */
11
+ export declare function createProtocolInjector(send: ProtocolSend): KeyInjector;
12
+ /** Makes the page behave as focused although its window is not. Call once after attaching the debugger. */
13
+ export declare function emulatePageFocus(send: ProtocolSend): Promise<void>;
14
+ /** `meta` on macOS (`darwin`), `control` elsewhere: the usual command-palette modifier. */
15
+ export declare function modifierForPlatform(platform?: string): 'meta' | 'control';
16
+ export declare function resolveInjector(contents: WebContentsLike, options: CommonOptions): KeyInjector;
package/dist/input.js ADDED
@@ -0,0 +1,46 @@
1
+ const KEY_NAMES = { ' ': 'Space', '\n': 'Enter' };
2
+ export const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
3
+ /** Key presses through `webContents.sendInputEvent`, which uses Chromium's input pipeline. */
4
+ export function createInputEventInjector(contents) {
5
+ return {
6
+ press(key, modifiers) {
7
+ const keyCode = KEY_NAMES[key] ?? key;
8
+ const hasModifiers = !!modifiers && modifiers.length > 0;
9
+ const mods = hasModifiers ? { modifiers: [...modifiers] } : {};
10
+ const send = (event) => contents.sendInputEvent(event);
11
+ send({ type: 'keyDown', keyCode, ...mods });
12
+ // A character key also produces a `char` event so the text field receives it.
13
+ if (key.length === 1 && !hasModifiers)
14
+ send({ type: 'char', keyCode: key === '\n' ? '\r' : key });
15
+ send({ type: 'keyUp', keyCode, ...mods });
16
+ },
17
+ };
18
+ }
19
+ const MODIFIER_BITS = { alt: 1, control: 2, ctrl: 2, meta: 4, command: 4, shift: 8 };
20
+ /**
21
+ * Key presses through the DevTools protocol (`Input.dispatchKeyEvent`). `send` is
22
+ * `(method, params) => webContents.debugger.sendCommand(method, params)`. Nothing
23
+ * is sent to the operating system, so the window never needs focus.
24
+ */
25
+ export function createProtocolInjector(send) {
26
+ return {
27
+ async press(key, modifiers = []) {
28
+ const bits = modifiers.reduce((acc, m) => acc | (MODIFIER_BITS[m.toLowerCase()] ?? 0), 0);
29
+ const printable = key.length === 1 && bits === 0;
30
+ const base = { key: key === '\n' ? 'Enter' : key, modifiers: bits };
31
+ await send('Input.dispatchKeyEvent', printable ? { ...base, type: 'keyDown', text: key === '\n' ? '\r' : key } : { ...base, type: 'rawKeyDown' });
32
+ await send('Input.dispatchKeyEvent', { ...base, type: 'keyUp' });
33
+ },
34
+ };
35
+ }
36
+ /** Makes the page behave as focused although its window is not. Call once after attaching the debugger. */
37
+ export async function emulatePageFocus(send) {
38
+ await send('Emulation.setFocusEmulationEnabled', { enabled: true });
39
+ }
40
+ /** `meta` on macOS (`darwin`), `control` elsewhere: the usual command-palette modifier. */
41
+ export function modifierForPlatform(platform = process.platform) {
42
+ return platform === 'darwin' || platform === 'macos' ? 'meta' : 'control';
43
+ }
44
+ export function resolveInjector(contents, options) {
45
+ return options.injector ?? createInputEventInjector(contents);
46
+ }
@@ -0,0 +1,26 @@
1
+ /**
2
+ * Page-side scripts. Each is an expression for `webContents.executeJavaScript`.
3
+ * Results are kept on `window.__qaLatency`, `window.__qaSlow` and `window.__qaPalette`.
4
+ */
5
+ export interface ProbeOptions {
6
+ /** `PerformanceObserver` duration threshold for slow interactions, in ms. The platform minimum is 16. */
7
+ slowThresholdMs?: number;
8
+ }
9
+ /**
10
+ * Installs listeners on the field matched by `field` (a CSS selector). For each key it records the time from
11
+ * the key event's own timestamp to the end of the frame that rendered the resulting change.
12
+ * Safe to call again for the same element.
13
+ */
14
+ export declare function createLatencyProbeScript(field: string, options?: ProbeOptions): string;
15
+ export declare const resetProbeScript = "window.__qaLatency = []; window.__qaSlow = []; true";
16
+ export declare function readProbeScript(field: string): string;
17
+ export declare function focusFieldScript(field: string): string;
18
+ export declare function readFieldScript(field: string): string;
19
+ /**
20
+ * Arms a one-shot listener for the key chord. When the chord arrives, polls each frame until `openSelector`
21
+ * matches an element, then stores the time from the key event to the end of that frame in `window.__qaPalette`.
22
+ */
23
+ export declare function armPaletteScript(openSelector: string, key: string, modifier: 'control' | 'meta'): string;
24
+ export declare const readPaletteScript = "window.__qaPalette";
25
+ /** Resolves with the first-contentful-paint time and the clock after two animation frames. */
26
+ export declare const paintScript = "new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(() => resolve({\n fcp: (performance.getEntriesByName('first-contentful-paint')[0] || {}).startTime || null,\n timeOrigin: performance.timeOrigin,\n now: performance.now(),\n}))))";
package/dist/probe.js ADDED
@@ -0,0 +1,84 @@
1
+ /**
2
+ * Page-side scripts. Each is an expression for `webContents.executeJavaScript`.
3
+ * Results are kept on `window.__qaLatency`, `window.__qaSlow` and `window.__qaPalette`.
4
+ */
5
+ const q = (value) => JSON.stringify(value);
6
+ /**
7
+ * Installs listeners on the field matched by `field` (a CSS selector). For each key it records the time from
8
+ * the key event's own timestamp to the end of the frame that rendered the resulting change.
9
+ * Safe to call again for the same element.
10
+ */
11
+ export function createLatencyProbeScript(field, options = {}) {
12
+ const threshold = Math.max(16, options.slowThresholdMs ?? 16);
13
+ return `(() => {
14
+ const el = document.querySelector(${q(field)});
15
+ if (!el) return false;
16
+ if (window.__qaProbeFor === el) return true;
17
+ window.__qaProbeFor = el;
18
+ window.__qaLatency = [];
19
+ window.__qaSlow = [];
20
+ let keyAt = null;
21
+ el.addEventListener('keydown', (e) => { keyAt = e.timeStamp; }, true);
22
+ el.addEventListener('input', () => {
23
+ const t0 = keyAt;
24
+ if (t0 === null) return;
25
+ keyAt = null;
26
+ requestAnimationFrame(() => {
27
+ const channel = new MessageChannel();
28
+ channel.port1.onmessage = () => window.__qaLatency.push(performance.now() - t0);
29
+ channel.port2.postMessage(0);
30
+ });
31
+ }, true);
32
+ new PerformanceObserver((list) => {
33
+ for (const entry of list.getEntries()) if (entry.name === 'keydown' || entry.name === 'keypress' || entry.name === 'input') window.__qaSlow.push(entry.duration);
34
+ }).observe({ type: 'event', durationThreshold: ${threshold}, buffered: false });
35
+ return true;
36
+ })()`;
37
+ }
38
+ export const resetProbeScript = 'window.__qaLatency = []; window.__qaSlow = []; true';
39
+ export function readProbeScript(field) {
40
+ return `(() => { const el = document.querySelector(${q(field)}); return { lat: window.__qaLatency || [], slow: window.__qaSlow || [], length: el ? String(el.value ?? el.textContent ?? '').length : 0 }; })()`;
41
+ }
42
+ export function focusFieldScript(field) {
43
+ return `(() => {
44
+ const el = document.querySelector(${q(field)});
45
+ if (!el) return false;
46
+ el.focus();
47
+ if (typeof el.value === 'string' && el.setSelectionRange) el.setSelectionRange(el.value.length, el.value.length);
48
+ return document.activeElement === el;
49
+ })()`;
50
+ }
51
+ export function readFieldScript(field) {
52
+ return `(() => { const el = document.querySelector(${q(field)}); return el ? String(el.value ?? el.textContent ?? '') : null; })()`;
53
+ }
54
+ /**
55
+ * Arms a one-shot listener for the key chord. When the chord arrives, polls each frame until `openSelector`
56
+ * matches an element, then stores the time from the key event to the end of that frame in `window.__qaPalette`.
57
+ */
58
+ export function armPaletteScript(openSelector, key, modifier) {
59
+ const flag = modifier === 'meta' ? 'metaKey' : 'ctrlKey';
60
+ return `(() => {
61
+ window.__qaPalette = null;
62
+ window.addEventListener('keydown', function once(e) {
63
+ if (e.key.toLowerCase() !== ${q(key.toLowerCase())} || !e.${flag}) return;
64
+ window.removeEventListener('keydown', once, true);
65
+ const t0 = e.timeStamp;
66
+ const look = () => {
67
+ if (document.querySelector(${q(openSelector)})) {
68
+ const channel = new MessageChannel();
69
+ channel.port1.onmessage = () => { window.__qaPalette = performance.now() - t0; };
70
+ channel.port2.postMessage(0);
71
+ } else requestAnimationFrame(look);
72
+ };
73
+ requestAnimationFrame(look);
74
+ }, true);
75
+ return true;
76
+ })()`;
77
+ }
78
+ export const readPaletteScript = 'window.__qaPalette';
79
+ /** Resolves with the first-contentful-paint time and the clock after two animation frames. */
80
+ export const paintScript = `new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(() => resolve({
81
+ fcp: (performance.getEntriesByName('first-contentful-paint')[0] || {}).startTime || null,
82
+ timeOrigin: performance.timeOrigin,
83
+ now: performance.now(),
84
+ }))))`;
@@ -0,0 +1,131 @@
1
+ import { type ProbeOptions } from './probe.js';
2
+ import type { Bounds, CommonOptions, Stats, WindowLike } from './types.js';
3
+ export interface TypingOptions extends CommonOptions, ProbeOptions {
4
+ /** CSS selector of the text field, for example `#search`. */
5
+ field: string;
6
+ /** Characters to type, one key press each. */
7
+ text: string;
8
+ /** Wait between key presses. Default 35. */
9
+ gapMs?: number;
10
+ /** Wait after the last key before reading results. Default 400. */
11
+ settleMs?: number;
12
+ }
13
+ export interface TypingResult {
14
+ latency: Stats;
15
+ typed: number;
16
+ fieldLengthAfter: number;
17
+ /** Interactions the browser itself timed at or over the slow threshold. */
18
+ interactionsOverThreshold: number;
19
+ worstEventTimingMs: number;
20
+ /** Whether the field was the active element after the focus step. */
21
+ focused: boolean;
22
+ }
23
+ /** Types `text` into the field and measures key-event-to-frame latency for each key. */
24
+ export declare function measureTyping(win: WindowLike, options: TypingOptions): Promise<TypingResult>;
25
+ export interface PaletteOptions extends CommonOptions {
26
+ /** CSS selector that matches only while the palette is open. */
27
+ openSelector: string;
28
+ /** Key of the shortcut. Default `k`. */
29
+ key?: string;
30
+ /** Default: `meta` on macOS, `control` elsewhere. */
31
+ modifier?: 'control' | 'meta';
32
+ /** Number of open-close rounds. Default 6. */
33
+ runs?: number;
34
+ /** Key that closes the palette. Default `Escape`. */
35
+ closeKey?: string;
36
+ /** Wait for the palette to appear after the shortcut. Default 300. */
37
+ settleMs?: number;
38
+ /** Wait after the close key. Default 250. */
39
+ closeMs?: number;
40
+ }
41
+ export interface PaletteResult {
42
+ open: Stats;
43
+ samples: number[];
44
+ runs: number;
45
+ /** Rounds in which the palette never appeared. */
46
+ missed: number;
47
+ }
48
+ /** Presses the palette shortcut repeatedly and measures key-event-to-frame time until the palette is shown. */
49
+ export declare function measureCommandPalette(win: WindowLike, options: PaletteOptions): Promise<PaletteResult>;
50
+ export interface DisplayInfo {
51
+ hz?: number;
52
+ scale?: number;
53
+ primary?: boolean;
54
+ }
55
+ export interface LaunchMarksOptions {
56
+ /** Epoch ms when the process started, taken by the caller as early as it can. */
57
+ launchedAt: number;
58
+ /** Source of the current epoch ms. Default `Date.now`. */
59
+ now?: () => number;
60
+ /** Describes the display the window is on, for example from Electron's `screen`. */
61
+ getDisplay?: (bounds: Bounds | undefined) => DisplayInfo | undefined;
62
+ /** A script to run in the page after the first frame; its result is stored as `bench`. */
63
+ benchScript?: string;
64
+ }
65
+ export interface LaunchMarks {
66
+ launchedAt: number;
67
+ /** Epoch ms when this function was called; call it from the `did-finish-load` handler. */
68
+ didFinishLoad: number;
69
+ msLaunchToLoad: number;
70
+ paint?: {
71
+ fcp: number | null;
72
+ timeOrigin: number;
73
+ now: number;
74
+ };
75
+ /** Epoch ms of the second animation frame after load. */
76
+ firstFrameAfterLoad?: number;
77
+ msLaunchToFirstFrame?: number;
78
+ display?: DisplayInfo;
79
+ bench?: unknown;
80
+ paintError?: string;
81
+ benchError?: string;
82
+ }
83
+ /** Records launch-to-load and launch-to-first-frame times, and optionally runs a workload script in the page. */
84
+ export declare function measureLaunchMarks(win: WindowLike, options: LaunchMarksOptions): Promise<LaunchMarks>;
85
+ export interface KillRecordOptions extends CommonOptions {
86
+ field: string;
87
+ text: string;
88
+ /** Process id to report, so an outside script can terminate it. Default `process.pid`. */
89
+ pid?: number;
90
+ gapMs?: number;
91
+ now?: () => number;
92
+ }
93
+ export interface KillRecord {
94
+ pid: number;
95
+ /** The whole field value that should be there after recovery. */
96
+ expected: string;
97
+ typed: string;
98
+ lastKeyAt: number;
99
+ }
100
+ /** The text currently in the field, or null when no element matches. */
101
+ export declare function readField(win: WindowLike, field: string): Promise<string | null>;
102
+ /**
103
+ * Types into the field and returns what a later run must find. The caller writes the record,
104
+ * terminates the process from outside, relaunches, and compares with {@link checkRecovery}.
105
+ */
106
+ export declare function typeAndRecord(win: WindowLike, options: KillRecordOptions): Promise<KillRecord>;
107
+ export interface RecoveryResult {
108
+ exact: boolean;
109
+ /** The restored text ends with everything typed after the record's starting text. */
110
+ typedSurvived: boolean;
111
+ expectedLength: number;
112
+ restoredLength: number;
113
+ commonPrefixLength: number;
114
+ /** Characters of the expected text missing from the restored text, counted from the first difference. */
115
+ lostChars: number;
116
+ }
117
+ /** Compares the text restored after a relaunch with the record written before the kill. */
118
+ export declare function checkRecovery(record: Pick<KillRecord, 'expected' | 'typed'>, restored: string): RecoveryResult;
119
+ /** Reloads the page and resolves when it has loaded again. */
120
+ export declare function reloadPage(win: WindowLike): Promise<void>;
121
+ export interface WindowDescription {
122
+ bounds?: Bounds;
123
+ visible?: boolean;
124
+ focused?: boolean;
125
+ }
126
+ /** Bounds, visibility and focus of the window, for the report. */
127
+ export declare function describeWindow(win: WindowLike): WindowDescription;
128
+ /** Writes `value` as indented JSON, creating the folder when needed. Returns the absolute path. */
129
+ export declare function writeJsonReport(file: string, value: unknown): Promise<string>;
130
+ /** The value of `--name=value` in `argv`, or null. Default `argv` is `process.argv`. */
131
+ export declare function readArg(name: string, argv?: readonly string[]): string | null;
@@ -0,0 +1,149 @@
1
+ import { mkdir, writeFile } from 'node:fs/promises';
2
+ import { dirname, resolve } from 'node:path';
3
+ import { defaultSleep, modifierForPlatform, resolveInjector } from './input.js';
4
+ /** Focuses the window only when asked, or when the default injector needs it (see CommonOptions.focusWindow). */
5
+ function focusWindowIfNeeded(win, options) {
6
+ if (options.focusWindow ?? !options.injector)
7
+ win.webContents.focus?.();
8
+ }
9
+ import { armPaletteScript, createLatencyProbeScript, focusFieldScript, paintScript, readFieldScript, readPaletteScript, readProbeScript, resetProbeScript, } from './probe.js';
10
+ import { computeStats } from './stats.js';
11
+ /** Types `text` into the field and measures key-event-to-frame latency for each key. */
12
+ export async function measureTyping(win, options) {
13
+ const { field, text, gapMs = 35, settleMs = 400 } = options;
14
+ const sleep = options.sleep ?? defaultSleep;
15
+ const injector = resolveInjector(win.webContents, options);
16
+ focusWindowIfNeeded(win, options);
17
+ const focused = (await win.webContents.executeJavaScript(focusFieldScript(field))) === true;
18
+ const installed = await win.webContents.executeJavaScript(createLatencyProbeScript(field, options));
19
+ if (installed !== true)
20
+ throw new Error(`No element matches ${field}`);
21
+ await win.webContents.executeJavaScript(resetProbeScript);
22
+ for (const ch of text) {
23
+ await injector.press(ch);
24
+ await sleep(gapMs);
25
+ }
26
+ await sleep(settleMs);
27
+ const reading = (await win.webContents.executeJavaScript(readProbeScript(field)));
28
+ return {
29
+ latency: computeStats(reading.lat),
30
+ typed: [...text].length,
31
+ fieldLengthAfter: reading.length,
32
+ interactionsOverThreshold: reading.slow.length,
33
+ worstEventTimingMs: reading.slow.length ? Math.max(...reading.slow) : 0,
34
+ focused,
35
+ };
36
+ }
37
+ /** Presses the palette shortcut repeatedly and measures key-event-to-frame time until the palette is shown. */
38
+ export async function measureCommandPalette(win, options) {
39
+ const { openSelector, key = 'k', runs = 6, closeKey = 'Escape', settleMs = 300, closeMs = 250 } = options;
40
+ const modifier = options.modifier ?? modifierForPlatform();
41
+ const sleep = options.sleep ?? defaultSleep;
42
+ const injector = resolveInjector(win.webContents, options);
43
+ const samples = [];
44
+ for (let i = 0; i < runs; i++) {
45
+ await win.webContents.executeJavaScript(armPaletteScript(openSelector, key, modifier));
46
+ await injector.press(key.toUpperCase(), [modifier]);
47
+ await sleep(settleMs);
48
+ const value = await win.webContents.executeJavaScript(readPaletteScript);
49
+ if (typeof value === 'number')
50
+ samples.push(value);
51
+ await injector.press(closeKey);
52
+ await sleep(closeMs);
53
+ }
54
+ return { open: computeStats(samples), samples, runs, missed: runs - samples.length };
55
+ }
56
+ /** Records launch-to-load and launch-to-first-frame times, and optionally runs a workload script in the page. */
57
+ export async function measureLaunchMarks(win, options) {
58
+ const now = options.now ?? Date.now;
59
+ const didFinishLoad = now();
60
+ const marks = { launchedAt: options.launchedAt, didFinishLoad, msLaunchToLoad: didFinishLoad - options.launchedAt };
61
+ const display = options.getDisplay?.(win.getBounds?.());
62
+ if (display)
63
+ marks.display = display;
64
+ try {
65
+ const paint = (await win.webContents.executeJavaScript(paintScript));
66
+ marks.paint = paint;
67
+ marks.firstFrameAfterLoad = paint.timeOrigin + paint.now;
68
+ marks.msLaunchToFirstFrame = Math.round((marks.firstFrameAfterLoad - marks.launchedAt) * 10) / 10;
69
+ }
70
+ catch (error) {
71
+ marks.paintError = String(error);
72
+ }
73
+ if (options.benchScript) {
74
+ try {
75
+ marks.bench = await win.webContents.executeJavaScript(options.benchScript);
76
+ }
77
+ catch (error) {
78
+ marks.benchError = String(error);
79
+ }
80
+ }
81
+ return marks;
82
+ }
83
+ /** The text currently in the field, or null when no element matches. */
84
+ export async function readField(win, field) {
85
+ const value = await win.webContents.executeJavaScript(readFieldScript(field));
86
+ return typeof value === 'string' ? value : null;
87
+ }
88
+ /**
89
+ * Types into the field and returns what a later run must find. The caller writes the record,
90
+ * terminates the process from outside, relaunches, and compares with {@link checkRecovery}.
91
+ */
92
+ export async function typeAndRecord(win, options) {
93
+ const { field, text, gapMs = 25 } = options;
94
+ const sleep = options.sleep ?? defaultSleep;
95
+ const now = options.now ?? Date.now;
96
+ const injector = resolveInjector(win.webContents, options);
97
+ focusWindowIfNeeded(win, options);
98
+ await win.webContents.executeJavaScript(focusFieldScript(field));
99
+ const before = await readField(win, field);
100
+ if (before === null)
101
+ throw new Error(`No element matches ${field}`);
102
+ for (const ch of text) {
103
+ await injector.press(ch);
104
+ await sleep(gapMs);
105
+ }
106
+ return { pid: options.pid ?? process.pid, expected: before + text, typed: text, lastKeyAt: now() };
107
+ }
108
+ /** Compares the text restored after a relaunch with the record written before the kill. */
109
+ export function checkRecovery(record, restored) {
110
+ let common = 0;
111
+ const max = Math.min(record.expected.length, restored.length);
112
+ while (common < max && record.expected[common] === restored[common])
113
+ common++;
114
+ return {
115
+ exact: restored === record.expected,
116
+ typedSurvived: restored.endsWith(record.typed),
117
+ expectedLength: record.expected.length,
118
+ restoredLength: restored.length,
119
+ commonPrefixLength: common,
120
+ lostChars: record.expected.length - common,
121
+ };
122
+ }
123
+ /** Reloads the page and resolves when it has loaded again. */
124
+ export function reloadPage(win) {
125
+ const { webContents } = win;
126
+ if (!webContents.reload || !webContents.once)
127
+ return Promise.reject(new Error('webContents.reload and once are required'));
128
+ return new Promise((done) => {
129
+ webContents.once('did-finish-load', () => done());
130
+ webContents.reload();
131
+ });
132
+ }
133
+ /** Bounds, visibility and focus of the window, for the report. */
134
+ export function describeWindow(win) {
135
+ return { bounds: win.getBounds?.(), visible: win.isVisible?.(), focused: win.isFocused?.() };
136
+ }
137
+ /** Writes `value` as indented JSON, creating the folder when needed. Returns the absolute path. */
138
+ export async function writeJsonReport(file, value) {
139
+ const target = resolve(file);
140
+ await mkdir(dirname(target), { recursive: true });
141
+ await writeFile(target, JSON.stringify(value, null, 2));
142
+ return target;
143
+ }
144
+ /** The value of `--name=value` in `argv`, or null. Default `argv` is `process.argv`. */
145
+ export function readArg(name, argv = process.argv) {
146
+ const prefix = `--${name}=`;
147
+ const hit = argv.find((a) => a.startsWith(prefix));
148
+ return hit ? hit.slice(prefix.length) : null;
149
+ }
@@ -0,0 +1,6 @@
1
+ import type { Stats } from './types.js';
2
+ /** Nearest-rank percentiles of the finite values, rounded to 0.1 ms. */
3
+ export declare function computeStats(values: readonly number[]): Stats;
4
+ export type SampleKind = 'prose' | 'digits';
5
+ /** Deterministic text of exactly `count` characters to type into a field. */
6
+ export declare function generateText(count: number, kind?: SampleKind): string;
package/dist/stats.js ADDED
@@ -0,0 +1,25 @@
1
+ const round1 = (n) => Math.round(n * 10) / 10;
2
+ /** Nearest-rank percentiles of the finite values, rounded to 0.1 ms. */
3
+ export function computeStats(values) {
4
+ const sorted = values.filter((v) => Number.isFinite(v)).sort((a, b) => a - b);
5
+ if (sorted.length === 0)
6
+ return { samples: 0 };
7
+ const at = (q) => sorted[Math.min(sorted.length - 1, Math.max(0, Math.ceil(q * sorted.length) - 1))];
8
+ return { samples: sorted.length, p50: round1(at(0.5)), p95: round1(at(0.95)), max: round1(sorted[sorted.length - 1]) };
9
+ }
10
+ const WORDS = 'the quick brown fox jumps over the lazy dog while the mix is rendering and nobody is watching the meters'.split(' ');
11
+ const DIGIT_KEYS = '1234567890.+-';
12
+ /** Deterministic text of exactly `count` characters to type into a field. */
13
+ export function generateText(count, kind = 'prose') {
14
+ if (!Number.isInteger(count) || count < 0)
15
+ throw new RangeError('count must be a non-negative integer');
16
+ let out = '';
17
+ if (kind === 'digits') {
18
+ for (let i = 0; out.length < count; i++)
19
+ out += DIGIT_KEYS[(i * 7) % DIGIT_KEYS.length];
20
+ return out.slice(0, count);
21
+ }
22
+ for (let i = 0; out.length < count; i++)
23
+ out += (i % 14 === 13 ? '\n' : '') + WORDS[i % WORDS.length] + ' ';
24
+ return out.slice(0, count);
25
+ }
@@ -0,0 +1,52 @@
1
+ /** Summary of a set of timings in milliseconds. `samples` is 0 when there was nothing to measure. */
2
+ export interface Stats {
3
+ samples: number;
4
+ p50?: number;
5
+ p95?: number;
6
+ max?: number;
7
+ }
8
+ /** Presses keys in the page. `modifiers` use Electron's names: `control`, `meta`, `shift`, `alt`. */
9
+ export interface KeyInjector {
10
+ press(key: string, modifiers?: readonly string[]): void | Promise<void>;
11
+ }
12
+ export interface InputEventLike {
13
+ type: string;
14
+ keyCode: string;
15
+ modifiers?: string[];
16
+ }
17
+ /** The parts of Electron's `webContents` the measurements use. */
18
+ export interface WebContentsLike {
19
+ executeJavaScript(source: string): Promise<unknown>;
20
+ sendInputEvent(event: InputEventLike): void;
21
+ focus?(): void;
22
+ reload?(): void;
23
+ once?(event: string, listener: () => void): unknown;
24
+ }
25
+ export interface Bounds {
26
+ x: number;
27
+ y: number;
28
+ width: number;
29
+ height: number;
30
+ }
31
+ /** The parts of Electron's `BrowserWindow` the measurements use. A real `BrowserWindow` satisfies it. */
32
+ export interface WindowLike {
33
+ webContents: WebContentsLike;
34
+ getBounds?(): Bounds;
35
+ isVisible?(): boolean;
36
+ isFocused?(): boolean;
37
+ close?(): void;
38
+ }
39
+ /** Options every scenario accepts so tests can run without real time or real input. */
40
+ export interface CommonOptions {
41
+ /** Defaults to a `setTimeout` wait. */
42
+ sleep?: (ms: number) => Promise<void>;
43
+ /** Defaults to an injector that sends `webContents.sendInputEvent` events. */
44
+ injector?: KeyInjector;
45
+ /**
46
+ * Whether to call `webContents.focus()` before typing. On macOS that makes the window the key
47
+ * window, which takes the user's focus. The default `sendInputEvent` injector needs it, so the
48
+ * default is true without an `injector` and false with one (a protocol injector with
49
+ * `emulatePageFocus` reaches the page without the window ever being focused).
50
+ */
51
+ focusWindow?: boolean;
52
+ }
package/dist/types.js ADDED
@@ -0,0 +1 @@
1
+ export {};
package/package.json CHANGED
@@ -1,6 +1,57 @@
1
- {
2
- "name": "@uppercut-labs/electron-qa-measurements",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
1
+ {
2
+ "name": "@uppercut-labs/electron-qa-measurements",
3
+ "version": "0.1.1",
4
+ "description": "Measure typing latency, command-palette open time, launch marks and kill-and-relaunch recovery of an Electron window, with p50, p95 and max statistics.",
5
+ "license": "MIT",
6
+ "author": "Uppercut Labs <packages@uppercut-labs.com>",
7
+ "type": "module",
8
+ "exports": {
9
+ ".": {
10
+ "types": "./dist/index.d.ts",
11
+ "default": "./dist/index.js"
12
+ }
13
+ },
14
+ "main": "./dist/index.js",
15
+ "types": "./dist/index.d.ts",
16
+ "files": [
17
+ "dist",
18
+ "README.md",
19
+ "LICENSE"
20
+ ],
21
+ "sideEffects": false,
22
+ "scripts": {
23
+ "build": "tsc -p tsconfig.json",
24
+ "prepack": "node -e \"require('fs').copyFileSync('../../LICENSE','LICENSE')\""
25
+ },
26
+ "keywords": [
27
+ "electron",
28
+ "qa",
29
+ "latency",
30
+ "benchmark",
31
+ "typing",
32
+ "performance"
33
+ ],
34
+ "peerDependencies": {
35
+ "electron": ">=25"
36
+ },
37
+ "peerDependenciesMeta": {
38
+ "electron": {
39
+ "optional": true
40
+ }
41
+ },
42
+ "repository": {
43
+ "type": "git",
44
+ "url": "git+https://github.com/uppercut-labs/js-kit.git",
45
+ "directory": "packages/electron-qa-measurements"
46
+ },
47
+ "bugs": {
48
+ "url": "https://github.com/uppercut-labs/js-kit/issues"
49
+ },
50
+ "homepage": "https://github.com/uppercut-labs/js-kit/tree/main/packages/electron-qa-measurements#readme",
51
+ "engines": {
52
+ "node": ">=18"
53
+ },
54
+ "publishConfig": {
55
+ "access": "public"
56
+ }
57
+ }