@regressionbot/sdk 1.2.3 ā 2.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +291 -8
- package/dist/cli.d.ts +27 -1
- package/dist/cli.js +194 -43
- package/dist/index.d.ts +27 -9
- package/dist/index.js +54 -15
- package/dist/types.d.ts +330 -27
- package/package.json +1 -1
package/dist/cli.js
CHANGED
|
@@ -34,34 +34,130 @@ var __importStar = (this && this.__importStar) || (function () {
|
|
|
34
34
|
};
|
|
35
35
|
})();
|
|
36
36
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
37
|
+
exports.parseArgs = parseArgs;
|
|
38
|
+
exports.parseFailOn = parseFailOn;
|
|
39
|
+
exports.isBlocking = isBlocking;
|
|
40
|
+
exports.selectBlocking = selectBlocking;
|
|
41
|
+
exports.buildRunContext = buildRunContext;
|
|
42
|
+
exports.printRegression = printRegression;
|
|
37
43
|
const index_1 = require("./index");
|
|
38
44
|
const security_1 = require("./security");
|
|
39
45
|
const path = __importStar(require("path"));
|
|
46
|
+
function formatSummary(items) {
|
|
47
|
+
if (!items || items.length === 0)
|
|
48
|
+
return '';
|
|
49
|
+
return items
|
|
50
|
+
.map(item => (item.label ? `[${item.label}] ${item.text}` : item.text))
|
|
51
|
+
.join('\n ');
|
|
52
|
+
}
|
|
53
|
+
function printRegression(r) {
|
|
54
|
+
console.log(`- ${r.url} [${r.variantName}] (Score: ${r.visualMatchScore.toFixed(2)})`);
|
|
55
|
+
if (r.diffUrl)
|
|
56
|
+
console.log(` Diff: ${r.diffUrl}`);
|
|
57
|
+
if (r.verdict) {
|
|
58
|
+
console.log(` Verdict: ${r.verdict.decision} (confidence ${r.verdict.minConfidence.toFixed(2)}-${r.verdict.avgConfidence.toFixed(2)})`);
|
|
59
|
+
}
|
|
60
|
+
const summary = formatSummary(r.regressionbotSummary);
|
|
61
|
+
if (summary)
|
|
62
|
+
console.log(` Summary: ${summary}`);
|
|
63
|
+
}
|
|
64
|
+
/**
|
|
65
|
+
* A mistake in how the command was invoked, rather than a run that worked and found
|
|
66
|
+
* something. Exits 2 so CI can tell the two apart ā a pipeline that treats "regressions
|
|
67
|
+
* found" as a real result but "bad flag" as a broken job could not distinguish them when
|
|
68
|
+
* both exited 1.
|
|
69
|
+
*/
|
|
70
|
+
class UsageError extends Error {
|
|
71
|
+
}
|
|
72
|
+
function printIntent(summary) {
|
|
73
|
+
const ia = summary.intentAssessment;
|
|
74
|
+
if (!ia || !ia.intentProvided)
|
|
75
|
+
return;
|
|
76
|
+
console.log(`\nš§ Intent: ${ia.summary}`);
|
|
77
|
+
console.log(` bugs: ${ia.bugCount}, intentional: ${ia.intentionalCount}, noise: ${ia.noiseCount}, needs review: ${ia.needsReviewCount}`);
|
|
78
|
+
}
|
|
79
|
+
function parseFailOn(raw) {
|
|
80
|
+
if (raw === undefined)
|
|
81
|
+
return 'any';
|
|
82
|
+
if (raw === 'any' || raw === 'unintended')
|
|
83
|
+
return raw;
|
|
84
|
+
throw new UsageError("--fail-on takes 'any' or 'unintended'.");
|
|
85
|
+
}
|
|
86
|
+
/**
|
|
87
|
+
* Whether one regression should fail the build under `--fail-on unintended`.
|
|
88
|
+
*
|
|
89
|
+
* A regression with no verdict always blocks. Nothing judged it ā the run carried no
|
|
90
|
+
* intent, or the summary pass had not finished ā and treating unjudged as wanted would
|
|
91
|
+
* turn a missing verdict into a silent pass, which is the one outcome a regression
|
|
92
|
+
* detector must never produce.
|
|
93
|
+
*/
|
|
94
|
+
function isBlocking(r) {
|
|
95
|
+
if (!r.verdict)
|
|
96
|
+
return true;
|
|
97
|
+
return r.verdict.decision === 'bug' || r.verdict.decision === 'needs_review';
|
|
98
|
+
}
|
|
99
|
+
/**
|
|
100
|
+
* Splits regressions into the ones that fail the build and a count of the ones excused.
|
|
101
|
+
*
|
|
102
|
+
* Pure, and exported, because this is the decision that sets the exit code ā the whole
|
|
103
|
+
* point of --fail-on. Testing isBlocking alone proves nothing about whether the caller
|
|
104
|
+
* applies it correctly for each mode.
|
|
105
|
+
*/
|
|
106
|
+
function selectBlocking(regressions, failOn) {
|
|
107
|
+
const blocking = failOn === 'any' ? regressions : regressions.filter(isBlocking);
|
|
108
|
+
return { blocking, excused: regressions.length - blocking.length };
|
|
109
|
+
}
|
|
110
|
+
function buildRunContext(options) {
|
|
111
|
+
const context = {};
|
|
112
|
+
if (typeof options['change-description'] === 'string')
|
|
113
|
+
context.changeDescription = options['change-description'];
|
|
114
|
+
if (typeof options['pr-title'] === 'string')
|
|
115
|
+
context.prTitle = options['pr-title'];
|
|
116
|
+
if (typeof options.commit === 'string')
|
|
117
|
+
context.gitCommitSha = options.commit;
|
|
118
|
+
if (typeof options['expected-changes'] === 'string') {
|
|
119
|
+
const expected = options['expected-changes'].split(',').map((s) => s.trim()).filter(Boolean);
|
|
120
|
+
if (expected.length > 0)
|
|
121
|
+
context.expectedChanges = expected;
|
|
122
|
+
}
|
|
123
|
+
return Object.keys(context).length > 0 ? context : undefined;
|
|
124
|
+
}
|
|
125
|
+
// š”ļø SECURITY: never let an argument name reach Object.prototype.
|
|
126
|
+
const BLOCKED_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
|
|
40
127
|
function parseArgs(args) {
|
|
41
128
|
const options = Object.create(null);
|
|
42
129
|
options._ = [];
|
|
43
130
|
for (let i = 0; i < args.length; i++) {
|
|
44
131
|
const arg = args[i];
|
|
45
|
-
if (arg.startsWith('--')) {
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
132
|
+
if (!arg.startsWith('--')) {
|
|
133
|
+
options._.push(arg);
|
|
134
|
+
continue;
|
|
135
|
+
}
|
|
136
|
+
const body = arg.slice(2);
|
|
137
|
+
const eq = body.indexOf('=');
|
|
138
|
+
// --key=value carries its own value, so the value survives even when it starts
|
|
139
|
+
// with '--'. That is the only way to pass CSS custom properties:
|
|
140
|
+
// `--custom-css="--brand: red"` loses its value in the space-separated form,
|
|
141
|
+
// because a leading '--' is indistinguishable from the next flag.
|
|
142
|
+
if (eq !== -1) {
|
|
143
|
+
const key = body.slice(0, eq);
|
|
144
|
+
if (!BLOCKED_KEYS.has(key))
|
|
145
|
+
options[key] = body.slice(eq + 1);
|
|
146
|
+
continue;
|
|
147
|
+
}
|
|
148
|
+
if (BLOCKED_KEYS.has(body)) {
|
|
54
149
|
const value = args[i + 1];
|
|
55
|
-
if (value && !value.startsWith('--'))
|
|
56
|
-
options[key] = value;
|
|
150
|
+
if (value && !value.startsWith('--'))
|
|
57
151
|
i++;
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
152
|
+
continue;
|
|
153
|
+
}
|
|
154
|
+
const value = args[i + 1];
|
|
155
|
+
if (value && !value.startsWith('--')) {
|
|
156
|
+
options[body] = value;
|
|
157
|
+
i++;
|
|
62
158
|
}
|
|
63
159
|
else {
|
|
64
|
-
options
|
|
160
|
+
options[body] = true;
|
|
65
161
|
}
|
|
66
162
|
}
|
|
67
163
|
return options;
|
|
@@ -104,7 +200,7 @@ async function main() {
|
|
|
104
200
|
catch (error) {
|
|
105
201
|
console.error(`
|
|
106
202
|
Error: ${error.message}`);
|
|
107
|
-
process.exit(1);
|
|
203
|
+
process.exit(error instanceof UsageError ? 2 : 1);
|
|
108
204
|
}
|
|
109
205
|
}
|
|
110
206
|
function showHelp() {
|
|
@@ -126,23 +222,56 @@ Options for <url>:
|
|
|
126
222
|
--on <devices> Comma-separated device names (e.g. "Desktop Chrome,iPhone 12").
|
|
127
223
|
--scan <pattern> Glob pattern to scan in sitemap (e.g. "/blog/**").
|
|
128
224
|
--exclude <patterns> Comma-separated glob patterns to exclude.
|
|
129
|
-
--concurrency <n>
|
|
225
|
+
--concurrency <n> Pages captured in parallel, 1-20 (default 4).
|
|
130
226
|
--auto-approve Automatically approve results as new baselines.
|
|
131
227
|
--mask <selectors> Comma-separated CSS selectors to hide (e.g. ".ad,#popup").
|
|
228
|
+
--custom-css <css> CSS injected before each screenshot (max 4096 chars).
|
|
229
|
+
Use --custom-css="..." if the CSS starts with '--'.
|
|
132
230
|
--skip-summaries Skip waiting for parallel AI summaries in the CLI.
|
|
133
231
|
|
|
232
|
+
Describing the change (lets each regression be judged against your intent):
|
|
233
|
+
--change-description <text> What this run is meant to change.
|
|
234
|
+
--expected-changes <list> Comma-separated list of expected changes.
|
|
235
|
+
--pr-title <text> PR title.
|
|
236
|
+
--commit <sha> Git commit SHA.
|
|
237
|
+
|
|
238
|
+
--fail-on <mode> What counts as a failure. 'any' (default) fails on any
|
|
239
|
+
regression. 'unintended' fails only on changes judged a
|
|
240
|
+
bug or needing review, so expected changes keep the build
|
|
241
|
+
green. Needs --change-description; anything unjudged
|
|
242
|
+
still fails.
|
|
243
|
+
|
|
244
|
+
Note: any flag can be written --flag=value, which is required when the value
|
|
245
|
+
itself starts with '--'.
|
|
246
|
+
|
|
134
247
|
Environment Variables:
|
|
135
248
|
REGRESSIONBOT_API_KEY Override the API Key.
|
|
136
249
|
REGRESSIONBOT_API_URL Override the API URL.
|
|
250
|
+
|
|
251
|
+
Exit codes:
|
|
252
|
+
0 Nothing failed (see --fail-on).
|
|
253
|
+
1 Regressions or capture errors found, or the run failed.
|
|
254
|
+
2 The command was used incorrectly (bad flag or missing argument).
|
|
137
255
|
`);
|
|
138
256
|
}
|
|
139
257
|
async function startJob(url, options) {
|
|
140
258
|
console.log(`š Initializing visual test...`);
|
|
141
259
|
const projectId = options.project;
|
|
142
|
-
const
|
|
143
|
-
const builder = sdk.test(url)
|
|
144
|
-
|
|
145
|
-
|
|
260
|
+
const failOn = parseFailOn(options['fail-on']);
|
|
261
|
+
const builder = sdk.test(url);
|
|
262
|
+
// Only set what the caller actually asked for. Anything sent here is compared against
|
|
263
|
+
// the saved project config, so a default invented by the CLI fails the run instead of
|
|
264
|
+
// being overridden by it.
|
|
265
|
+
if (typeof options.on === 'string') {
|
|
266
|
+
builder.on(options.on.split(',').map((s) => s.trim()).filter(Boolean));
|
|
267
|
+
}
|
|
268
|
+
if (options.concurrency !== undefined) {
|
|
269
|
+
const n = typeof options.concurrency === 'string' ? Number(options.concurrency) : NaN;
|
|
270
|
+
if (!Number.isInteger(n) || n < 1 || n > 20) {
|
|
271
|
+
throw new UsageError('--concurrency takes a whole number from 1 to 20.');
|
|
272
|
+
}
|
|
273
|
+
builder.concurrency(n);
|
|
274
|
+
}
|
|
146
275
|
if (projectId) {
|
|
147
276
|
builder.forProject(projectId);
|
|
148
277
|
}
|
|
@@ -167,10 +296,23 @@ async function startJob(url, options) {
|
|
|
167
296
|
const selectors = options.mask.split(',').map((s) => s.trim());
|
|
168
297
|
builder.mask(selectors);
|
|
169
298
|
}
|
|
299
|
+
if (typeof options['custom-css'] === 'string') {
|
|
300
|
+
builder.customCss(options['custom-css']);
|
|
301
|
+
}
|
|
302
|
+
const runContext = buildRunContext(options);
|
|
303
|
+
if (runContext) {
|
|
304
|
+
builder.withContext(runContext);
|
|
305
|
+
}
|
|
306
|
+
if (failOn === 'unintended' && !runContext) {
|
|
307
|
+
console.log('ā ļø --fail-on unintended needs intent to judge against. Pass --change-description (see --help).');
|
|
308
|
+
}
|
|
309
|
+
if (failOn === 'unintended' && options['skip-summaries']) {
|
|
310
|
+
console.log('ā ļø --skip-summaries leaves every change unjudged, so --fail-on unintended cannot excuse any of them.');
|
|
311
|
+
}
|
|
170
312
|
const job = await builder.run();
|
|
171
313
|
console.log(`ā
Job started! ID: ${job.jobId}`);
|
|
172
314
|
console.log(`š Project: ${projectId}`);
|
|
173
|
-
console.log(`š± Matrix: ${
|
|
315
|
+
console.log(`š± Matrix: ${typeof options.on === 'string' ? options.on : 'Desktop Chrome (default)'}`);
|
|
174
316
|
if (options.scan) {
|
|
175
317
|
console.log(`š Scan: ${options.scan} (Exclude: ${options.exclude || 'none'})`);
|
|
176
318
|
}
|
|
@@ -179,7 +321,7 @@ Waiting for completion...
|
|
|
179
321
|
`);
|
|
180
322
|
const result = await job.waitForCompletion(2000, (status) => {
|
|
181
323
|
const progress = status.progress || { percent: '0' };
|
|
182
|
-
const aiStatusDetail = status.summaryStatus
|
|
324
|
+
const aiStatusDetail = status.summaryStatus ? ` [RegressionBot Summary: ${status.summaryStatus}]` : '';
|
|
183
325
|
process.stdout.write(`\r Status: ${status.status} (${progress.percent}%)${aiStatusDetail}`);
|
|
184
326
|
}, { waitForSummaries: !options['skip-summaries'] });
|
|
185
327
|
console.log('\n\nā
Job Completed.');
|
|
@@ -195,27 +337,36 @@ Waiting for completion...
|
|
|
195
337
|
console.log(`- ${nb.url} [${nb.variantName}]`);
|
|
196
338
|
});
|
|
197
339
|
}
|
|
340
|
+
let exitCode = 0;
|
|
198
341
|
if (summary.regressionCount > 0) {
|
|
199
342
|
console.log('\nā Regressions found:');
|
|
200
|
-
summary.regressions.forEach(
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
343
|
+
summary.regressions.forEach(printRegression);
|
|
344
|
+
const { blocking, excused } = selectBlocking(summary.regressions, failOn);
|
|
345
|
+
if (excused > 0) {
|
|
346
|
+
console.log(`\nā
${excused} of ${summary.regressionCount} matched the stated intent and did not fail the build.`);
|
|
347
|
+
}
|
|
348
|
+
if (blocking.length > 0) {
|
|
349
|
+
console.log(`\nTo approve these changes, run:\n npx regressionbot approve ${job.jobId}`);
|
|
350
|
+
exitCode = 1;
|
|
351
|
+
}
|
|
208
352
|
}
|
|
209
|
-
|
|
353
|
+
printIntent(summary);
|
|
354
|
+
// Reported even when there are regressions. These used to be hidden behind an
|
|
355
|
+
// else-if, so a run with both showed only the regressions and exited 1 for what
|
|
356
|
+
// looked like the wrong reason.
|
|
357
|
+
if (summary.errorCount > 0) {
|
|
210
358
|
console.log('\nā ļø Errors encountered:');
|
|
211
359
|
summary.errors.forEach((e) => {
|
|
212
360
|
console.log(`- ${e.url}: ${e.errorMessage}`);
|
|
213
361
|
});
|
|
214
|
-
|
|
362
|
+
exitCode = 1;
|
|
215
363
|
}
|
|
216
|
-
|
|
217
|
-
|
|
364
|
+
if (exitCode !== 0) {
|
|
365
|
+
process.exit(exitCode);
|
|
218
366
|
}
|
|
367
|
+
console.log(summary.regressionCount > 0
|
|
368
|
+
? '\n⨠Every change was intended. All good!'
|
|
369
|
+
: '\n⨠No regressions found. All good!');
|
|
219
370
|
}
|
|
220
371
|
async function checkStatus(jobId) {
|
|
221
372
|
const job = sdk.job(jobId);
|
|
@@ -237,13 +388,9 @@ Errors: ${summary.errorCount}
|
|
|
237
388
|
`);
|
|
238
389
|
if (summary.regressionCount > 0) {
|
|
239
390
|
console.log('ā Regressions found:');
|
|
240
|
-
|
|
241
|
-
console.log(`- ${r.url} [${r.variantName}] (Score: ${r.visualMatchScore.toFixed(2)})`);
|
|
242
|
-
console.log(` Diff: ${r.diffUrl}`);
|
|
243
|
-
if (r.regressionbotSummary)
|
|
244
|
-
console.log(` Summary: ${r.regressionbotSummary}`);
|
|
245
|
-
}
|
|
391
|
+
summary.regressions.forEach(printRegression);
|
|
246
392
|
}
|
|
393
|
+
printIntent(summary);
|
|
247
394
|
const doDownload = options.download || options['download-full'];
|
|
248
395
|
if (doDownload) {
|
|
249
396
|
console.log(`\nš¾ Downloading results...`);
|
|
@@ -265,4 +412,8 @@ async function approveJob(jobId) {
|
|
|
265
412
|
const res = await job.approve();
|
|
266
413
|
console.log(`Success! ${res.message}`);
|
|
267
414
|
}
|
|
268
|
-
|
|
415
|
+
// Only run when invoked as a command, so the pure helpers below can be imported and
|
|
416
|
+
// tested without the CLI executing on require.
|
|
417
|
+
if (require.main === module) {
|
|
418
|
+
main();
|
|
419
|
+
}
|
package/dist/index.d.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
|
-
import { VRConfig, Viewport, Viewports, JobStatus, JobSummary, JobProgress, PageResult, ProjectConfig, ProjectPath, ProjectScan, JobAiSummary } from './types';
|
|
1
|
+
import { VRConfig, Viewport, Viewports, JobStatus, JobSummary, JobProgress, PageResult, ProjectConfig, ProjectPath, ProjectScan, JobAiSummary, RegionVerdict, ResultVerdict, VerdictDecision, RegressionbotSummaryItem, RunContext, IntentAssessment, BaselinePolicy, ProjectSchedule, ProjectConfigUpdate, EnvGate, SummaryStatus, ApproveResult, Change, ChangeType, StyleDelta, ChangeBox } from './types';
|
|
2
2
|
import { sanitizeFilename, sanitizeUrlToPath } from './security';
|
|
3
3
|
export { sanitizeFilename, sanitizeUrlToPath, Viewports };
|
|
4
|
-
export type { PageResult, JobProgress, JobStatus, JobSummary, Viewport, VRConfig, ProjectConfig, ProjectPath, ProjectScan, JobAiSummary };
|
|
4
|
+
export type { PageResult, JobProgress, JobStatus, JobSummary, Viewport, VRConfig, ProjectConfig, ProjectPath, ProjectScan, JobAiSummary, RegionVerdict, ResultVerdict, VerdictDecision, RegressionbotSummaryItem, RunContext, IntentAssessment, BaselinePolicy, ProjectSchedule, ProjectConfigUpdate, EnvGate, SummaryStatus, ApproveResult, Change, ChangeType, StyleDelta, ChangeBox };
|
|
5
5
|
export declare class RegressionBot {
|
|
6
6
|
private apiKey;
|
|
7
7
|
private apiUrl;
|
|
@@ -40,13 +40,20 @@ export declare class RegressionBot {
|
|
|
40
40
|
options?: any;
|
|
41
41
|
}>;
|
|
42
42
|
masks?: string[];
|
|
43
|
+
/** CSS injected before screenshotting. Max 4096 characters. */
|
|
44
|
+
customCss?: string;
|
|
43
45
|
concurrency?: number;
|
|
44
46
|
autoApprove?: boolean;
|
|
47
|
+
/** What this run is testing, used to judge whether changes were intended. */
|
|
48
|
+
runContext?: RunContext;
|
|
45
49
|
}): Promise<JobHandle>;
|
|
46
50
|
/**
|
|
47
51
|
* Update the configuration settings for a named project.
|
|
52
|
+
*
|
|
53
|
+
* Changing anything that decides what a capture looks like invalidates the
|
|
54
|
+
* stored baselines ā see {@link ProjectConfigUpdate}.
|
|
48
55
|
*/
|
|
49
|
-
updateProject(projectName: string, config:
|
|
56
|
+
updateProject(projectName: string, config: ProjectConfigUpdate): Promise<ProjectConfig>;
|
|
50
57
|
_request<T>(path: string, method?: string, body?: any): Promise<T>;
|
|
51
58
|
}
|
|
52
59
|
export declare class JobBuilder {
|
|
@@ -71,9 +78,25 @@ export declare class JobBuilder {
|
|
|
71
78
|
limit?: number;
|
|
72
79
|
exclude?: string[];
|
|
73
80
|
}): this;
|
|
81
|
+
/**
|
|
82
|
+
* How many pages are captured in parallel, 1ā20. Leave it unset to take the API's
|
|
83
|
+
* default of 4 ā the ceiling is the site being captured, not RegressionBot, so
|
|
84
|
+
* raising it is a load decision about someone else's environment.
|
|
85
|
+
*/
|
|
74
86
|
concurrency(n: number): this;
|
|
75
87
|
autoApprove(val?: boolean): this;
|
|
76
88
|
mask(selectors: string[]): this;
|
|
89
|
+
/**
|
|
90
|
+
* Inject custom CSS before each screenshot, e.g. to hide a dynamic widget:
|
|
91
|
+
* `'#chat-widget { display: none !important; }'`. Max 4096 characters.
|
|
92
|
+
*/
|
|
93
|
+
customCss(css: string): this;
|
|
94
|
+
/**
|
|
95
|
+
* Describe what this run is testing ā commit, PR, expected changes ā so
|
|
96
|
+
* RegressionBot can judge whether each change was intentional.
|
|
97
|
+
* Merges with anything set by an earlier call.
|
|
98
|
+
*/
|
|
99
|
+
withContext(context: RunContext): this;
|
|
77
100
|
/**
|
|
78
101
|
* Compiles the manifest and triggers the API.
|
|
79
102
|
*/
|
|
@@ -85,12 +108,7 @@ export declare class JobHandle {
|
|
|
85
108
|
constructor(sdk: RegressionBot, jobId: string);
|
|
86
109
|
getStatus(): Promise<JobStatus>;
|
|
87
110
|
getSummary(): Promise<JobSummary>;
|
|
88
|
-
approve(): Promise<
|
|
89
|
-
message: string;
|
|
90
|
-
jobId: string;
|
|
91
|
-
approvedUrlsCount: number;
|
|
92
|
-
failedCount?: number;
|
|
93
|
-
}>;
|
|
111
|
+
approve(): Promise<ApproveResult>;
|
|
94
112
|
/**
|
|
95
113
|
* Generate AI summaries on-demand for all regressions in a completed job.
|
|
96
114
|
*/
|
package/dist/index.js
CHANGED
|
@@ -55,9 +55,14 @@ class RegressionBot {
|
|
|
55
55
|
}
|
|
56
56
|
/**
|
|
57
57
|
* Update the configuration settings for a named project.
|
|
58
|
+
*
|
|
59
|
+
* Changing anything that decides what a capture looks like invalidates the
|
|
60
|
+
* stored baselines ā see {@link ProjectConfigUpdate}.
|
|
58
61
|
*/
|
|
59
62
|
async updateProject(projectName, config) {
|
|
60
|
-
|
|
63
|
+
// The API wraps the updated project in { message, project }.
|
|
64
|
+
const res = await this._request(`/project/${encodeURIComponent(projectName)}`, 'PUT', config);
|
|
65
|
+
return res.project;
|
|
61
66
|
}
|
|
62
67
|
// Internal fetch wrapper
|
|
63
68
|
async _request(path, method = 'GET', body) {
|
|
@@ -89,8 +94,7 @@ class JobBuilder {
|
|
|
89
94
|
testOrigin: testOrigin.replace(/\/$/, ''),
|
|
90
95
|
variants: [],
|
|
91
96
|
checks: [],
|
|
92
|
-
scans: []
|
|
93
|
-
concurrency: 10
|
|
97
|
+
scans: []
|
|
94
98
|
};
|
|
95
99
|
}
|
|
96
100
|
against(origin) {
|
|
@@ -128,6 +132,11 @@ class JobBuilder {
|
|
|
128
132
|
this.manifest.scans.push({ pattern, options });
|
|
129
133
|
return this;
|
|
130
134
|
}
|
|
135
|
+
/**
|
|
136
|
+
* How many pages are captured in parallel, 1ā20. Leave it unset to take the API's
|
|
137
|
+
* default of 4 ā the ceiling is the site being captured, not RegressionBot, so
|
|
138
|
+
* raising it is a load decision about someone else's environment.
|
|
139
|
+
*/
|
|
131
140
|
concurrency(n) {
|
|
132
141
|
this.manifest.concurrency = n;
|
|
133
142
|
return this;
|
|
@@ -140,6 +149,23 @@ class JobBuilder {
|
|
|
140
149
|
this.manifest.masks = selectors;
|
|
141
150
|
return this;
|
|
142
151
|
}
|
|
152
|
+
/**
|
|
153
|
+
* Inject custom CSS before each screenshot, e.g. to hide a dynamic widget:
|
|
154
|
+
* `'#chat-widget { display: none !important; }'`. Max 4096 characters.
|
|
155
|
+
*/
|
|
156
|
+
customCss(css) {
|
|
157
|
+
this.manifest.customCss = css;
|
|
158
|
+
return this;
|
|
159
|
+
}
|
|
160
|
+
/**
|
|
161
|
+
* Describe what this run is testing ā commit, PR, expected changes ā so
|
|
162
|
+
* RegressionBot can judge whether each change was intentional.
|
|
163
|
+
* Merges with anything set by an earlier call.
|
|
164
|
+
*/
|
|
165
|
+
withContext(context) {
|
|
166
|
+
this.manifest.runContext = { ...this.manifest.runContext, ...context };
|
|
167
|
+
return this;
|
|
168
|
+
}
|
|
143
169
|
/**
|
|
144
170
|
* Compiles the manifest and triggers the API.
|
|
145
171
|
*/
|
|
@@ -151,17 +177,23 @@ class JobBuilder {
|
|
|
151
177
|
if (this.manifest.checks.length === 0 && this.manifest.scans.length === 0) {
|
|
152
178
|
this.manifest.checks.push({ path: '/', label: 'Home' });
|
|
153
179
|
}
|
|
180
|
+
// Every field present here is compared against the saved project config, and a
|
|
181
|
+
// value that differs fails the run rather than overriding it. So a field the
|
|
182
|
+
// caller never set must stay absent: an empty `devices` or a `concurrency` this
|
|
183
|
+
// builder picked on its own would be read as an opinion and diffed.
|
|
154
184
|
const payload = {
|
|
155
185
|
project: this.manifest.projectId,
|
|
156
186
|
testOrigin: this.manifest.testOrigin,
|
|
157
187
|
sitemapUrl: this.manifest.sitemapUrl,
|
|
158
188
|
baseOrigin: this.manifest.baseOrigin,
|
|
159
|
-
devices: this.manifest.variants,
|
|
189
|
+
devices: this.manifest.variants.length > 0 ? this.manifest.variants : undefined,
|
|
160
190
|
paths: this.manifest.checks,
|
|
161
|
-
scans: this.manifest.scans,
|
|
191
|
+
scans: this.manifest.scans.length > 0 ? this.manifest.scans : undefined,
|
|
162
192
|
concurrency: this.manifest.concurrency,
|
|
163
193
|
autoApprove: this.manifest.autoApprove,
|
|
164
|
-
masks: this.manifest.masks
|
|
194
|
+
masks: this.manifest.masks,
|
|
195
|
+
customCss: this.manifest.customCss,
|
|
196
|
+
runContext: this.manifest.runContext
|
|
165
197
|
};
|
|
166
198
|
const res = await this.sdk._request('/crawl', 'POST', payload);
|
|
167
199
|
return new JobHandle(this.sdk, res.jobId);
|
|
@@ -203,22 +235,29 @@ class JobHandle {
|
|
|
203
235
|
const jobDir = path.join(baseDir, safeJobId);
|
|
204
236
|
if (!fs.existsSync(jobDir))
|
|
205
237
|
fs.mkdirSync(jobDir, { recursive: true });
|
|
206
|
-
const download = async (url,
|
|
238
|
+
const download = async (url, baseName) => {
|
|
207
239
|
try {
|
|
208
240
|
// š”ļø SECURITY: Prevent SSRF and local file reads by enforcing HTTP(S) protocol
|
|
209
241
|
(0, security_1.validateProtocol)(url, 'download URL');
|
|
210
242
|
// š”ļø SECURITY: Fetch with timeout
|
|
211
243
|
const res = await (0, security_1.fetchWithTimeout)(url);
|
|
212
244
|
if (!res.ok) {
|
|
213
|
-
console.warn(`Warning: Failed to download ${
|
|
245
|
+
console.warn(`Warning: Failed to download ${baseName} from ${url} (Status: ${res.status})`);
|
|
214
246
|
return;
|
|
215
247
|
}
|
|
248
|
+
// Determine file extension from Content-Type header
|
|
249
|
+
const contentType = res.headers.get('content-type') || '';
|
|
250
|
+
let ext = '.png'; // default fallback
|
|
251
|
+
if (contentType.includes('image/jpeg') || contentType.includes('image/jpg')) {
|
|
252
|
+
ext = '.jpg';
|
|
253
|
+
}
|
|
254
|
+
const finalName = `${baseName}${ext}`;
|
|
216
255
|
const buffer = Buffer.from(await res.arrayBuffer());
|
|
217
|
-
const filePath = path.join(jobDir,
|
|
256
|
+
const filePath = path.join(jobDir, finalName);
|
|
218
257
|
fs.writeFileSync(filePath, buffer);
|
|
219
258
|
}
|
|
220
259
|
catch (err) {
|
|
221
|
-
console.warn(`Warning: Failed to download ${
|
|
260
|
+
console.warn(`Warning: Failed to download ${baseName}: ${err.message}`);
|
|
222
261
|
}
|
|
223
262
|
};
|
|
224
263
|
// Regressions
|
|
@@ -226,12 +265,12 @@ class JobHandle {
|
|
|
226
265
|
const nameBase = (0, security_1.sanitizeUrlToPath)(r.url);
|
|
227
266
|
const safeVariant = (0, security_1.sanitizeFilename)(r.variantName);
|
|
228
267
|
if (r.diffUrl)
|
|
229
|
-
await download(r.diffUrl, `${nameBase}_diff_${safeVariant}
|
|
268
|
+
await download(r.diffUrl, `${nameBase}_diff_${safeVariant}`);
|
|
230
269
|
if (options.full) {
|
|
231
270
|
if (r.baselineUrl)
|
|
232
|
-
await download(r.baselineUrl, `${nameBase}_baseline_${safeVariant}
|
|
271
|
+
await download(r.baselineUrl, `${nameBase}_baseline_${safeVariant}`);
|
|
233
272
|
if (r.currentUrl)
|
|
234
|
-
await download(r.currentUrl, `${nameBase}_current_${safeVariant}
|
|
273
|
+
await download(r.currentUrl, `${nameBase}_current_${safeVariant}`);
|
|
235
274
|
}
|
|
236
275
|
}
|
|
237
276
|
// Matches (Full only)
|
|
@@ -240,9 +279,9 @@ class JobHandle {
|
|
|
240
279
|
const nameBase = (0, security_1.sanitizeUrlToPath)(m.url);
|
|
241
280
|
const safeVariant = (0, security_1.sanitizeFilename)(m.variantName);
|
|
242
281
|
if (m.baselineUrl)
|
|
243
|
-
await download(m.baselineUrl, `${nameBase}_baseline_${safeVariant}
|
|
282
|
+
await download(m.baselineUrl, `${nameBase}_baseline_${safeVariant}`);
|
|
244
283
|
if (m.currentUrl)
|
|
245
|
-
await download(m.currentUrl, `${nameBase}_current_${safeVariant}
|
|
284
|
+
await download(m.currentUrl, `${nameBase}_current_${safeVariant}`);
|
|
246
285
|
}
|
|
247
286
|
}
|
|
248
287
|
}
|