@regressionbot/sdk 2.9.0 → 2.10.1
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 +41 -1
- package/dist/cli.js +38 -0
- package/dist/index.d.ts +7 -3
- package/dist/index.js +7 -3
- package/dist/types.d.ts +158 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -38,6 +38,45 @@ npm install @regressionbot/sdk
|
|
|
38
38
|
|
|
39
39
|
## Migration from 1.x
|
|
40
40
|
|
|
41
|
+
### 2.10.1
|
|
42
|
+
|
|
43
|
+
Documentation only; no change to any type's shape or any method.
|
|
44
|
+
|
|
45
|
+
- **`ResultAssessment.reason` can be `deferred`**: the verdict pass ran short of time for that page
|
|
46
|
+
and will retry it.
|
|
47
|
+
- **`autoApprove` with a `runContext`**: auto-approve fires only if every changed page has an AI
|
|
48
|
+
verdict (a page skipped under `aiSummaryThreshold` counts as having none); otherwise the run is
|
|
49
|
+
held for review.
|
|
50
|
+
|
|
51
|
+
### 2.10.0
|
|
52
|
+
|
|
53
|
+
Needs the current production API for these fields to be populated. On an older API they are simply absent.
|
|
54
|
+
|
|
55
|
+
- **`approve()`'s `warning` can now be `'PREVIEW_RUN'`.** A job whose origin differs from its
|
|
56
|
+
project's `testOrigin` (a PR preview) has the decision recorded (`triageStatus`, `triagedBy`)
|
|
57
|
+
but copies nothing to the shared baseline; `note` explains why.
|
|
58
|
+
- **`intentAssessment.reasons`** (`GateReason[]`) — every condition behind `decision`, worst
|
|
59
|
+
first, empty on a clean pass. Tells a `review` caused by a page that needs a person apart
|
|
60
|
+
from one caused by pages that failed or were never assessed.
|
|
61
|
+
- **`intentAssessment.coverage`** (`RunCoverage`) — what the run compared and how much of it
|
|
62
|
+
the verdict covers, including a reason → count breakdown for every unassessed page.
|
|
63
|
+
- **A regression's `assessment`** (`ResultAssessment`) — where that page stands with the
|
|
64
|
+
verdict, including why it has none (`status`, `reason`). Present only on a regression from
|
|
65
|
+
`getSummary()`, never on a match and never on a result from `getStatus()`.
|
|
66
|
+
- **`isNewPage`**, on a result — true when the base answered 404/410 while the head loaded: a
|
|
67
|
+
new page, not a failure and not a regression.
|
|
68
|
+
- **`JobSummary.newPageCount`** and **`JobSummary.newPages`** — the same new-page pages,
|
|
69
|
+
counted and listed, the way `newBaselineCount`/`newBaselines` already are.
|
|
70
|
+
- **`JobSummary.changeClusters`** (`ChangeCluster[]`) — an edit that repeats on two or more
|
|
71
|
+
changed pages, listed once with every page it reaches. Empty when no edit repeats;
|
|
72
|
+
`regressions[].changes` stays the full per-page record.
|
|
73
|
+
- **`usage`** (`UsageBlock`), on `JobStatus`, `JobSummary`, and now also on the `JobHandle`
|
|
74
|
+
returned by `.run()` and `runProject()` — comparisons charged to the run and where the
|
|
75
|
+
month's meter stands. `.run()`/`runProject()` previously discarded every field but `jobId`.
|
|
76
|
+
- **`QuotaExceededBody`** — the shape of the 402 a run gets when it does not fit the plan's
|
|
77
|
+
allowance, exported for callers that want to parse the thrown error's message themselves.
|
|
78
|
+
`run()`/`runProject()` still just throw a plain `Error`; no error-handling behaviour change.
|
|
79
|
+
|
|
41
80
|
### 2.9.0
|
|
42
81
|
|
|
43
82
|
- **`approve()`'s `warning` can now be `'BASELINE_OUTDATED'`**, alongside `'NO_BASELINE'`. A
|
|
@@ -413,6 +452,7 @@ const summary = await job.getSummary();
|
|
|
413
452
|
// Whole-job roll-up: does everything that changed line up with the stated intent?
|
|
414
453
|
console.log(summary.intentAssessment?.summary);
|
|
415
454
|
console.log(`Bugs: ${summary.intentAssessment?.bugCount}`);
|
|
455
|
+
// What's behind a `review` or `fail`, worst first (needs API 2.10.0+): summary.intentAssessment?.reasons
|
|
416
456
|
|
|
417
457
|
// Per-result verdict, plus the per-region verdicts behind it
|
|
418
458
|
for (const r of summary.regressions) {
|
|
@@ -466,7 +506,7 @@ const status = await job.waitForCompletion(3000, (s) => {
|
|
|
466
506
|
|
|
467
507
|
### Auto-Approval
|
|
468
508
|
|
|
469
|
-
Set `.autoApprove()` to automatically promote screenshots to baselines when the job completes. Useful for scheduled health checks or first-run baseline seeding.
|
|
509
|
+
Set `.autoApprove()` to automatically promote screenshots to baselines when the job completes. Useful for scheduled health checks or first-run baseline seeding. When the run carries a `runContext`, auto-approve fires only if every changed page has an AI verdict (a page skipped under `aiSummaryThreshold` counts as having none); otherwise the run is held for review.
|
|
470
510
|
|
|
471
511
|
```typescript
|
|
472
512
|
const job = await rb
|
package/dist/cli.js
CHANGED
|
@@ -60,10 +60,27 @@ function printRegression(r) {
|
|
|
60
60
|
if (r.verdict) {
|
|
61
61
|
console.log(` Verdict: ${r.verdict.decision} (confidence ${r.verdict.minConfidence.toFixed(2)}-${r.verdict.avgConfidence.toFixed(2)})`);
|
|
62
62
|
}
|
|
63
|
+
if (r.assessment && r.assessment.status !== 'assessed') {
|
|
64
|
+
console.log(` Assessment: ${r.assessment.status}${r.assessment.reason ? ` (${r.assessment.reason})` : ''}`);
|
|
65
|
+
}
|
|
63
66
|
const summary = formatSummary(r.regressionbotSummary);
|
|
64
67
|
if (summary)
|
|
65
68
|
console.log(` Summary: ${summary}`);
|
|
66
69
|
}
|
|
70
|
+
function printUsage(usage) {
|
|
71
|
+
if (!usage)
|
|
72
|
+
return;
|
|
73
|
+
console.log(`\n💳 Usage: ${usage.charged} charged, ${usage.usedThisPeriod}/${usage.limit} used this period.`);
|
|
74
|
+
}
|
|
75
|
+
function printChangeClusters(clusters) {
|
|
76
|
+
if (!clusters || clusters.length === 0)
|
|
77
|
+
return;
|
|
78
|
+
console.log('\n🔁 Repeated across pages:');
|
|
79
|
+
clusters.forEach(c => {
|
|
80
|
+
const label = c.change.label ? `${c.change.element} (${c.change.label})` : c.change.element;
|
|
81
|
+
console.log(`- ${label}: ${c.pageCount} pages`);
|
|
82
|
+
});
|
|
83
|
+
}
|
|
67
84
|
/**
|
|
68
85
|
* A mistake in how the command was invoked, rather than a run that worked and found
|
|
69
86
|
* something. Exits 2 so CI can tell the two apart — a pipeline that treats "regressions
|
|
@@ -78,6 +95,9 @@ function printIntent(summary) {
|
|
|
78
95
|
return;
|
|
79
96
|
console.log(`\n🧭 Intent: ${ia.summary}`);
|
|
80
97
|
console.log(` bugs: ${ia.bugCount}, intentional: ${ia.intentionalCount}, noise: ${ia.noiseCount}, needs review: ${ia.needsReviewCount}`);
|
|
98
|
+
if (ia.reasons && ia.reasons.length > 0) {
|
|
99
|
+
console.log(` reasons: ${ia.reasons.join(', ')}`);
|
|
100
|
+
}
|
|
81
101
|
}
|
|
82
102
|
function parseFailOn(raw) {
|
|
83
103
|
if (raw === undefined)
|
|
@@ -337,6 +357,7 @@ async function startJob(url, options) {
|
|
|
337
357
|
}
|
|
338
358
|
const job = await builder.run();
|
|
339
359
|
console.log(`✅ Job started! ID: ${job.jobId}`);
|
|
360
|
+
printUsage(job.usage);
|
|
340
361
|
console.log(`📊 Project: ${projectId}`);
|
|
341
362
|
console.log(`📱 Matrix: ${typeof options.on === 'string' ? options.on : 'Desktop Chrome (default)'}`);
|
|
342
363
|
if (options.scan) {
|
|
@@ -356,6 +377,7 @@ Waiting for completion...
|
|
|
356
377
|
console.log(`Total Tasks: ${summary.totalUrls}`);
|
|
357
378
|
console.log(`Regressions: ${summary.regressionCount}`);
|
|
358
379
|
console.log(`New Baselines: ${summary.newBaselineCount}`);
|
|
380
|
+
console.log(`New Pages: ${summary.newPageCount}`);
|
|
359
381
|
console.log(`Errors: ${summary.errorCount}`);
|
|
360
382
|
if (summary.newBaselineCount > 0) {
|
|
361
383
|
console.log('\n✨ New Baselines Created:');
|
|
@@ -363,6 +385,12 @@ Waiting for completion...
|
|
|
363
385
|
console.log(`- ${nb.url} [${nb.variantName}]`);
|
|
364
386
|
});
|
|
365
387
|
}
|
|
388
|
+
if (summary.newPageCount > 0) {
|
|
389
|
+
console.log('\n🆕 New Pages (nothing to compare):');
|
|
390
|
+
summary.newPages.forEach((np) => {
|
|
391
|
+
console.log(`- ${np.url} [${np.variantName}]`);
|
|
392
|
+
});
|
|
393
|
+
}
|
|
366
394
|
let exitCode = 0;
|
|
367
395
|
if (summary.regressionCount > 0) {
|
|
368
396
|
console.log('\n❌ Regressions found:');
|
|
@@ -376,7 +404,9 @@ Waiting for completion...
|
|
|
376
404
|
exitCode = 1;
|
|
377
405
|
}
|
|
378
406
|
}
|
|
407
|
+
printChangeClusters(summary.changeClusters);
|
|
379
408
|
printIntent(summary);
|
|
409
|
+
printUsage(summary.usage);
|
|
380
410
|
// Reported even when there are regressions. These used to be hidden behind an
|
|
381
411
|
// else-if, so a run with both showed only the regressions and exited 1 for what
|
|
382
412
|
// looked like the wrong reason.
|
|
@@ -416,7 +446,15 @@ Errors: ${summary.errorCount}
|
|
|
416
446
|
console.log('❌ Regressions found:');
|
|
417
447
|
summary.regressions.forEach(printRegression);
|
|
418
448
|
}
|
|
449
|
+
if (summary.newPageCount > 0) {
|
|
450
|
+
console.log('\n🆕 New Pages (nothing to compare):');
|
|
451
|
+
summary.newPages.forEach((np) => {
|
|
452
|
+
console.log(`- ${np.url} [${np.variantName}]`);
|
|
453
|
+
});
|
|
454
|
+
}
|
|
455
|
+
printChangeClusters(summary.changeClusters);
|
|
419
456
|
printIntent(summary);
|
|
457
|
+
printUsage(summary.usage);
|
|
420
458
|
const doDownload = options.download || options['download-full'];
|
|
421
459
|
if (doDownload) {
|
|
422
460
|
console.log(`\n💾 Downloading results...`);
|
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, ProjectUpdateResult, EnvGate, SummaryStatus, ApproveResult, ApproveWhere, 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, ProjectUpdateResult, EnvGate, SummaryStatus, ApproveResult, ApproveWhere, Change, ChangeType, StyleDelta, ChangeBox, UsageBlock, QuotaExceededBody, GateReason, AssessmentStatus, ResultAssessment, RunCoverage, ChangeCluster, ChangeClusterPage } 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, ProjectUpdateResult, EnvGate, SummaryStatus, ApproveResult, ApproveWhere, 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, ProjectUpdateResult, EnvGate, SummaryStatus, ApproveResult, ApproveWhere, Change, ChangeType, StyleDelta, ChangeBox, UsageBlock, QuotaExceededBody, GateReason, AssessmentStatus, ResultAssessment, RunCoverage, ChangeCluster, ChangeClusterPage };
|
|
5
5
|
export declare class RegressionBot {
|
|
6
6
|
private apiKey;
|
|
7
7
|
private apiUrl;
|
|
@@ -47,6 +47,7 @@ export declare class RegressionBot {
|
|
|
47
47
|
/** CSS injected before screenshotting. Max 4096 characters. */
|
|
48
48
|
customCss?: string;
|
|
49
49
|
concurrency?: number;
|
|
50
|
+
/** Automatically promote all captures to baselines. When the run carries an intent (`runContext`), auto-approve fires only if every changed page has an AI verdict (a page skipped under `aiSummaryThreshold` counts as having none); otherwise the run is held for review. */
|
|
50
51
|
autoApprove?: boolean;
|
|
51
52
|
/** What this run is testing, used to judge whether changes were intended. */
|
|
52
53
|
runContext?: RunContext;
|
|
@@ -94,6 +95,7 @@ export declare class JobBuilder {
|
|
|
94
95
|
* raising it is a load decision about someone else's environment.
|
|
95
96
|
*/
|
|
96
97
|
concurrency(n: number): this;
|
|
98
|
+
/** Automatically promote all captures to baselines. When the run carries an intent (`runContext`), auto-approve fires only if every changed page has an AI verdict (a page skipped under `aiSummaryThreshold` counts as having none); otherwise the run is held for review. */
|
|
97
99
|
autoApprove(val?: boolean): this;
|
|
98
100
|
mask(selectors: string[]): this;
|
|
99
101
|
/**
|
|
@@ -121,7 +123,9 @@ export declare class JobBuilder {
|
|
|
121
123
|
export declare class JobHandle {
|
|
122
124
|
private sdk;
|
|
123
125
|
jobId: string;
|
|
124
|
-
|
|
126
|
+
/** What starting this job cost, when the usage meter could be read. Needs API 2.10.0 or later. */
|
|
127
|
+
usage?: UsageBlock;
|
|
128
|
+
constructor(sdk: RegressionBot, jobId: string, usage?: UsageBlock);
|
|
125
129
|
getStatus(): Promise<JobStatus>;
|
|
126
130
|
getSummary(): Promise<JobSummary>;
|
|
127
131
|
/**
|
package/dist/index.js
CHANGED
|
@@ -55,7 +55,7 @@ class RegressionBot {
|
|
|
55
55
|
*/
|
|
56
56
|
async runProject(projectName, options = {}) {
|
|
57
57
|
const res = await this._request(`/project/${encodeURIComponent(projectName)}/run`, 'POST', options);
|
|
58
|
-
return new JobHandle(this, res.jobId);
|
|
58
|
+
return new JobHandle(this, res.jobId, res.usage);
|
|
59
59
|
}
|
|
60
60
|
/**
|
|
61
61
|
* Update the configuration settings for a named project.
|
|
@@ -145,6 +145,7 @@ class JobBuilder {
|
|
|
145
145
|
this.manifest.concurrency = n;
|
|
146
146
|
return this;
|
|
147
147
|
}
|
|
148
|
+
/** Automatically promote all captures to baselines. When the run carries an intent (`runContext`), auto-approve fires only if every changed page has an AI verdict (a page skipped under `aiSummaryThreshold` counts as having none); otherwise the run is held for review. */
|
|
148
149
|
autoApprove(val = true) {
|
|
149
150
|
this.manifest.autoApprove = val;
|
|
150
151
|
return this;
|
|
@@ -206,16 +207,19 @@ class JobBuilder {
|
|
|
206
207
|
fidelity: this.manifest.fidelity
|
|
207
208
|
};
|
|
208
209
|
const res = await this.sdk._request('/crawl', 'POST', payload);
|
|
209
|
-
return new JobHandle(this.sdk, res.jobId);
|
|
210
|
+
return new JobHandle(this.sdk, res.jobId, res.usage);
|
|
210
211
|
}
|
|
211
212
|
}
|
|
212
213
|
exports.JobBuilder = JobBuilder;
|
|
213
214
|
class JobHandle {
|
|
214
215
|
sdk;
|
|
215
216
|
jobId;
|
|
216
|
-
|
|
217
|
+
/** What starting this job cost, when the usage meter could be read. Needs API 2.10.0 or later. */
|
|
218
|
+
usage;
|
|
219
|
+
constructor(sdk, jobId, usage) {
|
|
217
220
|
this.sdk = sdk;
|
|
218
221
|
this.jobId = jobId;
|
|
222
|
+
this.usage = usage;
|
|
219
223
|
}
|
|
220
224
|
async getStatus() {
|
|
221
225
|
return this.sdk._request(`/job/${encodeURIComponent(this.jobId)}`);
|
package/dist/types.d.ts
CHANGED
|
@@ -440,6 +440,11 @@ export interface PageResult {
|
|
|
440
440
|
visualMatchScore: number;
|
|
441
441
|
/** True when this capture became a baseline because none existed to compare against. */
|
|
442
442
|
isNewBaseline: boolean;
|
|
443
|
+
/**
|
|
444
|
+
* True when the base answered 404/410 while the head loaded: a new page, not a failure and
|
|
445
|
+
* not a regression. Absent otherwise. Needs API 2.10.0 or later.
|
|
446
|
+
*/
|
|
447
|
+
isNewPage?: boolean;
|
|
443
448
|
/** Why the capture or comparison failed. Present when status is ERROR. */
|
|
444
449
|
errorMessage?: string;
|
|
445
450
|
/** Plain-English description of what visually changed, generated by RegressionBot. */
|
|
@@ -449,6 +454,13 @@ export interface PageResult {
|
|
|
449
454
|
* the run carried a {@link RunContext}, and only once summaryStatus is COMPLETE.
|
|
450
455
|
*/
|
|
451
456
|
verdict?: ResultVerdict;
|
|
457
|
+
/**
|
|
458
|
+
* Where this page stands with the verdict, including why it has none: `failed` with
|
|
459
|
+
* `reason: 'timeout'` is a different thing from `not_judged` or `pending`. Present only on
|
|
460
|
+
* a regression from `getSummary()` — never on a match, and never on a result from
|
|
461
|
+
* `getStatus()`. Needs API 2.10.0 or later.
|
|
462
|
+
*/
|
|
463
|
+
assessment?: ResultAssessment;
|
|
452
464
|
/** A person's Approve or Reject on this page, written by {@link Job.approve} or the dashboard. */
|
|
453
465
|
triageStatus?: 'PENDING' | 'APPROVING' | 'APPROVED' | 'REJECTED';
|
|
454
466
|
triagedAt?: string;
|
|
@@ -500,8 +512,40 @@ export interface JobProgress {
|
|
|
500
512
|
}
|
|
501
513
|
/** Progress of the asynchronous AI summary pass. */
|
|
502
514
|
export type SummaryStatus = 'PENDING' | 'PROCESSING' | 'COMPLETE' | 'FAILED';
|
|
515
|
+
/**
|
|
516
|
+
* What a run was charged and where the month stands. Comparisons are metered per UTC calendar
|
|
517
|
+
* month, and a run costs its unique paths times its devices (a live-vs-live run is not
|
|
518
|
+
* doubled). Present when the meter could be read. Needs API 2.10.0 or later.
|
|
519
|
+
*/
|
|
520
|
+
export interface UsageBlock {
|
|
521
|
+
/** Comparisons charged to this run. 0 when the run was never metered. */
|
|
522
|
+
charged: number;
|
|
523
|
+
/** Comparisons used this month, or, on the free trial, used of the 500-comparison trial window. */
|
|
524
|
+
usedThisPeriod: number;
|
|
525
|
+
/** The plan's monthly limit, applied to this month's used count even after a mid-month plan change. */
|
|
526
|
+
limit: number;
|
|
527
|
+
/** First instant of the current UTC month. */
|
|
528
|
+
periodStart: string;
|
|
529
|
+
/** First instant of the next UTC month, when the meter resets. */
|
|
530
|
+
periodEnd: string;
|
|
531
|
+
}
|
|
532
|
+
/**
|
|
533
|
+
* The 402 body for a run that does not fit the allowance: no jobId is returned, nothing is
|
|
534
|
+
* charged and nothing starts. `run()`/`runProject()` still throw a plain `Error` whose message
|
|
535
|
+
* is this JSON; exported here for callers that want to parse it themselves.
|
|
536
|
+
*/
|
|
537
|
+
export interface QuotaExceededBody {
|
|
538
|
+
error: string;
|
|
539
|
+
used: number;
|
|
540
|
+
limit: number;
|
|
541
|
+
requested: number;
|
|
542
|
+
periodEnd: string | null;
|
|
543
|
+
window?: 'trial' | 'month';
|
|
544
|
+
}
|
|
503
545
|
export interface JobStatus {
|
|
504
546
|
jobId: string;
|
|
547
|
+
/** Present when the usage meter could be read. Needs API 2.10.0 or later. */
|
|
548
|
+
usage?: UsageBlock;
|
|
505
549
|
/** The project's environment when the run started. A label only. Absent when the project has none. */
|
|
506
550
|
environment?: string;
|
|
507
551
|
/** Live-vs-live runs only: the environment of the base origin. Absent otherwise. */
|
|
@@ -543,6 +587,8 @@ export interface JobStatus {
|
|
|
543
587
|
}
|
|
544
588
|
export interface JobSummary {
|
|
545
589
|
jobId: string;
|
|
590
|
+
/** Present when the usage meter could be read. Needs API 2.10.0 or later. */
|
|
591
|
+
usage?: UsageBlock;
|
|
546
592
|
/** The project's environment when the run started. A label only. Absent when the project has none. */
|
|
547
593
|
environment?: string;
|
|
548
594
|
/** Live-vs-live runs only: the environment of the base origin. Absent otherwise. */
|
|
@@ -567,6 +613,11 @@ export interface JobSummary {
|
|
|
567
613
|
regressionCount: number;
|
|
568
614
|
matchCount: number;
|
|
569
615
|
newBaselineCount: number;
|
|
616
|
+
/**
|
|
617
|
+
* Pages the base answered 404/410 for while the head loaded: new, nothing to compare. Not
|
|
618
|
+
* counted as a regression or an error. Needs API 2.10.0 or later.
|
|
619
|
+
*/
|
|
620
|
+
newPageCount: number;
|
|
570
621
|
errorCount: number;
|
|
571
622
|
/** Pages where a visual regression was detected. */
|
|
572
623
|
regressions: PageResult[];
|
|
@@ -577,6 +628,16 @@ export interface JobSummary {
|
|
|
577
628
|
url: string;
|
|
578
629
|
variantName: string;
|
|
579
630
|
}>;
|
|
631
|
+
/**
|
|
632
|
+
* Pages that exist only on the head (base answered 404/410 while the head loaded): new,
|
|
633
|
+
* nothing to compare, not an error. Clients that ignore this field see those pages in no
|
|
634
|
+
* list, as before they existed. Needs API 2.10.0 or later.
|
|
635
|
+
*/
|
|
636
|
+
newPages: Array<{
|
|
637
|
+
url: string;
|
|
638
|
+
variantName: string;
|
|
639
|
+
note: string;
|
|
640
|
+
}>;
|
|
580
641
|
/** Pages that failed to capture or compare. */
|
|
581
642
|
errors: Array<{
|
|
582
643
|
url: string;
|
|
@@ -600,6 +661,32 @@ export interface JobSummary {
|
|
|
600
661
|
intentAssessment: IntentAssessment;
|
|
601
662
|
/** The intent this run was given, echoed back. */
|
|
602
663
|
runContext?: RunContext;
|
|
664
|
+
/**
|
|
665
|
+
* Edits that appear on two or more of the changed pages, each listed once with the pages
|
|
666
|
+
* it reaches. Empty when no edit repeats. `regressions[].changes` stays the full per-page
|
|
667
|
+
* record. Not yet in the API's published openapi.yaml schema; this doc comment is taken
|
|
668
|
+
* from the API's own JSDoc instead. Needs API 2.10.0 or later.
|
|
669
|
+
*/
|
|
670
|
+
changeClusters: ChangeCluster[];
|
|
671
|
+
}
|
|
672
|
+
export interface ChangeClusterPage {
|
|
673
|
+
url: string;
|
|
674
|
+
variantName: string;
|
|
675
|
+
diffUrl: string | null;
|
|
676
|
+
}
|
|
677
|
+
/** The same edit repeated on two or more changed pages, listed once with every page it reaches. */
|
|
678
|
+
export interface ChangeCluster {
|
|
679
|
+
/** Stable for the same edit: a hash of its element, type, before/after text and styles. */
|
|
680
|
+
id: string;
|
|
681
|
+
/** The shared edit, as it appears in each page's `changes` (without its per-page box). */
|
|
682
|
+
change: Omit<Change, 'box'>;
|
|
683
|
+
pageCount: number;
|
|
684
|
+
pages: ChangeClusterPage[];
|
|
685
|
+
/**
|
|
686
|
+
* How the pages carrying this edit were judged, decision → count. A page's verdict covers
|
|
687
|
+
* all its edits, so this is a count by page, not a verdict on the edit alone.
|
|
688
|
+
*/
|
|
689
|
+
pageVerdicts: Record<string, number>;
|
|
603
690
|
}
|
|
604
691
|
/**
|
|
605
692
|
* What a run is testing. Supplying it lets RegressionBot judge each change as
|
|
@@ -636,6 +723,72 @@ export interface IntentAssessment {
|
|
|
636
723
|
allAccountedFor: boolean;
|
|
637
724
|
/** One line summarising the job, safe to print straight into CI output. */
|
|
638
725
|
summary: string;
|
|
726
|
+
/**
|
|
727
|
+
* Every condition behind `decision`, worst first; empty on a clean pass. Tells a review
|
|
728
|
+
* caused by a page that needs a person from one caused by pages that failed or were never
|
|
729
|
+
* assessed. Needs API 2.10.0 or later.
|
|
730
|
+
*/
|
|
731
|
+
reasons?: GateReason[];
|
|
732
|
+
/** What the run compared and how much of it the verdict covers. Needs API 2.10.0 or later. */
|
|
733
|
+
coverage?: RunCoverage;
|
|
734
|
+
}
|
|
735
|
+
/** Every condition {@link IntentAssessment.decision} can be built from, worst first. */
|
|
736
|
+
export type GateReason = 'no_intent' | 'nothing_compared' | 'bug' | 'needs_review' | 'assessment_in_progress' | 'assessment_incomplete' | 'device_disagreement' | 'comparison_failures';
|
|
737
|
+
/**
|
|
738
|
+
* Where one changed page stands with the verdict.
|
|
739
|
+
*
|
|
740
|
+
* - assessed: it has a verdict.
|
|
741
|
+
* - pending: the analysis is still running, so no verdict yet.
|
|
742
|
+
* - failed: the verdict pass, or the summary before it, tried and failed (`reason` says how).
|
|
743
|
+
* - skipped: deliberately not analysed (below the project's AI summary threshold).
|
|
744
|
+
* - unassessed: the run finished and nothing tried to judge it.
|
|
745
|
+
* - not_judged: the run carried no intent, so no page is judged.
|
|
746
|
+
*/
|
|
747
|
+
export type AssessmentStatus = 'assessed' | 'pending' | 'failed' | 'skipped' | 'unassessed' | 'not_judged';
|
|
748
|
+
/** Where one changed page stands with the verdict, including why it has none. */
|
|
749
|
+
export interface ResultAssessment {
|
|
750
|
+
status: AssessmentStatus;
|
|
751
|
+
/**
|
|
752
|
+
* Why, when status is not `assessed`. One of no_intent, analysis_in_progress, timeout,
|
|
753
|
+
* model_error, malformed_response, incomplete_response, capped, deferred, pass_error,
|
|
754
|
+
* pass_interrupted, no_assessor, summary_failed, below_ai_threshold, not_analysed,
|
|
755
|
+
* not_reached. `deferred` means the analysis ran short of time and will be retried.
|
|
756
|
+
*/
|
|
757
|
+
reason?: string;
|
|
758
|
+
}
|
|
759
|
+
/** What one run compared and how much of it the verdict covers. */
|
|
760
|
+
export interface RunCoverage {
|
|
761
|
+
comparisons: {
|
|
762
|
+
/** Every result: compared, failed or first capture. */
|
|
763
|
+
attempted: number;
|
|
764
|
+
/** Compared against a baseline or the other origin: changed + matched. */
|
|
765
|
+
compared: number;
|
|
766
|
+
changed: number;
|
|
767
|
+
matched: number;
|
|
768
|
+
/** Pages that could not be captured or compared, `unreported` included. Never counted as a pass. */
|
|
769
|
+
failed: number;
|
|
770
|
+
/** Of `failed`, pages that never reported a result at all (left PROCESSING). */
|
|
771
|
+
unreported: number;
|
|
772
|
+
newBaselines: number;
|
|
773
|
+
/** Pages the base answered 404/410 for while the head loaded: nothing to compare, not a failure. */
|
|
774
|
+
newPages: number;
|
|
775
|
+
};
|
|
776
|
+
assessment: {
|
|
777
|
+
/** Whether the run asked for verdicts (it carried an intent). */
|
|
778
|
+
required: boolean;
|
|
779
|
+
/** Changed pages, which are the ones a verdict is for. */
|
|
780
|
+
eligible: number;
|
|
781
|
+
assessed: number;
|
|
782
|
+
pending: number;
|
|
783
|
+
failed: number;
|
|
784
|
+
skipped: number;
|
|
785
|
+
unassessed: number;
|
|
786
|
+
notJudged: number;
|
|
787
|
+
/** Reason → count, for every page not assessed. */
|
|
788
|
+
reasons: Record<string, number>;
|
|
789
|
+
};
|
|
790
|
+
/** Every changed page that needed a verdict has one, and no page failed. */
|
|
791
|
+
complete: boolean;
|
|
639
792
|
}
|
|
640
793
|
/** Approve only the pages whose verdict is in the list. A job-level filter. */
|
|
641
794
|
export interface ApproveWhere {
|
|
@@ -655,8 +808,11 @@ export interface ApproveResult {
|
|
|
655
808
|
triageStatus?: 'APPROVED' | 'REJECTED';
|
|
656
809
|
/** `'NO_BASELINE'`: there was no stored baseline to advance into — the decision was still recorded.
|
|
657
810
|
* `'BASELINE_OUTDATED'`: job-level approve skipped some pages because another job updated their
|
|
658
|
-
* baseline first; they are listed in `conflictedUrls`.
|
|
659
|
-
|
|
811
|
+
* baseline first; they are listed in `conflictedUrls`.
|
|
812
|
+
* `'PREVIEW_RUN'`: the job's origin differs from its project's testOrigin (a PR preview) —
|
|
813
|
+
* the decision was recorded but nothing was copied to the shared baseline. Needs API 2.10.0
|
|
814
|
+
* or later. */
|
|
815
|
+
warning?: 'NO_BASELINE' | 'BASELINE_OUTDATED' | 'PREVIEW_RUN';
|
|
660
816
|
/** Explains `warning` when present. */
|
|
661
817
|
note?: string;
|
|
662
818
|
/** One page only, and only when `warning` is `'NO_BASELINE'`: always `false`. */
|
package/package.json
CHANGED