tripwire-e2e 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.
Files changed (52) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +201 -3
  3. package/bin/tripwire.js +8 -0
  4. package/operators/_util.js +127 -0
  5. package/operators/agent-proposed.js +41 -0
  6. package/operators/auth-drop.js +30 -0
  7. package/operators/dead-control.js +23 -0
  8. package/operators/double-apply.js +20 -0
  9. package/operators/fake-success.js +21 -0
  10. package/operators/field-swap.js +42 -0
  11. package/operators/hide-control.js +30 -0
  12. package/operators/index.js +81 -0
  13. package/operators/item-drop.js +36 -0
  14. package/operators/item-dup.js +20 -0
  15. package/operators/label-swap.js +30 -0
  16. package/operators/missing-row-action.js +24 -0
  17. package/operators/number-drift.js +40 -0
  18. package/operators/rendered-item-drop.js +31 -0
  19. package/operators/rendered-item-dup.js +20 -0
  20. package/operators/rendered-number-drift.js +24 -0
  21. package/operators/silent-fail.js +19 -0
  22. package/operators/stale-read.js +34 -0
  23. package/operators/text-change.js +43 -0
  24. package/operators/validation-off.js +21 -0
  25. package/operators/wrong-link.js +28 -0
  26. package/operators/wrong-owner.js +41 -0
  27. package/package.json +41 -4
  28. package/policies/tripwire.clean.policy.yaml +23 -0
  29. package/policies/tripwire.mutant.policy.yaml +13 -0
  30. package/src/actions.js +59 -0
  31. package/src/agent.js +30 -0
  32. package/src/browser/mutate.js +156 -0
  33. package/src/browser/recorder.js +102 -0
  34. package/src/cli.js +41 -0
  35. package/src/commands/check.js +45 -0
  36. package/src/commands/coverage.js +110 -0
  37. package/src/commands/doctor.js +28 -0
  38. package/src/commands/fix.js +208 -0
  39. package/src/commands/list.js +24 -0
  40. package/src/commands/proxy.js +28 -0
  41. package/src/commands/report.js +11 -0
  42. package/src/commands/run.js +370 -0
  43. package/src/commands/sabotage.js +85 -0
  44. package/src/config.js +52 -0
  45. package/src/jsonpath.js +58 -0
  46. package/src/kane.js +158 -0
  47. package/src/ledger.js +53 -0
  48. package/src/mutant.js +26 -0
  49. package/src/orphans.js +40 -0
  50. package/src/profile.js +46 -0
  51. package/src/proxy.js +292 -0
  52. package/src/report.js +183 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 da-b0s
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,201 @@
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
+ # Tripwire
2
+
3
+ **Break the app on purpose to find out whether a green Kane suite means anything.**
4
+
5
+ Coding agents write the app and its tests, and they are very good at writing tests that pass.
6
+ A passing end-to-end test only matters if it would have failed when the app was broken, and
7
+ nobody checks that. Tripwire does.
8
+
9
+ A proxy sits between the browser and your app and breaks it in one small, realistic way at a time:
10
+ a wrong total, a failed save reported as success, a missing button, another user's order in your
11
+ list. It never touches your code. [Kane CLI](https://github.com/LambdaTest/kane-cli) replays your
12
+ suite against each broken version with healing off. Every bug the suite walks past goes to your
13
+ coding agent, which adds one plain-English assertion, and Kane proves it: the strengthened test
14
+ **passes on the real app and fails on the broken one**.
15
+
16
+ ![tripwire score](https://raw.githubusercontent.com/da-b0s/tripwire/main/demo/shop/.tripwire/report/badge.svg)
17
+
18
+ ## Results
19
+
20
+ Two apps, each with a suite written by a fresh Claude Code session that was never told about
21
+ Tripwire (Kane CLI 0.10.5, 18 to 20 Nov 2026). Every fix below was proven by two Kane runs: the
22
+ strengthened test passes on the real app and fails with the bug armed.
23
+
24
+ **Demo shop** (`demo/shop`, 6 tests, JSON API)
25
+
26
+ | Run | Mutants | Score | Killed | Survived | Masked by heal | Not reached |
27
+ |---|---|---|---|---|---|---|
28
+ | First-draft suite | 40 | **78.4%** | 29 | 7 | 1 | 3 |
29
+ | After `tripwire fix` (5 proven fixes) | 40 | **91.9%** | 34 | 2 | 1 | 3 |
30
+ | Fresh measured re-run of the strengthened suite, harder set (adds 8 saboteur bugs and the in-page operators) | 50 | **78.7%** | 37 | 10 | 0 | 3 |
31
+ | After 3 more proven fixes | 50 | **85.1%** | 40 | 7 | 0 | 3 |
32
+
33
+ 5 of the 7 remaining survivors are flagged *suspected equivalent*: the bug fired but no page ever
34
+ showed anything different (mostly saboteur bugs placed in write responses that the shop ignores
35
+ because it re-reads the data). They stay in the score: only a person can exclude a mutant.
36
+
37
+ **TodoMVC** (`demo/third-party`, the unmodified JavaScript ES5 example, 6 tests, no backend)
38
+
39
+ | Run | Mutants | Score | Killed | Survived | Masked by heal |
40
+ |---|---|---|---|---|---|
41
+ | First-draft suite | 18 | **77.8%** | 14 | 2 | 2 |
42
+ | After `tripwire fix` (4 proven fixes, including both masked bugs) | 18 | **100%** | 18 | 0 | 0 |
43
+ | Incremental re-check of the strengthened suite (`--since`, corrected operators) | 17 | **94.1%** | 16 | 1 | 0 |
44
+ | After 1 more proven fix | 17 | **100%** | 17 | 0 | 0 |
45
+
46
+ **What the runs found**
47
+
48
+ - **Another customer's order (#91002) in "My orders"**, and a product price 10% too high, both green
49
+ in the first-draft shop suite. Both now caught by one appended step each.
50
+ - **Default healing passed a bug Kane's own triage had just diagnosed.** With a TodoMVC row hidden,
51
+ strict replay failed and Kane's triage said "application issue, major: the page says 3 items left
52
+ but shows only 'Walk the dog' and 'Read a book'". With healing on, Kane re-authored the check,
53
+ read the hidden row from the DOM, and passed. For masked bugs the agent learned to write checks
54
+ that forbid re-entering data, and those failed on the broken app even with healing on.
55
+ - **A replayed "exactly three items" check passed with four rows on screen** (screenshot in the
56
+ report). The appended fix pins the row to directly above the footer.
57
+ - **Coverage, with a third state.** Of the shop's 21 acceptance criteria: 7 proven and guarded,
58
+ 4 *proven but unguarded* (tests check them, a bug that broke them got past), 3 untouched by any
59
+ mutant, 7 owed (no test checks them).
60
+
61
+ Reports: [shop](https://da-b0s.github.io/tripwire/) · [TodoMVC](https://da-b0s.github.io/tripwire/todomvc/)
62
+ (each survivor with a screenshot of the broken page the suite passed on, Kane's triage of every
63
+ failure, every fix and lesson). Full measurements and findings: [NOTES.md](https://github.com/da-b0s/tripwire/blob/main/NOTES.md).
64
+
65
+ **Cost:** a passing replay ≈ 0.7 credits per test; a failing one ≈ 5 (Kane investigates it); a heal
66
+ check 15 to 35; each proven fix ≈ 25.
67
+
68
+ ## Quickstart
69
+
70
+ You need Node 18+, Chrome, and a [TestMu AI](https://www.testmuai.com) account (free credits).
71
+
72
+ ```bash
73
+ npm install -g @testmuai/kane-cli tripwire-e2e
74
+ kane-cli login
75
+ ```
76
+
77
+ Point your `*_test.md` files at the proxy (`url: http://localhost:8080` in the frontmatter), start
78
+ your app, then:
79
+
80
+ ```bash
81
+ tripwire run # baseline, generate mutants, replay, score, report
82
+ tripwire fix # hand each survivor to your agent; Kane proves every new assertion
83
+ tripwire check # exit 1 below the threshold (for hooks and CI)
84
+ ```
85
+
86
+ More: `tripwire sabotage` (your agent proposes domain bugs from your acceptance criteria),
87
+ `tripwire coverage` (criteria as owed / proven and guarded / proven but unguarded),
88
+ `tripwire run --since <ref>` (only mutants whose tests changed), `tripwire doctor` (checks
89
+ kane-cli, the login, and leftover Kane browsers that can change a shared app's state).
90
+
91
+ Try it on the bundled demo shop (its Kane suite and recordings are committed):
92
+
93
+ ```bash
94
+ git clone https://github.com/da-b0s/tripwire && cd tripwire && npm install
95
+ npm run shop # terminal 1: the app, on :3000
96
+ ```
97
+
98
+ ```bash
99
+ cd demo/shop && npx tripwire run # terminal 2: starts the proxy on :8080 itself
100
+ ```
101
+
102
+ Without spending any credits you can inspect the committed results: `npx tripwire check`,
103
+ `npx tripwire list`, `npx tripwire run --dry-run` and `npx tripwire report` all work offline.
104
+
105
+ Long runs are safe to interrupt: `tripwire run --resume` continues from the last finished mutant,
106
+ `--retry-errors` re-runs only mutants that hit a Kane service error, and `--redo <id>` re-runs
107
+ named mutants. Kane service hiccups before a run starts are waited out automatically.
108
+
109
+ ## What a score means
110
+
111
+ | Status | Meaning | Counted |
112
+ |---|---|---|
113
+ | **killed** | at least one test failed while the bug was live | yes |
114
+ | **survived** | the bug fired and every test still passed | yes, against you |
115
+ | **masked** | strict replay caught it, but with Kane's default healing the test re-authored itself and passed on the broken app | yes, against you |
116
+ | **not reached** | the bug never fired in any test (e.g. no test submits invalid input) | no, listed separately |
117
+
118
+ Score = killed ÷ (killed + survived + masked). Kane errors and timeouts are retried and never
119
+ counted. A survivor whose pages never showed anything different from the clean run is flagged as a
120
+ *suspected equivalent*; it is excluded only when a person adds it to `.tripwire/equivalents.json`
121
+ with a reason, and every exclusion is listed in the report. A gate can set flagged ones aside
122
+ without changing the score: `tripwire check --allow-suspected-equivalents` (this repo's CI does).
123
+
124
+ ## The operators
125
+
126
+ Generated from the traffic and the pages your suite actually produced, so every mutant is
127
+ relevant to at least one test. Data mutants only change values that were on screen; interface
128
+ mutants target controls by their visible text, or by tag and class with their row for icon buttons
129
+ and checkboxes. Links to other sites are never mutated.
130
+
131
+ | Family | Operator | What breaks |
132
+ |---|---|---|
133
+ | data | number-drift | a price, total or count is off by one unit or 10% |
134
+ | data | item-drop / item-dup | a list loses or repeats an element |
135
+ | data | field-swap | two displayed fields of a record are exchanged |
136
+ | data | stale-read | a read after a write returns the old data |
137
+ | data | wrong-owner | another user's record appears in a list |
138
+ | data | rendered-number-drift | a number shown on the page is off by one, changed in the page (no JSON needed) |
139
+ | data | rendered-item-drop / -dup | a list row disappears or shows twice, changed in the page |
140
+ | behaviour | silent-fail | a write returns 500 and is dropped |
141
+ | behaviour | fake-success | a write answers with its usual success body but is never saved |
142
+ | behaviour | double-apply | a POST is applied twice |
143
+ | behaviour | validation-off | a 400/422 becomes 200 |
144
+ | behaviour | auth-drop | one request mid-flow returns 401 |
145
+ | interface | hide-control | a control the tests see but never use disappears |
146
+ | interface | dead-control | a control the tests click does nothing |
147
+ | interface | label-swap | two button labels are exchanged |
148
+ | interface | text-change | a heading or status shows the wrong words |
149
+ | interface | wrong-link | a link points to a different page |
150
+ | interface | missing-row-action | the first row loses its edit/delete/cancel action |
151
+ | saboteur | agent-proposed | domain rules broken on purpose, proposed by your agent (`tripwire sabotage`) |
152
+
153
+ ## Use it in your agent
154
+
155
+ - **Claude Code Stop hook**: [hooks/stop-hook.mjs](https://github.com/da-b0s/tripwire/blob/main/hooks/stop-hook.mjs) blocks "done" while tests
156
+ changed since the last run or the score is below the threshold, and names the bugs that got past.
157
+ Merge [hooks/claude-settings.json](https://github.com/da-b0s/tripwire/blob/main/hooks/claude-settings.json) into `.claude/settings.json`.
158
+ - **Any agent**: copy [hooks/AGENTS.md](https://github.com/da-b0s/tripwire/blob/main/hooks/AGENTS.md).
159
+ - **CI**: [hooks/tripwire.yml](https://github.com/da-b0s/tripwire/blob/main/hooks/tripwire.yml) runs incrementally (`--since`) on pull requests.
160
+ - **Memory**: `.tripwire/lessons.md` records each bug with the exact step that was proven to catch
161
+ it; the agent reads it before writing new tests (seen live in the hook session above).
162
+
163
+ ## What Kane does here
164
+
165
+ | Kane feature | Role in Tripwire |
166
+ |---|---|
167
+ | `_test.md` replay | the suite runs once per mutant without re-authoring |
168
+ | `--no-adaptive-heal` and heal events | strict verdicts; then a healing-on rerun detects masked bugs |
169
+ | Policies and `evidence verdict` | an inverted policy (`failed + broken >= 1`) judges every mutant run; a clean policy gates the baseline |
170
+ | `metrics.tests_without_checks` | assertion-free tests are reported first |
171
+ | Evidence packs | screenshots of the broken page for the report and for the agent |
172
+ | NDJSON events, exit codes, failure triage | machine-readable verdicts; Kane's own triage is shown next to each planted bug |
173
+ | Official skill | the test-writing agent uses TestMu's skill; Tripwire checks the result |
174
+
175
+ ## Limits
176
+
177
+ - Tripwire mutates traffic and the rendered page, not source code. It measures whether the suite
178
+ notices breakage a user would see. It does not replace unit-level mutation testing.
179
+ - JSON operators need a JSON API; the in-page operators and interface operators work on any page.
180
+ Websockets and static assets pass through untouched.
181
+ - Kane's checks are AI-judged and not perfectly repeatable: the same mutant was caught by a test in
182
+ one run and survived it in another, and one check failed with `analyzer_failed` and passed on the
183
+ next replay. Treat a single kill or survival as strong evidence, not proof.
184
+ - Equivalence is flagged by comparing page text, so it cannot see effects that never reach the
185
+ page, and older baselines cannot see duplicated rows (duplicating mutants are never flagged then).
186
+ - A Kane replay re-evaluates its AI checks, so it is cheap but not free. See [NOTES.md](https://github.com/da-b0s/tripwire/blob/main/NOTES.md).
187
+ - Only run it against apps you own or run locally.
188
+
189
+ ## For judges
190
+
191
+ - Everything runs locally against the two demos; you only need a Kane login.
192
+ - Both suites were written by separate Claude Code sessions in clean folders that never saw
193
+ Tripwire; transcripts are in `demo/*/agent-session.jsonl`, prompts and what happened in
194
+ `demo/*/WRITE_TESTS_PROMPT.md`.
195
+ - `demo/shop/stop-hook-session.jsonl` is a real Claude Code session blocked by the Stop hook.
196
+ - If you cannot run it: the committed reports, ledgers, fixes, lessons and screenshots in
197
+ `demo/*/.tripwire/` are the record of every run.
198
+
199
+ ## License
200
+
201
+ MIT
@@ -0,0 +1,8 @@
1
+ #!/usr/bin/env node
2
+ // tripwire: mutation testing for Kane CLI suites.
3
+ import { main } from '../src/cli.js';
4
+
5
+ main(process.argv.slice(2)).then(
6
+ (code) => { process.exitCode = code ?? 0; },
7
+ (err) => { console.error(`tripwire: ${err.message}`); if (process.env.TRIPWIRE_DEBUG) console.error(err.stack); process.exitCode = 2; }
8
+ );
@@ -0,0 +1,127 @@
1
+ // Shared helpers for operators. An operator receives the baseline profile:
2
+ // profile.tests = [{ test, traffic: [entry], pages: [{url, controls, text}], clicks: [control] }]
3
+ // and returns concrete mutant definitions (see README "Mutant definition format").
4
+ import { walk, get } from '../src/jsonpath.js';
5
+
6
+ export const WRITE = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
7
+ export const routeKey = (e) => `${e.method} ${e.path}`;
8
+ export const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
9
+
10
+ const MONEYISH = /total|price|subtotal|amount|cost|discount|shipping|tax|fee|balance/i;
11
+ const COUNTISH = /count|qty|quantity|items?$|stock|number|seats|nights|guests/i;
12
+
13
+ export function testText(t) {
14
+ return t.pages.map((p) => p.text || '').join('\n');
15
+ }
16
+
17
+ // Is this value something a user could actually see on one of the test's pages?
18
+ export function rendered(value, text, key = '') {
19
+ if (typeof value === 'number') {
20
+ if (!Number.isFinite(value)) return false;
21
+ const forms = Number.isInteger(value) ? [String(value), value.toFixed(2)] : [value.toFixed(2), String(value)];
22
+ if (Number.isInteger(value) && Math.abs(value) < 10 && !COUNTISH.test(key) && !MONEYISH.test(key)) return false;
23
+ return forms.some((f) => new RegExp(`(^|[^\\d.])${esc(f)}(?![\\d])`).test(text));
24
+ }
25
+ if (typeof value === 'string') {
26
+ const v = value.trim();
27
+ if (v.length < 3 || v.length > 200) return false;
28
+ if (/^\d{4}-\d\d-\d\dT/.test(v)) return false; // timestamps are usually reformatted
29
+ return text.includes(v);
30
+ }
31
+ return false;
32
+ }
33
+
34
+ export const isMoneyKey = (k) => MONEYISH.test(k);
35
+ export const isCountKey = (k) => COUNTISH.test(k);
36
+ export const lastKey = (p) => { const m = p.match(/(?:\.([\w$-]+)|\[(\d+)\])$/); return m ? (m[1] ?? m[2]) : ''; };
37
+
38
+ // Unique (method, path) JSON GET responses per test, keeping the last body seen.
39
+ export function jsonReads(t) {
40
+ const by = new Map();
41
+ for (const e of t.traffic) if (e.method === 'GET' && e.type === 'json' && e.status < 400 && e.json !== undefined && !e.mutated) by.set(routeKey(e), e);
42
+ return [...by.values()];
43
+ }
44
+
45
+ export function writes(t) {
46
+ const by = new Map();
47
+ for (const e of t.traffic) if (WRITE.has(e.method) && !e.mutated) { if (!by.has(routeKey(e)) || e.status < 400) by.set(routeKey(e), e); }
48
+ return [...by.values()];
49
+ }
50
+
51
+ // All tests whose baseline traffic touched this route.
52
+ export function touchingRoute(profile, method, path) {
53
+ return profile.tests.filter((t) => t.traffic.some((e) => e.method === method && e.path === path)).map((t) => t.test);
54
+ }
55
+
56
+ // All tests that saw a control with this role and text.
57
+ export function touchingControl(profile, role, text) {
58
+ return profile.tests.filter((t) => t.pages.some((p) => p.controls.some((c) => c.role === role && c.text === text))).map((t) => t.test);
59
+ }
60
+
61
+ export function clickedAnywhere(profile, role, text) {
62
+ return profile.tests.some((t) => t.clicks.some((c) => c.role === role && c.text === text));
63
+ }
64
+
65
+ // A label with a live number in it ("Cart 2", "3 items") is one control, not several.
66
+ // A private-use character marks "a number was here", so a literal '#' in a label ("#1002") is kept.
67
+ const NUM = '';
68
+ const masked = (text) => text.replace(/\d+(?:[.,]\d+)?/g, NUM);
69
+ const patternFor = (text) => '^' + esc(masked(text)).split(NUM).join('\\d+(?:[.,]\\d+)?') + '$';
70
+
71
+ // Distinct visible controls across the suite:
72
+ // [{ role, text, pattern?, href, inRow, tag, cls, tests:[...], pages:[...], clicked }]
73
+ export function controls(profile) {
74
+ const variants = new Map();
75
+ for (const t of profile.tests) for (const p of t.pages) for (const c of p.controls) {
76
+ const k = `${c.role}|${masked(c.text)}`;
77
+ if (!variants.has(k)) variants.set(k, new Set());
78
+ variants.get(k).add(c.text);
79
+ }
80
+ const keyOf = (c) => {
81
+ const k = `${c.role}|${masked(c.text)}`;
82
+ return variants.get(k) && variants.get(k).size > 1 ? k : `${c.role}|${c.text}`;
83
+ };
84
+ const by = new Map();
85
+ for (const t of profile.tests) {
86
+ for (const p of t.pages) for (const c of p.controls) {
87
+ const k = keyOf(c);
88
+ if (!by.has(k)) {
89
+ const dynamic = k !== `${c.role}|${c.text}`;
90
+ by.set(k, { ...c, ...(dynamic ? { pattern: patternFor(c.text), text: masked(c.text).split(NUM).join('N') } : {}), tests: new Set(), pages: new Set(), clicked: false });
91
+ }
92
+ by.get(k).tests.add(t.test);
93
+ by.get(k).pages.add(p.url);
94
+ }
95
+ for (const c of t.clicks) { const k = keyOf(c); if (by.has(k)) by.get(k).clicked = true; }
96
+ }
97
+ // Links to other sites (author credits, social links) are not part of the app under test.
98
+ return [...by.values()].filter((c) => !(c.role === 'link' && isExternal(c.href))).map((c) => ({ ...c, tests: [...c.tests], pages: [...c.pages] }));
99
+ }
100
+
101
+ export const isExternal = (href) => /^(https?:)?\/\//i.test(href || '') && !/^(https?:)?\/\/(localhost|127\.0\.0\.1|\[::1\])(:\d+)?(\/|$)/i.test(href);
102
+
103
+ // How a control reads in a sentence. "[button.destroy]" (no visible text) becomes
104
+ // 'the "destroy" button on the "Buy milk" row'; a labelled one becomes 'the "Save" button'.
105
+ export function labelOf(c) {
106
+ const anon = /^\[([a-z0-9-]+)(?:\.([\w-]+))?\]$/i.exec(c.text || '');
107
+ const kind = c.role === 'link' ? 'link' : c.role === 'checkbox' ? 'checkbox' : c.role === 'heading' ? 'heading' : 'button';
108
+ const name = anon ? `the unlabelled "${anon[2] || anon[1]}" ${kind}` : `the "${c.text}" ${kind}`;
109
+ return c.row && c.inRow && c.row !== c.text ? `${name} on the "${c.row}" row` : name;
110
+ }
111
+ export const sentence = (s) => s.charAt(0).toUpperCase() + s.slice(1);
112
+
113
+ // The target a DOM mutant uses to find a control again in the page.
114
+ export const targetOf = (c) => (c.pattern ? { role: c.role, text: c.text, pattern: c.pattern } : { role: c.role, text: c.text });
115
+
116
+ export { walk, get };
117
+
118
+ export function mutant(fields) {
119
+ const { id, family, operator, match, action, touches_tests, describe, times, expect } = fields;
120
+ const m = { id, family, operator, match, action, touches_tests: [...new Set(touches_tests)].sort(), describe };
121
+ if (times) m.times = times;
122
+ if (expect) m.expect = expect; // what a good test should notice
123
+ return m;
124
+ }
125
+
126
+ export const fmtVal = (v) => (typeof v === 'number' ? (Number.isInteger(v) ? String(v) : v.toFixed(2)) : JSON.stringify(v));
127
+ export const nice = (key) => key.replace(/([a-z])([A-Z])/g, '$1 $2').replace(/[_-]/g, ' ').toLowerCase();
@@ -0,0 +1,41 @@
1
+ // Saboteur: domain-specific mutants proposed by the coding agent from the acceptance criteria and
2
+ // test files ("coupon stacks", "free shipping off by one", "past dates accepted"), expressed in the
3
+ // same definition format as every other mutant. `tripwire sabotage` writes them to .tripwire/saboteur.json.
4
+ import fs from 'node:fs';
5
+ import path from 'node:path';
6
+ import { touchingRoute, touchingControl, mutant } from './_util.js';
7
+ import { validateMutant } from '../src/mutant.js';
8
+
9
+ export function loadSaboteur(dir) {
10
+ const file = path.join(dir, 'saboteur.json');
11
+ if (!fs.existsSync(file)) return { mutants: [], rejected: [] };
12
+ const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
13
+ const list = Array.isArray(raw) ? raw : raw.mutants || [];
14
+ const mutants = [];
15
+ const rejected = [];
16
+ for (const m of list) {
17
+ const errors = validateMutant(m);
18
+ if (errors.length) rejected.push({ id: m?.id, errors });
19
+ else mutants.push(m);
20
+ }
21
+ return { mutants, rejected };
22
+ }
23
+
24
+ export default {
25
+ name: 'agent-proposed',
26
+ family: 'saboteur',
27
+ summary: 'Domain rules from the acceptance criteria, broken on purpose and expressed as response rewrites.',
28
+ generate(profile, ctx = {}) {
29
+ const { mutants } = loadSaboteur(ctx.dir || '.tripwire');
30
+ return mutants.map((m) => {
31
+ let touches = m.touches_tests;
32
+ if (!touches || !touches.length) {
33
+ touches = m.match.document
34
+ ? touchingControl(profile, m.action.dom?.target?.role || 'button', m.action.dom?.target?.text || '')
35
+ : touchingRoute(profile, m.match.method || 'GET', m.match.path);
36
+ if (!touches.length && m.match.document) touches = profile.tests.map((t) => t.test);
37
+ }
38
+ return mutant({ ...m, id: m.id.startsWith('agent-proposed:') ? m.id : `agent-proposed:${m.id}`, family: 'saboteur', operator: 'agent-proposed', touches_tests: touches });
39
+ });
40
+ }
41
+ };
@@ -0,0 +1,30 @@
1
+ // Behaviour: one request in the middle of a flow returns 401 (an expired session).
2
+ // The user should see a sign-in prompt, not a blank or half-rendered page.
3
+ import { touchingRoute, mutant } from './_util.js';
4
+
5
+ export default {
6
+ name: 'auth-drop',
7
+ family: 'behaviour',
8
+ summary: 'One request mid-flow returns 401. The user should see a sign-in prompt, not a blank page.',
9
+ generate(profile) {
10
+ const out = new Map();
11
+ for (const t of profile.tests) {
12
+ // skip the first JSON read of the test (that is the page load, not "mid-flow")
13
+ const reads = t.traffic.filter((e) => e.type === 'json' && e.status < 400 && !e.mutated);
14
+ for (const e of reads.slice(1)) {
15
+ const id = `auth-drop:${e.method} ${e.path}`;
16
+ if (out.has(id)) continue;
17
+ out.set(id, mutant({
18
+ id, family: 'behaviour', operator: 'auth-drop', times: 1,
19
+ match: { method: e.method, path: e.path },
20
+ action: { type: 'respond', status: 401, body: { error: 'Unauthorized' } },
21
+ touches_tests: touchingRoute(profile, e.method, e.path),
22
+ describe: `${e.method} ${e.path} returns 401 once, mid-flow`,
23
+ expect: 'The test checks the page it lands on after each step'
24
+ }));
25
+ }
26
+ }
27
+ // keep this family small: up to 4, preferring writes (the riskiest place to lose a session)
28
+ return [...out.values()].sort((a, b) => (a.match.method === 'GET') - (b.match.method === 'GET')).slice(0, 4);
29
+ }
30
+ };
@@ -0,0 +1,23 @@
1
+ // Interface: a control the test clicks no longer does anything. If the test passes anyway,
2
+ // it never checked the effect of the click.
3
+ import { controls, mutant, labelOf } from './_util.js';
4
+ import { domMutant } from './hide-control.js';
5
+
6
+ export default {
7
+ name: 'dead-control',
8
+ family: 'interface',
9
+ summary: 'The click handler of a control is disabled by an injected script.',
10
+ generate(profile) {
11
+ return controls(profile)
12
+ .filter((c) => (c.role === 'button' || c.role === 'checkbox') && c.clicked)
13
+ .map((c) => mutant({
14
+ id: `dead-control:${c.role}:"${c.text}"`,
15
+ family: 'interface', operator: 'dead-control',
16
+ match: { document: true },
17
+ action: domMutant('dead', c),
18
+ touches_tests: c.tests,
19
+ describe: `${c.role === 'checkbox' ? 'Ticking' : 'Clicking'} ${labelOf(c)} does nothing`,
20
+ expect: `The test checks what "${c.text}" is supposed to change`
21
+ }));
22
+ }
23
+ };
@@ -0,0 +1,20 @@
1
+ // Behaviour: a non-idempotent write is applied twice (double submit, retry without idempotency key).
2
+ import { writes, touchingRoute, mutant } from './_util.js';
3
+
4
+ export default {
5
+ name: 'double-apply',
6
+ family: 'behaviour',
7
+ summary: 'A POST or PATCH is forwarded twice: two rows, or a doubled quantity.',
8
+ generate(profile) {
9
+ // PUT and DELETE are idempotent by contract, so applying them twice is an equivalent mutant.
10
+ return profile.tests.flatMap((t) => writes(t).filter((e) => e.status < 400 && (e.method === 'POST' || e.method === 'PATCH')).map((e) => mutant({
11
+ id: `double-apply:${e.method} ${e.path}`,
12
+ family: 'behaviour', operator: 'double-apply',
13
+ match: { method: e.method, path: e.path },
14
+ action: { type: 'forward-twice' },
15
+ touches_tests: touchingRoute(profile, e.method, e.path),
16
+ describe: `${e.method} ${e.path} is applied twice`,
17
+ expect: 'The test checks the exact quantity or number of records afterwards'
18
+ })));
19
+ }
20
+ };
@@ -0,0 +1,21 @@
1
+ // Behaviour: a write answers with its usual success body but never reaches the app.
2
+ // The page looks right until anything re-reads the data.
3
+ import { writes, touchingRoute, mutant } from './_util.js';
4
+
5
+ export default {
6
+ name: 'fake-success',
7
+ family: 'behaviour',
8
+ summary: 'A write returns its normal success response but is not forwarded, so after a reload the change is gone.',
9
+ generate(profile) {
10
+ return profile.tests.flatMap((t) => writes(t).filter((e) => e.status < 400 && e.json !== undefined).map((e) => mutant({
11
+ id: `fake-success:${e.method} ${e.path}`,
12
+ family: 'behaviour', operator: 'fake-success',
13
+ match: { method: e.method, path: e.path },
14
+ // replay the success body recorded at baseline: realistic, and the UI keeps working
15
+ action: { type: 'respond', status: e.status, body: e.json },
16
+ touches_tests: touchingRoute(profile, e.method, e.path),
17
+ describe: `${e.method} ${e.path} reports success but the change is never saved`,
18
+ expect: 'The test re-reads the data (reload or another page) after the change'
19
+ })));
20
+ }
21
+ };
@@ -0,0 +1,42 @@
1
+ // Data: two displayed string fields of one record are exchanged (first/last name, from/to, name/email).
2
+ import { jsonReads, walk, rendered, testText, touchingRoute, mutant, nice } from './_util.js';
3
+
4
+ const ID_LIKE = /^(id|_id|uuid|.*Id|.*_id|sku|slug|key|ref)$/;
5
+
6
+ export default {
7
+ name: 'field-swap',
8
+ family: 'data',
9
+ summary: 'Two displayed string fields of one record are exchanged.',
10
+ generate(profile) {
11
+ const out = [];
12
+ for (const t of profile.tests) {
13
+ const text = testText(t);
14
+ for (const e of jsonReads(t)) {
15
+ let perRoute = 0;
16
+ walk(e.json, (p, v) => {
17
+ if (perRoute >= 2 || !v || typeof v !== 'object' || Array.isArray(v)) return;
18
+ // human-readable fields only: swapping an id or code into a label is not a mix-up users meet
19
+ const shown = Object.entries(v).filter(([k, x]) => typeof x === 'string' && !ID_LIKE.test(k) && /[A-Za-z]{2}/.test(x) && rendered(x, text, k));
20
+ for (let i = 0; i < shown.length && perRoute < 2; i++) {
21
+ for (let j = i + 1; j < shown.length && perRoute < 2; j++) {
22
+ if (shown[i][1] === shown[j][1]) continue;
23
+ const [a, av] = shown[i];
24
+ const [b, bv] = shown[j];
25
+ perRoute++;
26
+ out.push(mutant({
27
+ id: `field-swap:${e.method} ${e.path}:${p}.${a}<->${b}`,
28
+ family: 'data', operator: 'field-swap',
29
+ match: { method: e.method, path: e.path },
30
+ action: { type: 'json', ops: [{ op: 'swap', path: p, a, b }] },
31
+ touches_tests: touchingRoute(profile, e.method, e.path),
32
+ describe: `${nice(a)} and ${nice(b)} are swapped ("${av}" shows as ${nice(b)})`,
33
+ expect: `The ${nice(a)} shown is checked, not just that something is shown`
34
+ }));
35
+ }
36
+ }
37
+ });
38
+ }
39
+ }
40
+ return out;
41
+ }
42
+ };
@@ -0,0 +1,30 @@
1
+ // Interface: a button or link the tests saw but never clicked disappears.
2
+ // Catches suites that never look at controls they do not use.
3
+ import { controls, mutant, targetOf, labelOf, sentence } from './_util.js';
4
+
5
+ const domMutant = (op, c, extra = {}) => ({ type: 'dom', dom: { op, target: targetOf(c), ...extra } });
6
+
7
+ export default {
8
+ name: 'hide-control',
9
+ family: 'interface',
10
+ summary: 'A button or link that the flow does not click is hidden.',
11
+ generate(profile) {
12
+ // Buttons first, then links outside lists (navigation, calls to action), then the rest.
13
+ const rank = (c) => (c.role === 'button' ? 0 : c.inRow ? 2 : 1);
14
+ return controls(profile)
15
+ .filter((c) => (c.role === 'button' || c.role === 'link') && !c.clicked && c.text.length <= 40)
16
+ .sort((a, b) => rank(a) - rank(b))
17
+ .slice(0, 12)
18
+ .map((c) => mutant({
19
+ id: `hide-control:${c.role}:"${c.text}"`,
20
+ family: 'interface', operator: 'hide-control',
21
+ match: { document: true },
22
+ action: domMutant('hide', c),
23
+ touches_tests: c.tests,
24
+ describe: `${sentence(labelOf(c))} is missing`,
25
+ expect: `The test checks that ${labelOf(c)} is offered`
26
+ }));
27
+ }
28
+ };
29
+
30
+ export { domMutant };