@regressionbot/sdk 2.2.1 → 2.4.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 +142 -11
- package/dist/cli.d.ts +10 -2
- package/dist/cli.js +44 -4
- package/dist/index.d.ts +23 -4
- package/dist/index.js +61 -4
- package/dist/types.d.ts +160 -16
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -25,7 +25,7 @@ Unlike traditional visual diffing libraries, RegressionBot is designed for moder
|
|
|
25
25
|
- **Auto-Discovery**: Scan sitemaps with glob patterns and limits.
|
|
26
26
|
- **RegressionBot Summaries**: Plain-English change descriptions for every regression, generated on-demand via the API.
|
|
27
27
|
- **Intent-Aware Verdicts**: Describe what a run is meant to change, and every regression comes back judged as intentional, a bug, or noise.
|
|
28
|
-
- **Scheduled Checks**: Run a saved project unattended,
|
|
28
|
+
- **Scheduled Checks**: Run a saved project unattended, daily or weekly — and at a set UTC hour.
|
|
29
29
|
- **Project-Based Baselines**: Save and reuse test configurations; share visual history across environments.
|
|
30
30
|
- **Auto-Approval**: Automatically promote screenshots to baselines on jobs that pass your criteria.
|
|
31
31
|
- **Zero Infrastructure**: No browser maintenance or server provisioning — RegressionBot handles it all.
|
|
@@ -74,6 +74,56 @@ the builder, intent-aware verdicts, environment gates, baseline policies, and
|
|
|
74
74
|
scheduling. `scheduleHourUtc` needs API 2.7.0 or later — on an older API the
|
|
75
75
|
field is accepted and ignored, and the schedule stays anchored to its first run.
|
|
76
76
|
|
|
77
|
+
### 2.4.0
|
|
78
|
+
|
|
79
|
+
Needs API 2.9.0 or later. On an older API the new fields are simply absent.
|
|
80
|
+
|
|
81
|
+
- **`'hourly'` is gone from `ProjectSchedule`.** The API stopped accepting it on
|
|
82
|
+
2026-08-20 and rejects it outright, so code that sends it already fails at runtime;
|
|
83
|
+
now it fails at compile time instead. Use `'daily'` (with `scheduleHourUtc`) or
|
|
84
|
+
`'weekly'`. Kept as a minor release because no working call can depend on it.
|
|
85
|
+
- **Environment labels.** `environment` and `baseEnvironment` on a project
|
|
86
|
+
(`updateProject`, `getProject`) and on each run's status and summary, so a run reads
|
|
87
|
+
"staging vs production" instead of a bare URL. A label only: never resets baselines.
|
|
88
|
+
- **A standing `intent` on a project**, which scheduled runs are judged against.
|
|
89
|
+
- **`runSummary`** on the job summary: a short AI reading of the whole run.
|
|
90
|
+
- **`changeGroup`** on each regression (`structural`, `edited`, `metadata`,
|
|
91
|
+
`cosmetic`), the same grouping the digest email uses.
|
|
92
|
+
- **New change detail:** `attribute-edit` and `font-failed` change types, and `label`,
|
|
93
|
+
`attributes` and `valueOnly` on a change.
|
|
94
|
+
- **`project`, `origin`, `baseOrigin`, `totalUrls` and `completedCount`** on the job status.
|
|
95
|
+
- **Deprecated:** `visualMatchScore`, `overallScore`, `domAssistSkipReason`,
|
|
96
|
+
`elementsChanged` and a summary item's `verdict`. All still typed; none measure what
|
|
97
|
+
their names say under the DOM engine.
|
|
98
|
+
|
|
99
|
+
### 2.3.0
|
|
100
|
+
|
|
101
|
+
Needs API 2.9.0 or later. On an older API the verdict fields are simply absent, with
|
|
102
|
+
one exception called out below.
|
|
103
|
+
|
|
104
|
+
- **`RESOLVED` is a terminal status, and `waitForCompletion` now stops on it.** A run
|
|
105
|
+
reaches `APPROVED` only when every page carrying a diff was approved; decide them all
|
|
106
|
+
and reject one and it lands on `RESOLVED` instead. The old terminal check knew
|
|
107
|
+
`COMPLETED` and `APPROVED` only, so a triaged run with a single rejection polled until
|
|
108
|
+
the caller gave up. API 2.9.0 made that the common way such a run ends.
|
|
109
|
+
- **`approvePage(url, variantName, note?)` and `rejectPage(...)`** decide one page and
|
|
110
|
+
leave the rest of the job alone. The optional `note` records what the verdict missed,
|
|
111
|
+
and is worth sending when you are overruling it. Both refuse a url without a
|
|
112
|
+
`variantName`: the API gates its per-page path on having both, and a half-identified
|
|
113
|
+
page falls through to approving the whole job.
|
|
114
|
+
- **`approve(where)` throws if it reaches an API that does not support the filter.**
|
|
115
|
+
This is the exception. An older API reads `jobId`, ignores the rest of the body, and
|
|
116
|
+
approves EVERY page — including the ones the verdict called bugs — while answering
|
|
117
|
+
like a success. `skippedUrlsCount` is the tell: the filter path always reports it,
|
|
118
|
+
even as 0, and no other path reports it at all. The error says plainly that the
|
|
119
|
+
baselines have already moved, because by then they have.
|
|
120
|
+
- **Verdict and triage fields typed.** On a regression: `basis`, `coveredBy`,
|
|
121
|
+
`reasoning` and a deprecated `judgedAt`. On a page a person decided: `triageStatus`,
|
|
122
|
+
`triagedAt`, `triagedBy`, `triagedVerdict` and `triageNote`. On the job:
|
|
123
|
+
`intentAssessment.decision` and `intentProvided`.
|
|
124
|
+
- **`comparisonMode`** on the job status says whether the run compared two live origins
|
|
125
|
+
or one origin against a stored baseline.
|
|
126
|
+
|
|
77
127
|
### 2.2.1
|
|
78
128
|
|
|
79
129
|
- **A builder run with no `check()` or `scan()` no longer invents a home path.** It
|
|
@@ -262,6 +312,16 @@ Two things to know before you rely on it:
|
|
|
262
312
|
- **`changes` absent is not "nothing changed".** It means the document comparison could not
|
|
263
313
|
run on that page — check `domAssistSkipReason`.
|
|
264
314
|
|
|
315
|
+
Each change also carries a `type` beyond the ones above — `attribute-edit` for a reader-facing
|
|
316
|
+
attribute (`href`, `alt`, `aria-label`, …; see `c.attributes`) and `font-failed` for a web font
|
|
317
|
+
that didn't load. A change with no words of its own (`style-only`, `attribute-edit`,
|
|
318
|
+
`image-change`) may carry a short `label` naming the element instead, and a date-only edit
|
|
319
|
+
("Sep 17" → "Sep 23") is reported with `valueOnly: 'date'` without counting as a change.
|
|
320
|
+
|
|
321
|
+
Every regression also carries a `changeGroup` — `structural`, `edited`, `metadata`,
|
|
322
|
+
`cosmetic`, or (on older results) `unmeasured`/`date` — the same grouping the digest email
|
|
323
|
+
uses, so you can filter a run down to one kind of change without re-deriving the rule.
|
|
324
|
+
|
|
265
325
|
`box` gives you the location in the capture, in CSS pixels from the top-left of the
|
|
266
326
|
full-page image, so it indexes straight into `currentUrl` if you want to crop:
|
|
267
327
|
|
|
@@ -309,7 +369,6 @@ intent-aware too:
|
|
|
309
369
|
|
|
310
370
|
```typescript
|
|
311
371
|
const job = await rb.runProject('marketing-site-v2', {
|
|
312
|
-
testOrigin: process.env.VERCEL_PREVIEW_URL,
|
|
313
372
|
runContext: { changeDescription: 'Restyle the pricing table' },
|
|
314
373
|
});
|
|
315
374
|
```
|
|
@@ -333,7 +392,11 @@ const job = await rb
|
|
|
333
392
|
|
|
334
393
|
### Progress Tracking
|
|
335
394
|
|
|
336
|
-
|
|
395
|
+
`waitForCompletion` returns on `COMPLETED`, `APPROVED` or `RESOLVED`, and throws on
|
|
396
|
+
`FAILED`. `APPROVED` means every page carrying a diff was approved; `RESOLVED` means
|
|
397
|
+
they were all decided and at least one was rejected.
|
|
398
|
+
|
|
399
|
+
Pass a callback to receive status updates while the job runs:
|
|
337
400
|
|
|
338
401
|
```typescript
|
|
339
402
|
const status = await job.waitForCompletion(3000, (s) => {
|
|
@@ -361,6 +424,34 @@ const result = await job.approve();
|
|
|
361
424
|
console.log(`Approved ${result.approvedUrlsCount} URLs.`);
|
|
362
425
|
```
|
|
363
426
|
|
|
427
|
+
When the run carried an intent (`.withContext()`), approve only the pages the
|
|
428
|
+
verdict cleared and leave the flagged ones for a person:
|
|
429
|
+
|
|
430
|
+
```typescript
|
|
431
|
+
const summary = await job.getSummary();
|
|
432
|
+
if (summary.intentAssessment.decision !== 'pass') {
|
|
433
|
+
const result = await job.approve({ decision: ['intentional', 'noise'] });
|
|
434
|
+
console.log(`Approved ${result.approvedUrlsCount}, ${result.skippedUrlsCount} left for review.`);
|
|
435
|
+
}
|
|
436
|
+
```
|
|
437
|
+
|
|
438
|
+
`intentAssessment.decision` is `pass`, `review`, `fail`, or `not_judged` when the
|
|
439
|
+
run carried no intent. Each regression's `verdict` carries `reasoning`, `basis`
|
|
440
|
+
(`measured` or `described`) and, for `intentional`, the words of the intent it
|
|
441
|
+
`coveredBy`. Both need API 2.9.0 or later.
|
|
442
|
+
|
|
443
|
+
To decide one page at a time, name the page and the device:
|
|
444
|
+
|
|
445
|
+
```typescript
|
|
446
|
+
await job.rejectPage('https://example.com/pricing', 'Desktop Chrome', 'the nav lost a link');
|
|
447
|
+
await job.approvePage('https://example.com/pricing', 'iPhone 12');
|
|
448
|
+
```
|
|
449
|
+
|
|
450
|
+
The third argument is a note, and it is worth sending when you are overruling the
|
|
451
|
+
verdict — approving a page it called a bug, or rejecting one it cleared. What you
|
|
452
|
+
write is stored on that page as `triageNote`, beside `triageStatus`, `triagedAt`,
|
|
453
|
+
`triagedBy` and the `triagedVerdict` you overruled.
|
|
454
|
+
|
|
364
455
|
### Saved Projects
|
|
365
456
|
|
|
366
457
|
Projects let you save a test configuration in the RegressionBot dashboard and trigger runs against it without re-specifying every option.
|
|
@@ -374,10 +465,10 @@ console.log(projects.map(p => p.name));
|
|
|
374
465
|
const project = await rb.getProject('marketing-site-v2');
|
|
375
466
|
console.log(project);
|
|
376
467
|
|
|
377
|
-
// Trigger a run from a saved project
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
468
|
+
// Trigger a run from a saved project. Any capture field you pass is checked
|
|
469
|
+
// against the saved config and rejected if it differs; leave it out to use
|
|
470
|
+
// the saved value. Change the config with updateProject().
|
|
471
|
+
const job = await rb.runProject('marketing-site-v2');
|
|
381
472
|
|
|
382
473
|
const status = await job.waitForCompletion();
|
|
383
474
|
const summary = await job.getSummary();
|
|
@@ -418,7 +509,7 @@ combination. Live-vs-live projects store no baseline and are exempt.
|
|
|
418
509
|
// Turn on a daily unattended check
|
|
419
510
|
await rb.updateProject('marketing-site-v2', {
|
|
420
511
|
baselinePolicy: 'rolling',
|
|
421
|
-
schedule: 'daily', // '
|
|
512
|
+
schedule: 'daily', // 'daily' | 'weekly'
|
|
422
513
|
});
|
|
423
514
|
|
|
424
515
|
// Or pin it to a UTC hour — this one runs at 03:00 UTC every day
|
|
@@ -438,15 +529,44 @@ console.log(project.schedule, project.scheduleHourUtc, project.lastScheduledRunA
|
|
|
438
529
|
|
|
439
530
|
Without `scheduleHourUtc` the first run starts at the next hourly sweep and the cadence
|
|
440
531
|
anchors to it. With it, the first run waits for that hour as well. Hours only, since the
|
|
441
|
-
scheduler sweeps once an hour, and UTC only. It is rejected on
|
|
442
|
-
|
|
443
|
-
|
|
532
|
+
scheduler sweeps once an hour, and UTC only. It is rejected on a project with no schedule
|
|
533
|
+
to apply it to. Clearing the schedule clears the hour with it, and a missed slot waits
|
|
534
|
+
for the next one rather than catching up.
|
|
444
535
|
|
|
445
536
|
Setting a schedule, its hour, or a baseline policy does **not** invalidate
|
|
446
537
|
baselines — only changes that affect what a capture looks like (`testOrigin`,
|
|
447
538
|
`baseOrigin`, `sitemapUrl`, `paths`, `scans`, `devices`, `masks`, `customCss`) do that.
|
|
448
539
|
Billing is per comparison, so cost scales with frequency.
|
|
449
540
|
|
|
541
|
+
A scheduled run has no PR or commit to draw an intent from, so give the project a standing
|
|
542
|
+
`intent` instead — every scheduled run is judged against it:
|
|
543
|
+
|
|
544
|
+
```typescript
|
|
545
|
+
await rb.updateProject('marketing-site-v2', {
|
|
546
|
+
intent: 'Content is edited in the CMS daily; navigation, pricing and layout must not change.',
|
|
547
|
+
});
|
|
548
|
+
```
|
|
549
|
+
|
|
550
|
+
Without one, a scheduled run's `intentAssessment.decision` reads `not_judged`. Runs started
|
|
551
|
+
by a caller keep their own `runContext` and are never judged against the project's `intent`.
|
|
552
|
+
Pass `null` or an empty string to remove it. Does not invalidate baselines.
|
|
553
|
+
|
|
554
|
+
### Environment Labels
|
|
555
|
+
|
|
556
|
+
Label which environment a project's origins are — `environment` for `testOrigin`,
|
|
557
|
+
`baseEnvironment` for `baseOrigin` on a live-vs-live project — so runs, emails and the
|
|
558
|
+
dashboard read "staging vs production" instead of a bare URL:
|
|
559
|
+
|
|
560
|
+
```typescript
|
|
561
|
+
await rb.updateProject('marketing-site-v2', { environment: 'staging' });
|
|
562
|
+
|
|
563
|
+
const project = await rb.getProject('marketing-site-v2');
|
|
564
|
+
console.log(project.environment); // 'staging'
|
|
565
|
+
```
|
|
566
|
+
|
|
567
|
+
A label only: 1–24 letters, digits, spaces or hyphens, stored lower-case. It never resets
|
|
568
|
+
baselines and never changes a run. Pass `null` or an empty string to remove it.
|
|
569
|
+
|
|
450
570
|
### Reconnecting to an Existing Job
|
|
451
571
|
|
|
452
572
|
If you have a job ID from a previous run (e.g., stored in CI state), you can attach to it without re-running the test:
|
|
@@ -534,6 +654,17 @@ Promote the current screenshots of a job to be the new baselines.
|
|
|
534
654
|
npx @regressionbot/sdk approve <jobId>
|
|
535
655
|
```
|
|
536
656
|
|
|
657
|
+
When the run carried an intent, `--decision` approves only the pages whose verdict is in
|
|
658
|
+
the list and leaves the rest pending:
|
|
659
|
+
```bash
|
|
660
|
+
npx @regressionbot/sdk approve <jobId> --decision intentional,noise
|
|
661
|
+
```
|
|
662
|
+
|
|
663
|
+
It prints how many changed pages were left for a person. Treat a number above zero as a
|
|
664
|
+
build that is not done: those are the pages the verdict did not clear, plus any it never
|
|
665
|
+
assessed. An unknown value stops the command rather than being sent, because an API that
|
|
666
|
+
does not understand the filter approves the whole job instead.
|
|
667
|
+
|
|
537
668
|
## Examples & Integrations
|
|
538
669
|
|
|
539
670
|
Check out the [examples/](./examples/) directory for real-world integration guides:
|
package/dist/cli.d.ts
CHANGED
|
@@ -1,8 +1,16 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
|
-
import { PageResult, RunContext } from './types';
|
|
2
|
+
import { PageResult, RunContext, VerdictDecision } from './types';
|
|
3
3
|
declare function printRegression(r: PageResult): void;
|
|
4
4
|
type FailOn = 'any' | 'unintended';
|
|
5
5
|
declare function parseFailOn(raw: unknown): FailOn;
|
|
6
|
+
/**
|
|
7
|
+
* `--decision intentional,noise` -> the approve filter, or undefined for no filter.
|
|
8
|
+
*
|
|
9
|
+
* Validated here rather than at the API, because the failure is asymmetric: a typo the API
|
|
10
|
+
* rejects costs a round trip, but a typo that reached a filter-blind API would approve the
|
|
11
|
+
* whole job. Unknown values stop the command.
|
|
12
|
+
*/
|
|
13
|
+
declare function parseDecisions(raw: unknown): VerdictDecision[] | undefined;
|
|
6
14
|
/**
|
|
7
15
|
* Whether one regression should fail the build under `--fail-on unintended`.
|
|
8
16
|
*
|
|
@@ -25,4 +33,4 @@ declare function selectBlocking(regressions: PageResult[], failOn: FailOn): {
|
|
|
25
33
|
};
|
|
26
34
|
declare function buildRunContext(options: any): RunContext | undefined;
|
|
27
35
|
declare function parseArgs(args: string[]): any;
|
|
28
|
-
export { parseArgs, parseFailOn, isBlocking, selectBlocking, buildRunContext, printRegression };
|
|
36
|
+
export { parseArgs, parseFailOn, parseDecisions, isBlocking, selectBlocking, buildRunContext, printRegression };
|
package/dist/cli.js
CHANGED
|
@@ -36,6 +36,7 @@ var __importStar = (this && this.__importStar) || (function () {
|
|
|
36
36
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
37
37
|
exports.parseArgs = parseArgs;
|
|
38
38
|
exports.parseFailOn = parseFailOn;
|
|
39
|
+
exports.parseDecisions = parseDecisions;
|
|
39
40
|
exports.isBlocking = isBlocking;
|
|
40
41
|
exports.selectBlocking = selectBlocking;
|
|
41
42
|
exports.buildRunContext = buildRunContext;
|
|
@@ -52,6 +53,8 @@ function formatSummary(items) {
|
|
|
52
53
|
}
|
|
53
54
|
function printRegression(r) {
|
|
54
55
|
console.log(`- ${r.url} [${r.variantName}] (Score: ${r.visualMatchScore.toFixed(2)})`);
|
|
56
|
+
if (r.changeGroup)
|
|
57
|
+
console.log(` Group: ${r.changeGroup}`);
|
|
55
58
|
if (r.diffUrl)
|
|
56
59
|
console.log(` Diff: ${r.diffUrl}`);
|
|
57
60
|
if (r.verdict) {
|
|
@@ -83,6 +86,27 @@ function parseFailOn(raw) {
|
|
|
83
86
|
return raw;
|
|
84
87
|
throw new UsageError("--fail-on takes 'any' or 'unintended'.");
|
|
85
88
|
}
|
|
89
|
+
const DECISIONS = ['intentional', 'bug', 'noise', 'needs_review'];
|
|
90
|
+
/**
|
|
91
|
+
* `--decision intentional,noise` -> the approve filter, or undefined for no filter.
|
|
92
|
+
*
|
|
93
|
+
* Validated here rather than at the API, because the failure is asymmetric: a typo the API
|
|
94
|
+
* rejects costs a round trip, but a typo that reached a filter-blind API would approve the
|
|
95
|
+
* whole job. Unknown values stop the command.
|
|
96
|
+
*/
|
|
97
|
+
function parseDecisions(raw) {
|
|
98
|
+
if (raw === undefined)
|
|
99
|
+
return undefined;
|
|
100
|
+
if (typeof raw !== 'string' || !raw.trim()) {
|
|
101
|
+
throw new UsageError(`--decision takes a comma-separated list of: ${DECISIONS.join(', ')}.`);
|
|
102
|
+
}
|
|
103
|
+
const wanted = raw.split(',').map(d => d.trim()).filter(Boolean);
|
|
104
|
+
const bad = wanted.filter(d => !DECISIONS.includes(d));
|
|
105
|
+
if (bad.length > 0) {
|
|
106
|
+
throw new UsageError(`--decision does not take ${bad.join(', ')}. Use: ${DECISIONS.join(', ')}.`);
|
|
107
|
+
}
|
|
108
|
+
return wanted;
|
|
109
|
+
}
|
|
86
110
|
/**
|
|
87
111
|
* Whether one regression should fail the build under `--fail-on unintended`.
|
|
88
112
|
*
|
|
@@ -185,7 +209,7 @@ async function main() {
|
|
|
185
209
|
else if (command === 'approve') {
|
|
186
210
|
if (!param)
|
|
187
211
|
throw new Error('Job ID is required for approve command.');
|
|
188
|
-
await approveJob(param);
|
|
212
|
+
await approveJob(param, parseDecisions(argv['decision']));
|
|
189
213
|
}
|
|
190
214
|
else if (command.startsWith('http')) {
|
|
191
215
|
// Implicit test command
|
|
@@ -214,6 +238,8 @@ Usage:
|
|
|
214
238
|
Use --download to save the diff image locally.
|
|
215
239
|
Use --download-full to save baseline and current images too.
|
|
216
240
|
npx regressionbot approve <jobId> Approve a job's results as new baselines.
|
|
241
|
+
Use --decision to approve only what the verdict
|
|
242
|
+
cleared, e.g. --decision intentional,noise.
|
|
217
243
|
|
|
218
244
|
Options for <url>:
|
|
219
245
|
--project <id> Required project ID.
|
|
@@ -406,11 +432,25 @@ Errors: ${summary.errorCount}
|
|
|
406
432
|
});
|
|
407
433
|
}
|
|
408
434
|
}
|
|
409
|
-
async function approveJob(jobId) {
|
|
410
|
-
console.log(`Approving baselines for job: ${jobId}...`);
|
|
435
|
+
async function approveJob(jobId, decision) {
|
|
411
436
|
const job = sdk.job(jobId);
|
|
412
|
-
|
|
437
|
+
if (!decision) {
|
|
438
|
+
console.log(`Approving every page in job: ${jobId}...`);
|
|
439
|
+
const res = await job.approve();
|
|
440
|
+
console.log(`Success! ${res.message}`);
|
|
441
|
+
return;
|
|
442
|
+
}
|
|
443
|
+
console.log(`Approving pages the verdict called ${decision.join(' or ')} in job: ${jobId}...`);
|
|
444
|
+
const res = await job.approve({ decision });
|
|
413
445
|
console.log(`Success! ${res.message}`);
|
|
446
|
+
// Left pending on purpose, and the reason a CI step should not go green here: these are
|
|
447
|
+
// the changed pages the verdict did not clear, plus any it never assessed.
|
|
448
|
+
if (res.skippedUrlsCount) {
|
|
449
|
+
console.log(`${res.skippedUrlsCount} changed page(s) left for a person to decide.`);
|
|
450
|
+
}
|
|
451
|
+
if (res.conflictedUrls?.length) {
|
|
452
|
+
console.log(`${res.conflictedUrls.length} page(s) skipped: another job moved their baseline first.`);
|
|
453
|
+
}
|
|
414
454
|
}
|
|
415
455
|
// Only run when invoked as a command, so the pure helpers below can be imported and
|
|
416
456
|
// tested without the CLI executing on require.
|
package/dist/index.d.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
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';
|
|
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, ApproveWhere, 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, RegionVerdict, ResultVerdict, VerdictDecision, RegressionbotSummaryItem, RunContext, IntentAssessment, BaselinePolicy, ProjectSchedule, ProjectConfigUpdate, EnvGate, SummaryStatus, ApproveResult, Change, ChangeType, StyleDelta, ChangeBox };
|
|
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, ApproveWhere, Change, ChangeType, StyleDelta, ChangeBox };
|
|
5
5
|
export declare class RegressionBot {
|
|
6
6
|
private apiKey;
|
|
7
7
|
private apiUrl;
|
|
@@ -24,6 +24,10 @@ export declare class RegressionBot {
|
|
|
24
24
|
listProjects(): Promise<ProjectConfig[]>;
|
|
25
25
|
/**
|
|
26
26
|
* Trigger a new job run using a saved project configuration.
|
|
27
|
+
*
|
|
28
|
+
* Capture fields passed here are not overrides: the API compares each one to the
|
|
29
|
+
* saved config and rejects the run if it differs. Omit a field to use the saved
|
|
30
|
+
* value; change the saved value with updateProject().
|
|
27
31
|
*/
|
|
28
32
|
runProject(projectName: string, options?: {
|
|
29
33
|
testOrigin?: string;
|
|
@@ -108,7 +112,22 @@ export declare class JobHandle {
|
|
|
108
112
|
constructor(sdk: RegressionBot, jobId: string);
|
|
109
113
|
getStatus(): Promise<JobStatus>;
|
|
110
114
|
getSummary(): Promise<JobSummary>;
|
|
111
|
-
|
|
115
|
+
/**
|
|
116
|
+
* Promote this job's captures to baselines. Pass `where` to approve only the pages whose
|
|
117
|
+
* verdict is in the list — `{ decision: ['intentional', 'noise'] }` approves what the verdict
|
|
118
|
+
* cleared and leaves the flagged pages for a person.
|
|
119
|
+
*/
|
|
120
|
+
approve(where?: ApproveWhere): Promise<ApproveResult>;
|
|
121
|
+
/**
|
|
122
|
+
* Approve one page's capture, leaving the rest of the job alone.
|
|
123
|
+
*
|
|
124
|
+
* `note` records what the verdict missed, and is worth sending when you are overruling it —
|
|
125
|
+
* approving a page it called a bug, or rejecting one it cleared.
|
|
126
|
+
*/
|
|
127
|
+
approvePage(url: string, variantName: string, note?: string): Promise<ApproveResult>;
|
|
128
|
+
/** Reject one page, leaving its baseline where it is. See `approvePage` for `note`. */
|
|
129
|
+
rejectPage(url: string, variantName: string, note?: string): Promise<ApproveResult>;
|
|
130
|
+
private decidePage;
|
|
112
131
|
/**
|
|
113
132
|
* Generate AI summaries on-demand for all regressions in a completed job.
|
|
114
133
|
*/
|
|
@@ -122,7 +141,7 @@ export declare class JobHandle {
|
|
|
122
141
|
baseDir?: string;
|
|
123
142
|
}): Promise<void>;
|
|
124
143
|
/**
|
|
125
|
-
* Poll until the job reaches a terminal state (COMPLETED, APPROVED, or FAILED).
|
|
144
|
+
* Poll until the job reaches a terminal state (COMPLETED, APPROVED, RESOLVED or FAILED).
|
|
126
145
|
* @param intervalMs Polling interval in milliseconds. Defaults to 2000.
|
|
127
146
|
* @param callback Optional callback invoked on each status poll.
|
|
128
147
|
* @param options.waitForSummaries If true, keeps polling until AI summaries are fully populated before returning.
|
package/dist/index.js
CHANGED
|
@@ -48,6 +48,10 @@ class RegressionBot {
|
|
|
48
48
|
}
|
|
49
49
|
/**
|
|
50
50
|
* Trigger a new job run using a saved project configuration.
|
|
51
|
+
*
|
|
52
|
+
* Capture fields passed here are not overrides: the API compares each one to the
|
|
53
|
+
* saved config and rejects the run if it differs. Omit a field to use the saved
|
|
54
|
+
* value; change the saved value with updateProject().
|
|
51
55
|
*/
|
|
52
56
|
async runProject(projectName, options = {}) {
|
|
53
57
|
const res = await this._request(`/project/${encodeURIComponent(projectName)}/run`, 'POST', options);
|
|
@@ -209,8 +213,58 @@ class JobHandle {
|
|
|
209
213
|
async getSummary() {
|
|
210
214
|
return this.sdk._request(`/job/${encodeURIComponent(this.jobId)}/summary`);
|
|
211
215
|
}
|
|
212
|
-
|
|
213
|
-
|
|
216
|
+
/**
|
|
217
|
+
* Promote this job's captures to baselines. Pass `where` to approve only the pages whose
|
|
218
|
+
* verdict is in the list — `{ decision: ['intentional', 'noise'] }` approves what the verdict
|
|
219
|
+
* cleared and leaves the flagged pages for a person.
|
|
220
|
+
*/
|
|
221
|
+
async approve(where) {
|
|
222
|
+
const result = await this.sdk._request('/approve', 'POST', {
|
|
223
|
+
jobId: this.jobId,
|
|
224
|
+
...(where ? { where } : {}),
|
|
225
|
+
});
|
|
226
|
+
// An API that predates the filter reads `jobId` and ignores everything else, so a body
|
|
227
|
+
// it does not understand approves EVERY page — including the ones the verdict called
|
|
228
|
+
// bugs — and answers like a success. The tell is `skippedUrlsCount`: the filter path
|
|
229
|
+
// always reports it, even as 0, and no other path reports it at all.
|
|
230
|
+
//
|
|
231
|
+
// Thrown after the fact because that is when it can be known, and the message has to
|
|
232
|
+
// say so: the baselines have already moved, and someone has to look.
|
|
233
|
+
if (where && result.skippedUrlsCount === undefined) {
|
|
234
|
+
throw new Error('approve(where) reached an API that does not support the filter, so EVERY page in '
|
|
235
|
+
+ `job ${this.jobId} was approved and its baselines have already moved. Check the `
|
|
236
|
+
+ 'job and re-reject anything that should not have been promoted. Upgrade the API '
|
|
237
|
+
+ 'to 2.9.0 or later, or decide the pages one at a time with approvePage and '
|
|
238
|
+
+ 'rejectPage.');
|
|
239
|
+
}
|
|
240
|
+
return result;
|
|
241
|
+
}
|
|
242
|
+
/**
|
|
243
|
+
* Approve one page's capture, leaving the rest of the job alone.
|
|
244
|
+
*
|
|
245
|
+
* `note` records what the verdict missed, and is worth sending when you are overruling it —
|
|
246
|
+
* approving a page it called a bug, or rejecting one it cleared.
|
|
247
|
+
*/
|
|
248
|
+
async approvePage(url, variantName, note) {
|
|
249
|
+
return this.decidePage('approve', url, variantName, note);
|
|
250
|
+
}
|
|
251
|
+
/** Reject one page, leaving its baseline where it is. See `approvePage` for `note`. */
|
|
252
|
+
async rejectPage(url, variantName, note) {
|
|
253
|
+
return this.decidePage('reject', url, variantName, note);
|
|
254
|
+
}
|
|
255
|
+
async decidePage(action, url, variantName, note) {
|
|
256
|
+
// Both halves are required together: `url` without `variantName` matches nothing, and the
|
|
257
|
+
// API answers that with a whole-job approval rather than an error.
|
|
258
|
+
if (!url || !variantName) {
|
|
259
|
+
throw new Error('approvePage and rejectPage need both a url and a variantName.');
|
|
260
|
+
}
|
|
261
|
+
return this.sdk._request('/approve', 'POST', {
|
|
262
|
+
jobId: this.jobId,
|
|
263
|
+
url,
|
|
264
|
+
variantName,
|
|
265
|
+
action,
|
|
266
|
+
...(note ? { note } : {}),
|
|
267
|
+
});
|
|
214
268
|
}
|
|
215
269
|
/**
|
|
216
270
|
* Generate AI summaries on-demand for all regressions in a completed job.
|
|
@@ -285,7 +339,7 @@ class JobHandle {
|
|
|
285
339
|
}
|
|
286
340
|
}
|
|
287
341
|
/**
|
|
288
|
-
* Poll until the job reaches a terminal state (COMPLETED, APPROVED, or FAILED).
|
|
342
|
+
* Poll until the job reaches a terminal state (COMPLETED, APPROVED, RESOLVED or FAILED).
|
|
289
343
|
* @param intervalMs Polling interval in milliseconds. Defaults to 2000.
|
|
290
344
|
* @param callback Optional callback invoked on each status poll.
|
|
291
345
|
* @param options.waitForSummaries If true, keeps polling until AI summaries are fully populated before returning.
|
|
@@ -295,7 +349,10 @@ class JobHandle {
|
|
|
295
349
|
const status = await this.getStatus();
|
|
296
350
|
if (callback)
|
|
297
351
|
callback(status);
|
|
298
|
-
|
|
352
|
+
// RESOLVED is terminal too: every page carrying a diff was decided and at least one
|
|
353
|
+
// was rejected. Omitting it polled until the caller's timeout on any run with a
|
|
354
|
+
// rejection, which this release made the common way a triaged run ends.
|
|
355
|
+
if (status.status === 'COMPLETED' || status.status === 'APPROVED' || status.status === 'RESOLVED') {
|
|
299
356
|
if (options?.waitForSummaries) {
|
|
300
357
|
if (status.summaryStatus !== 'PENDING' && status.summaryStatus !== 'PROCESSING') {
|
|
301
358
|
return status;
|
package/dist/types.d.ts
CHANGED
|
@@ -28,7 +28,7 @@ export interface EnvGate {
|
|
|
28
28
|
/** How a project's baseline advances between runs. Absent means `approved`. */
|
|
29
29
|
export type BaselinePolicy = 'approved' | 'rolling';
|
|
30
30
|
/** Frequency at which a project runs unattended. */
|
|
31
|
-
export type ProjectSchedule = '
|
|
31
|
+
export type ProjectSchedule = 'daily' | 'weekly';
|
|
32
32
|
/**
|
|
33
33
|
* A saved project as the API returns it.
|
|
34
34
|
*
|
|
@@ -81,6 +81,16 @@ export interface ProjectConfig {
|
|
|
81
81
|
scheduleKeyId?: string;
|
|
82
82
|
/** When the scheduler last started a run. The next run is due one interval after this. */
|
|
83
83
|
lastScheduledRunAt?: string;
|
|
84
|
+
/** The standing intent scheduled runs are judged against. Absent means scheduled runs are not judged. */
|
|
85
|
+
intent?: string;
|
|
86
|
+
/**
|
|
87
|
+
* Which environment `testOrigin` is: "production", "staging", "preview", "development",
|
|
88
|
+
* or the team's own word. A label only, shown in emails, the dashboard and MCP; never
|
|
89
|
+
* resets baselines. Absent when unset.
|
|
90
|
+
*/
|
|
91
|
+
environment?: string;
|
|
92
|
+
/** Live-vs-live projects only: which environment `baseOrigin` is. */
|
|
93
|
+
baseEnvironment?: string;
|
|
84
94
|
createdAt: string;
|
|
85
95
|
updatedAt: string;
|
|
86
96
|
lastRunAt?: string;
|
|
@@ -136,15 +146,37 @@ export interface ProjectConfigUpdate {
|
|
|
136
146
|
* into the hour from the following day. Hours only, because the scheduler sweeps once
|
|
137
147
|
* an hour; UTC only, because RegressionBot has no timezone to convert from.
|
|
138
148
|
*
|
|
139
|
-
* Rejected
|
|
140
|
-
*
|
|
141
|
-
* same update. Clearing the schedule with
|
|
149
|
+
* Rejected if the project has no schedule to apply it to — either one already set, or
|
|
150
|
+
* one sent in the same update. Clearing the schedule with
|
|
142
151
|
* `schedule: null` clears this too, so re-enabling later cannot resurrect an hour
|
|
143
152
|
* nobody asked for on that run. Pass null to clear it on its own.
|
|
144
153
|
*
|
|
145
154
|
* A missed slot waits for the next one rather than catching up.
|
|
146
155
|
*/
|
|
147
156
|
scheduleHourUtc?: number | null;
|
|
157
|
+
/**
|
|
158
|
+
* The API key the scheduled runs are attributed to. Ignored when the request itself
|
|
159
|
+
* carries an API key — that key is recorded instead. Required, and checked against the
|
|
160
|
+
* organisation's keys, when a schedule is set by a caller holding no key (the dashboard).
|
|
161
|
+
*/
|
|
162
|
+
scheduleKeyId?: string;
|
|
163
|
+
/**
|
|
164
|
+
* A standing intent for scheduled runs, which have no PR to draw one from. Say what the
|
|
165
|
+
* pages are expected to do between checks and what must not change; every scheduled run
|
|
166
|
+
* is judged against it. Without one a scheduled run reports
|
|
167
|
+
* `intentAssessment.decision: 'not_judged'`. Runs started by a caller are never judged
|
|
168
|
+
* against it. Trimmed; pass null or an empty string to remove. Does not invalidate
|
|
169
|
+
* baselines. Max 1000 characters.
|
|
170
|
+
*/
|
|
171
|
+
intent?: string | null;
|
|
172
|
+
/**
|
|
173
|
+
* Which environment `testOrigin` is: production, staging, preview, development, or your
|
|
174
|
+
* own word (1-24 letters, digits, spaces, hyphens; stored lower-case). A label only:
|
|
175
|
+
* never resets baselines and never changes a run. Pass null or an empty string to remove.
|
|
176
|
+
*/
|
|
177
|
+
environment?: string | null;
|
|
178
|
+
/** Live-vs-live projects only, which environment `baseOrigin` is. Same rules as `environment`. */
|
|
179
|
+
baseEnvironment?: string | null;
|
|
148
180
|
}
|
|
149
181
|
export interface VRConfig {
|
|
150
182
|
apiKey?: string;
|
|
@@ -180,12 +212,28 @@ export interface RegionVerdict {
|
|
|
180
212
|
confidence: number;
|
|
181
213
|
reasoning: string;
|
|
182
214
|
}
|
|
183
|
-
/**
|
|
215
|
+
/**
|
|
216
|
+
* How one page's change measures against the intent the run was given. Present only when the
|
|
217
|
+
* job carried a {@link RunContext}. A verdict is a recommendation: {@link Job.approve} and
|
|
218
|
+
* rejecting remain the only actions that move a baseline.
|
|
219
|
+
*/
|
|
184
220
|
export interface ResultVerdict {
|
|
185
221
|
decision: VerdictDecision;
|
|
222
|
+
/** The confidence in the decision, 0–1. */
|
|
186
223
|
minConfidence: number;
|
|
224
|
+
/** One sentence saying why. */
|
|
225
|
+
reasoning?: string;
|
|
226
|
+
/**
|
|
227
|
+
* For `intentional` only: the words of the intent, quoted verbatim, that name this change.
|
|
228
|
+
* An intentional verdict whose quoted words are not in the intent is downgraded to
|
|
229
|
+
* `needs_review` before it is stored.
|
|
230
|
+
*/
|
|
231
|
+
coveredBy?: string;
|
|
232
|
+
/** When the decision was made. */
|
|
233
|
+
judgedAt?: string;
|
|
234
|
+
/** @deprecated Equal to `minConfidence`. Kept for older clients. */
|
|
187
235
|
avgConfidence: number;
|
|
188
|
-
/**
|
|
236
|
+
/** @deprecated Always empty. Kept for older clients. */
|
|
189
237
|
regions: Record<string, RegionVerdict>;
|
|
190
238
|
/**
|
|
191
239
|
* What the judgement was made from.
|
|
@@ -208,6 +256,10 @@ export interface ResultVerdict {
|
|
|
208
256
|
* content pushed by a change elsewhere — both are consequences, not edits.
|
|
209
257
|
*/
|
|
210
258
|
export type ChangeType = 'text-edit' | 'insert' | 'delete' | 'style-only' | 'image-change' | 'move' | 'move-with-edit' | 'sticky-reposition' | 'reflow-displacement'
|
|
259
|
+
/** A reader-facing attribute changed (a link target, alt text, an aria-label). See `Change.attributes`. */
|
|
260
|
+
| 'attribute-edit'
|
|
261
|
+
/** A web font failed to load for this capture. */
|
|
262
|
+
| 'font-failed'
|
|
211
263
|
/**
|
|
212
264
|
* The six metadata types: the page's head or its structured data changed while nothing
|
|
213
265
|
* visible moved — a title edited, a canonical rewritten, a JSON-LD block dropped. They
|
|
@@ -232,8 +284,7 @@ export interface Change {
|
|
|
232
284
|
type: ChangeType;
|
|
233
285
|
/**
|
|
234
286
|
* Tag name only, lowercase, e.g. `div` — not a CSS selector and not unique on the page.
|
|
235
|
-
* For a metadata type, the field that changed instead.
|
|
236
|
-
* with, see `PageResult.elementsChanged`.
|
|
287
|
+
* For a metadata type, the field that changed instead.
|
|
237
288
|
*/
|
|
238
289
|
element: string;
|
|
239
290
|
/**
|
|
@@ -246,8 +297,29 @@ export interface Change {
|
|
|
246
297
|
before?: string;
|
|
247
298
|
/** The text after the edit. Absent on a delete. Clipped the same way as `before`. */
|
|
248
299
|
after?: string;
|
|
300
|
+
/**
|
|
301
|
+
* On a change with no words of its own (`style-only`, `attribute-edit`, `image-change`):
|
|
302
|
+
* what a reader calls the element, its text or an image's alt text, up to 40 characters
|
|
303
|
+
* ("Apply now"). Absent on a large element such as a section, whose text would not name
|
|
304
|
+
* it, and when the page's changes left no room in the field's size budget: a label never
|
|
305
|
+
* displaces a change.
|
|
306
|
+
*/
|
|
307
|
+
label?: string;
|
|
249
308
|
/** Changed computed styles, keyed by CSS property name. */
|
|
250
309
|
style?: Record<string, StyleDelta>;
|
|
310
|
+
/**
|
|
311
|
+
* On an `attribute-edit`: each changed reader-facing attribute (href, alt, title,
|
|
312
|
+
* aria-label, placeholder, role, type, value) as name to [before, after]. A same-origin
|
|
313
|
+
* link is compared as its path, so a preview's own host is not a change.
|
|
314
|
+
*/
|
|
315
|
+
attributes?: Record<string, StyleDelta>;
|
|
316
|
+
/**
|
|
317
|
+
* Present as `"date"` when every changed word belongs to a date or time ("Sep 17" to
|
|
318
|
+
* "Sep 23", "3 hours ago"). The edit is reported but does not count toward the page
|
|
319
|
+
* having changed, so a page can list one and still read unchanged. Numbers, prices and
|
|
320
|
+
* percentages are never labelled this way.
|
|
321
|
+
*/
|
|
322
|
+
valueOnly?: 'date';
|
|
251
323
|
/**
|
|
252
324
|
* Where it sits in the current capture.
|
|
253
325
|
*
|
|
@@ -282,6 +354,7 @@ export interface RegressionbotSummaryItem {
|
|
|
282
354
|
label: string;
|
|
283
355
|
/** Single-sentence description of what changed in that region. */
|
|
284
356
|
text: string;
|
|
357
|
+
/** @deprecated Never set on current results. To be removed after 2026-10-28. */
|
|
285
358
|
verdict?: RegionVerdict;
|
|
286
359
|
}
|
|
287
360
|
/**
|
|
@@ -319,12 +392,23 @@ export interface PageResult {
|
|
|
319
392
|
* page whose baseline predates metadata capture, which is silence rather than "no".
|
|
320
393
|
*/
|
|
321
394
|
metadataChanged?: true;
|
|
395
|
+
/**
|
|
396
|
+
* Which group this page's change belongs to — `structural`, `edited`, `metadata`,
|
|
397
|
+
* `unmeasured`, `date` or `cosmetic` — so a caller can filter a run to one kind of
|
|
398
|
+
* change without re-deriving the rule. The same value the digest email groups on.
|
|
399
|
+
* Present only on a page that counts as a change. `unmeasured` and `date` occur only
|
|
400
|
+
* on results from before 2026-09-28.
|
|
401
|
+
*/
|
|
402
|
+
changeGroup?: 'structural' | 'edited' | 'metadata' | 'unmeasured' | 'date' | 'cosmetic';
|
|
322
403
|
/**
|
|
323
404
|
* Percentage of pixels that differed from the baseline. Not a change test on its own:
|
|
324
405
|
* 0 does not mean identical — see `changed`.
|
|
325
406
|
*/
|
|
326
407
|
diffPercentage: number;
|
|
327
|
-
/**
|
|
408
|
+
/**
|
|
409
|
+
* @deprecated Deprecated 2026-09-29. 100 minus `diffPercentage`; it no longer measures
|
|
410
|
+
* how alike two pictures look. Kept for existing callers. Read `changed` and `changes`.
|
|
411
|
+
*/
|
|
328
412
|
visualMatchScore: number;
|
|
329
413
|
/** True when this capture became a baseline because none existed to compare against. */
|
|
330
414
|
isNewBaseline: boolean;
|
|
@@ -337,6 +421,14 @@ export interface PageResult {
|
|
|
337
421
|
* the run carried a {@link RunContext}, and only once summaryStatus is COMPLETE.
|
|
338
422
|
*/
|
|
339
423
|
verdict?: ResultVerdict;
|
|
424
|
+
/** A person's Approve or Reject on this page, written by {@link Job.approve} or the dashboard. */
|
|
425
|
+
triageStatus?: 'PENDING' | 'APPROVING' | 'APPROVED' | 'REJECTED';
|
|
426
|
+
triagedAt?: string;
|
|
427
|
+
triagedBy?: string;
|
|
428
|
+
/** The verdict's decision at the moment of the click; null when the page had none. */
|
|
429
|
+
triagedVerdict?: VerdictDecision | null;
|
|
430
|
+
/** Optional, from the person, when their action disagreed with the verdict. */
|
|
431
|
+
triageNote?: string;
|
|
340
432
|
/**
|
|
341
433
|
* The exact edits the engine computed from the two documents — element, text before,
|
|
342
434
|
* text after, changed styles. Absent when the DOM comparison could not run on the page,
|
|
@@ -350,12 +442,13 @@ export interface PageResult {
|
|
|
350
442
|
* not necessarily all of them.
|
|
351
443
|
*/
|
|
352
444
|
changes?: Change[];
|
|
353
|
-
/**
|
|
445
|
+
/** @deprecated Dropped 2026-09-28; already never set before that. Use `changes` instead. */
|
|
354
446
|
elementsChanged?: string[];
|
|
355
447
|
/**
|
|
356
|
-
*
|
|
357
|
-
*
|
|
358
|
-
*
|
|
448
|
+
* @deprecated Only on results from before 2026-09-28, when the pixel engine compared a
|
|
449
|
+
* page without its DOM. To be removed after 2026-10-28, when the last of those expire.
|
|
450
|
+
* The result is a plain pixel diff with no semantic change types, so treat its
|
|
451
|
+
* classifications as absent rather than as "nothing structural changed".
|
|
359
452
|
*/
|
|
360
453
|
domAssistSkipReason?: string;
|
|
361
454
|
/** Pre-signed URL for the stored baseline screenshot. */
|
|
@@ -381,7 +474,16 @@ export interface JobProgress {
|
|
|
381
474
|
export type SummaryStatus = 'PENDING' | 'PROCESSING' | 'COMPLETE' | 'FAILED';
|
|
382
475
|
export interface JobStatus {
|
|
383
476
|
jobId: string;
|
|
384
|
-
|
|
477
|
+
/** The project's environment when the run started. A label only. Absent when the project has none. */
|
|
478
|
+
environment?: string;
|
|
479
|
+
/** Live-vs-live runs only: the environment of the base origin. Absent otherwise. */
|
|
480
|
+
baseEnvironment?: string;
|
|
481
|
+
/**
|
|
482
|
+
* Terminal states are COMPLETED, APPROVED, RESOLVED and FAILED. APPROVED means every page
|
|
483
|
+
* carrying a diff was approved; RESOLVED means they were all decided and at least one was
|
|
484
|
+
* rejected. RESOLVED was missing here, and waitForCompletion polled past it forever.
|
|
485
|
+
*/
|
|
486
|
+
status: 'INITIALIZING' | 'PROCESSING' | 'FINISHING' | 'SUMMARIZING' | 'COMPLETED' | 'APPROVED' | 'RESOLVED' | 'FAILED';
|
|
385
487
|
/**
|
|
386
488
|
* PENDING means not yet started, COMPLETE that regressionbotSummary is populated
|
|
387
489
|
* (or that nothing needed one). Poll until COMPLETE before reading summaries.
|
|
@@ -389,20 +491,41 @@ export interface JobStatus {
|
|
|
389
491
|
summaryStatus: SummaryStatus;
|
|
390
492
|
error: string | null;
|
|
391
493
|
progress: JobProgress;
|
|
494
|
+
/** The project whose configuration this run used, when it had one. */
|
|
495
|
+
project?: string;
|
|
496
|
+
/** The origin that was captured as "current". */
|
|
497
|
+
origin?: string;
|
|
498
|
+
/** The second origin, captured as the comparison. Present only in live-vs-live mode. */
|
|
499
|
+
baseOrigin?: string;
|
|
392
500
|
executionTime: number;
|
|
393
501
|
createdAt: string;
|
|
502
|
+
/** Whether the run carried an intent. Without one no page gets a verdict. */
|
|
503
|
+
intentProvided?: boolean;
|
|
504
|
+
/** Whether this run compared two live origins or one origin against a stored baseline. */
|
|
505
|
+
comparisonMode?: 'live-vs-live' | 'managed';
|
|
506
|
+
/** Page-checks the run made, and how many finished. Mirrors `progress`. */
|
|
507
|
+
totalUrls?: number;
|
|
508
|
+
completedCount?: number;
|
|
394
509
|
/** Partial or complete results. Fills in as workers finish. */
|
|
395
510
|
results: PageResult[];
|
|
396
511
|
}
|
|
397
512
|
export interface JobSummary {
|
|
398
513
|
jobId: string;
|
|
514
|
+
/** The project's environment when the run started. A label only. Absent when the project has none. */
|
|
515
|
+
environment?: string;
|
|
516
|
+
/** Live-vs-live runs only: the environment of the base origin. Absent otherwise. */
|
|
517
|
+
baseEnvironment?: string;
|
|
399
518
|
/** getSummary() throws until the job reaches one of these. */
|
|
400
|
-
status: 'COMPLETED' | 'APPROVED' | 'FAILED';
|
|
519
|
+
status: 'COMPLETED' | 'APPROVED' | 'RESOLVED' | 'FAILED';
|
|
401
520
|
summaryStatus: SummaryStatus;
|
|
402
521
|
error: string | null;
|
|
403
522
|
totalUrls: number;
|
|
404
523
|
completedCount: number;
|
|
405
|
-
/**
|
|
524
|
+
/**
|
|
525
|
+
* @deprecated Deprecated 2026-09-29. 100 minus the average `diffPercentage` over the
|
|
526
|
+
* job's pages, an errored page counting as 100: not a similarity score. Kept for
|
|
527
|
+
* existing callers. Read `regressionCount` and each regression's `changes`.
|
|
528
|
+
*/
|
|
406
529
|
overallScore: number;
|
|
407
530
|
executionTime: number;
|
|
408
531
|
regressionCount: number;
|
|
@@ -424,6 +547,13 @@ export interface JobSummary {
|
|
|
424
547
|
variantName: string;
|
|
425
548
|
errorMessage: string;
|
|
426
549
|
}>;
|
|
550
|
+
/**
|
|
551
|
+
* An AI summary of the whole run, two or three sentences, written once when the run
|
|
552
|
+
* finished from the exact edits in `regressions` (the same text opens the scheduled-run
|
|
553
|
+
* email). Null when nothing changed or none could be written. The changes are the
|
|
554
|
+
* record; this is a reading of them.
|
|
555
|
+
*/
|
|
556
|
+
runSummary: string | null;
|
|
427
557
|
/** Whole-job roll-up of how the changes line up with the run's stated intent. */
|
|
428
558
|
intentAssessment: IntentAssessment;
|
|
429
559
|
/** The intent this run was given, echoed back. */
|
|
@@ -448,6 +578,12 @@ export interface RunContext {
|
|
|
448
578
|
scope?: string[];
|
|
449
579
|
}
|
|
450
580
|
export interface IntentAssessment {
|
|
581
|
+
/**
|
|
582
|
+
* The one field a CI step reads. `fail`: a page contradicts the intent. `review`: a page
|
|
583
|
+
* needs a person, or was never assessed. `pass`: every changed page is accounted for.
|
|
584
|
+
* `not_judged`: the run carried no intent, so nothing was assessed.
|
|
585
|
+
*/
|
|
586
|
+
decision: 'pass' | 'review' | 'fail' | 'not_judged';
|
|
451
587
|
/** False when the run carried no RunContext, in which case the counts are all zero. */
|
|
452
588
|
intentProvided: boolean;
|
|
453
589
|
bugCount: number;
|
|
@@ -459,14 +595,22 @@ export interface IntentAssessment {
|
|
|
459
595
|
/** One line summarising the job, safe to print straight into CI output. */
|
|
460
596
|
summary: string;
|
|
461
597
|
}
|
|
598
|
+
/** Approve only the pages whose verdict is in the list. A job-level filter. */
|
|
599
|
+
export interface ApproveWhere {
|
|
600
|
+
decision: VerdictDecision[];
|
|
601
|
+
}
|
|
462
602
|
export interface ApproveResult {
|
|
463
603
|
message: string;
|
|
464
604
|
jobId: string;
|
|
465
605
|
approvedUrlsCount: number;
|
|
606
|
+
/** With `where` only: changed pages left pending because their verdict was outside the list or absent. */
|
|
607
|
+
skippedUrlsCount?: number;
|
|
466
608
|
/** Present when some captures could not be promoted. */
|
|
467
609
|
failedCount?: number;
|
|
468
610
|
/** Pages skipped because another job updated their baseline first. */
|
|
469
611
|
conflictedUrls?: string[];
|
|
612
|
+
/** One page only: what approvePage or rejectPage wrote on that page's result. */
|
|
613
|
+
triageStatus?: 'APPROVED' | 'REJECTED';
|
|
470
614
|
}
|
|
471
615
|
export interface JobAiSummary {
|
|
472
616
|
message: string;
|
package/package.json
CHANGED