methandle

methandle tests how your frontend handles API failures along a Playwright journey.

methandle is an experimental, local-first OSS alpha for automatic frontend failure-state coverage. Give it one trusted browser journey. It discovers the first-party API dependencies behind that journey, verifies a clean replay, mutates one dependency at a time, and renders the result as a Failure Matrix.

It is not a generic chaos framework, autonomous crawler, AI QA agent, Playwright replacement, or hosted testing service.

Quickstart

Install the alpha in the application that owns the journey:

npm install -D methandle
npx playwright install chromium

Create a small journey module:

// checkout.journey.ts
import type { Page } from 'playwright';

export async function journey(page: Page) {
  await page.goto('/checkout');
  await page.getByRole('button', { name: 'Place order' }).click();
}

The repository contains the same minimal shape at examples/checkout.journey.ts.

Run it while the application server is available:

npx methandle check ./checkout.journey.ts \
  --base-url http://localhost:3000

The command runs one live baseline, records a local HAR, verifies strict replay, and only then runs the fault sweep. The default artifacts are written to .methandle/.

Failure Matrix

The terminal result is organized by discovered dependency and injected fault:

Failure Matrix

Dependency                 HTTP 500       ABORT
-------------------------  -------------  ----------
GET /api/profile           BROKEN / HIGH  NO FINDING
GET /api/cart              BROKEN / HIGH  NO FINDING
GET /api/address           NO FINDING     BROKEN / HIGH
POST /api/checkout         BROKEN / HIGH  NO FINDING

Each cell is an experiment. The JSON result also keeps the raw observation, request evidence, page and console errors, visible text, loading signals, screenshots, and finding evidence.

What It Does

For one exported async journey(page) function, methandle:

1. runs the clean journey against the supplied base URL;
2. inventories first-party browser fetch/XHR dependencies;
3. records a HAR and a clean baseline;
4. verifies that strict HAR replay reproduces the clean journey;
5. stops if replay cannot be verified;
6. runs one HTTP 500 and one network-abort scenario per discovered dependency;
7. evaluates the resulting state with four deterministic rules;
8. writes the Failure Matrix and local JSON evidence.

Non-target requests stay on the recorded replay. Fault runs never silently fall back to the live backend.

Read Findings Carefully

BROKEN / HIGH means methandle has strong deterministic evidence that the observed degraded frontend state occurred under the injected scenario. It does not mean that every real-world failure response from that API will produce exactly the same state.

The current HTTP 500 fault uses a deterministic synthetic response body:

{"error":"Injected HTTP 500"}

That body can influence application behavior. A finding that depends on its response shape may be a real resilience risk, but it is not automatically proof of a production defect. Review response-body-dependent findings before treating them as confirmed bugs.

NO FINDING means that none of the currently implemented deterministic rules produced a finding for that verified experiment. It does not mean HEALTHY, HANDLED, or "no bug".

INVALID means the experiment could not establish its targeting or execution assumptions. REPLAY MISMATCH means the clean baseline was not reproduced. In either case, methandle does not make a degraded-UX claim.

Safety And Artifacts

Replay is a safety gate, not just an optimization:

one live baseline
        -> strict replay verification
        -> replay-based fault scenarios

If clean replay does not verify, methandle stops before fault injection, reports the mismatch, exits nonzero, and uses no live fallback. This prevents repeated mutation-heavy journeys from unexpectedly reaching the backend.

Recorded HARs and result files may contain credentials, tokens, cookies, request bodies, response bodies, internal URLs, or personal data. authorization, cookie, set-cookie, proxy-authorization, and x-api-key headers are redacted. Body redaction is not implemented. If a live baseline fails, methandle redacts the partial HAR before rethrowing; if that cannot be done, it removes or quarantines the artifact rather than leaving it unredacted.

Add the artifact directory to the application's ignore file:

.methandle/

Keep .methandle/ local. Do not commit it, publish it, or upload it as a CI artifact. The alpha has no upload service or user-project CI integration; this repository's own CI only verifies the package and demo.

Works Best Today

• Node.js 22 or newer;
• Chromium;
• a JavaScript or TypeScript module exporting async journey(page);
• same-origin first-party browser fetch/XHR JSON or text traffic;
• deterministic journeys that pass strict HAR replay verification;
• HTTP 500 and network-abort experiments;
• local execution with the target application server managed separately.

Known Limits

• Arbitrary Playwright test() or test.describe() files are not accepted directly;
• Playwright request-fixture traffic is outside the page-only journey contract;
• cross-origin API architectures are outside the current dependency boundary;
• dynamic Next.js/RSC replay, including the tested Umami journey, is not supported;
• WebSockets and SSE are not supported;
• service-worker-dependent traffic is not supported by the interception model;
• normalized dependencies with multiple concrete URLs or repeated target requests are skipped or invalidated rather than guessed;
• screenshot capture is best-effort and does not erase otherwise valid observation or finding evidence;
• a journey that cannot verify strict replay stops before any fault scenarios;
• there is no live fallback, HTML dashboard, CI mode, multi-browser mode, or AI oracle.

Validation Status

The current evidence supports an experimental OSS alpha, not a broad precision claim:

• controlled demo: 4 of 5 seeded degraded states detected, with 0 controlled high-confidence false positives;
• external: three unrelated applications completed full packaged HTTP 500 and abort sweeps;
• safety: strict replay and server-offline replay/fault proof passed, with no live fallback;
• real defect: Inventra GET /api/dashboard plus abort was independently reproduced as an uncaught Failed to fetch with a persistent Loading... state and no synthetic HTTP response body;
• precision: 9 HTTP 500 findings remain ambiguous because the synthetic response body influenced the observed behavior; 0 confirmed external false positives were observed;
• unsupported boundary: ACDC stopped at replay mismatch before mutation and produced no fault claim.

Read the concise validation report and the detailed M20 evidence.

Repository Demo

The repository includes a deliberately seeded React shop for deterministic local validation. From the repository root:

npm install
npx playwright install chromium
npm run build:shop
npm run demo:server

In another terminal:

npm run check -- demo/tests/checkout.journey.ts \
  --base-url http://127.0.0.1:4173

The demo produces ten verified scenarios, four seeded high-confidence findings, six NO FINDING cells, and zero backend API requests during replay and fault execution.

Diagnostic Commands

check is the supported high-level workflow. These commands remain available for inspecting individual phases:

npx methandle discover ./checkout.journey.ts --base-url http://localhost:3000
npx methandle record ./checkout.journey.ts --base-url http://localhost:3000
npx methandle replay ./checkout.journey.ts --base-url http://localhost:3000
npx methandle fault ./checkout.journey.ts --base-url http://localhost:3000

Run npx methandle --help for all options and artifact overrides.

Scope

The current alpha deliberately does not add new faults, oracle rules, verdict semantics, generalized replay, cross-origin support, WebSocket/SSE support, Next.js/RSC reconstruction, HTML reporting, user-project CI integration, AI, or server lifecycle management. Those limitations are part of the validation experiment rather than promises of future behavior.

More context is available in the product definition, the architecture, the validation plan, and the decision log.

See the contribution guide and security policy before sharing issues or artifacts.