kryptheon 0.1.49 → 0.1.51

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,333 +1,435 @@
1
- # kryptheon
2
-
3
- Record a flow in your app once, replay it after every AI change, and get told in
4
- plain English what broke.
5
-
6
- Runs entirely on your machine. No account, no API key, nothing leaves your
7
- computer. It is a wrapper around [Playwright](https://playwright.dev).
8
-
9
- ## The one command
10
-
11
- ```
12
- npx kryptheon@latest dashboard
13
- ```
14
-
15
- Run it in your project's folder. It opens a page in your browser, and
16
- everything else is a button on that page:
17
-
18
- | | how often |
19
- | --- | --- |
20
- | Read my code | after every change |
21
- | Record a flow | one time - again only when that flow changes |
22
- | Replay | after every change |
23
- | Connect your database | one time |
24
- | Check my database | after every change |
25
- | Set up the nightly check | one time |
26
- | Re-check a finding | after every change |
27
-
28
- Every button shows the terminal command that does the same thing, in small
29
- print, for when the page cannot be used. The database connection string is
30
- pasted into the page, used for one run, and never saved, logged or shown
31
- again; reload the page and it is gone.
32
-
33
- ## Only have a web address?
34
-
35
- Built your app in Lovable, Bolt or v0, and there is no project folder on your
36
- computer? Open a terminal and run:
37
-
38
- ```
39
- npx kryptheon record https://your-app.lovable.app
40
- ```
41
-
42
- Before it opens anything, it looks at the folder you are in. If that folder is
43
- not set up for recordings it says so and asks first, then adds a `package.json`
44
- and kryptheon itself (about 20MB) — nothing else. A new terminal opens in your
45
- home folder, so from there it keeps your recordings in a `kryptheon-tests`
46
- folder of their own and tells you where that is.
47
-
48
- After every change to your app, from that same folder:
49
-
50
- ```
51
- npx kryptheon check
52
- ```
53
-
54
- ## Install
55
-
56
- ```
57
- npm i -D kryptheon
58
- ```
59
-
60
- Install it into your project, not globally — every recording imports
61
- `kryptheon/kryptheon-fixture`, and your tests can only find that if kryptheon is
62
- in your project's `node_modules`.
63
-
64
- ## Record
65
-
66
- ```
67
- npx kryptheon record https://your-app.example.com
68
- ```
69
-
70
- A browser opens. Use your app the way a customer would. Close the browser when
71
- you are done, and the recording is saved as a test.
72
-
73
- Add `--phone` to record in a phone-sized window (390 x 844) - for a menu or a
74
- layout that only changes on a phone. The recording keeps that size, so every
75
- replay uses it too. On the dashboard it is the "Phone size" box under Record.
76
-
77
- On its own, a recording knows that every button and field is still there and
78
- that the last page looks the same. To say what must be true — "Reservation
79
- received" appears after booking — use the toolbar at the top of the page while
80
- recording:
81
-
82
- | Button | Click it, then click… | Kryptheon then checks |
83
- | --- | --- | --- |
84
- | Eye | any element | it is on the page |
85
- | `ab` | some text | that text is there |
86
- | Box | a filled-in field | the field still holds that value |
87
- | `{ }` | a part of the page | that part is laid out the same |
88
-
89
- The round red button pauses and resumes recording. The arrow only shows how an
90
- element would be found; it adds nothing to the test. One check at the end of a
91
- flow — on the success message — is usually all a recording needs.
92
-
93
- ## Check
94
-
95
- ```
96
- npx kryptheon check
97
- ```
98
-
99
- Runs everything you have recorded:
100
-
101
- ```
102
- OK Sign in (4.1s)
103
-
104
- X Checkout
105
- Could not find the button "Place order" on the page.
106
- This was working on 12 Mar at 9:14 AM.
107
- What to check: your last change may have renamed, hidden, or removed it.
108
- Where to look:
109
- - Browser was on: https://your-app.example.com/cart
110
- - POST /api/orders returned 500
111
- the server crashed or is unavailable - the error is in backend code, not the page
112
- ```
113
-
114
- Every failure ends with a short summary you can paste straight into an AI coding
115
- tool.
116
-
117
- ## Recording something that replays
118
-
119
- A recording is only useful if it still works the second time. So:
120
-
121
- - **Record one simple flow.** Sign in and look at a page. Open a thing and check
122
- it loaded. Short beats thorough.
123
- - **Sign in with an account that already exists.** Do not sign up during a
124
- recording — the account exists next time, and the signup step fails.
125
- - **Avoid steps that cannot repeat.** Adding data piles up a row on every run.
126
- Logging out at the end means the next run does not start where this one did.
127
-
128
- Kryptheon warns you about these after a recording, and names the exact step.
129
-
130
- ## Make your AI assistant check its own work
131
-
132
- An assistant will happily call a change done after only reading the code. This
133
- writes a rule into the files assistants already read, so it has to run the check
134
- first:
135
-
136
- ```
137
- npx kryptheon setup-ai
138
- ```
139
-
140
- It writes `CLAUDE.md`, `AGENTS.md` and `.cursorrules`. If a file already exists,
141
- it adds a marked section at the end rather than overwriting anything, and
142
- running it again replaces that section instead of adding a second copy.
143
-
144
- The rule: after any change, run `npx kryptheon check`, show the output, and do
145
- not report the work as done until it passes.
146
-
147
- For an assistant running the check after every change, `--quiet` keeps the
148
- conversation readable — one line when everything passes, the full explanation
149
- only when something breaks:
150
-
151
- ```
152
- npx kryptheon check --quiet
153
- ```
154
-
155
- ```
156
- OK 3 recordings still working.
157
- ```
158
-
159
- ## Automatic checks
160
-
161
- The first time a test passes, kryptheon remembers where the browser ended up and
162
- what the page was called. If either changes later, the test fails and says what
163
- changed — so a recording catches regressions without you writing a single
164
- assertion.
165
-
166
- When a change is intentional, accept it for that one test:
167
-
168
- ```
169
- npx kryptheon accept "Checkout"
170
- ```
171
-
172
- `npx kryptheon accept` on its own lists what has been saved.
173
-
174
- ## Renamed buttons
175
-
176
- A button that only changed its words has not broken anything. When a step
177
- cannot find "Reserve a table" and the page shows exactly one new button in its
178
- place — "Reserve here" — kryptheon clicks that one, carries on through the rest
179
- of the flow, and says so:
180
-
181
- ```
182
- OK Reserve a table (16.0s)
183
- Renamed: The button "Reserve a table" is now called "Reserve here" - I used "Reserve here" and carried on.
184
- Nothing is broken. To stop seeing this, record the flow again.
185
- ```
186
-
187
- It only does this when the page proves it: one name gone, the one the step
188
- wanted, and one new name of the same kind. A button that is gone with nothing
189
- in its place, or a rename next to other new buttons, fails as it always did.
190
- Checks you added with the toolbar are never redirected.
191
-
192
- ## Dashboard
193
-
194
- ```
195
- npx kryptheon
196
- ```
197
-
198
- In a terminal, with no command, this opens a page on your own machine
199
- (`http://127.0.0.1:4789/`) for this project, in your browser by itself (the
200
- address is printed too): what is broken, what needs a look, every run, recent
201
- changes, and switches for each check. Every check runs from a button, one at a
202
- time, with its progress shown on the page as it goes. It is only reachable
203
- from this machine; press Ctrl+C to stop it. From a script, use
204
- `npx kryptheon dashboard`; set `KRYPTHEON_NO_OPEN=1` to keep the browser shut.
205
-
206
- It opens on the one thing to do next, and under it "Start here": read your
207
- code, record your main flows, replay them, connect and check your database,
208
- and set up the nightly check - each marked done only once it has actually run,
209
- and each labelled "one time" or "after every change".
210
-
211
- Checks that are not built yet are listed as "not available" - never as
212
- passed.
213
-
214
- ## Reading your code
215
-
216
- ```
217
- npx kryptheon code
218
- ```
219
-
220
- Reads your frontend code for values put into the page as HTML - `innerHTML`,
221
- `insertAdjacentHTML`, `document.write`, React's `dangerouslySetInnerHTML`,
222
- Vue's `v-html`. If such a value can hold text someone typed, a `<` in it can
223
- run script with the signed-in person's session. Nothing is run; every result
224
- is "verification required", ranked HIGH when the value comes from a server
225
- response or an error message, MEDIUM when the code alone cannot say. The fix
226
- prompt for each one names the file, line and value.
227
-
228
- ## Unusual inputs
229
-
230
- ```
231
- npx kryptheon edge
232
- ```
233
-
234
- Replays your recorded forms with one field at a time given a value people
235
- type by accident: nothing, 5000 characters, text with an HTML tag, emoji, a
236
- negative number, a date that does not exist. It reports only what the run
237
- proves:
238
-
239
- - the page threw an error that the plain replay did not;
240
- - the server answered 5xx where the plain replay did not;
241
- - the app saved a value it should not take - shown as the field's value in
242
- the plain replay's request next to the same field in this one, with the
243
- 2xx answer;
244
- - a tag typed into a field came back as a real element on the page (the app
245
- does not escape it).
246
-
247
- A form that refuses a value is doing its job, so a replay that fails after it
248
- is said as "held", never as a problem. A "too many requests" (429) answer
249
- means that value was not tested. A 5xx or page error is run a second time
250
- before it is called a problem.
251
-
252
- **It adds test data to your app, and leaves it there.** So it never runs on
253
- its own - not after a change, not at night - only when you run the command and
254
- say yes, or press its button in the dashboard. Most of what it types contains
255
- the word `kryptheon-test`; every write that was accepted is listed at the end.
256
- It never creates an account, never changes the sign-in, and never prints or
257
- keeps a password. At most 40 runs per press, with a pause between runs, and
258
- Stop in the dashboard ends it part way.
259
-
260
- Run it against your app on your own computer, or your own test copy. `--yes`
261
- says yes in advance, and only works when every address is on this computer.
262
- For any other address - including a database your local page saves to, which
263
- it notices on the first replay - you are warned and must answer yourself.
264
-
265
- `npx kryptheon recheck <id>` tries a finding's value again: FIXED, or STILL
266
- OPEN with the new proof.
267
-
268
- ## Reliability
269
-
270
- ```
271
- npx kryptheon reliability
272
- ```
273
-
274
- Asks two questions of your recorded flows:
275
-
276
- - **Does it work every time?** Each flow is replayed three times. One that
277
- fails and then works again, with nothing changed, is reported - with the
278
- failed run as proof. It is called a problem only when your app answered
279
- differently in the failed run (a 5xx or a page error the good runs did not
280
- get); without that, the recording's own timing could be the cause, and it
281
- is said as a thing to check. A flow that fails all three times is broken,
282
- which `npx kryptheon check` reports. One that works once and then stops is
283
- a thing to check: the first run's own data may be in the way.
284
- - **What happens on a double-click?** Each step that saves (Save, Add,
285
- Create, Submit...) is clicked twice, quickly. When that saves twice - more
286
- successful POSTs to the same place than one click makes - it is reported
287
- with both answers, and the two record ids the server named when it names
288
- them. A server that answers both clicks with the same record saved it once,
289
- and that is not reported. A double save is tried a second time before it is
290
- called a problem.
291
-
292
- Slower networks are not tried yet.
293
-
294
- Like the input check, **it adds data to your app** - your flows' own saves,
295
- replayed - and leaves it there. It runs only when you say yes, with the same
296
- rules: `--yes` only for an app on this computer, at most 40 runs, Stop in the
297
- dashboard. `npx kryptheon recheck <id>` replays a flaky flow five times (FIXED
298
- only if all five work), or double-clicks the step again.
299
-
300
- ## What goes where
301
-
302
- Only your recordings go in your project, in `tests/`. Everything Kryptheon
303
- remembers about the project is kept outside it, so it can never end up in your
304
- repo:
305
-
306
- ~/.kryptheon/projects/<folder-name>-<id>/
307
- baselines.json the remembered result for each test
308
- history.jsonl one line per run, used for "this was working on …"
309
- test-results/ the screenshot of the last failure
310
-
311
- Set `KRYPTHEON_HOME` to keep them somewhere else. Each project folder gets its
312
- own store, so two projects are never mixed. A project folder that is moved or
313
- renamed starts a new store.
314
-
315
- Older versions kept `kryptheon-baselines.json`, `kryptheon-history.jsonl` and
316
- `test-results/` in the project. The first run of this version moves them out,
317
- once, and says so.
318
-
319
- A `.env` in the same folder is loaded automatically, and anything you type into a
320
- password box is replaced with an environment variable rather than written into
321
- the test. When there is a password, `.env` is added to an existing `.gitignore`.
322
-
323
- ## Requirements
324
-
325
- Node 20.6 or later. The first run downloads a browser (about 200MB, once).
326
-
327
- Recording opens a browser window, so it needs a machine with a screen. It will
328
- always try — if no window appears within 30 seconds it stops and says so,
329
- rather than refusing up front.
330
-
331
- ## Licence
332
-
333
- Proprietary software, not open source - see LICENSE. It runs on your own machine, with no account and no card. The nightly check, with its morning report, alerts and history, is part of the Pro and Studio plans on kryptheon.tech.
1
+ # kryptheon
2
+
3
+ Record a flow in your app once, replay it after every AI change, and get told in
4
+ plain English what broke.
5
+
6
+ Runs entirely on your machine. No account, no API key, nothing leaves your
7
+ computer. It is a wrapper around [Playwright](https://playwright.dev).
8
+
9
+ ## The one command
10
+
11
+ ```
12
+ npx kryptheon@latest dashboard
13
+ ```
14
+
15
+ Run it in your project's folder. It opens a page in your browser, and
16
+ everything else is a button on that page:
17
+
18
+ | | how often |
19
+ | --- | --- |
20
+ | Read my code | after every change |
21
+ | Record a flow | one time - again only when that flow changes |
22
+ | Replay | after every change |
23
+ | Connect your database | one time |
24
+ | Check my database | after every change |
25
+ | Set up the nightly check | one time |
26
+ | Re-check a finding | after every change |
27
+
28
+ Every button shows the terminal command that does the same thing, in small
29
+ print, for when the page cannot be used. The database connection string is
30
+ pasted into the page, used for one run, and never saved, logged or shown
31
+ again; reload the page and it is gone.
32
+
33
+ ## Only have a web address?
34
+
35
+ Built your app in Lovable, Bolt or v0, and there is no project folder on your
36
+ computer? Open a terminal and run:
37
+
38
+ ```
39
+ npx kryptheon record https://your-app.lovable.app
40
+ ```
41
+
42
+ Before it opens anything, it looks at the folder you are in. If that folder is
43
+ not set up for recordings it says so and asks first, then adds a `package.json`
44
+ and kryptheon itself (about 20MB) — nothing else. A new terminal opens in your
45
+ home folder, so from there it keeps your recordings in a `kryptheon-tests`
46
+ folder of their own and tells you where that is.
47
+
48
+ After every change to your app, from that same folder:
49
+
50
+ ```
51
+ npx kryptheon check
52
+ ```
53
+
54
+ ## Install
55
+
56
+ ```
57
+ npm i -D kryptheon
58
+ ```
59
+
60
+ Install it into your project, not globally — every recording imports
61
+ `kryptheon/kryptheon-fixture`, and your tests can only find that if kryptheon is
62
+ in your project's `node_modules`.
63
+
64
+ ## Record
65
+
66
+ ```
67
+ npx kryptheon record https://your-app.example.com
68
+ ```
69
+
70
+ A browser opens. Use your app the way a customer would. Close the browser when
71
+ you are done, and the recording is saved as a test.
72
+
73
+ Add `--phone` to record in a phone-sized window (390 x 844) - for a menu or a
74
+ layout that only changes on a phone. The recording keeps that size, so every
75
+ replay uses it too. On the dashboard it is the "Phone size" box under Record.
76
+
77
+ On its own, a recording knows that every button and field is still there and
78
+ that the last page looks the same. To say what must be true — "Reservation
79
+ received" appears after booking — use the toolbar at the top of the page while
80
+ recording:
81
+
82
+ | Button | Click it, then click… | Kryptheon then checks |
83
+ | --- | --- | --- |
84
+ | Eye | any element | it is on the page |
85
+ | `ab` | some text | that text is there |
86
+ | Box | a filled-in field | the field still holds that value |
87
+ | `{ }` | a part of the page | that part is laid out the same |
88
+
89
+ The round red button pauses and resumes recording. The arrow only shows how an
90
+ element would be found; it adds nothing to the test. One check at the end of a
91
+ flow — on the success message — is usually all a recording needs.
92
+
93
+ ## Check
94
+
95
+ ```
96
+ npx kryptheon check
97
+ ```
98
+
99
+ Runs everything you have recorded:
100
+
101
+ ```
102
+ OK Sign in (4.1s)
103
+
104
+ X Checkout
105
+ Could not find the button "Place order" on the page.
106
+ This was working on 12 Mar at 9:14 AM.
107
+ What to check: your last change may have renamed, hidden, or removed it.
108
+ Where to look:
109
+ - Browser was on: https://your-app.example.com/cart
110
+ - POST /api/orders returned 500
111
+ the server crashed or is unavailable - the error is in backend code, not the page
112
+ ```
113
+
114
+ Every failure ends with a short summary you can paste straight into an AI coding
115
+ tool.
116
+
117
+ ## Recording something that replays
118
+
119
+ A recording is only useful if it still works the second time. So:
120
+
121
+ - **Record one simple flow.** Sign in and look at a page. Open a thing and check
122
+ it loaded. Short beats thorough.
123
+ - **Sign in with an account that already exists.** Do not sign up during a
124
+ recording — the account exists next time, and the signup step fails.
125
+ - **Avoid steps that cannot repeat.** Adding data piles up a row on every run.
126
+ Logging out at the end means the next run does not start where this one did.
127
+
128
+ Kryptheon warns you about these after a recording, and names the exact step -
129
+ and about a step that clicks an error page's words ("Something went wrong",
130
+ "Internal Server Error"): the page you recorded was your app failing, so fix
131
+ that and record again.
132
+
133
+ A password you type is never saved in the test. It becomes a variable named
134
+ for the account it signs in - `KRYPTHEON_PASSWORD_OWNER_EXAMPLE` for
135
+ owner@example.com - so recordings of two accounts (an owner and a member) can
136
+ both run. Put each one in `.env`; Kryptheon lists the names it needs.
137
+
138
+ ## Make your AI assistant check its own work
139
+
140
+ An assistant will happily call a change done after only reading the code. This
141
+ writes a rule into the files assistants already read, so it has to run the check
142
+ first:
143
+
144
+ ```
145
+ npx kryptheon setup-ai
146
+ ```
147
+
148
+ It writes `CLAUDE.md`, `AGENTS.md` and `.cursorrules`. If a file already exists,
149
+ it adds a marked section at the end rather than overwriting anything, and
150
+ running it again replaces that section instead of adding a second copy.
151
+
152
+ The rule: after any change, run `npx kryptheon check`, show the output, and do
153
+ not report the work as done until it passes.
154
+
155
+ For an assistant running the check after every change, `--quiet` keeps the
156
+ conversation readable — one line when everything passes, the full explanation
157
+ only when something breaks:
158
+
159
+ ```
160
+ npx kryptheon check --quiet
161
+ ```
162
+
163
+ ```
164
+ OK 3 recordings still working.
165
+ ```
166
+
167
+ ## Automatic checks
168
+
169
+ The first time a test passes, kryptheon remembers where the browser ended up and
170
+ what the page was called. If either changes later, the test fails and says what
171
+ changed — so a recording catches regressions without you writing a single
172
+ assertion.
173
+
174
+ When a change is intentional, accept it for that one test:
175
+
176
+ ```
177
+ npx kryptheon accept "Checkout"
178
+ ```
179
+
180
+ `npx kryptheon accept` on its own lists what has been saved.
181
+
182
+ ## Renamed buttons
183
+
184
+ A button that only changed its words has not broken anything. When a step
185
+ cannot find "Reserve a table" and the page shows exactly one new button in its
186
+ place — "Reserve here" — kryptheon clicks that one, carries on through the rest
187
+ of the flow, and says so:
188
+
189
+ ```
190
+ OK Reserve a table (16.0s)
191
+ Renamed: The button "Reserve a table" is now called "Reserve here" - I used "Reserve here" and carried on.
192
+ Nothing is broken. To stop seeing this, record the flow again.
193
+ ```
194
+
195
+ It only does this when the page proves it: one name gone, the one the step
196
+ wanted, and one new name of the same kind. A button that is gone with nothing
197
+ in its place, or a rename next to other new buttons, fails as it always did.
198
+ Checks you added with the toolbar are never redirected.
199
+
200
+ The same goes for a text step whose only change is a number - a recording that
201
+ clicked "Projects3" finds "Projects4" after a replay added a project - when
202
+ exactly one text on the page matches:
203
+
204
+ ```
205
+ Renamed: The text "Projects3" now reads "Projects4" - only its number changed, so I clicked it and carried on.
206
+ ```
207
+
208
+ ## Dashboard
209
+
210
+ ```
211
+ npx kryptheon
212
+ ```
213
+
214
+ In a terminal, with no command, this opens a page on your own machine
215
+ (`http://127.0.0.1:4789/`) for this project, in your browser by itself (the
216
+ address is printed too): what is broken, what needs a look, every run, recent
217
+ changes, and switches for each check. Every check runs from a button, one at a
218
+ time, with its progress shown on the page as it goes. It is only reachable
219
+ from this machine; press Ctrl+C to stop it. From a script, use
220
+ `npx kryptheon dashboard`; set `KRYPTHEON_NO_OPEN=1` to keep the browser shut.
221
+
222
+ It opens on the one thing to do next, and under it "Start here": read your
223
+ code, record your main flows, replay them, connect and check your database,
224
+ and set up the nightly check - each marked done only once it has actually run,
225
+ and each labelled "one time" or "after every change".
226
+
227
+ Checks that are not built yet are listed as "not available" - never as
228
+ passed.
229
+
230
+ ## Reading your code
231
+
232
+ ```
233
+ npx kryptheon code
234
+ ```
235
+
236
+ Reads your frontend code for values put into the page as HTML - `innerHTML`,
237
+ `insertAdjacentHTML`, `document.write`, React's `dangerouslySetInnerHTML`,
238
+ Vue's `v-html` - and the pages your server fills in: EJS `<%- %>`, Handlebars
239
+ `{{{ }}}`, Pug `!=`, Nunjucks `| safe`, ERB `<%== %>` and `raw`. If such a
240
+ value can hold text someone typed, a `<` in it can run script with the
241
+ signed-in person's session. A template field whose name says it holds typed
242
+ text (a comment's body, a description) is ranked HIGH. Nothing is run; every result
243
+ is "verification required", ranked HIGH when the value comes from a server
244
+ response or an error message, MEDIUM when the code alone cannot say. The fix
245
+ prompt for each one names the file, line and value.
246
+
247
+ ## Unusual inputs
248
+
249
+ ```
250
+ npx kryptheon edge
251
+ ```
252
+
253
+ Replays your recorded forms with one field at a time given a value people
254
+ type by accident: nothing, 5000 characters, text with an HTML tag, emoji, a
255
+ negative number, a date that does not exist. It reports only what the run
256
+ proves:
257
+
258
+ - the page threw an error that the plain replay did not;
259
+ - the server answered 5xx where the plain replay did not;
260
+ - the app saved a value it should not take - shown as the field's value in
261
+ the plain replay's request next to the same field in this one, with the
262
+ 2xx answer;
263
+ - a tag typed into a field came back as a real element on the page (the app
264
+ does not escape it).
265
+
266
+ Plain HTML forms that post and then redirect work too: a redirect on to
267
+ another page is the save going through (and the page it went to is opened to
268
+ see the value), while a redirect back to the form, to the sign-in page, or
269
+ with an error in its address - or the form drawn again - is the app refusing.
270
+ The same problem found by two flows (a create and an edit) is said once.
271
+
272
+ A form that refuses a value is doing its job, so a replay that fails after it
273
+ is said as "held", never as a problem. A "too many requests" (429) answer
274
+ means that value was not tested. A 5xx or page error is run a second time
275
+ before it is called a problem.
276
+
277
+ **It adds test data to your app, and leaves it there.** So it never runs on
278
+ its own - not after a change, not at night - only when you run the command and
279
+ say yes, or press its button in the dashboard. Most of what it types contains
280
+ the word `kryptheon-test`; every write that was accepted is listed at the end.
281
+ It never creates an account, never changes the sign-in, and never prints or
282
+ keeps a password. At most 40 runs per press, with a pause between runs, and
283
+ Stop in the dashboard ends it part way.
284
+
285
+ Run it against your app on your own computer, or your own test copy. `--yes`
286
+ says yes in advance, and only works when every address is on this computer.
287
+ For any other address - including a database your local page saves to, which
288
+ it notices on the first replay - you are warned and must answer yourself.
289
+
290
+ `npx kryptheon recheck <id>` tries a finding's value again: FIXED, or STILL
291
+ OPEN with the new proof.
292
+
293
+ ## Reliability
294
+
295
+ ```
296
+ npx kryptheon reliability
297
+ ```
298
+
299
+ Asks these questions of your recorded flows:
300
+
301
+ - **Does it work every time?** Each flow is replayed three times. One that
302
+ fails and then works again, with nothing changed, is reported - with the
303
+ failed run as proof. It is called a problem only when your app answered
304
+ differently in the failed run (a 5xx or a page error the good runs did not
305
+ get); without that, the recording's own timing could be the cause, and it
306
+ is said as a thing to check. A flow that fails all three times is broken,
307
+ which `npx kryptheon check` reports. One that works once and then stops is
308
+ a thing to check: the first run's own data may be in the way.
309
+ - **What happens on a double-click?** Each step that saves (Save, Add,
310
+ Create, Submit...) is clicked twice, quickly. When that saves twice - more
311
+ successful POSTs to the same place than one click makes - it is reported
312
+ with both answers, and the two record ids the server named when it names
313
+ them. A server that answers both clicks with the same record saved it once,
314
+ and that is not reported. A double save is tried a second time before it is
315
+ called a problem. On an app on this computer, the save is also sent twice
316
+ at the same moment, to ask the server rather than the button. When a form
317
+ answers with a redirect, which names no record, the page opened again
318
+ decides: what was typed shows up twice, or once.
319
+ - **Was the edit kept?** After a step that saves an edit, the form is opened
320
+ again in a new tab and each field it typed into is read back. A field that
321
+ still shows its old value - a description that was not saved, a date that
322
+ could not be cleared - is reported, one finding per field. A form for
323
+ something new, or a save the app refused, is not judged.
324
+
325
+ Slower networks are not tried yet.
326
+
327
+ Like the input check, **it adds data to your app** - your flows' own saves,
328
+ replayed - and leaves it there. It runs only when you say yes, with the same
329
+ rules: `--yes` only for an app on this computer, at most 40 runs, Stop in the
330
+ dashboard. `npx kryptheon recheck <id>` replays a flaky flow five times (FIXED
331
+ only if all five work), or double-clicks the step again.
332
+
333
+ ## Payments
334
+
335
+ ```
336
+ KRYPTHEON_DATABASE_URL="postgresql://..." npx kryptheon payments --app http://localhost:3000
337
+ ```
338
+
339
+ Asks one question, of a real payment: **does the same payment webhook, sent
340
+ again, give the customer the plan, the credits or the order a second time?**
341
+ Razorpay and Stripe send a webhook again whenever your server is slow or
342
+ answers with an error, so a handler that grants every time it is called will,
343
+ one day, grant twice.
344
+
345
+ 1. A small proxy starts on this computer (port 4790) and passes everything on
346
+ to your app unchanged.
347
+ 2. You point your provider's **test-mode** webhook at it -
348
+ `stripe listen --forward-to localhost:4790/<path>`, or for Razorpay
349
+ `ngrok http 4790` and that address in Dashboard (Test Mode) > Webhooks -
350
+ and make your test payments in your app, one at a time - each is checked as it
351
+ comes, until you press Stop (or Ctrl-C).
352
+ 3. The provider's own signed webhook reaches your app through the proxy.
353
+ Kryptheon sends the identical webhook again, then a copy with a wrong
354
+ signature, and reads your database before and after each one - on this
355
+ computer, never writing to it itself.
356
+
357
+ What changed is the proof: `profiles.credits 100 -> 200`, `subscriptions.current_period_end`
358
+ a month later, a second order. A new row in a log table and a moved
359
+ `updated_at` are shown as normal, not as a problem. It also reports an app
360
+ that answers a repeat with an error (the provider keeps resending, and
361
+ Razorpay switches a failing webhook off), and one that accepts a wrong
362
+ signature. Each finding comes with a prompt to paste into your AI tool.
363
+
364
+ Every run keeps its own trace on this computer (the newest 50, in the
365
+ project's store under `payments/`): for each delivery - the provider's own,
366
+ the repeat, the wrong signature - when it went, how long the app took, what
367
+ it answered, and every row it wrote (table, primary key, before and after).
368
+ The database is read once before the provider's webhook reaches your app, so
369
+ the first delivery's own writes are there too (`credits 0 -> 100`, then the
370
+ repeat's `100 -> 200`). Webhook bodies, headers and signatures are never kept
371
+ - a SHA-256 of the body shows the repeat was the same bytes - and columns that
372
+ look like secrets (password, token, key, card, otp ...) are written as
373
+ `[hidden]`.
374
+
375
+ It never sends a live-mode payment again: Stripe's `livemode`, or a
376
+ `rzp_live_` key in your `.env`, stops it. When it cannot tell Razorpay's mode,
377
+ it asks you to say `--test-mode`. Use your development database: your app does
378
+ process the copies, so if it has this bug your test account gets the plan or
379
+ credits again. Not tested yet: two copies arriving at the same moment on the
380
+ first delivery, and work your app does more than 4 seconds after a webhook.
381
+
382
+ ## What goes where
383
+
384
+ Only your recordings go in your project, in `tests/`. Everything Kryptheon
385
+ remembers about the project is kept outside it, so it can never end up in your
386
+ repo:
387
+
388
+ ~/.kryptheon/projects/<folder-name>-<id>/
389
+ baselines.json the remembered result for each test
390
+ history.jsonl one line per run, used for "this was working on …"
391
+ test-results/ the screenshot of the last failure
392
+
393
+ Set `KRYPTHEON_HOME` to keep them somewhere else. Each project folder gets its
394
+ own store, so two projects are never mixed. A project folder that is moved or
395
+ renamed starts a new store.
396
+
397
+ Older versions kept `kryptheon-baselines.json`, `kryptheon-history.jsonl` and
398
+ `test-results/` in the project. The first run of this version moves them out,
399
+ once, and says so.
400
+
401
+ A `.env` in the same folder is loaded automatically, and anything you type into a
402
+ password box is replaced with an environment variable rather than written into
403
+ the test. When there is a password, `.env` is added to an existing `.gitignore`.
404
+
405
+ ## What Kryptheon does not check
406
+
407
+ No check here looks at these, so a clean report says nothing about them.
408
+ The dashboard lists them too, under Checks.
409
+
410
+ - **Who can do what.** Whether a lower role - a member, a customer - can
411
+ open, change or delete what only a higher role should, or reach another
412
+ account's record by changing an id in the address. Each recording is
413
+ replayed as the person who made it. Sign in as each role and open the
414
+ higher role's pages and actions directly.
415
+ - **Payment rules beyond a repeat.** Only the same webhook sent again, and a
416
+ copy with a wrong signature, are tried - not a webhook with no signature,
417
+ an amount or currency that does not match the order, buying again while a
418
+ plan is active, or when a refund takes access away.
419
+ - **Whether numbers and lists are right.** A count or total that leaves
420
+ something out, a search or filter that drops results.
421
+ - **Permissions decided in your server code.** The database check tests what
422
+ the database itself enforces (row level security, grants); an app that
423
+ decides who sees what in its own code is not tested there.
424
+
425
+ ## Requirements
426
+
427
+ Node 20.6 or later. The first run downloads a browser (about 200MB, once).
428
+
429
+ Recording opens a browser window, so it needs a machine with a screen. It will
430
+ always try — if no window appears within 30 seconds it stops and says so,
431
+ rather than refusing up front.
432
+
433
+ ## Licence
434
+
435
+ Proprietary software, not open source - see LICENSE. It runs on your own machine, with no account and no card. The nightly check, with its morning report, alerts and history, is part of the Pro and Studio plans on kryptheon.tech.