@uppercut-labs/electron-qa-measurements 0.1.0 → 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/README.md CHANGED
@@ -1,91 +1,93 @@
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
- Options for `measureCommandPalette`: `openSelector`, `key` (`k`), `modifier` (`meta` on macOS, `control` elsewhere), `runs` (6), `closeKey` (`Escape`), `settleMs` (300), `closeMs` (250).
56
-
57
- 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.
58
-
59
- Options for `typeAndRecord`: `field`, `text`, `pid` (current process), `gapMs` (25), `now`.
60
-
61
- 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.
62
-
63
- ## Key injection
64
-
65
- By default keys go through `webContents.sendInputEvent`. Pass `injector` to use something else.
66
-
67
- | Function | Meaning |
68
- | --- | --- |
69
- | `createInputEventInjector(webContents)` | The default: `keyDown`, `char` and `keyUp` events |
70
- | `createProtocolInjector(send)` | Keys through the DevTools protocol (`Input.dispatchKeyEvent`), where `send` is `(method, params) => webContents.debugger.sendCommand(method, params)`; the window never needs focus |
71
- | `emulatePageFocus(send)` | Makes the page behave as focused while its window is not, for use with the protocol injector |
72
- | `modifierForPlatform(platform?)` | `'meta'` for `darwin` or `macos`, otherwise `'control'` |
73
-
74
- A `KeyInjector` is `{ press(key, modifiers?) }`, and may be asynchronous.
75
-
76
- ## Reports and arguments
77
-
78
- | Function | Meaning |
79
- | --- | --- |
80
- | `writeJsonReport(file, value)` | Writes indented JSON, creating folders, and returns the absolute path |
81
- | `describeWindow(win)` | `{ bounds, visible, focused }` for whatever the window can answer |
82
- | `readArg(name, argv?)` | The value of `--name=value`, or `null` |
83
- | `createLatencyProbeScript(field, options?)` and other `*Script` exports | The page-side scripts, if you want to run them yourself |
84
-
85
- ## Errors
86
-
87
- `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`.
88
-
89
- ## License
90
-
91
- MIT
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
package/dist/scenarios.js CHANGED
@@ -1,6 +1,11 @@
1
1
  import { mkdir, writeFile } from 'node:fs/promises';
2
2
  import { dirname, resolve } from 'node:path';
3
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
+ }
4
9
  import { armPaletteScript, createLatencyProbeScript, focusFieldScript, paintScript, readFieldScript, readPaletteScript, readProbeScript, resetProbeScript, } from './probe.js';
5
10
  import { computeStats } from './stats.js';
6
11
  /** Types `text` into the field and measures key-event-to-frame latency for each key. */
@@ -8,7 +13,7 @@ export async function measureTyping(win, options) {
8
13
  const { field, text, gapMs = 35, settleMs = 400 } = options;
9
14
  const sleep = options.sleep ?? defaultSleep;
10
15
  const injector = resolveInjector(win.webContents, options);
11
- win.webContents.focus?.();
16
+ focusWindowIfNeeded(win, options);
12
17
  const focused = (await win.webContents.executeJavaScript(focusFieldScript(field))) === true;
13
18
  const installed = await win.webContents.executeJavaScript(createLatencyProbeScript(field, options));
14
19
  if (installed !== true)
@@ -89,7 +94,7 @@ export async function typeAndRecord(win, options) {
89
94
  const sleep = options.sleep ?? defaultSleep;
90
95
  const now = options.now ?? Date.now;
91
96
  const injector = resolveInjector(win.webContents, options);
92
- win.webContents.focus?.();
97
+ focusWindowIfNeeded(win, options);
93
98
  await win.webContents.executeJavaScript(focusFieldScript(field));
94
99
  const before = await readField(win, field);
95
100
  if (before === null)
package/dist/types.d.ts CHANGED
@@ -42,4 +42,11 @@ export interface CommonOptions {
42
42
  sleep?: (ms: number) => Promise<void>;
43
43
  /** Defaults to an injector that sends `webContents.sendInputEvent` events. */
44
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;
45
52
  }
package/package.json CHANGED
@@ -1,57 +1,57 @@
1
- {
2
- "name": "@uppercut-labs/electron-qa-measurements",
3
- "version": "0.1.0",
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
- }
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
+ }