recovery-probe 0.0.0-stage → 0.2.0

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/CHANGELOG.md ADDED
@@ -0,0 +1,18 @@
1
+ # Changelog
2
+
3
+ All notable changes to Recovery Probe are documented here. The project follows [Semantic Versioning](https://semver.org/).
4
+
5
+ Version 0.2.0 is the first npm release. Earlier 0.1.x revisions were repository-only prototypes.
6
+
7
+ ## [0.2.0] - 2026-09-22
8
+
9
+ ### Added
10
+
11
+ - Deterministic HTTP error, connection failure, and invalid JSON injection.
12
+ - Playwright `withFault` helper with bounded counts and route cleanup.
13
+ - Browser-independent `createFaultFetch` adapter.
14
+ - JSON-configured CLI runner with human-readable and machine-readable output.
15
+ - Broken-versus-fixed browser demonstration.
16
+ - Core, real-browser, package-installation, and TypeScript integration tests.
17
+
18
+ [0.2.0]: https://github.com/BojanKovachki/recovery-probe/releases/tag/v0.2.0
@@ -0,0 +1,39 @@
1
+ # Contributing
2
+
3
+ Thanks for helping make recovery checks easier to trust.
4
+
5
+ ## Before opening a change
6
+
7
+ - Use Node.js 22 or newer.
8
+ - Keep changes focused on deterministic request-level recovery testing.
9
+ - Open an issue first for new fault models or public API changes.
10
+ - Do not include real credentials, production URLs, request bodies, or response bodies in fixtures or reports.
11
+
12
+ ## Development setup
13
+
14
+ ```bash
15
+ npm ci
16
+ npm test
17
+ npm run test:package
18
+ npx playwright install chromium
19
+ npm run test:browser
20
+ ```
21
+
22
+ Run the controlled demonstrations when behavior or output changes:
23
+
24
+ ```bash
25
+ npm run demo
26
+ npm run demo:browser
27
+ ```
28
+
29
+ ## Pull requests
30
+
31
+ A useful pull request:
32
+
33
+ - explains the recovery behavior it covers;
34
+ - includes a failing test for a bug fix;
35
+ - preserves the distinction between failed, inconclusive, and skipped results;
36
+ - keeps fault injection bounded and verifies that the fault occurred;
37
+ - updates the README and changelog when the public interface changes.
38
+
39
+ By submitting a contribution, you agree that it is licensed under the project's MIT license.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Bojan Kovachki
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,206 @@
1
- # Temporary Holding Version
1
+ # Recovery Probe
2
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.
3
+ [![CI](https://github.com/BojanKovachki/recovery-probe/actions/workflows/validate.yml/badge.svg)](https://github.com/BojanKovachki/recovery-probe/actions/workflows/validate.yml)
4
+ [![npm](https://img.shields.io/npm/v/recovery-probe.svg)](https://www.npmjs.com/package/recovery-probe)
5
+ [![Node.js](https://img.shields.io/badge/Node.js-22%2B-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
6
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
7
+
8
+ **Deterministic fault injection for testing whether web applications actually recover after failed requests.**
9
+
10
+ A happy-path test can pass while a Retry button is completely broken. Recovery Probe adds a small, explicit workflow around Playwright routing and `fetch`: inject one controlled failure, exercise the application's recovery path, and prove that the intended fault really occurred.
11
+
12
+ ![Recovery Probe catches a broken retry flow and verifies the corrected flow](docs/demo.svg)
13
+
14
+ ## What it catches
15
+
16
+ Consider an application that loads normally, but forgets to clear its loading state after an error. Its ordinary end-to-end test stays green. After a transient `503`, interrupted request, or malformed response, Retry does nothing.
17
+
18
+ Recovery Probe makes that failure deterministic:
19
+
20
+ 1. Match one endpoint and request method.
21
+ 2. Inject a bounded fault without replacing global `fetch`.
22
+ 3. Run the real recovery interaction and assertion.
23
+ 4. Fail if the fault was never observed, so a wrong route cannot create a false positive.
24
+ 5. Remove only its own route handler and preserve existing mocks.
25
+
26
+ ## Install
27
+
28
+ Recovery Probe is designed to be added to an existing Playwright project:
29
+
30
+ ```bash
31
+ npm install --save-dev recovery-probe
32
+ ```
33
+
34
+ Node.js 22 or newer is required. Playwright is an optional peer dependency: the fetch-only API works without it, while the browser helper and CLI require Playwright 1.62.1 or newer.
35
+
36
+ ## Quick start
37
+
38
+ Use `withFault` inside an existing Playwright test. The callback contains the real user action and the application-specific recovery assertion.
39
+
40
+ ```js
41
+ import { test, expect } from '@playwright/test';
42
+ import { withFault } from 'recovery-probe';
43
+
44
+ test('profile recovers after a transient 503', async ({ page }) => {
45
+ const stats = await withFault(page, {
46
+ match: '**/api/profile',
47
+ kind: 'http-error',
48
+ status: 503,
49
+ count: 1,
50
+ }, async () => {
51
+ await page.goto('http://127.0.0.1:3000/profile');
52
+ await page.getByRole('button', { name: 'Retry' }).click();
53
+ await expect(page.getByTestId('profile-name')).toHaveText('Test User');
54
+ });
55
+
56
+ expect(stats.applied).toBe(1);
57
+ });
58
+ ```
59
+
60
+ If the endpoint does not match, Recovery Probe throws `FAULT_NOT_TRIGGERED` instead of allowing the test to pass silently. If the fault is applied but the recovery assertion fails, it throws `RECOVERY_ASSERTION_FAILED` and retains the original assertion error as `cause`.
61
+
62
+ ## Run the demonstration
63
+
64
+ The repository includes deliberately broken and corrected applications. Both pass their normal loading check; only the corrected application recovers from all three faults.
65
+
66
+ ```bash
67
+ npm install
68
+ npx playwright install chromium
69
+ npx recovery-probe --demo
70
+ ```
71
+
72
+ The command prints a concise comparison:
73
+
74
+ ```text
75
+ broken synthetic fixture
76
+ PASS Normal connection (OK)
77
+ CAUGHT HTTP 503 once (RECOVERY_ASSERTION_FAILED, injected 1)
78
+ CAUGHT Interrupted request once (RECOVERY_ASSERTION_FAILED, injected 1)
79
+ CAUGHT Malformed JSON once (RECOVERY_ASSERTION_FAILED, injected 1)
80
+
81
+ fixed synthetic fixture
82
+ PASS Normal connection (OK)
83
+ PASS HTTP 503 once (OK, injected 1)
84
+ PASS Interrupted request once (OK, injected 1)
85
+ PASS Malformed JSON once (OK, injected 1)
86
+ ```
87
+
88
+ `--demo` exits successfully only when it observes the expected contrast: the happy path passes, the broken recovery is caught, and the corrected flow passes. Add `--json` to print the full report or `--out report.json` to save it.
89
+
90
+ ## Supported faults
91
+
92
+ | Kind | Injected behavior |
93
+ | --- | --- |
94
+ | `http-error` | Fulfils the matched request with an HTTP error status; defaults to `503`. |
95
+ | `connection-failure` | Aborts the matched Playwright request with `connectionfailed`, or throws from the fetch adapter. |
96
+ | `invalid-json` | Returns status `200` with a deliberately malformed JSON body. |
97
+
98
+ Faults are bounded by `count` (default `1`, maximum `20`). The count is reserved synchronously, so concurrent matching requests cannot over-inject.
99
+
100
+ ## Fetch-only tests
101
+
102
+ The lightweight `recovery-probe/fetch` entry point has no runtime dependencies and does not require Playwright. It matches one exact absolute URL, including its query string, and never patches global `fetch`.
103
+
104
+ ```js
105
+ import { createFaultFetch } from 'recovery-probe/fetch';
106
+
107
+ const probe = createFaultFetch(fetch, {
108
+ url: 'http://127.0.0.1:3000/api/profile',
109
+ kind: 'connection-failure',
110
+ });
111
+
112
+ await exerciseApplication(probe.fetch);
113
+ probe.assertApplied();
114
+ ```
115
+
116
+ `exerciseApplication` represents your own test adapter or application controller. Calling `assertApplied()` is essential: it proves that every requested fault was consumed.
117
+
118
+ ## JSON-configured runner
119
+
120
+ The CLI supports pages that automatically load GET data, expose a visible Retry button after failure, and show a ready element after recovery.
121
+
122
+ ```json
123
+ {
124
+ "name": "Profile recovery",
125
+ "url": "http://127.0.0.1:3000/profile",
126
+ "requestPattern": "**/api/profile",
127
+ "readySelector": "[data-testid=profile-ready]",
128
+ "retrySelector": "[data-testid=profile-retry]",
129
+ "timeoutMs": 3000
130
+ }
131
+ ```
132
+
133
+ ```bash
134
+ npx recovery-probe --config recovery-probe.json --out artifacts/profile-recovery.json
135
+ ```
136
+
137
+ The runner first checks the normal baseline in a fresh browser context. If that baseline fails, fault comparisons are skipped and reported as inconclusive. Each fault then receives its own fresh context with service workers blocked so Playwright can intercept the request.
138
+
139
+ Exit codes:
140
+
141
+ - `0`: every configured check passed, or the controlled demo observed its expected broken-versus-fixed result.
142
+ - `1`: a recovery check failed, was inconclusive, or was skipped.
143
+ - `2`: invalid arguments, configuration, or environment setup.
144
+
145
+ ## Result semantics
146
+
147
+ | Code | Meaning |
148
+ | --- | --- |
149
+ | `OK` | The configured assertion completed and the expected fault count was observed. |
150
+ | `RECOVERY_ASSERTION_FAILED` | The fault occurred, but the recovery assertion did not pass. |
151
+ | `FAULT_NOT_TRIGGERED` | The requested fault count was not observed. Check the route, method, cache, and service worker. |
152
+ | `BASELINE_FAILED` | The ordinary flow failed, so the runner could not make a useful fault comparison. |
153
+ | `INJECTION_ERROR` | Playwright could not apply or clean up the route reliably. |
154
+
155
+ A passing result proves the configured recovery behavior for that test. It is not a certification of overall application resilience.
156
+
157
+ ## API
158
+
159
+ ### `withFault(page, options, exercise)`
160
+
161
+ Installs one temporary Playwright route, runs `exercise`, verifies the requested fault count, and removes only that route handler.
162
+
163
+ ```ts
164
+ interface FaultOptions {
165
+ match: string | RegExp;
166
+ kind: 'http-error' | 'connection-failure' | 'invalid-json';
167
+ status?: number;
168
+ count?: number;
169
+ method?: string;
170
+ }
171
+ ```
172
+
173
+ Register the fault after your own route mocks. The helper uses `route.fallback()` for requests it does not inject, allowing earlier handlers to continue processing them.
174
+
175
+ ### `createFaultFetch(baseFetch, options)`
176
+
177
+ Creates an isolated fetch wrapper for one exact URL and method. It returns `{ fetch, summary, assertApplied }` and leaves the supplied fetch function unchanged.
178
+
179
+ ### `probeRecovery(browser, config)`
180
+
181
+ Runs the baseline and the three default recovery checks used by the JSON CLI. For custom interactions or stronger assertions, prefer `withFault` inside your own test.
182
+
183
+ ## Scope
184
+
185
+ Recovery Probe deliberately focuses on deterministic request-level recovery checks. It does not simulate whole-device offline states, WebSocket interruptions, token expiry, browser sleep, slow-network profiles, or duplicate-submission safety.
186
+
187
+ Playwright already provides the routing primitives used here. Recovery Probe adds bounded recipes, fault-occurrence verification, cleanup, consistent result codes, a fetch adapter, and a runnable broken-versus-fixed example. If a few direct `page.route()` calls are clearer for your test, use them; this package is most useful when teams want the recovery pattern to be repeatable.
188
+
189
+ The runner requires explicit selectors and endpoint matching. It does not discover an application's recovery policy automatically. Reports contain structural outcomes and environment versions, not request bodies, response bodies, headers, or full target URLs. Recovery Probe sends no telemetry.
190
+
191
+ ## Development
192
+
193
+ ```bash
194
+ npm ci
195
+ npm test # 9 fetch/core tests
196
+ npm run test:package # isolated tarball install + TypeScript + CLI checks
197
+ npx playwright install chromium
198
+ npm run test:browser # 7 real-browser integration tests
199
+ npm run demo:browser
200
+ ```
201
+
202
+ CI runs package checks on Node.js 22 and 24, then runs the integration suite and controlled demo in Chromium. See [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution workflow and [SECURITY.md](SECURITY.md) for private vulnerability reporting.
203
+
204
+ ## License
205
+
206
+ [MIT](LICENSE) © 2026 Bojan Kovachki
package/SECURITY.md ADDED
@@ -0,0 +1,18 @@
1
+ # Security
2
+
3
+ ## Supported versions
4
+
5
+ Security fixes are applied to the latest published version of Recovery Probe.
6
+
7
+ ## Reporting a vulnerability
8
+
9
+ Please do not open a public issue for a suspected vulnerability.
10
+
11
+ Use [GitHub's private vulnerability reporting](https://github.com/BojanKovachki/recovery-probe/security/advisories/new) and include:
12
+
13
+ - the affected version;
14
+ - a minimal reproduction;
15
+ - the expected and observed behavior;
16
+ - any known impact.
17
+
18
+ Reports should not contain real credentials, production request data, or other sensitive application information. I aim to acknowledge reports within seven days.
@@ -0,0 +1,8 @@
1
+ #!/usr/bin/env node
2
+ import { mkdir, writeFile } from 'node:fs/promises';
3
+ import { runCoreDemo } from '../examples/core-demo.mjs';
4
+ const report = await runCoreDemo();
5
+ await mkdir('artifacts', { recursive: true });
6
+ await writeFile('artifacts/core-demo.json', JSON.stringify(report, null, 2) + '\n');
7
+ console.log(JSON.stringify(report, null, 2));
8
+ process.exitCode = report.expectedDemonstrationVerified ? 0 : 1;
@@ -0,0 +1,120 @@
1
+ #!/usr/bin/env node
2
+ import { readFile, writeFile, mkdir } from 'node:fs/promises';
3
+ import { dirname } from 'node:path';
4
+ import { probeRecovery } from '../src/index.mjs';
5
+ import { startDemoServer } from '../examples/demo-server.mjs';
6
+
7
+ const { version } = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
8
+
9
+ function printHelp() {
10
+ console.log(`Recovery Probe ${version}
11
+
12
+ Usage:
13
+ recovery-probe --demo [--out report.json] [--json]
14
+ recovery-probe --config scenario.json [--out report.json] [--json]
15
+ recovery-probe --version
16
+
17
+ Options:
18
+ --demo Run the included broken-versus-fixed browser demonstration.
19
+ --config <file> Check one JSON-configured recovery scenario.
20
+ --out <file> Save the full machine-readable report.
21
+ --json Print the full JSON report instead of a terminal summary.
22
+ --help Show this help.
23
+
24
+ Use only development or test targets you control.`);
25
+ }
26
+
27
+ function marker(outcome) {
28
+ if (outcome === 'pass') return 'PASS';
29
+ if (outcome === 'fail') return 'CAUGHT';
30
+ return outcome.toUpperCase();
31
+ }
32
+
33
+ function printSummary(report) {
34
+ console.log(`Recovery Probe ${report.version} — ${report.mode}\n`);
35
+ for (const app of report.apps) {
36
+ console.log(app.name);
37
+ for (const row of app.results) {
38
+ const injected = row.applied ? `, injected ${row.applied}` : '';
39
+ console.log(` ${marker(row.outcome).padEnd(12)} ${row.scenario} (${row.code}${injected})`);
40
+ }
41
+ console.log('');
42
+ }
43
+ if (report.mode === 'controlled demonstration') {
44
+ console.log(report.expectedDemonstrationVerified
45
+ ? 'Demo verified: the happy path passes, the broken recovery is caught, and the fixed app recovers.'
46
+ : 'Demo failed: the expected broken-versus-fixed distinction was not observed.');
47
+ } else {
48
+ console.log(report.apps.every(app => app.ok) ? 'Recovery check passed.' : 'Recovery check did not pass.');
49
+ }
50
+ }
51
+
52
+ async function main() {
53
+ const args = process.argv.slice(2);
54
+ if (args.includes('--help') || !args.length) {
55
+ printHelp();
56
+ return;
57
+ }
58
+ if (args.length === 1 && args[0] === '--version') {
59
+ console.log(version);
60
+ return;
61
+ }
62
+ let demo = false;
63
+ let json = false;
64
+ let configPath;
65
+ let output;
66
+ for (let i = 0; i < args.length; i++) {
67
+ const arg = args[i];
68
+ if (arg === '--demo') demo = true;
69
+ else if (arg === '--json') json = true;
70
+ else if (arg === '--config' || arg === '--out') {
71
+ const value = args[++i];
72
+ if (!value || value.startsWith('--')) throw new Error(`${arg} needs a value`);
73
+ if (arg === '--config') configPath = value; else output = value;
74
+ } else throw new Error(`Unknown argument: ${arg}`);
75
+ }
76
+ if (demo === Boolean(configPath)) throw new Error('Choose exactly one of --demo or --config');
77
+
78
+ const config = configPath ? JSON.parse(await readFile(configPath, 'utf8')) : null;
79
+ const { chromium } = await import('playwright');
80
+ const browser = await chromium.launch({ headless: true });
81
+ let server;
82
+ let report;
83
+ try {
84
+ const apps = [];
85
+ if (demo) {
86
+ server = await startDemoServer();
87
+ for (const variant of ['broken', 'fixed']) {
88
+ apps.push(await probeRecovery(browser, {
89
+ name: `${variant} synthetic fixture`, url: `${server.url}/${variant}`,
90
+ requestPattern: '**/api/profile', readySelector: '#profile', retrySelector: '#retry', timeoutMs: 1200,
91
+ }));
92
+ }
93
+ } else apps.push(await probeRecovery(browser, config));
94
+ report = {
95
+ tool: 'Recovery Probe', version, generatedAt: new Date().toISOString(),
96
+ environment: { node: process.version, platform: process.platform, chromium: browser.version() },
97
+ mode: demo ? 'controlled demonstration' : 'configured recovery check', apps,
98
+ };
99
+ if (demo) {
100
+ report.expectedDemonstrationVerified = apps[0].results[0].outcome === 'pass'
101
+ && apps[0].results.slice(1).every(row => row.outcome === 'fail' && row.applied === 1)
102
+ && apps[1].ok;
103
+ process.exitCode = report.expectedDemonstrationVerified ? 0 : 1;
104
+ } else process.exitCode = apps.every(app => app.ok) ? 0 : 1;
105
+ } finally {
106
+ await browser.close();
107
+ if (server) await server.close();
108
+ }
109
+ if (json) console.log(JSON.stringify(report, null, 2));
110
+ else printSummary(report);
111
+ if (output) {
112
+ await mkdir(dirname(output), { recursive: true });
113
+ await writeFile(output, JSON.stringify(report, null, 2) + '\n');
114
+ }
115
+ }
116
+
117
+ main().catch(error => {
118
+ console.error(`Recovery Probe: ${error.message}`);
119
+ process.exitCode = 2;
120
+ });
package/docs/demo.svg ADDED
@@ -0,0 +1,70 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="960" height="480" viewBox="0 0 960 480" role="img" aria-labelledby="title description">
2
+ <title id="title">Recovery Probe demonstration</title>
3
+ <desc id="description">A normal test passes for both applications. Recovery Probe catches three broken recovery paths and verifies the fixed application.</desc>
4
+ <defs>
5
+ <linearGradient id="background" x1="0" y1="0" x2="1" y2="1">
6
+ <stop offset="0" stop-color="#0b1220"/>
7
+ <stop offset="1" stop-color="#111c32"/>
8
+ </linearGradient>
9
+ <filter id="shadow" x="-20%" y="-20%" width="140%" height="140%">
10
+ <feDropShadow dx="0" dy="8" stdDeviation="12" flood-color="#020617" flood-opacity=".35"/>
11
+ </filter>
12
+ </defs>
13
+
14
+ <rect width="960" height="480" rx="24" fill="url(#background)"/>
15
+ <circle cx="44" cy="38" r="6" fill="#fb7185"/>
16
+ <circle cx="64" cy="38" r="6" fill="#fbbf24"/>
17
+ <circle cx="84" cy="38" r="6" fill="#34d399"/>
18
+ <text x="120" y="45" fill="#cbd5e1" font-family="ui-monospace, SFMono-Regular, Consolas, monospace" font-size="18">recovery-probe --demo</text>
19
+
20
+ <text x="54" y="102" fill="#f8fafc" font-family="Inter, system-ui, sans-serif" font-size="24" font-weight="700">The happy path passes in both apps</text>
21
+ <rect x="54" y="124" width="852" height="54" rx="12" fill="#16243d" stroke="#334155"/>
22
+ <circle cx="83" cy="151" r="11" fill="#10b981"/>
23
+ <path d="M78 151l4 4 7-8" fill="none" stroke="white" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"/>
24
+ <text x="108" y="158" fill="#e2e8f0" font-family="Inter, system-ui, sans-serif" font-size="18">Normal loading test</text>
25
+ <text x="824" y="158" fill="#6ee7b7" font-family="ui-monospace, SFMono-Regular, Consolas, monospace" font-size="15" font-weight="700">PASS</text>
26
+
27
+ <text x="54" y="229" fill="#f8fafc" font-family="Inter, system-ui, sans-serif" font-size="22" font-weight="700">Broken recovery</text>
28
+ <text x="533" y="229" fill="#f8fafc" font-family="Inter, system-ui, sans-serif" font-size="22" font-weight="700">Fixed recovery</text>
29
+
30
+ <g filter="url(#shadow)">
31
+ <rect x="54" y="247" width="373" height="156" rx="16" fill="#1b2034" stroke="#7f1d1d"/>
32
+ <rect x="533" y="247" width="373" height="156" rx="16" fill="#132b2a" stroke="#166534"/>
33
+ </g>
34
+
35
+ <g font-family="ui-monospace, SFMono-Regular, Consolas, monospace" font-size="15">
36
+ <circle cx="83" cy="281" r="10" fill="#e11d48"/>
37
+ <path d="M79 277l8 8m0-8l-8 8" stroke="white" stroke-width="2.2" stroke-linecap="round"/>
38
+ <text x="106" y="287" fill="#fecdd3">HTTP 503</text>
39
+ <text x="338" y="287" fill="#fb7185" font-weight="700">CAUGHT</text>
40
+
41
+ <circle cx="83" cy="325" r="10" fill="#e11d48"/>
42
+ <path d="M79 321l8 8m0-8l-8 8" stroke="white" stroke-width="2.2" stroke-linecap="round"/>
43
+ <text x="106" y="331" fill="#fecdd3">Connection failure</text>
44
+ <text x="338" y="331" fill="#fb7185" font-weight="700">CAUGHT</text>
45
+
46
+ <circle cx="83" cy="369" r="10" fill="#e11d48"/>
47
+ <path d="M79 365l8 8m0-8l-8 8" stroke="white" stroke-width="2.2" stroke-linecap="round"/>
48
+ <text x="106" y="375" fill="#fecdd3">Invalid JSON</text>
49
+ <text x="338" y="375" fill="#fb7185" font-weight="700">CAUGHT</text>
50
+
51
+ <circle cx="562" cy="281" r="10" fill="#10b981"/>
52
+ <path d="M557 281l4 4 7-8" fill="none" stroke="white" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"/>
53
+ <text x="585" y="287" fill="#d1fae5">HTTP 503</text>
54
+ <text x="832" y="287" fill="#6ee7b7" font-weight="700">PASS</text>
55
+
56
+ <circle cx="562" cy="325" r="10" fill="#10b981"/>
57
+ <path d="M557 325l4 4 7-8" fill="none" stroke="white" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"/>
58
+ <text x="585" y="331" fill="#d1fae5">Connection failure</text>
59
+ <text x="832" y="331" fill="#6ee7b7" font-weight="700">PASS</text>
60
+
61
+ <circle cx="562" cy="369" r="10" fill="#10b981"/>
62
+ <path d="M557 369l4 4 7-8" fill="none" stroke="white" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"/>
63
+ <text x="585" y="375" fill="#d1fae5">Invalid JSON</text>
64
+ <text x="832" y="375" fill="#6ee7b7" font-weight="700">PASS</text>
65
+ </g>
66
+
67
+ <path d="M447 325h58" stroke="#64748b" stroke-width="3" stroke-linecap="round"/>
68
+ <path d="M497 316l10 9-10 9" fill="none" stroke="#64748b" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>
69
+ <text x="54" y="444" fill="#94a3b8" font-family="Inter, system-ui, sans-serif" font-size="16">Same happy path. Different behavior under failure. Recovery Probe makes the difference visible.</text>
70
+ </svg>
@@ -0,0 +1,39 @@
1
+ import { readFile } from 'node:fs/promises';
2
+ import { createFaultFetch, defaultFaults } from '../src/index.mjs';
3
+ import { startDemoServer } from './demo-server.mjs';
4
+ import { createProfileController } from './profile-controller.mjs';
5
+
6
+ const { version } = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
7
+
8
+ export async function runCoreDemo() {
9
+ const server = await startDemoServer();
10
+ const endpoint = `${server.url}/api/profile`;
11
+ const apps = [];
12
+ try {
13
+ for (const fixed of [false, true]) {
14
+ const results = [];
15
+ const baseline = createProfileController(() => fetch(endpoint), { fixed });
16
+ await baseline.load();
17
+ results.push({ scenario: 'Normal connection', outcome: baseline.getState().phase === 'ready' ? 'pass' : 'fail', injected: 0 });
18
+ for (const fault of defaultFaults) {
19
+ const probe = createFaultFetch(fetch, { ...fault, url: endpoint });
20
+ const controller = createProfileController(() => probe.fetch(endpoint), { fixed });
21
+ await controller.load();
22
+ const afterFault = controller.getState().phase;
23
+ await controller.load();
24
+ const stats = probe.assertApplied();
25
+ results.push({ scenario: fault.name, outcome: controller.getState().phase === 'ready' ? 'pass' : 'fail', afterFault, afterRetry: controller.getState().phase, injected: stats.applied });
26
+ }
27
+ apps.push({ name: fixed ? 'Corrected controller' : 'Broken controller', results });
28
+ }
29
+ } finally { await server.close(); }
30
+ const expectedDemonstrationVerified = apps[0].results[0].outcome === 'pass'
31
+ && apps[0].results.slice(1).every(row => row.outcome === 'fail' && row.afterFault === 'error')
32
+ && apps[1].results.every(row => row.outcome === 'pass');
33
+ return {
34
+ tool: 'Recovery Probe', version, generatedAt: new Date().toISOString(),
35
+ runtime: { node: process.version, platform: process.platform },
36
+ scope: 'Fetch fault engine and shared application controller over local HTTP; no browser engine in this run.',
37
+ apps, expectedDemonstrationVerified,
38
+ };
39
+ }
@@ -0,0 +1,56 @@
1
+ import { createServer } from 'node:http';
2
+ import { readFile } from 'node:fs/promises';
3
+
4
+ function app(fixed) {
5
+ return `<!doctype html><html lang="en"><meta charset="utf-8"><title>Recovery Probe fixture</title>
6
+ <main><h1>Sample profile</h1><p id="status" role="status"></p><p id="profile" hidden></p><button id="retry" hidden>Retry</button></main>
7
+ <script type="module">
8
+ import { createProfileController } from '/profile-controller.mjs';
9
+ const status = document.querySelector('#status');
10
+ const profile = document.querySelector('#profile');
11
+ const retry = document.querySelector('#retry');
12
+ const controller = createProfileController(() => fetch('/api/profile'), {
13
+ fixed: ${fixed},
14
+ onChange(state) {
15
+ status.textContent = state.phase;
16
+ retry.hidden = state.phase !== 'error';
17
+ profile.hidden = state.phase !== 'ready';
18
+ profile.textContent = state.name ?? '';
19
+ },
20
+ });
21
+ retry.addEventListener('click', () => controller.load());
22
+ controller.load();
23
+ </script></html>`;
24
+ }
25
+
26
+ export async function startDemoServer() {
27
+ const controllerSource = await readFile(new URL('./profile-controller.mjs', import.meta.url), 'utf8');
28
+ const server = createServer((request, response) => {
29
+ const path = new URL(request.url, 'http://127.0.0.1').pathname;
30
+ response.setHeader('Cache-Control', 'no-store');
31
+ if (path === '/api/profile') {
32
+ response.writeHead(200, { 'Content-Type': 'application/json' });
33
+ response.end(JSON.stringify({ name: 'Synthetic Example', method: request.method }));
34
+ } else if (path === '/profile-controller.mjs') {
35
+ response.writeHead(200, { 'Content-Type': 'text/javascript; charset=utf-8' });
36
+ response.end(controllerSource);
37
+ } else if (path === '/broken' || path === '/fixed') {
38
+ response.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
39
+ response.end(app(path === '/fixed'));
40
+ } else {
41
+ response.writeHead(404);
42
+ response.end('Not found');
43
+ }
44
+ });
45
+ await new Promise((resolve, reject) => {
46
+ server.once('error', reject);
47
+ server.listen(0, '127.0.0.1', resolve);
48
+ });
49
+ return {
50
+ url: `http://127.0.0.1:${server.address().port}`,
51
+ close: () => new Promise((resolve, reject) => {
52
+ server.close(error => error ? reject(error) : resolve());
53
+ server.closeAllConnections();
54
+ }),
55
+ };
56
+ }
@@ -0,0 +1,26 @@
1
+ /** Synthetic application controller shared by the browser fixture and Node tests. */
2
+ export function createProfileController(fetchProfile, { fixed = true, onChange = () => {} } = {}) {
3
+ let pending = false;
4
+ let state = { phase: 'idle', name: null };
5
+ const setState = (next) => { state = next; onChange({ ...state }); };
6
+ return {
7
+ getState: () => ({ ...state }),
8
+ async load() {
9
+ if (pending) return;
10
+ pending = true;
11
+ setState({ phase: 'loading', name: null });
12
+ try {
13
+ const response = await fetchProfile();
14
+ if (!response.ok) throw new Error('Request failed');
15
+ const data = await response.json();
16
+ setState({ phase: 'ready', name: data.name });
17
+ pending = false;
18
+ } catch {
19
+ setState({ phase: 'error', name: null });
20
+ } finally {
21
+ // The broken fixture intentionally leaves pending set on failure.
22
+ if (fixed) pending = false;
23
+ }
24
+ },
25
+ };
26
+ }
package/package.json CHANGED
@@ -1,6 +1,84 @@
1
1
  {
2
2
  "name": "recovery-probe",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.2.0",
4
+ "type": "module",
5
+ "description": "Deterministic fault injection for testing recovery after failed requests.",
6
+ "license": "MIT",
7
+ "author": "Bojan Kovachki",
8
+ "homepage": "https://github.com/BojanKovachki/recovery-probe#readme",
9
+ "main": "./src/index.mjs",
10
+ "types": "./src/index.d.ts",
11
+ "exports": {
12
+ ".": {
13
+ "types": "./src/index.d.ts",
14
+ "import": "./src/index.mjs",
15
+ "default": "./src/index.mjs"
16
+ },
17
+ "./fetch": {
18
+ "types": "./src/fetch-fault.d.mts",
19
+ "import": "./src/fetch-fault.mjs",
20
+ "default": "./src/fetch-fault.mjs"
21
+ }
22
+ },
23
+ "bin": {
24
+ "recovery-probe": "bin/recovery-probe.mjs"
25
+ },
26
+ "files": [
27
+ "src",
28
+ "bin",
29
+ "examples",
30
+ "docs/demo.svg",
31
+ "CHANGELOG.md",
32
+ "CONTRIBUTING.md",
33
+ "SECURITY.md",
34
+ "README.md",
35
+ "LICENSE"
36
+ ],
37
+ "sideEffects": false,
38
+ "engines": {
39
+ "node": ">=22"
40
+ },
41
+ "peerDependencies": {
42
+ "playwright": "^1.62.1"
43
+ },
44
+ "peerDependenciesMeta": {
45
+ "playwright": {
46
+ "optional": true
47
+ }
48
+ },
49
+ "devDependencies": {
50
+ "@types/node": "24.13.6",
51
+ "playwright": "1.62.1",
52
+ "typescript": "7.0.2"
53
+ },
54
+ "repository": {
55
+ "type": "git",
56
+ "url": "git+https://github.com/BojanKovachki/recovery-probe.git"
57
+ },
58
+ "bugs": {
59
+ "url": "https://github.com/BojanKovachki/recovery-probe/issues"
60
+ },
61
+ "publishConfig": {
62
+ "access": "public"
63
+ },
64
+ "keywords": [
65
+ "playwright",
66
+ "testing",
67
+ "resilience",
68
+ "recovery",
69
+ "fault-injection",
70
+ "e2e",
71
+ "retry",
72
+ "fetch"
73
+ ],
74
+ "scripts": {
75
+ "test": "npm run test:core",
76
+ "test:core": "node --test test/fetch-core.test.mjs",
77
+ "test:browser": "node --test test/recovery.integration.test.mjs",
78
+ "test:package": "node --test test/package.integration.test.mjs",
79
+ "test:all": "npm run test:core && npm run test:package && npm run test:browser",
80
+ "demo": "node bin/core-demo.mjs",
81
+ "demo:browser": "node bin/recovery-probe.mjs --demo --out artifacts/browser-demo.json",
82
+ "prepublishOnly": "npm run test:core && npm run test:package"
83
+ }
84
+ }
@@ -0,0 +1,19 @@
1
+ export type FaultKind = 'http-error' | 'connection-failure' | 'invalid-json';
2
+ export interface FetchFaultOptions {
3
+ url: string;
4
+ kind: FaultKind;
5
+ status?: number;
6
+ count?: number;
7
+ method?: string;
8
+ }
9
+ export interface FetchFaultStats {
10
+ kind: FaultKind;
11
+ requested: number;
12
+ applied: number;
13
+ matchingRequests: number;
14
+ }
15
+ export function createFaultFetch(baseFetch: typeof fetch, options: FetchFaultOptions): {
16
+ fetch: typeof fetch;
17
+ summary(): FetchFaultStats;
18
+ assertApplied(): FetchFaultStats;
19
+ };
@@ -0,0 +1,54 @@
1
+ const kinds = new Set(['http-error', 'connection-failure', 'invalid-json']);
2
+
3
+ /** Fault-injected fetch for an exact, absolute URL. Each instance is isolated. */
4
+ export function createFaultFetch(baseFetch, options) {
5
+ if (typeof baseFetch !== 'function') throw new TypeError('baseFetch must be a function');
6
+ if (typeof options?.url !== 'string') throw new TypeError('url must be an absolute HTTP(S) URL');
7
+ const target = new URL(options.url);
8
+ if (!['http:', 'https:'].includes(target.protocol) || target.username || target.password) {
9
+ throw new TypeError('Use an absolute HTTP(S) URL without embedded credentials');
10
+ }
11
+ if (!kinds.has(options.kind)) throw new TypeError('Unsupported fault kind');
12
+ const count = options.count ?? 1;
13
+ const method = options.method ?? 'GET';
14
+ const status = options.status ?? 503;
15
+ if (!Number.isInteger(count) || count < 1 || count > 20) throw new TypeError('count must be an integer from 1 to 20');
16
+ if (!/^[A-Z]+$/.test(method)) throw new TypeError('method must be an uppercase HTTP method');
17
+ if (options.kind === 'http-error' && (!Number.isInteger(status) || status < 400 || status > 599)) {
18
+ throw new TypeError('HTTP fault status must be from 400 to 599');
19
+ }
20
+ let applied = 0;
21
+ let matchingRequests = 0;
22
+ const summary = () => ({ kind: options.kind, requested: count, applied, matchingRequests });
23
+
24
+ return {
25
+ summary,
26
+ assertApplied() {
27
+ if (applied !== count) {
28
+ const error = new Error(`Expected ${count} fault(s); observed ${applied}.`);
29
+ error.code = 'FAULT_NOT_TRIGGERED';
30
+ error.stats = summary();
31
+ throw error;
32
+ }
33
+ return summary();
34
+ },
35
+ async fetch(input, init) {
36
+ const inputUrl = input instanceof Request ? input.url : input;
37
+ const requestUrl = new URL(inputUrl);
38
+ const requestMethod = (init?.method ?? (input instanceof Request ? input.method : 'GET')).toUpperCase();
39
+ const signal = init?.signal ?? (input instanceof Request ? input.signal : undefined);
40
+ if (requestUrl.href !== target.href || requestMethod !== method || signal?.aborted) {
41
+ return baseFetch(input, init);
42
+ }
43
+ matchingRequests += 1;
44
+ if (applied >= count) return baseFetch(input, init);
45
+ // Reserve before any await so concurrent calls cannot over-inject.
46
+ applied += 1;
47
+ if (options.kind === 'connection-failure') throw new TypeError('Injected fetch connection failure');
48
+ if (options.kind === 'http-error') {
49
+ return new Response('{"error":"injected-test-fault"}', { status, headers: { 'Content-Type': 'application/json' } });
50
+ }
51
+ return new Response('{invalid-json', { status: 200, headers: { 'Content-Type': 'application/json' } });
52
+ },
53
+ };
54
+ }
package/src/index.d.ts ADDED
@@ -0,0 +1,26 @@
1
+ import type { Browser, Page } from 'playwright';
2
+ import type { FaultKind } from './fetch-fault.mjs';
3
+ export { createFaultFetch } from './fetch-fault.mjs';
4
+ export type { FaultKind, FetchFaultOptions, FetchFaultStats } from './fetch-fault.mjs';
5
+
6
+ export interface FaultOptions {
7
+ match: string | RegExp;
8
+ kind: FaultKind;
9
+ status?: number;
10
+ count?: number;
11
+ method?: string;
12
+ }
13
+ export interface FaultStats { kind: FaultKind; requested: number; applied: number; injectionErrors: number }
14
+ export class ProbeError extends Error { code: string; stats: FaultStats }
15
+ export const defaultFaults: readonly Readonly<{name: string; kind: FaultKind; status?: number}>[];
16
+ export function withFault(page: Page, options: FaultOptions, exercise: () => Promise<void>): Promise<FaultStats>;
17
+ export interface RecoveryConfig {
18
+ name?: string;
19
+ url: string;
20
+ requestPattern: string;
21
+ readySelector: string;
22
+ retrySelector: string;
23
+ timeoutMs?: number;
24
+ }
25
+ export interface ProbeRow { scenario: string; outcome: 'pass' | 'fail' | 'inconclusive' | 'skipped'; code: string; applied: number }
26
+ export function probeRecovery(browser: Browser, config: RecoveryConfig): Promise<{name: string; ok: boolean; results: ProbeRow[]}>;
package/src/index.mjs ADDED
@@ -0,0 +1,159 @@
1
+ export { createFaultFetch } from './fetch-fault.mjs';
2
+
3
+ const modes = new Set(['http-error', 'connection-failure', 'invalid-json']);
4
+
5
+ export const defaultFaults = Object.freeze([
6
+ Object.freeze({ name: 'HTTP 503 once', kind: 'http-error', status: 503 }),
7
+ Object.freeze({ name: 'Interrupted request once', kind: 'connection-failure' }),
8
+ Object.freeze({ name: 'Malformed JSON once', kind: 'invalid-json' }),
9
+ ]);
10
+
11
+ export class ProbeError extends Error {
12
+ constructor(code, message, stats, cause) {
13
+ super(message, cause ? { cause } : undefined);
14
+ this.name = 'ProbeError';
15
+ this.code = code;
16
+ this.stats = stats;
17
+ }
18
+ }
19
+
20
+ function checkFault(options) {
21
+ if (!options || !(typeof options.match === 'string' && options.match.trim() || options.match instanceof RegExp)) {
22
+ throw new TypeError('match must be a non-empty Playwright URL glob or RegExp');
23
+ }
24
+ if (!modes.has(options.kind)) throw new TypeError('Unsupported fault kind');
25
+ const count = options.count ?? 1;
26
+ if (!Number.isInteger(count) || count < 1 || count > 20) throw new TypeError('count must be an integer from 1 to 20');
27
+ const status = options.status ?? 503;
28
+ if (options.kind === 'http-error' && (!Number.isInteger(status) || status < 400 || status > 599)) {
29
+ throw new TypeError('HTTP fault status must be from 400 to 599');
30
+ }
31
+ const method = options.method ?? 'GET';
32
+ if (!/^[A-Z]+$/.test(method)) throw new TypeError('method must be an uppercase HTTP method');
33
+ return { count, status, method };
34
+ }
35
+
36
+ /** Inject a bounded fault for one explicitly matched endpoint, then restore routing. */
37
+ export async function withFault(page, options, exercise) {
38
+ const { count, status, method } = checkFault(options);
39
+ if (typeof exercise !== 'function') throw new TypeError('exercise must be a function');
40
+ let reserved = 0;
41
+ let applied = 0;
42
+ let injectionErrors = 0;
43
+ const pending = new Set();
44
+ const stats = () => ({ kind: options.kind, requested: count, applied, injectionErrors });
45
+
46
+ const handler = async (route) => {
47
+ if (route.request().method() !== method || reserved >= count) {
48
+ await route.fallback();
49
+ return;
50
+ }
51
+ // Reserve synchronously: concurrent matching requests cannot exceed the count.
52
+ reserved += 1;
53
+ const operation = (async () => {
54
+ try {
55
+ if (options.kind === 'connection-failure') {
56
+ await route.abort('connectionfailed');
57
+ } else if (options.kind === 'http-error') {
58
+ await route.fulfill({ status, contentType: 'application/json', body: '{"error":"injected-test-fault"}' });
59
+ } else {
60
+ await route.fulfill({ status: 200, contentType: 'application/json', body: '{invalid-json' });
61
+ }
62
+ applied += 1;
63
+ } catch {
64
+ injectionErrors += 1;
65
+ // Error details can contain URLs or credentials. Keep the report structural.
66
+ }
67
+ })();
68
+ pending.add(operation);
69
+ try { await operation; } finally { pending.delete(operation); }
70
+ };
71
+
72
+ await page.route(options.match, handler);
73
+ let exerciseError;
74
+ let exerciseFailed = false;
75
+ let cleanupError;
76
+ try {
77
+ await exercise();
78
+ } catch (error) {
79
+ exerciseFailed = true;
80
+ exerciseError = error;
81
+ } finally {
82
+ try {
83
+ // Remove only our handler; existing user mocks remain registered.
84
+ await page.unroute(options.match, handler);
85
+ } catch (error) { cleanupError = error; }
86
+ await Promise.allSettled([...pending]);
87
+ }
88
+
89
+ if (cleanupError || injectionErrors) {
90
+ throw new ProbeError('INJECTION_ERROR', 'The fault could not be applied or cleaned up reliably.', stats(), cleanupError);
91
+ }
92
+ if (applied !== count) {
93
+ throw new ProbeError('FAULT_NOT_TRIGGERED', `Expected ${count} injected request(s), observed ${applied}. Check the endpoint, method, cache and service workers.`, stats(), exerciseError);
94
+ }
95
+ if (exerciseFailed) {
96
+ throw new ProbeError('RECOVERY_ASSERTION_FAILED', 'The configured recovery expectation did not pass.', stats(), exerciseError);
97
+ }
98
+ return stats();
99
+ }
100
+
101
+ function checkScenario(config) {
102
+ for (const name of ['url', 'requestPattern', 'readySelector', 'retrySelector']) {
103
+ if (typeof config?.[name] !== 'string' || !config[name].trim()) throw new TypeError(`${name} is required`);
104
+ }
105
+ const parsed = new URL(config.url);
106
+ if (!['http:', 'https:'].includes(parsed.protocol)) throw new TypeError('url must use HTTP or HTTPS');
107
+ if (parsed.username || parsed.password) throw new TypeError('Credentials in the URL are unsupported');
108
+ const timeoutMs = config.timeoutMs ?? 3000;
109
+ if (!Number.isInteger(timeoutMs) || timeoutMs < 100 || timeoutMs > 60000) throw new TypeError('timeoutMs must be 100–60000');
110
+ return timeoutMs;
111
+ }
112
+
113
+ /** Check a read-only page that automatically loads data and exposes a Retry button. */
114
+ export async function probeRecovery(browser, config) {
115
+ const timeoutMs = checkScenario(config);
116
+ const results = [];
117
+ async function inPage(fn) {
118
+ const context = await browser.newContext({ serviceWorkers: 'block' });
119
+ try {
120
+ const page = await context.newPage();
121
+ page.setDefaultTimeout(timeoutMs);
122
+ page.setDefaultNavigationTimeout(timeoutMs);
123
+ return await fn(page);
124
+ } finally { await context.close(); }
125
+ }
126
+
127
+ let baselineError;
128
+ try {
129
+ await inPage(async page => {
130
+ await page.goto(config.url, { waitUntil: 'domcontentloaded' });
131
+ await page.locator(config.readySelector).waitFor({ state: 'visible' });
132
+ });
133
+ } catch (error) { baselineError = error; }
134
+ results.push({ scenario: 'Normal connection', outcome: baselineError ? 'inconclusive' : 'pass', code: baselineError ? 'BASELINE_FAILED' : 'OK', applied: 0 });
135
+
136
+ if (baselineError) {
137
+ for (const fault of defaultFaults) results.push({ scenario: fault.name, outcome: 'skipped', code: 'BASELINE_FAILED', applied: 0 });
138
+ } else {
139
+ for (const fault of defaultFaults) {
140
+ try {
141
+ const stats = await inPage(page => withFault(page, { ...fault, match: config.requestPattern }, async () => {
142
+ await page.goto(config.url, { waitUntil: 'domcontentloaded' });
143
+ await page.locator(config.retrySelector).waitFor({ state: 'visible' });
144
+ await page.locator(config.retrySelector).click();
145
+ await page.locator(config.readySelector).waitFor({ state: 'visible' });
146
+ }));
147
+ results.push({ scenario: fault.name, outcome: 'pass', code: 'OK', applied: stats.applied });
148
+ } catch (error) {
149
+ results.push({
150
+ scenario: fault.name,
151
+ outcome: error.code === 'RECOVERY_ASSERTION_FAILED' ? 'fail' : 'inconclusive',
152
+ code: error.code ?? 'RUNNER_ERROR',
153
+ applied: error.stats?.applied ?? 0,
154
+ });
155
+ }
156
+ }
157
+ }
158
+ return { name: config.name ?? 'Recovery check', ok: results.every(row => row.outcome === 'pass'), results };
159
+ }