kryptheon 0.1.58 → 0.1.62

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.
@@ -1,232 +1,232 @@
1
- // Keeping a saved result tied to the recording it came from.
2
- //
3
- // A baseline used to be identified by where the recording lived and what it was
4
- // called. That is not enough. Delete the spec files with `del tests\*.spec.js` -
5
- // which is what anyone does before the tool has taught them `kryptheon remove` -
6
- // record the flow again, and the new recording is handed the same name. Same
7
- // path, same title, same key. It inherits the old recording's saved page and
8
- // fails on its very first run, against a baseline it never created and could
9
- // never have matched.
10
- //
11
- // The report that came out of that said both of these at once:
12
- //
13
- // This has not passed before.
14
- // Headings that are gone: "Transactions"
15
- //
16
- // Which cannot both be true. If it has never passed there is no baseline of its
17
- // own to have changed, so there is nothing to show a difference against.
18
- //
19
- // So a saved result now also records a fingerprint of the recording that made
20
- // it. When the recording is gone, or its steps are not the steps the baseline
21
- // was taken from, the saved result describes something that no longer exists
22
- // and is thrown away rather than compared against.
23
- //
24
- // Pure data work: no Playwright, no test runner.
25
-
26
- const fs = require('fs');
27
- const path = require('path');
28
- const replay = require('./kryptheon-replay.js');
29
-
30
- /** The spec file half of a baseline key, in one consistent shape. */
31
- function specOf(key) {
32
- return String(key || '').split(' :: ')[0].split('\\').join('/');
33
- }
34
-
35
- function titleOf(key) {
36
- const parts = String(key || '').split(' :: ');
37
- return parts.length > 1 ? parts.slice(1).join(' :: ') : '';
38
- }
39
-
40
- /** The fingerprint of the recording in a file, or null if it cannot be read. */
41
- function fingerprintOf(userDir, specPath) {
42
- let source;
43
- try {
44
- source = fs.readFileSync(path.join(userDir, specPath), 'utf8');
45
- } catch (e) {
46
- return null;
47
- }
48
- return replay.recordingId(source);
49
- }
50
-
51
- /**
52
- * What each saved result is: still current, orphaned, or stale.
53
- *
54
- * `orphan` - the recording it belongs to is not there any more.
55
- * `stale` - a recording of that name exists, but it is not the one this was
56
- * taken from. This is the case that cost twenty minutes: the file
57
- * is present, so nothing looks wrong.
58
- * `legacy` - written before fingerprints existed. There is no way to tell
59
- * whether it matches, so it is kept, and a fingerprint is written
60
- * in so the question can be answered next time. Guessing here would
61
- * mean either throwing away a good baseline or, far worse, quietly
62
- * accepting a real regression as the new normal.
63
- */
64
- function classifyBaselines(baselines, userDir) {
65
- const all = baselines || {};
66
- const verdicts = [];
67
-
68
- for (const key of Object.keys(all)) {
69
- const entry = all[key];
70
- const spec = specOf(key);
71
- if (!entry || typeof entry !== 'object') {
72
- verdicts.push({ key: key, state: 'orphan', spec: spec, title: titleOf(key) });
73
- continue;
74
- }
75
-
76
- let exists = false;
77
- try {
78
- exists = fs.statSync(path.join(userDir, spec)).isFile();
79
- } catch (e) {
80
- exists = false;
81
- }
82
- if (!exists) {
83
- verdicts.push({ key: key, state: 'orphan', spec: spec, title: titleOf(key) });
84
- continue;
85
- }
86
-
87
- const now = fingerprintOf(userDir, spec);
88
- if (!entry.recordingId) {
89
- verdicts.push({ key: key, state: 'legacy', spec: spec, title: titleOf(key), fingerprint: now });
90
- continue;
91
- }
92
- if (now && entry.recordingId !== now) {
93
- verdicts.push({ key: key, state: 'stale', spec: spec, title: titleOf(key), fingerprint: now });
94
- continue;
95
- }
96
- verdicts.push({ key: key, state: 'current', spec: spec, title: titleOf(key) });
97
- }
98
-
99
- return verdicts;
100
- }
101
-
102
- /**
103
- * The saved results with the dead ones taken out.
104
- *
105
- * Returns a new object; nothing is written here. The caller decides whether the
106
- * file is worth rewriting, so a check that changes nothing never touches it.
107
- */
108
- function pruneBaselines(baselines, userDir) {
109
- const all = baselines || {};
110
- const verdicts = classifyBaselines(all, userDir);
111
- const kept = {};
112
- const dropped = [];
113
- let stamped = 0;
114
-
115
- for (const verdict of verdicts) {
116
- if (verdict.state === 'orphan' || verdict.state === 'stale') {
117
- dropped.push(verdict);
118
- continue;
119
- }
120
- const entry = all[verdict.key];
121
- if (verdict.state === 'legacy' && verdict.fingerprint) {
122
- // Kept as it is, but tied to this recording from now on.
123
- kept[verdict.key] = Object.assign({}, entry, { recordingId: verdict.fingerprint });
124
- stamped++;
125
- continue;
126
- }
127
- kept[verdict.key] = entry;
128
- }
129
-
130
- return { baselines: kept, dropped: dropped, stamped: stamped, changed: dropped.length > 0 || stamped > 0 };
131
- }
132
-
133
- function plural(n, word) {
134
- return n + ' ' + word + (n === 1 ? '' : 's');
135
- }
136
-
137
- /**
138
- * One line about what was thrown away, said as a fact rather than a warning.
139
- *
140
- * Nothing has gone wrong when this happens - a recording was deleted or redone,
141
- * which is a normal thing to do. It is said out loud only so that a flow which
142
- * suddenly starts from scratch is not a mystery.
143
- */
144
- function pruneLines(dropped) {
145
- const list = dropped || [];
146
- if (!list.length) return [];
147
-
148
- const orphans = list.filter((d) => d.state === 'orphan');
149
- const stale = list.filter((d) => d.state === 'stale');
150
- const lines = [];
151
-
152
- if (orphans.length) {
153
- lines.push(
154
- ' ' + plural(orphans.length, 'old baseline') + ' removed - ' +
155
- (orphans.length === 1 ? 'its recording is' : 'their recordings are') + ' no longer here.',
156
- );
157
- }
158
- if (stale.length) {
159
- lines.push(
160
- ' ' + plural(stale.length, 'old baseline') + ' removed - ' +
161
- (stale.length === 1 ? 'its recording has' : 'those recordings have') +
162
- ' been recorded again since.',
163
- );
164
- }
165
- lines.push('');
166
- return lines;
167
- }
168
-
169
- /**
170
- * The last run of one recorded test, from the run history: whether it
171
- * passed, and where it broke if it did not. Null when it has never run.
172
- */
173
- function lastRunOf(historyFile, key) {
174
- let lines = [];
175
- try {
176
- lines = fs.readFileSync(historyFile, 'utf8').split('\n').filter(Boolean);
177
- } catch (e) {
178
- return null;
179
- }
180
- const spec = specOf(key);
181
- const title = titleOf(key);
182
- for (let i = lines.length - 1; i >= 0; i--) {
183
- let entry;
184
- try {
185
- entry = JSON.parse(lines[i]);
186
- } catch (e) {
187
- continue;
188
- }
189
- const test = (entry.tests || []).find((t) => t && t.title === title && specOf(t.specFile) === spec);
190
- if (test) return { status: test.status, at: entry.runAt, failure: test.failure || null };
191
- }
192
- return null;
193
- }
194
-
195
- /**
196
- * What accept says when there is nothing it can take, from the last run.
197
- *
198
- * Found on a blind test (HelixOps): a step was broken on purpose, and accept
199
- * answered "it last matched its saved result" - the opposite of what had
200
- * happened. accept only takes a run that went all the way through and ended
201
- * on a different page; a step that no longer matches is a changed flow or a
202
- * broken app, and neither is accepted.
203
- */
204
- function nothingToAcceptLines(name, last) {
205
- if (last && last.status === 'failed') {
206
- const failure = last.failure || {};
207
- const where = failure.line ? ' at line ' + failure.line + (failure.file ? ' of ' + specOf(failure.file) : '') : '';
208
- const what = failure.plainLanguage ? ' (' + String(failure.plainLanguage).replace(/\.$/, '') + ')' : '';
209
- return [
210
- '"' + name + '" has nothing to accept: its last run broke' + where + ', before the end' + what + '.',
211
- 'accept only covers a run that went all the way through and finished on a different page - ' +
212
- 'a new address or a new title.',
213
- 'A step that no longer matches cannot be accepted. If the flow changed on purpose, record it ' +
214
- 'again (npx kryptheon record). If it did not, the app broke, and npx kryptheon check says what to fix.',
215
- ];
216
- }
217
- if (last && last.status === 'passed') {
218
- return ['"' + name + '" has no new result waiting.', 'Nothing to accept - its last run matched its saved result.'];
219
- }
220
- return ['"' + name + '" has no new result waiting.', 'Nothing to accept - no run has finished on a different page.'];
221
- }
222
-
223
- module.exports = {
224
- specOf: specOf,
225
- titleOf: titleOf,
226
- fingerprintOf: fingerprintOf,
227
- classifyBaselines: classifyBaselines,
228
- pruneBaselines: pruneBaselines,
229
- pruneLines: pruneLines,
230
- lastRunOf: lastRunOf,
231
- nothingToAcceptLines: nothingToAcceptLines,
232
- };
1
+ // Keeping a saved result tied to the recording it came from.
2
+ //
3
+ // A baseline used to be identified by where the recording lived and what it was
4
+ // called. That is not enough. Delete the spec files with `del tests\*.spec.js` -
5
+ // which is what anyone does before the tool has taught them `kryptheon remove` -
6
+ // record the flow again, and the new recording is handed the same name. Same
7
+ // path, same title, same key. It inherits the old recording's saved page and
8
+ // fails on its very first run, against a baseline it never created and could
9
+ // never have matched.
10
+ //
11
+ // The report that came out of that said both of these at once:
12
+ //
13
+ // This has not passed before.
14
+ // Headings that are gone: "Transactions"
15
+ //
16
+ // Which cannot both be true. If it has never passed there is no baseline of its
17
+ // own to have changed, so there is nothing to show a difference against.
18
+ //
19
+ // So a saved result now also records a fingerprint of the recording that made
20
+ // it. When the recording is gone, or its steps are not the steps the baseline
21
+ // was taken from, the saved result describes something that no longer exists
22
+ // and is thrown away rather than compared against.
23
+ //
24
+ // Pure data work: no Playwright, no test runner.
25
+
26
+ const fs = require('fs');
27
+ const path = require('path');
28
+ const replay = require('./kryptheon-replay.js');
29
+
30
+ /** The spec file half of a baseline key, in one consistent shape. */
31
+ function specOf(key) {
32
+ return String(key || '').split(' :: ')[0].split('\\').join('/');
33
+ }
34
+
35
+ function titleOf(key) {
36
+ const parts = String(key || '').split(' :: ');
37
+ return parts.length > 1 ? parts.slice(1).join(' :: ') : '';
38
+ }
39
+
40
+ /** The fingerprint of the recording in a file, or null if it cannot be read. */
41
+ function fingerprintOf(userDir, specPath) {
42
+ let source;
43
+ try {
44
+ source = fs.readFileSync(path.join(userDir, specPath), 'utf8');
45
+ } catch (e) {
46
+ return null;
47
+ }
48
+ return replay.recordingId(source);
49
+ }
50
+
51
+ /**
52
+ * What each saved result is: still current, orphaned, or stale.
53
+ *
54
+ * `orphan` - the recording it belongs to is not there any more.
55
+ * `stale` - a recording of that name exists, but it is not the one this was
56
+ * taken from. This is the case that cost twenty minutes: the file
57
+ * is present, so nothing looks wrong.
58
+ * `legacy` - written before fingerprints existed. There is no way to tell
59
+ * whether it matches, so it is kept, and a fingerprint is written
60
+ * in so the question can be answered next time. Guessing here would
61
+ * mean either throwing away a good baseline or, far worse, quietly
62
+ * accepting a real regression as the new normal.
63
+ */
64
+ function classifyBaselines(baselines, userDir) {
65
+ const all = baselines || {};
66
+ const verdicts = [];
67
+
68
+ for (const key of Object.keys(all)) {
69
+ const entry = all[key];
70
+ const spec = specOf(key);
71
+ if (!entry || typeof entry !== 'object') {
72
+ verdicts.push({ key: key, state: 'orphan', spec: spec, title: titleOf(key) });
73
+ continue;
74
+ }
75
+
76
+ let exists = false;
77
+ try {
78
+ exists = fs.statSync(path.join(userDir, spec)).isFile();
79
+ } catch (e) {
80
+ exists = false;
81
+ }
82
+ if (!exists) {
83
+ verdicts.push({ key: key, state: 'orphan', spec: spec, title: titleOf(key) });
84
+ continue;
85
+ }
86
+
87
+ const now = fingerprintOf(userDir, spec);
88
+ if (!entry.recordingId) {
89
+ verdicts.push({ key: key, state: 'legacy', spec: spec, title: titleOf(key), fingerprint: now });
90
+ continue;
91
+ }
92
+ if (now && entry.recordingId !== now) {
93
+ verdicts.push({ key: key, state: 'stale', spec: spec, title: titleOf(key), fingerprint: now });
94
+ continue;
95
+ }
96
+ verdicts.push({ key: key, state: 'current', spec: spec, title: titleOf(key) });
97
+ }
98
+
99
+ return verdicts;
100
+ }
101
+
102
+ /**
103
+ * The saved results with the dead ones taken out.
104
+ *
105
+ * Returns a new object; nothing is written here. The caller decides whether the
106
+ * file is worth rewriting, so a check that changes nothing never touches it.
107
+ */
108
+ function pruneBaselines(baselines, userDir) {
109
+ const all = baselines || {};
110
+ const verdicts = classifyBaselines(all, userDir);
111
+ const kept = {};
112
+ const dropped = [];
113
+ let stamped = 0;
114
+
115
+ for (const verdict of verdicts) {
116
+ if (verdict.state === 'orphan' || verdict.state === 'stale') {
117
+ dropped.push(verdict);
118
+ continue;
119
+ }
120
+ const entry = all[verdict.key];
121
+ if (verdict.state === 'legacy' && verdict.fingerprint) {
122
+ // Kept as it is, but tied to this recording from now on.
123
+ kept[verdict.key] = Object.assign({}, entry, { recordingId: verdict.fingerprint });
124
+ stamped++;
125
+ continue;
126
+ }
127
+ kept[verdict.key] = entry;
128
+ }
129
+
130
+ return { baselines: kept, dropped: dropped, stamped: stamped, changed: dropped.length > 0 || stamped > 0 };
131
+ }
132
+
133
+ function plural(n, word) {
134
+ return n + ' ' + word + (n === 1 ? '' : 's');
135
+ }
136
+
137
+ /**
138
+ * One line about what was thrown away, said as a fact rather than a warning.
139
+ *
140
+ * Nothing has gone wrong when this happens - a recording was deleted or redone,
141
+ * which is a normal thing to do. It is said out loud only so that a flow which
142
+ * suddenly starts from scratch is not a mystery.
143
+ */
144
+ function pruneLines(dropped) {
145
+ const list = dropped || [];
146
+ if (!list.length) return [];
147
+
148
+ const orphans = list.filter((d) => d.state === 'orphan');
149
+ const stale = list.filter((d) => d.state === 'stale');
150
+ const lines = [];
151
+
152
+ if (orphans.length) {
153
+ lines.push(
154
+ ' ' + plural(orphans.length, 'old baseline') + ' removed - ' +
155
+ (orphans.length === 1 ? 'its recording is' : 'their recordings are') + ' no longer here.',
156
+ );
157
+ }
158
+ if (stale.length) {
159
+ lines.push(
160
+ ' ' + plural(stale.length, 'old baseline') + ' removed - ' +
161
+ (stale.length === 1 ? 'its recording has' : 'those recordings have') +
162
+ ' been recorded again since.',
163
+ );
164
+ }
165
+ lines.push('');
166
+ return lines;
167
+ }
168
+
169
+ /**
170
+ * The last run of one recorded test, from the run history: whether it
171
+ * passed, and where it broke if it did not. Null when it has never run.
172
+ */
173
+ function lastRunOf(historyFile, key) {
174
+ let lines = [];
175
+ try {
176
+ lines = fs.readFileSync(historyFile, 'utf8').split('\n').filter(Boolean);
177
+ } catch (e) {
178
+ return null;
179
+ }
180
+ const spec = specOf(key);
181
+ const title = titleOf(key);
182
+ for (let i = lines.length - 1; i >= 0; i--) {
183
+ let entry;
184
+ try {
185
+ entry = JSON.parse(lines[i]);
186
+ } catch (e) {
187
+ continue;
188
+ }
189
+ const test = (entry.tests || []).find((t) => t && t.title === title && specOf(t.specFile) === spec);
190
+ if (test) return { status: test.status, at: entry.runAt, failure: test.failure || null };
191
+ }
192
+ return null;
193
+ }
194
+
195
+ /**
196
+ * What accept says when there is nothing it can take, from the last run.
197
+ *
198
+ * Found on a blind test (HelixOps): a step was broken on purpose, and accept
199
+ * answered "it last matched its saved result" - the opposite of what had
200
+ * happened. accept only takes a run that went all the way through and ended
201
+ * on a different page; a step that no longer matches is a changed flow or a
202
+ * broken app, and neither is accepted.
203
+ */
204
+ function nothingToAcceptLines(name, last) {
205
+ if (last && last.status === 'failed') {
206
+ const failure = last.failure || {};
207
+ const where = failure.line ? ' at line ' + failure.line + (failure.file ? ' of ' + specOf(failure.file) : '') : '';
208
+ const what = failure.plainLanguage ? ' (' + String(failure.plainLanguage).replace(/\.$/, '') + ')' : '';
209
+ return [
210
+ '"' + name + '" has nothing to accept: its last run broke' + where + ', before the end' + what + '.',
211
+ 'accept only covers a run that went all the way through and finished on a different page - ' +
212
+ 'a new address or a new title.',
213
+ 'A step that no longer matches cannot be accepted. If the flow changed on purpose, record it ' +
214
+ 'again (npx kryptheon record). If it did not, the app broke, and npx kryptheon check says what to fix.',
215
+ ];
216
+ }
217
+ if (last && last.status === 'passed') {
218
+ return ['"' + name + '" has no new result waiting.', 'Nothing to accept - its last run matched its saved result.'];
219
+ }
220
+ return ['"' + name + '" has no new result waiting.', 'Nothing to accept - no run has finished on a different page.'];
221
+ }
222
+
223
+ module.exports = {
224
+ specOf: specOf,
225
+ titleOf: titleOf,
226
+ fingerprintOf: fingerprintOf,
227
+ classifyBaselines: classifyBaselines,
228
+ pruneBaselines: pruneBaselines,
229
+ pruneLines: pruneLines,
230
+ lastRunOf: lastRunOf,
231
+ nothingToAcceptLines: nothingToAcceptLines,
232
+ };