@9l/playwright 0.0.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 +12 -9
- package/dist/index.js +15 -0
- package/dist/prove.d.ts +30 -0
- package/dist/prove.js +182 -0
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -7,21 +7,24 @@ completing does not verify that behavior.
|
|
|
7
7
|
|
|
8
8
|
## Install
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
Published on [npm](https://www.npmjs.com/package/@9l/playwright):
|
|
11
11
|
|
|
12
12
|
```sh
|
|
13
|
-
npm install --save-dev @9l/playwright@0.
|
|
13
|
+
npm install --save-dev @9l/playwright@0.1.1 @playwright/test@1.64.0
|
|
14
14
|
npm exec playwright install chromium
|
|
15
15
|
```
|
|
16
16
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
17
|
+
Use Node 24 for the qualified runtime (Node 22 minimum), Playwright 1.61.1
|
|
18
|
+
through 1.64.0, and Chromium. macOS and Linux on amd64/arm64 are the qualified
|
|
19
|
+
runner targets. The peer range is `@playwright/test` `>=1.61.1 <2`; CI qualifies
|
|
20
|
+
every published release from 1.61.1 through 1.64.0 (1.61.1, 1.62.0, 1.62.1,
|
|
21
|
+
1.63.0 and 1.64.0). Later versions, and other browser engines, install but are
|
|
22
|
+
unqualified.
|
|
22
23
|
|
|
23
|
-
The Go `9l` executable is also required.
|
|
24
|
-
|
|
24
|
+
The Go `9l` executable is also required. Use the
|
|
25
|
+
[CLI installation guide](https://github.com/Quality-Max/9lives-runner/blob/main/docs/install.md)
|
|
26
|
+
for release availability or install from source with Go 1.25.13 or newer.
|
|
27
|
+
This npm package does not install Go or
|
|
25
28
|
bundle the runner, browsers or a hosted service. No platform account is needed.
|
|
26
29
|
|
|
27
30
|
## Use
|
package/dist/index.js
CHANGED
|
@@ -5,7 +5,22 @@ const test_1 = require("@playwright/test");
|
|
|
5
5
|
Object.defineProperty(exports, "expect", { enumerable: true, get: function () { return test_1.expect; } });
|
|
6
6
|
const protocol_1 = require("./protocol");
|
|
7
7
|
const goal_1 = require("./goal");
|
|
8
|
+
const prove_1 = require("./prove");
|
|
8
9
|
exports.test = test_1.test.extend({
|
|
10
|
+
// Outside `9l prove` this passes the context through unchanged. Overriding
|
|
11
|
+
// context, not adding an auto fixture, keeps tests that never use a browser
|
|
12
|
+
// from launching one.
|
|
13
|
+
context: async ({ context }, use, testInfo) => {
|
|
14
|
+
const channel = (0, prove_1.openProveChannel)(process.env, testInfo);
|
|
15
|
+
try {
|
|
16
|
+
if (channel)
|
|
17
|
+
await (0, prove_1.instrument)(context, channel);
|
|
18
|
+
await use(context);
|
|
19
|
+
}
|
|
20
|
+
finally {
|
|
21
|
+
channel?.close();
|
|
22
|
+
}
|
|
23
|
+
},
|
|
9
24
|
n9l: async ({ page }, use, testInfo) => {
|
|
10
25
|
(0, protocol_1.engineIdentity)();
|
|
11
26
|
await use({ goal: (instruction, options) => test_1.test.step('9l goal', () => {
|
package/dist/prove.d.ts
ADDED
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
import type { BrowserContext, Request } from '@playwright/test';
|
|
2
|
+
export declare const proveProtocol = "9l.prove/1";
|
|
3
|
+
export declare const faultKinds: readonly ["abort", "http-500", "empty-json"];
|
|
4
|
+
export type FaultKind = typeof faultKinds[number];
|
|
5
|
+
export type Target = {
|
|
6
|
+
method: string;
|
|
7
|
+
origin: string;
|
|
8
|
+
path: string;
|
|
9
|
+
};
|
|
10
|
+
export type Fault = Target & {
|
|
11
|
+
id: string;
|
|
12
|
+
kind: FaultKind;
|
|
13
|
+
};
|
|
14
|
+
export declare function requestTarget(request: Pick<Request, 'method' | 'url' | 'resourceType'>): Target | undefined;
|
|
15
|
+
export declare function matches(fault: Target, target: Target | undefined): boolean;
|
|
16
|
+
export declare function readFault(raw: string): Fault;
|
|
17
|
+
export declare class ProveChannel {
|
|
18
|
+
private fd;
|
|
19
|
+
readonly fault?: Fault | undefined;
|
|
20
|
+
private records;
|
|
21
|
+
private closed;
|
|
22
|
+
constructor(fd: number, fault?: Fault | undefined);
|
|
23
|
+
record(fields: Record<string, unknown>): void;
|
|
24
|
+
close(): void;
|
|
25
|
+
}
|
|
26
|
+
export declare function openProveChannel(env: NodeJS.ProcessEnv, testInfo: {
|
|
27
|
+
testId: string;
|
|
28
|
+
retry: number;
|
|
29
|
+
}): ProveChannel | undefined;
|
|
30
|
+
export declare function instrument(context: BrowserContext, channel: ProveChannel): Promise<void>;
|
package/dist/prove.js
ADDED
|
@@ -0,0 +1,182 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.ProveChannel = exports.faultKinds = exports.proveProtocol = void 0;
|
|
4
|
+
exports.requestTarget = requestTarget;
|
|
5
|
+
exports.matches = matches;
|
|
6
|
+
exports.readFault = readFault;
|
|
7
|
+
exports.openProveChannel = openProveChannel;
|
|
8
|
+
exports.instrument = instrument;
|
|
9
|
+
const node_crypto_1 = require("node:crypto");
|
|
10
|
+
const node_fs_1 = require("node:fs");
|
|
11
|
+
const node_path_1 = require("node:path");
|
|
12
|
+
const protocol_1 = require("./protocol");
|
|
13
|
+
// `9l prove` runs a spec once to observe its fetch/XHR requests, then once per
|
|
14
|
+
// injected network fault. Go owns the plan, budgets and verdicts; this module
|
|
15
|
+
// only records what the browser context did and applies the one named fault.
|
|
16
|
+
// Records go to a private per-test file that Go names and removes. They never
|
|
17
|
+
// enter the 9l.engine/1 stream, whose metadata excludes URLs by design.
|
|
18
|
+
exports.proveProtocol = '9l.prove/1';
|
|
19
|
+
exports.faultKinds = ['abort', 'http-500', 'empty-json'];
|
|
20
|
+
const maxRecords = 2000;
|
|
21
|
+
const maxRecordBytes = 4096;
|
|
22
|
+
const maxPathBytes = 2048;
|
|
23
|
+
const faultKeys = ['id', 'kind', 'method', 'origin', 'path'];
|
|
24
|
+
// Only fetch and XHR over http(s) are candidates. Query strings and fragments
|
|
25
|
+
// are dropped: one fault covers every request to the same method, origin and path.
|
|
26
|
+
function requestTarget(request) {
|
|
27
|
+
const type = request.resourceType();
|
|
28
|
+
if (type !== 'fetch' && type !== 'xhr')
|
|
29
|
+
return undefined;
|
|
30
|
+
let url;
|
|
31
|
+
try {
|
|
32
|
+
url = new URL(request.url());
|
|
33
|
+
}
|
|
34
|
+
catch {
|
|
35
|
+
return undefined;
|
|
36
|
+
}
|
|
37
|
+
if (url.protocol !== 'http:' && url.protocol !== 'https:')
|
|
38
|
+
return undefined;
|
|
39
|
+
const target = { method: request.method(), origin: url.origin, path: url.pathname };
|
|
40
|
+
return validTarget(target) ? target : undefined;
|
|
41
|
+
}
|
|
42
|
+
function validTarget(target) {
|
|
43
|
+
return /^[A-Z]{1,16}$/.test(target.method) && /^https?:\/\/[^/?#@\s]+$/.test(target.origin)
|
|
44
|
+
&& target.path.startsWith('/') && Buffer.byteLength(target.path) <= maxPathBytes
|
|
45
|
+
&& !/[\u0000-\u001f\u007f?#]/.test(target.path);
|
|
46
|
+
}
|
|
47
|
+
function matches(fault, target) {
|
|
48
|
+
return !!target && target.method === fault.method && target.origin === fault.origin && target.path === fault.path;
|
|
49
|
+
}
|
|
50
|
+
// The fault is Go-authored, but it crosses a process boundary: accept exactly
|
|
51
|
+
// the closed schema or refuse to run.
|
|
52
|
+
function readFault(raw) {
|
|
53
|
+
let value;
|
|
54
|
+
try {
|
|
55
|
+
value = JSON.parse(raw);
|
|
56
|
+
}
|
|
57
|
+
catch {
|
|
58
|
+
value = undefined;
|
|
59
|
+
}
|
|
60
|
+
const fault = value;
|
|
61
|
+
if (!value || typeof value !== 'object' || Array.isArray(value)
|
|
62
|
+
|| Object.keys(value).sort().join() !== [...faultKeys].sort().join()
|
|
63
|
+
|| typeof fault.id !== 'string' || !/^fault-[1-9][0-9]{0,3}$/.test(fault.id)
|
|
64
|
+
|| !exports.faultKinds.includes(fault.kind)
|
|
65
|
+
|| typeof fault.method !== 'string' || typeof fault.origin !== 'string' || typeof fault.path !== 'string'
|
|
66
|
+
|| !validTarget(fault)) {
|
|
67
|
+
throw new Error('9lives prove received an invalid fault');
|
|
68
|
+
}
|
|
69
|
+
return fault;
|
|
70
|
+
}
|
|
71
|
+
class ProveChannel {
|
|
72
|
+
fd;
|
|
73
|
+
fault;
|
|
74
|
+
records = 0;
|
|
75
|
+
closed = false;
|
|
76
|
+
constructor(fd, fault) {
|
|
77
|
+
this.fd = fd;
|
|
78
|
+
this.fault = fault;
|
|
79
|
+
}
|
|
80
|
+
record(fields) {
|
|
81
|
+
if (this.closed || this.records >= maxRecords)
|
|
82
|
+
return;
|
|
83
|
+
let line = JSON.stringify(fields) + '\n';
|
|
84
|
+
// A record that does not fit marks the file instead of being truncated.
|
|
85
|
+
if (++this.records === maxRecords || Buffer.byteLength(line) > maxRecordBytes) {
|
|
86
|
+
line = JSON.stringify({ type: 'overflow' }) + '\n';
|
|
87
|
+
this.records = maxRecords;
|
|
88
|
+
}
|
|
89
|
+
(0, node_fs_1.writeSync)(this.fd, line);
|
|
90
|
+
}
|
|
91
|
+
close() {
|
|
92
|
+
if (this.closed)
|
|
93
|
+
return;
|
|
94
|
+
this.closed = true;
|
|
95
|
+
(0, node_fs_1.closeSync)(this.fd);
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
exports.ProveChannel = ProveChannel;
|
|
99
|
+
// Returns undefined outside `9l prove`, so ordinary runs are untouched.
|
|
100
|
+
function openProveChannel(env, testInfo) {
|
|
101
|
+
if (env.NINELIVES_PROVE === undefined)
|
|
102
|
+
return undefined;
|
|
103
|
+
if (env.NINELIVES_PROVE !== exports.proveProtocol) {
|
|
104
|
+
throw new Error('9lives prove requires a supported Go engine; run this spec with 9l prove');
|
|
105
|
+
}
|
|
106
|
+
(0, protocol_1.engineIdentity)(env);
|
|
107
|
+
const dir = env.NINELIVES_PROVE_DIR;
|
|
108
|
+
if (!dir || !(0, node_path_1.isAbsolute)(dir))
|
|
109
|
+
throw new Error('9lives prove requires an engine evidence directory');
|
|
110
|
+
const fault = env.NINELIVES_PROVE_FAULT === undefined ? undefined : readFault(env.NINELIVES_PROVE_FAULT);
|
|
111
|
+
// One exclusive file per worker process and test attempt; never appended to.
|
|
112
|
+
const name = (0, node_crypto_1.createHash)('sha256').update(`${process.pid}\0${testInfo.testId}\0${testInfo.retry}`).digest('hex').slice(0, 32);
|
|
113
|
+
const channel = new ProveChannel((0, node_fs_1.openSync)((0, node_path_1.join)(dir, `${name}.ndjson`), 'wx', 0o600), fault);
|
|
114
|
+
// The handshake names the test attempt with the same hashed ID the engine
|
|
115
|
+
// reporter uses, so Go can judge each test separately and notice retries.
|
|
116
|
+
const testId = (0, node_crypto_1.createHash)('sha256').update(testInfo.testId).digest('hex');
|
|
117
|
+
channel.record({ type: 'hello', protocol: exports.proveProtocol, mode: fault ? 'fault' : 'observe', testId, retry: testInfo.retry });
|
|
118
|
+
return channel;
|
|
119
|
+
}
|
|
120
|
+
function emptyLike(text) {
|
|
121
|
+
let value;
|
|
122
|
+
try {
|
|
123
|
+
value = JSON.parse(text);
|
|
124
|
+
}
|
|
125
|
+
catch {
|
|
126
|
+
return undefined;
|
|
127
|
+
}
|
|
128
|
+
if (Array.isArray(value))
|
|
129
|
+
return '[]';
|
|
130
|
+
return value !== null && typeof value === 'object' ? '{}' : undefined;
|
|
131
|
+
}
|
|
132
|
+
function isJSON(contentType) {
|
|
133
|
+
const media = (contentType ?? '').split(';')[0].trim().toLowerCase();
|
|
134
|
+
return media.endsWith('/json') || media.endsWith('+json');
|
|
135
|
+
}
|
|
136
|
+
async function instrument(context, channel) {
|
|
137
|
+
const fault = channel.fault;
|
|
138
|
+
if (!fault) {
|
|
139
|
+
// Observation is passive: listeners only, so the baseline run is unchanged.
|
|
140
|
+
context.on('request', request => {
|
|
141
|
+
const target = requestTarget(request);
|
|
142
|
+
if (target)
|
|
143
|
+
channel.record({ type: 'request', ...target, resourceType: request.resourceType() });
|
|
144
|
+
});
|
|
145
|
+
context.on('response', response => {
|
|
146
|
+
const target = requestTarget(response.request());
|
|
147
|
+
if (target)
|
|
148
|
+
channel.record({ type: 'response', ...target, status: response.status(), json: isJSON(response.headers()['content-type']) });
|
|
149
|
+
});
|
|
150
|
+
return;
|
|
151
|
+
}
|
|
152
|
+
// Registered when the context is created, so routes the test adds later run
|
|
153
|
+
// first; a request the test fulfills itself is never faulted.
|
|
154
|
+
await context.route('**/*', async (route) => {
|
|
155
|
+
if (!matches(fault, requestTarget(route.request())))
|
|
156
|
+
return route.fallback();
|
|
157
|
+
// Credit a fault only once Playwright has delivered it: a request the
|
|
158
|
+
// page already cancelled rejects here, and must not count as applied.
|
|
159
|
+
const applied = () => channel.record({ type: 'applied', fault: fault.id });
|
|
160
|
+
if (fault.kind === 'abort')
|
|
161
|
+
return route.abort('failed').then(applied);
|
|
162
|
+
if (fault.kind === 'http-500')
|
|
163
|
+
return route.fulfill({ status: 500, body: '' }).then(applied);
|
|
164
|
+
// empty-json needs the real response first; say why when it cannot be
|
|
165
|
+
// replaced: the upstream was unreachable, or the body was not an object
|
|
166
|
+
// or array.
|
|
167
|
+
let response;
|
|
168
|
+
try {
|
|
169
|
+
response = await route.fetch();
|
|
170
|
+
}
|
|
171
|
+
catch {
|
|
172
|
+
channel.record({ type: 'not-applicable', fault: fault.id, reason: 'unreachable' });
|
|
173
|
+
return route.continue().catch(() => { });
|
|
174
|
+
}
|
|
175
|
+
const empty = emptyLike(await response.text().catch(() => ''));
|
|
176
|
+
if (empty === undefined) {
|
|
177
|
+
channel.record({ type: 'not-applicable', fault: fault.id, reason: 'not-json' });
|
|
178
|
+
return route.fulfill({ response });
|
|
179
|
+
}
|
|
180
|
+
return route.fulfill({ response, body: empty }).then(applied);
|
|
181
|
+
});
|
|
182
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@9l/playwright",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.1.1",
|
|
4
4
|
"description": "Playwright fixtures and the versioned 9lives Go engine bridge",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"homepage": "https://github.com/Quality-Max/9lives-runner#local-playwright-sdk",
|
|
@@ -19,7 +19,7 @@
|
|
|
19
19
|
},
|
|
20
20
|
"files": ["dist", "LICENSE", "NOTICE", "README.md"],
|
|
21
21
|
"scripts": {"build": "tsc -p tsconfig.json"},
|
|
22
|
-
"peerDependencies": {"@playwright/test": "1.61.1"},
|
|
22
|
+
"peerDependencies": {"@playwright/test": ">=1.61.1 <2"},
|
|
23
23
|
"engines": {"node": ">=22"},
|
|
24
24
|
"publishConfig": {"access": "public"}
|
|
25
25
|
}
|