@regressionbot/sdk 1.2.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 +242 -0
- package/dist/cli.d.ts +2 -0
- package/dist/cli.js +268 -0
- package/dist/index.d.ts +111 -0
- package/dist/index.js +270 -0
- package/dist/security.d.ts +30 -0
- package/dist/security.js +113 -0
- package/dist/types.d.ts +135 -0
- package/dist/types.js +9 -0
- package/package.json +45 -0
package/README.md
ADDED
|
@@ -0,0 +1,242 @@
|
|
|
1
|
+
# RegressionBot SDK
|
|
2
|
+
|
|
3
|
+
The official SDK for [RegressionBot.com](https://regressionbot.com) — the simplest way to automate visual regression testing.
|
|
4
|
+
|
|
5
|
+
RegressionBot is a declarative visual regression testing platform that helps you catch UI changes before they reach production. This SDK provides a fluent, chainable API to define your test scope, run visual tests, and manage baselines programmatically.
|
|
6
|
+
|
|
7
|
+
## Why RegressionBot?
|
|
8
|
+
|
|
9
|
+
Unlike traditional visual diffing libraries, RegressionBot is designed for modern, automated development loops and agentic pipelines:
|
|
10
|
+
|
|
11
|
+
- **Highly Accurate Regressions (Zero Noise)**: Leveraging advanced pixel-matching algorithms and element masking (using CSS selectors or the automatic `data-vr-mask` attribute), RegressionBot eliminates false positives caused by dynamic data, layout shifting, or third-party widgets.
|
|
12
|
+
- **Plain-English Summaries**: No more manual screenshot comparisons. RegressionBot translates visual diffs into concise, plain-English descriptions of what changed, so you know exactly what was modified at a glance.
|
|
13
|
+
- **Agentic Workflow Ready**: Built from the ground up to support autonomous coding agents (like Gemini or Claude) and automated developer loops. Through standard API endpoints, CLI commands, and Model Context Protocol (MCP) integrations, agents can trigger tests, read plain-English results, and approve baseline changes programmatically without human intervention.
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
## Features
|
|
17
|
+
|
|
18
|
+
- **Fluent Manifest Builder**: Chainable methods to define your test scope.
|
|
19
|
+
- **Matrix Testing**: Test multiple devices and viewports in a single job.
|
|
20
|
+
- **Auto-Discovery**: Scan sitemaps with glob patterns and limits.
|
|
21
|
+
- **RegressionBot Summaries**: Plain-English change descriptions for every regression, generated on-demand via the API.
|
|
22
|
+
- **Project-Based Baselines**: Save and reuse test configurations; share visual history across environments.
|
|
23
|
+
- **Auto-Approval**: Automatically promote screenshots to baselines on jobs that pass your criteria.
|
|
24
|
+
- **Zero Infrastructure**: No browser maintenance or server provisioning — RegressionBot handles it all.
|
|
25
|
+
|
|
26
|
+
## Installation
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
npm install @regressionbot/sdk
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
## Usage
|
|
33
|
+
|
|
34
|
+
### Basic Example
|
|
35
|
+
|
|
36
|
+
```typescript
|
|
37
|
+
import { RegressionBot } from '@regressionbot/sdk';
|
|
38
|
+
|
|
39
|
+
const rb = new RegressionBot(); // uses REGRESSIONBOT_API_KEY env var
|
|
40
|
+
|
|
41
|
+
const job = await rb
|
|
42
|
+
.test('https://preview.myapp.com')
|
|
43
|
+
.forProject('my-app-web')
|
|
44
|
+
.run();
|
|
45
|
+
|
|
46
|
+
const status = await job.waitForCompletion();
|
|
47
|
+
const summary = await job.getSummary();
|
|
48
|
+
console.log(`Stability Score: ${summary.overallScore}/100`);
|
|
49
|
+
|
|
50
|
+
// Download only diff images
|
|
51
|
+
await job.downloadResults();
|
|
52
|
+
|
|
53
|
+
// Download all images (baseline, current, diff)
|
|
54
|
+
await job.downloadResults({ full: true });
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
### Full Matrix Example
|
|
58
|
+
|
|
59
|
+
```typescript
|
|
60
|
+
import { RegressionBot } from '@regressionbot/sdk';
|
|
61
|
+
|
|
62
|
+
const rb = new RegressionBot(process.env.API_KEY);
|
|
63
|
+
|
|
64
|
+
const job = await rb
|
|
65
|
+
.test(process.env.VERCEL_PREVIEW_URL) // The Candidate (Test Origin)
|
|
66
|
+
.against('https://production-app.com') // The Source of Truth (Base Origin)
|
|
67
|
+
.forProject('marketing-site-v2') // Context: Links to Baselines & History
|
|
68
|
+
|
|
69
|
+
// Matrix Configuration: Run all checks on both Desktop and Mobile
|
|
70
|
+
.on(['Desktop Chrome', 'iPhone 13'])
|
|
71
|
+
|
|
72
|
+
// Sitemap: Explicitly provide a sitemap location (optional)
|
|
73
|
+
.sitemap('https://production-app.com/sitemap_index.xml')
|
|
74
|
+
|
|
75
|
+
// Scope: Explicitly check critical paths
|
|
76
|
+
.check('/', 'Homepage')
|
|
77
|
+
.check('/pricing', 'Pricing Table')
|
|
78
|
+
|
|
79
|
+
// Discovery: Auto-discover up to 20 blog posts
|
|
80
|
+
.scan('/blog/**', { limit: 20 })
|
|
81
|
+
|
|
82
|
+
// Concurrency: Max parallel browser instances
|
|
83
|
+
.concurrency(10)
|
|
84
|
+
|
|
85
|
+
// Masking: Automatic and manual masking
|
|
86
|
+
.mask(['.ads', '#modal']) // Manual selectors
|
|
87
|
+
// Tip: Adding 'data-vr-mask' to your HTML elements masks them automatically!
|
|
88
|
+
|
|
89
|
+
// Execute: Compiles manifest and triggers the API
|
|
90
|
+
.run();
|
|
91
|
+
|
|
92
|
+
const result = await job.waitForCompletion();
|
|
93
|
+
const summary = await job.getSummary();
|
|
94
|
+
|
|
95
|
+
console.log(`Job ${job.jobId} finished. Overall Score: ${summary.overallScore}`);
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
### RegressionBot Summaries
|
|
99
|
+
|
|
100
|
+
RegressionBot can generate plain-English descriptions of what changed for each regression. Summaries are generated asynchronously after job completion.
|
|
101
|
+
|
|
102
|
+
```typescript
|
|
103
|
+
// Wait for the job and its RegressionBot summaries to both finish
|
|
104
|
+
const status = await job.waitForCompletion(2000, undefined, { waitForSummaries: true });
|
|
105
|
+
const summary = await job.getSummary();
|
|
106
|
+
|
|
107
|
+
if (summary.regressions.length > 0) {
|
|
108
|
+
console.log(`\n${summary.regressions.length} regressions found:`);
|
|
109
|
+
for (const regression of summary.regressions) {
|
|
110
|
+
if (regression.regressionbotSummary) {
|
|
111
|
+
console.log(`\nRegressionBot Summary for ${regression.url}:`);
|
|
112
|
+
console.log(`> ${regression.regressionbotSummary}`);
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
// Or trigger RegressionBot summary generation on-demand for a completed job:
|
|
118
|
+
const aiResult = await job.generateAiSummary();
|
|
119
|
+
console.log(`Generated summaries for ${aiResult.summaries.length} regressions.`);
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
### Progress Tracking
|
|
123
|
+
|
|
124
|
+
Pass a callback to `waitForCompletion` to receive status updates while the job runs:
|
|
125
|
+
|
|
126
|
+
```typescript
|
|
127
|
+
const status = await job.waitForCompletion(3000, (s) => {
|
|
128
|
+
console.log(`[${s.status}] ${s.progress?.completed}/${s.progress?.total} pages checked`);
|
|
129
|
+
});
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
### Auto-Approval
|
|
133
|
+
|
|
134
|
+
Set `.autoApprove()` to automatically promote screenshots to baselines when the job completes. Useful for scheduled health checks or first-run baseline seeding.
|
|
135
|
+
|
|
136
|
+
```typescript
|
|
137
|
+
const job = await rb
|
|
138
|
+
.test('https://production-app.com')
|
|
139
|
+
.forProject('health-check')
|
|
140
|
+
.scan('/**', { limit: 50 })
|
|
141
|
+
.autoApprove()
|
|
142
|
+
.run();
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
You can also approve an existing job's results programmatically:
|
|
146
|
+
|
|
147
|
+
```typescript
|
|
148
|
+
const result = await job.approve();
|
|
149
|
+
console.log(`Approved ${result.approvedUrlsCount} URLs.`);
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
### Saved Projects
|
|
153
|
+
|
|
154
|
+
Projects let you save a test configuration in the RegressionBot dashboard and trigger runs against it without re-specifying every option.
|
|
155
|
+
|
|
156
|
+
```typescript
|
|
157
|
+
// List all saved projects for your organization
|
|
158
|
+
const projects = await rb.listProjects();
|
|
159
|
+
console.log(projects.map(p => p.name));
|
|
160
|
+
|
|
161
|
+
// Fetch a specific project's configuration
|
|
162
|
+
const project = await rb.getProject('marketing-site-v2');
|
|
163
|
+
console.log(project);
|
|
164
|
+
|
|
165
|
+
// Trigger a run from a saved project, optionally overriding fields
|
|
166
|
+
const job = await rb.runProject('marketing-site-v2', {
|
|
167
|
+
testOrigin: process.env.VERCEL_PREVIEW_URL,
|
|
168
|
+
});
|
|
169
|
+
|
|
170
|
+
const status = await job.waitForCompletion();
|
|
171
|
+
const summary = await job.getSummary();
|
|
172
|
+
console.log(`Score: ${summary.overallScore}/100`);
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
### Reconnecting to an Existing Job
|
|
176
|
+
|
|
177
|
+
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:
|
|
178
|
+
|
|
179
|
+
```typescript
|
|
180
|
+
const job = rb.job('job_abc123');
|
|
181
|
+
const summary = await job.getSummary();
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
## CLI Usage
|
|
185
|
+
|
|
186
|
+
The `regressionbot` CLI is the easiest way to interact with the [RegressionBot API](https://regressionbot.com) from your terminal or CI scripts.
|
|
187
|
+
|
|
188
|
+
### Authentication
|
|
189
|
+
|
|
190
|
+
The CLI looks for the following environment variables:
|
|
191
|
+
- `REGRESSIONBOT_API_KEY`: Your project API key.
|
|
192
|
+
- `REGRESSIONBOT_API_URL`: (Optional) Override the default API endpoint.
|
|
193
|
+
|
|
194
|
+
### Commands
|
|
195
|
+
|
|
196
|
+
#### 1. Quick Check
|
|
197
|
+
Test a single URL against its established baseline.
|
|
198
|
+
```bash
|
|
199
|
+
npx @regressionbot/sdk https://example.com --project my-site --on "Desktop Chrome, iPhone 12"
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
#### 2. Sitemap Scan
|
|
203
|
+
Test an entire site using glob patterns.
|
|
204
|
+
```bash
|
|
205
|
+
npx @regressionbot/sdk https://example.com --project my-project --scan "/**" --exclude "/admin/**" --concurrency 20
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
#### 3. Job Summary
|
|
209
|
+
Get detailed results and diff URLs for a completed job.
|
|
210
|
+
```bash
|
|
211
|
+
npx @regressionbot/sdk summary <jobId>
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
Add the `--download` flag to save the diff images locally:
|
|
215
|
+
```bash
|
|
216
|
+
npx @regressionbot/sdk summary <jobId> --download
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
Use the `--download-full` flag to save baseline, current, and diff images:
|
|
220
|
+
```bash
|
|
221
|
+
npx @regressionbot/sdk summary <jobId> --download-full
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
#### 4. Approve Changes
|
|
225
|
+
Promote the current screenshots of a job to be the new baselines.
|
|
226
|
+
```bash
|
|
227
|
+
npx @regressionbot/sdk approve <jobId>
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
## Examples & Integrations
|
|
231
|
+
|
|
232
|
+
Check out the [examples/](./examples/) directory for real-world integration guides:
|
|
233
|
+
- [GitHub Actions](./examples/actions/regressionbot/): Self-contained composite action for CI.
|
|
234
|
+
- [Preview vs Production](./examples/workflows/workflow-preview-vs-prod.yml): Compare staging URLs to live sites.
|
|
235
|
+
- [AWS Amplify](./examples/workflows/platform-amplify.yml): Wait for builds and test dynamically.
|
|
236
|
+
- [Scheduled Health Checks](./examples/workflows/daily-health-check.yml): Monitor production visuals daily.
|
|
237
|
+
|
|
238
|
+
Visit [RegressionBot.com](https://regressionbot.com) for more documentation, pricing, and to create your account.
|
|
239
|
+
|
|
240
|
+
---
|
|
241
|
+
|
|
242
|
+
Made with ❤️ by [RegressionBot](https://regressionbot.com). Report issues on [GitHub](https://github.com/RegressionBot/regressionbot-sdk/issues).
|
package/dist/cli.d.ts
ADDED
package/dist/cli.js
ADDED
|
@@ -0,0 +1,268 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
"use strict";
|
|
3
|
+
var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
|
|
4
|
+
if (k2 === undefined) k2 = k;
|
|
5
|
+
var desc = Object.getOwnPropertyDescriptor(m, k);
|
|
6
|
+
if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
|
|
7
|
+
desc = { enumerable: true, get: function() { return m[k]; } };
|
|
8
|
+
}
|
|
9
|
+
Object.defineProperty(o, k2, desc);
|
|
10
|
+
}) : (function(o, m, k, k2) {
|
|
11
|
+
if (k2 === undefined) k2 = k;
|
|
12
|
+
o[k2] = m[k];
|
|
13
|
+
}));
|
|
14
|
+
var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
|
|
15
|
+
Object.defineProperty(o, "default", { enumerable: true, value: v });
|
|
16
|
+
}) : function(o, v) {
|
|
17
|
+
o["default"] = v;
|
|
18
|
+
});
|
|
19
|
+
var __importStar = (this && this.__importStar) || (function () {
|
|
20
|
+
var ownKeys = function(o) {
|
|
21
|
+
ownKeys = Object.getOwnPropertyNames || function (o) {
|
|
22
|
+
var ar = [];
|
|
23
|
+
for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
|
|
24
|
+
return ar;
|
|
25
|
+
};
|
|
26
|
+
return ownKeys(o);
|
|
27
|
+
};
|
|
28
|
+
return function (mod) {
|
|
29
|
+
if (mod && mod.__esModule) return mod;
|
|
30
|
+
var result = {};
|
|
31
|
+
if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
|
|
32
|
+
__setModuleDefault(result, mod);
|
|
33
|
+
return result;
|
|
34
|
+
};
|
|
35
|
+
})();
|
|
36
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
37
|
+
const index_1 = require("./index");
|
|
38
|
+
const security_1 = require("./security");
|
|
39
|
+
const path = __importStar(require("path"));
|
|
40
|
+
function parseArgs(args) {
|
|
41
|
+
const options = Object.create(null);
|
|
42
|
+
options._ = [];
|
|
43
|
+
for (let i = 0; i < args.length; i++) {
|
|
44
|
+
const arg = args[i];
|
|
45
|
+
if (arg.startsWith('--')) {
|
|
46
|
+
const key = arg.slice(2);
|
|
47
|
+
// Prevent prototype pollution
|
|
48
|
+
if (key === '__proto__' || key === 'constructor' || key === 'prototype') {
|
|
49
|
+
const value = args[i + 1];
|
|
50
|
+
if (value && !value.startsWith('--'))
|
|
51
|
+
i++;
|
|
52
|
+
continue;
|
|
53
|
+
}
|
|
54
|
+
const value = args[i + 1];
|
|
55
|
+
if (value && !value.startsWith('--')) {
|
|
56
|
+
options[key] = value;
|
|
57
|
+
i++;
|
|
58
|
+
}
|
|
59
|
+
else {
|
|
60
|
+
options[key] = true;
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
else {
|
|
64
|
+
options._.push(arg);
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
return options;
|
|
68
|
+
}
|
|
69
|
+
const argv = parseArgs(process.argv.slice(2));
|
|
70
|
+
const command = argv._[0];
|
|
71
|
+
const param = argv._[1];
|
|
72
|
+
const sdk = new index_1.RegressionBot();
|
|
73
|
+
async function main() {
|
|
74
|
+
if (!command || command === 'help' || command === '--help' || command === '-h') {
|
|
75
|
+
showHelp();
|
|
76
|
+
return;
|
|
77
|
+
}
|
|
78
|
+
try {
|
|
79
|
+
if (command === 'status') {
|
|
80
|
+
if (!param)
|
|
81
|
+
throw new Error('Job ID is required for status command.');
|
|
82
|
+
await checkStatus(param);
|
|
83
|
+
}
|
|
84
|
+
else if (command === 'summary') {
|
|
85
|
+
if (!param)
|
|
86
|
+
throw new Error('Job ID is required for summary command.');
|
|
87
|
+
await showSummary(param, argv);
|
|
88
|
+
}
|
|
89
|
+
else if (command === 'approve') {
|
|
90
|
+
if (!param)
|
|
91
|
+
throw new Error('Job ID is required for approve command.');
|
|
92
|
+
await approveJob(param);
|
|
93
|
+
}
|
|
94
|
+
else if (command.startsWith('http')) {
|
|
95
|
+
// Implicit test command
|
|
96
|
+
await startJob(command, argv);
|
|
97
|
+
}
|
|
98
|
+
else {
|
|
99
|
+
console.error(`Unknown command: ${command}`);
|
|
100
|
+
showHelp();
|
|
101
|
+
process.exit(1);
|
|
102
|
+
}
|
|
103
|
+
}
|
|
104
|
+
catch (error) {
|
|
105
|
+
console.error(`
|
|
106
|
+
Error: ${error.message}`);
|
|
107
|
+
process.exit(1);
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
function showHelp() {
|
|
111
|
+
console.log(`
|
|
112
|
+
RegressionBot CLI
|
|
113
|
+
|
|
114
|
+
Usage:
|
|
115
|
+
npx regressionbot <url> Quick test a URL.
|
|
116
|
+
npx regressionbot status <jobId> Check the status of a specific job.
|
|
117
|
+
npx regressionbot summary <jobId> Get detailed results and diff URLs.
|
|
118
|
+
Use --download to save the diff image locally.
|
|
119
|
+
Use --download-full to save baseline and current images too.
|
|
120
|
+
npx regressionbot approve <jobId> Approve a job's results as new baselines.
|
|
121
|
+
|
|
122
|
+
Options for <url>:
|
|
123
|
+
--project <id> Required project ID.
|
|
124
|
+
--against <url> Base origin to compare against.
|
|
125
|
+
--sitemap <url> Explicit sitemap.xml location.
|
|
126
|
+
--on <devices> Comma-separated device names (e.g. "Desktop Chrome,iPhone 12").
|
|
127
|
+
--scan <pattern> Glob pattern to scan in sitemap (e.g. "/blog/**").
|
|
128
|
+
--exclude <patterns> Comma-separated glob patterns to exclude.
|
|
129
|
+
--concurrency <n> Max concurrent workers (default 10).
|
|
130
|
+
--auto-approve Automatically approve results as new baselines.
|
|
131
|
+
--mask <selectors> Comma-separated CSS selectors to hide (e.g. ".ad,#popup").
|
|
132
|
+
--skip-summaries Skip waiting for parallel AI summaries in the CLI.
|
|
133
|
+
|
|
134
|
+
Environment Variables:
|
|
135
|
+
REGRESSIONBOT_API_KEY Override the API Key.
|
|
136
|
+
REGRESSIONBOT_API_URL Override the API URL.
|
|
137
|
+
`);
|
|
138
|
+
}
|
|
139
|
+
async function startJob(url, options) {
|
|
140
|
+
console.log(`🚀 Initializing visual test...`);
|
|
141
|
+
const projectId = options.project;
|
|
142
|
+
const devices = options.on ? options.on.split(',').map((s) => s.trim()) : ['Desktop Chrome'];
|
|
143
|
+
const builder = sdk.test(url)
|
|
144
|
+
.on(devices)
|
|
145
|
+
.concurrency(Number(options.concurrency) || 10);
|
|
146
|
+
if (projectId) {
|
|
147
|
+
builder.forProject(projectId);
|
|
148
|
+
}
|
|
149
|
+
if (options.against) {
|
|
150
|
+
builder.against(options.against);
|
|
151
|
+
}
|
|
152
|
+
if (options.sitemap) {
|
|
153
|
+
builder.sitemap(options.sitemap);
|
|
154
|
+
}
|
|
155
|
+
if (options.scan) {
|
|
156
|
+
const exclude = options.exclude ? options.exclude.split(',').map((s) => s.trim()) : [];
|
|
157
|
+
builder.scan(options.scan, { exclude });
|
|
158
|
+
}
|
|
159
|
+
if (options.check) {
|
|
160
|
+
const paths = options.check.split(',').map((s) => s.trim());
|
|
161
|
+
paths.forEach((p) => builder.check(p));
|
|
162
|
+
}
|
|
163
|
+
if (options['auto-approve']) {
|
|
164
|
+
builder.autoApprove(true);
|
|
165
|
+
}
|
|
166
|
+
if (options.mask) {
|
|
167
|
+
const selectors = options.mask.split(',').map((s) => s.trim());
|
|
168
|
+
builder.mask(selectors);
|
|
169
|
+
}
|
|
170
|
+
const job = await builder.run();
|
|
171
|
+
console.log(`✅ Job started! ID: ${job.jobId}`);
|
|
172
|
+
console.log(`📊 Project: ${projectId}`);
|
|
173
|
+
console.log(`📱 Matrix: ${devices.join(', ')}`);
|
|
174
|
+
if (options.scan) {
|
|
175
|
+
console.log(`🔍 Scan: ${options.scan} (Exclude: ${options.exclude || 'none'})`);
|
|
176
|
+
}
|
|
177
|
+
console.log(`
|
|
178
|
+
Waiting for completion...
|
|
179
|
+
`);
|
|
180
|
+
const result = await job.waitForCompletion(2000, (status) => {
|
|
181
|
+
const progress = status.progress || { percent: '0' };
|
|
182
|
+
const aiStatusDetail = status.summaryStatus && status.summaryStatus !== 'NONE' ? ` [RegressionBot Summary: ${status.summaryStatus}]` : '';
|
|
183
|
+
process.stdout.write(`\r Status: ${status.status} (${progress.percent}%)${aiStatusDetail}`);
|
|
184
|
+
}, { waitForSummaries: !options['skip-summaries'] });
|
|
185
|
+
console.log('\n\n✅ Job Completed.');
|
|
186
|
+
const summary = await job.getSummary();
|
|
187
|
+
console.log(`Overall Stability Score: ${summary.overallScore}/100`);
|
|
188
|
+
console.log(`Total Tasks: ${summary.totalUrls}`);
|
|
189
|
+
console.log(`Regressions: ${summary.regressionCount}`);
|
|
190
|
+
console.log(`New Baselines: ${summary.newBaselineCount}`);
|
|
191
|
+
console.log(`Errors: ${summary.errorCount}`);
|
|
192
|
+
if (summary.newBaselineCount > 0) {
|
|
193
|
+
console.log('\n✨ New Baselines Created:');
|
|
194
|
+
summary.newBaselines.forEach((nb) => {
|
|
195
|
+
console.log(`- ${nb.url} [${nb.variantName}]`);
|
|
196
|
+
});
|
|
197
|
+
}
|
|
198
|
+
if (summary.regressionCount > 0) {
|
|
199
|
+
console.log('\n❌ Regressions found:');
|
|
200
|
+
summary.regressions.forEach((r) => {
|
|
201
|
+
console.log(`- ${r.url} [${r.variantName}] (Score: ${r.visualMatchScore.toFixed(2)})`);
|
|
202
|
+
console.log(` Diff: ${r.diffUrl}`);
|
|
203
|
+
if (r.regressionbotSummary)
|
|
204
|
+
console.log(` Summary: ${r.regressionbotSummary}`);
|
|
205
|
+
});
|
|
206
|
+
console.log(`\nTo approve these changes, run:\n npx regressionbot approve ${job.jobId}`);
|
|
207
|
+
process.exit(1);
|
|
208
|
+
}
|
|
209
|
+
else if (summary.errorCount > 0) {
|
|
210
|
+
console.log('\n⚠️ Errors encountered:');
|
|
211
|
+
summary.errors.forEach((e) => {
|
|
212
|
+
console.log(`- ${e.url}: ${e.errorMessage}`);
|
|
213
|
+
});
|
|
214
|
+
process.exit(1);
|
|
215
|
+
}
|
|
216
|
+
else {
|
|
217
|
+
console.log('\n✨ No regressions found. All good!');
|
|
218
|
+
}
|
|
219
|
+
}
|
|
220
|
+
async function checkStatus(jobId) {
|
|
221
|
+
const job = sdk.job(jobId);
|
|
222
|
+
const status = await job.getStatus();
|
|
223
|
+
console.log(JSON.stringify(status, null, 2));
|
|
224
|
+
}
|
|
225
|
+
async function showSummary(jobId, options = {}) {
|
|
226
|
+
const job = sdk.job(jobId);
|
|
227
|
+
const summary = await job.getSummary();
|
|
228
|
+
console.log(`
|
|
229
|
+
Job Summary: ${jobId}
|
|
230
|
+
Status: ${summary.status}
|
|
231
|
+
Overall Score: ${summary.overallScore}/100
|
|
232
|
+
Execution Time: ${summary.executionTime}s
|
|
233
|
+
Total Tasks: ${summary.totalUrls}
|
|
234
|
+
Regressions: ${summary.regressionCount}
|
|
235
|
+
Matches: ${summary.matchCount}
|
|
236
|
+
Errors: ${summary.errorCount}
|
|
237
|
+
`);
|
|
238
|
+
if (summary.regressionCount > 0) {
|
|
239
|
+
console.log('❌ Regressions found:');
|
|
240
|
+
for (const r of summary.regressions) {
|
|
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
|
+
}
|
|
246
|
+
}
|
|
247
|
+
const doDownload = options.download || options['download-full'];
|
|
248
|
+
if (doDownload) {
|
|
249
|
+
console.log(`\n💾 Downloading results...`);
|
|
250
|
+
await job.downloadResults({
|
|
251
|
+
full: options['download-full']
|
|
252
|
+
});
|
|
253
|
+
console.log(`✅ Download complete. Saved to: ${path.join(process.cwd(), 'regressions', (0, security_1.sanitizeFilename)(jobId))}`);
|
|
254
|
+
}
|
|
255
|
+
if (summary.errorCount > 0) {
|
|
256
|
+
console.log('\n⚠️ Errors encountered:');
|
|
257
|
+
summary.errors.forEach((e) => {
|
|
258
|
+
console.log(`- ${e.url}: ${e.errorMessage}`);
|
|
259
|
+
});
|
|
260
|
+
}
|
|
261
|
+
}
|
|
262
|
+
async function approveJob(jobId) {
|
|
263
|
+
console.log(`Approving baselines for job: ${jobId}...`);
|
|
264
|
+
const job = sdk.job(jobId);
|
|
265
|
+
const res = await job.approve();
|
|
266
|
+
console.log(`Success! ${res.message}`);
|
|
267
|
+
}
|
|
268
|
+
main();
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
import { VRConfig, Viewport, Viewports, JobStatus, JobSummary, JobProgress, PageResult, ProjectConfig, ProjectPath, ProjectScan, JobAiSummary } from './types';
|
|
2
|
+
import { sanitizeFilename, sanitizeUrlToPath } from './security';
|
|
3
|
+
export { sanitizeFilename, sanitizeUrlToPath, Viewports };
|
|
4
|
+
export type { PageResult, JobProgress, JobStatus, JobSummary, Viewport, VRConfig, ProjectConfig, ProjectPath, ProjectScan, JobAiSummary };
|
|
5
|
+
export declare class RegressionBot {
|
|
6
|
+
private apiKey;
|
|
7
|
+
private apiUrl;
|
|
8
|
+
constructor(apiKey?: string, apiUrl?: string);
|
|
9
|
+
/**
|
|
10
|
+
* Set the candidate URL/Origin to test.
|
|
11
|
+
*/
|
|
12
|
+
test(origin: string): JobBuilder;
|
|
13
|
+
/**
|
|
14
|
+
* Get a handle to an existing job.
|
|
15
|
+
*/
|
|
16
|
+
job(jobId: string): JobHandle;
|
|
17
|
+
/**
|
|
18
|
+
* Get configuration details for a saved project.
|
|
19
|
+
*/
|
|
20
|
+
getProject(projectName: string): Promise<ProjectConfig>;
|
|
21
|
+
/**
|
|
22
|
+
* List all saved projects for the authenticated organization.
|
|
23
|
+
*/
|
|
24
|
+
listProjects(): Promise<ProjectConfig[]>;
|
|
25
|
+
/**
|
|
26
|
+
* Trigger a new job run using a saved project configuration.
|
|
27
|
+
*/
|
|
28
|
+
runProject(projectName: string, options?: {
|
|
29
|
+
testOrigin?: string;
|
|
30
|
+
url?: string;
|
|
31
|
+
sitemapUrl?: string;
|
|
32
|
+
baseOrigin?: string;
|
|
33
|
+
devices?: string[];
|
|
34
|
+
paths?: Array<{
|
|
35
|
+
path: string;
|
|
36
|
+
label?: string;
|
|
37
|
+
}>;
|
|
38
|
+
scans?: Array<{
|
|
39
|
+
pattern: string;
|
|
40
|
+
options?: any;
|
|
41
|
+
}>;
|
|
42
|
+
masks?: string[];
|
|
43
|
+
concurrency?: number;
|
|
44
|
+
autoApprove?: boolean;
|
|
45
|
+
}): Promise<JobHandle>;
|
|
46
|
+
_request<T>(path: string, method?: string, body?: any): Promise<T>;
|
|
47
|
+
}
|
|
48
|
+
export declare class JobBuilder {
|
|
49
|
+
private sdk;
|
|
50
|
+
private manifest;
|
|
51
|
+
constructor(sdk: RegressionBot, testOrigin: string);
|
|
52
|
+
against(origin: string): this;
|
|
53
|
+
sitemap(url: string): this;
|
|
54
|
+
forProject(id: string): this;
|
|
55
|
+
/**
|
|
56
|
+
* Define the matrix: list of Playwright devices or viewport names.
|
|
57
|
+
*/
|
|
58
|
+
on(variants: string[]): this;
|
|
59
|
+
/**
|
|
60
|
+
* Add a specific page to the test scope.
|
|
61
|
+
*/
|
|
62
|
+
check(path: string, label?: string): this;
|
|
63
|
+
/**
|
|
64
|
+
* Add a discovery rule to scan the sitemap.
|
|
65
|
+
*/
|
|
66
|
+
scan(pattern: string, options?: {
|
|
67
|
+
limit?: number;
|
|
68
|
+
exclude?: string[];
|
|
69
|
+
}): this;
|
|
70
|
+
concurrency(n: number): this;
|
|
71
|
+
autoApprove(val?: boolean): this;
|
|
72
|
+
mask(selectors: string[]): this;
|
|
73
|
+
/**
|
|
74
|
+
* Compiles the manifest and triggers the API.
|
|
75
|
+
*/
|
|
76
|
+
run(): Promise<JobHandle>;
|
|
77
|
+
}
|
|
78
|
+
export declare class JobHandle {
|
|
79
|
+
private sdk;
|
|
80
|
+
jobId: string;
|
|
81
|
+
constructor(sdk: RegressionBot, jobId: string);
|
|
82
|
+
getStatus(): Promise<JobStatus>;
|
|
83
|
+
getSummary(): Promise<JobSummary>;
|
|
84
|
+
approve(): Promise<{
|
|
85
|
+
message: string;
|
|
86
|
+
jobId: string;
|
|
87
|
+
approvedUrlsCount: number;
|
|
88
|
+
failedCount?: number;
|
|
89
|
+
}>;
|
|
90
|
+
/**
|
|
91
|
+
* Generate AI summaries on-demand for all regressions in a completed job.
|
|
92
|
+
*/
|
|
93
|
+
generateAiSummary(): Promise<JobAiSummary>;
|
|
94
|
+
/**
|
|
95
|
+
* Download images for the job locally.
|
|
96
|
+
* @param options Download options.
|
|
97
|
+
*/
|
|
98
|
+
downloadResults(options?: {
|
|
99
|
+
full?: boolean;
|
|
100
|
+
baseDir?: string;
|
|
101
|
+
}): Promise<void>;
|
|
102
|
+
/**
|
|
103
|
+
* Poll until the job reaches a terminal state (COMPLETED, APPROVED, or FAILED).
|
|
104
|
+
* @param intervalMs Polling interval in milliseconds. Defaults to 2000.
|
|
105
|
+
* @param callback Optional callback invoked on each status poll.
|
|
106
|
+
* @param options.waitForSummaries If true, keeps polling until AI summaries are fully populated before returning.
|
|
107
|
+
*/
|
|
108
|
+
waitForCompletion(intervalMs?: number, callback?: (status: JobStatus) => void, options?: {
|
|
109
|
+
waitForSummaries?: boolean;
|
|
110
|
+
}): Promise<JobStatus>;
|
|
111
|
+
}
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,270 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.JobHandle = exports.JobBuilder = exports.RegressionBot = exports.Viewports = exports.sanitizeUrlToPath = exports.sanitizeFilename = void 0;
|
|
4
|
+
const types_1 = require("./types");
|
|
5
|
+
Object.defineProperty(exports, "Viewports", { enumerable: true, get: function () { return types_1.Viewports; } });
|
|
6
|
+
const security_1 = require("./security");
|
|
7
|
+
Object.defineProperty(exports, "sanitizeFilename", { enumerable: true, get: function () { return security_1.sanitizeFilename; } });
|
|
8
|
+
Object.defineProperty(exports, "sanitizeUrlToPath", { enumerable: true, get: function () { return security_1.sanitizeUrlToPath; } });
|
|
9
|
+
class RegressionBot {
|
|
10
|
+
apiKey;
|
|
11
|
+
apiUrl;
|
|
12
|
+
constructor(apiKey, apiUrl) {
|
|
13
|
+
this.apiKey = apiKey || process.env.REGRESSIONBOT_API_KEY || "";
|
|
14
|
+
this.apiUrl = apiUrl || process.env.REGRESSIONBOT_API_URL || "https://api.regressionbot.com";
|
|
15
|
+
if (!this.apiKey) {
|
|
16
|
+
console.warn("Warning: No API Key provided. Set REGRESSIONBOT_API_KEY environment variable or pass it to the constructor.");
|
|
17
|
+
}
|
|
18
|
+
if (this.apiUrl.endsWith('/')) {
|
|
19
|
+
this.apiUrl = this.apiUrl.slice(0, -1);
|
|
20
|
+
}
|
|
21
|
+
// 🛡️ SECURITY: Warn about unencrypted data transmission
|
|
22
|
+
(0, security_1.warnIfInsecure)(this.apiUrl);
|
|
23
|
+
(0, security_1.validateProtocol)(this.apiUrl, 'API URL');
|
|
24
|
+
}
|
|
25
|
+
/**
|
|
26
|
+
* Set the candidate URL/Origin to test.
|
|
27
|
+
*/
|
|
28
|
+
test(origin) {
|
|
29
|
+
return new JobBuilder(this, origin);
|
|
30
|
+
}
|
|
31
|
+
/**
|
|
32
|
+
* Get a handle to an existing job.
|
|
33
|
+
*/
|
|
34
|
+
job(jobId) {
|
|
35
|
+
return new JobHandle(this, jobId);
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* Get configuration details for a saved project.
|
|
39
|
+
*/
|
|
40
|
+
async getProject(projectName) {
|
|
41
|
+
return this._request(`/project/${encodeURIComponent(projectName)}`);
|
|
42
|
+
}
|
|
43
|
+
/**
|
|
44
|
+
* List all saved projects for the authenticated organization.
|
|
45
|
+
*/
|
|
46
|
+
async listProjects() {
|
|
47
|
+
return this._request('/projects');
|
|
48
|
+
}
|
|
49
|
+
/**
|
|
50
|
+
* Trigger a new job run using a saved project configuration.
|
|
51
|
+
*/
|
|
52
|
+
async runProject(projectName, options = {}) {
|
|
53
|
+
const res = await this._request(`/project/${encodeURIComponent(projectName)}/run`, 'POST', options);
|
|
54
|
+
return new JobHandle(this, res.jobId);
|
|
55
|
+
}
|
|
56
|
+
// Internal fetch wrapper
|
|
57
|
+
async _request(path, method = 'GET', body) {
|
|
58
|
+
const headers = {
|
|
59
|
+
'Content-Type': 'application/json',
|
|
60
|
+
'Authorization': `Bearer ${this.apiKey}`,
|
|
61
|
+
'x-api-key': this.apiKey
|
|
62
|
+
};
|
|
63
|
+
const response = await (0, security_1.fetchWithTimeout)(`${this.apiUrl}${path}`, {
|
|
64
|
+
method,
|
|
65
|
+
headers,
|
|
66
|
+
body: body ? JSON.stringify(body) : undefined,
|
|
67
|
+
redirect: 'error'
|
|
68
|
+
});
|
|
69
|
+
if (!response.ok) {
|
|
70
|
+
await (0, security_1.handleApiError)(response, this.apiKey);
|
|
71
|
+
}
|
|
72
|
+
return await response.json();
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
exports.RegressionBot = RegressionBot;
|
|
76
|
+
class JobBuilder {
|
|
77
|
+
sdk;
|
|
78
|
+
manifest;
|
|
79
|
+
constructor(sdk, testOrigin) {
|
|
80
|
+
(0, security_1.validateProtocol)(testOrigin, 'testOrigin');
|
|
81
|
+
this.sdk = sdk;
|
|
82
|
+
this.manifest = {
|
|
83
|
+
testOrigin: testOrigin.replace(/\/$/, ''),
|
|
84
|
+
variants: [],
|
|
85
|
+
checks: [],
|
|
86
|
+
scans: [],
|
|
87
|
+
concurrency: 10
|
|
88
|
+
};
|
|
89
|
+
}
|
|
90
|
+
against(origin) {
|
|
91
|
+
(0, security_1.validateProtocol)(origin, 'baseOrigin');
|
|
92
|
+
this.manifest.baseOrigin = origin.replace(/\/$/, '');
|
|
93
|
+
return this;
|
|
94
|
+
}
|
|
95
|
+
sitemap(url) {
|
|
96
|
+
(0, security_1.validateProtocol)(url, 'sitemapUrl');
|
|
97
|
+
this.manifest.sitemapUrl = url;
|
|
98
|
+
return this;
|
|
99
|
+
}
|
|
100
|
+
forProject(id) {
|
|
101
|
+
this.manifest.projectId = id;
|
|
102
|
+
return this;
|
|
103
|
+
}
|
|
104
|
+
/**
|
|
105
|
+
* Define the matrix: list of Playwright devices or viewport names.
|
|
106
|
+
*/
|
|
107
|
+
on(variants) {
|
|
108
|
+
this.manifest.variants.push(...variants);
|
|
109
|
+
return this;
|
|
110
|
+
}
|
|
111
|
+
/**
|
|
112
|
+
* Add a specific page to the test scope.
|
|
113
|
+
*/
|
|
114
|
+
check(path, label) {
|
|
115
|
+
this.manifest.checks.push({ path, label });
|
|
116
|
+
return this;
|
|
117
|
+
}
|
|
118
|
+
/**
|
|
119
|
+
* Add a discovery rule to scan the sitemap.
|
|
120
|
+
*/
|
|
121
|
+
scan(pattern, options) {
|
|
122
|
+
this.manifest.scans.push({ pattern, options });
|
|
123
|
+
return this;
|
|
124
|
+
}
|
|
125
|
+
concurrency(n) {
|
|
126
|
+
this.manifest.concurrency = n;
|
|
127
|
+
return this;
|
|
128
|
+
}
|
|
129
|
+
autoApprove(val = true) {
|
|
130
|
+
this.manifest.autoApprove = val;
|
|
131
|
+
return this;
|
|
132
|
+
}
|
|
133
|
+
mask(selectors) {
|
|
134
|
+
this.manifest.masks = selectors;
|
|
135
|
+
return this;
|
|
136
|
+
}
|
|
137
|
+
/**
|
|
138
|
+
* Compiles the manifest and triggers the API.
|
|
139
|
+
*/
|
|
140
|
+
async run() {
|
|
141
|
+
if (!this.manifest.projectId && !this.manifest.baseOrigin) {
|
|
142
|
+
throw new Error('Project ID is required. Use .forProject("id") or provide an origin to compare against using .against()');
|
|
143
|
+
}
|
|
144
|
+
// If no checks/scans provided, default to root
|
|
145
|
+
if (this.manifest.checks.length === 0 && this.manifest.scans.length === 0) {
|
|
146
|
+
this.manifest.checks.push({ path: '/', label: 'Home' });
|
|
147
|
+
}
|
|
148
|
+
const payload = {
|
|
149
|
+
project: this.manifest.projectId,
|
|
150
|
+
testOrigin: this.manifest.testOrigin,
|
|
151
|
+
sitemapUrl: this.manifest.sitemapUrl,
|
|
152
|
+
baseOrigin: this.manifest.baseOrigin,
|
|
153
|
+
devices: this.manifest.variants,
|
|
154
|
+
paths: this.manifest.checks,
|
|
155
|
+
scans: this.manifest.scans,
|
|
156
|
+
concurrency: this.manifest.concurrency,
|
|
157
|
+
autoApprove: this.manifest.autoApprove,
|
|
158
|
+
masks: this.manifest.masks
|
|
159
|
+
};
|
|
160
|
+
const res = await this.sdk._request('/crawl', 'POST', payload);
|
|
161
|
+
return new JobHandle(this.sdk, res.jobId);
|
|
162
|
+
}
|
|
163
|
+
}
|
|
164
|
+
exports.JobBuilder = JobBuilder;
|
|
165
|
+
class JobHandle {
|
|
166
|
+
sdk;
|
|
167
|
+
jobId;
|
|
168
|
+
constructor(sdk, jobId) {
|
|
169
|
+
this.sdk = sdk;
|
|
170
|
+
this.jobId = jobId;
|
|
171
|
+
}
|
|
172
|
+
async getStatus() {
|
|
173
|
+
return this.sdk._request(`/job/${encodeURIComponent(this.jobId)}`);
|
|
174
|
+
}
|
|
175
|
+
async getSummary() {
|
|
176
|
+
return this.sdk._request(`/job/${encodeURIComponent(this.jobId)}/summary`);
|
|
177
|
+
}
|
|
178
|
+
async approve() {
|
|
179
|
+
return this.sdk._request('/approve', 'POST', { jobId: this.jobId });
|
|
180
|
+
}
|
|
181
|
+
/**
|
|
182
|
+
* Generate AI summaries on-demand for all regressions in a completed job.
|
|
183
|
+
*/
|
|
184
|
+
async generateAiSummary() {
|
|
185
|
+
return this.sdk._request(`/job/${encodeURIComponent(this.jobId)}/ai-summary`, 'POST');
|
|
186
|
+
}
|
|
187
|
+
/**
|
|
188
|
+
* Download images for the job locally.
|
|
189
|
+
* @param options Download options.
|
|
190
|
+
*/
|
|
191
|
+
async downloadResults(options = {}) {
|
|
192
|
+
const summary = await this.getSummary();
|
|
193
|
+
const fs = require('fs');
|
|
194
|
+
const path = require('path');
|
|
195
|
+
const baseDir = options.baseDir || path.join(process.cwd(), 'regressions');
|
|
196
|
+
const safeJobId = (0, security_1.sanitizeFilename)(this.jobId);
|
|
197
|
+
const jobDir = path.join(baseDir, safeJobId);
|
|
198
|
+
if (!fs.existsSync(jobDir))
|
|
199
|
+
fs.mkdirSync(jobDir, { recursive: true });
|
|
200
|
+
const download = async (url, name) => {
|
|
201
|
+
try {
|
|
202
|
+
// 🛡️ SECURITY: Prevent SSRF and local file reads by enforcing HTTP(S) protocol
|
|
203
|
+
(0, security_1.validateProtocol)(url, 'download URL');
|
|
204
|
+
// 🛡️ SECURITY: Fetch with timeout
|
|
205
|
+
const res = await (0, security_1.fetchWithTimeout)(url);
|
|
206
|
+
if (!res.ok) {
|
|
207
|
+
console.warn(`Warning: Failed to download ${name} from ${url} (Status: ${res.status})`);
|
|
208
|
+
return;
|
|
209
|
+
}
|
|
210
|
+
const buffer = Buffer.from(await res.arrayBuffer());
|
|
211
|
+
const filePath = path.join(jobDir, name);
|
|
212
|
+
fs.writeFileSync(filePath, buffer);
|
|
213
|
+
}
|
|
214
|
+
catch (err) {
|
|
215
|
+
console.warn(`Warning: Failed to download ${name}: ${err.message}`);
|
|
216
|
+
}
|
|
217
|
+
};
|
|
218
|
+
// Regressions
|
|
219
|
+
for (const r of summary.regressions) {
|
|
220
|
+
const nameBase = (0, security_1.sanitizeUrlToPath)(r.url);
|
|
221
|
+
const safeVariant = (0, security_1.sanitizeFilename)(r.variantName);
|
|
222
|
+
if (r.diffUrl)
|
|
223
|
+
await download(r.diffUrl, `${nameBase}_diff_${safeVariant}.png`);
|
|
224
|
+
if (options.full) {
|
|
225
|
+
if (r.baselineUrl)
|
|
226
|
+
await download(r.baselineUrl, `${nameBase}_baseline_${safeVariant}.png`);
|
|
227
|
+
if (r.currentUrl)
|
|
228
|
+
await download(r.currentUrl, `${nameBase}_current_${safeVariant}.png`);
|
|
229
|
+
}
|
|
230
|
+
}
|
|
231
|
+
// Matches (Full only)
|
|
232
|
+
if (options.full && summary.matches) {
|
|
233
|
+
for (const m of summary.matches) {
|
|
234
|
+
const nameBase = (0, security_1.sanitizeUrlToPath)(m.url);
|
|
235
|
+
const safeVariant = (0, security_1.sanitizeFilename)(m.variantName);
|
|
236
|
+
if (m.baselineUrl)
|
|
237
|
+
await download(m.baselineUrl, `${nameBase}_baseline_${safeVariant}.png`);
|
|
238
|
+
if (m.currentUrl)
|
|
239
|
+
await download(m.currentUrl, `${nameBase}_current_${safeVariant}.png`);
|
|
240
|
+
}
|
|
241
|
+
}
|
|
242
|
+
}
|
|
243
|
+
/**
|
|
244
|
+
* Poll until the job reaches a terminal state (COMPLETED, APPROVED, or FAILED).
|
|
245
|
+
* @param intervalMs Polling interval in milliseconds. Defaults to 2000.
|
|
246
|
+
* @param callback Optional callback invoked on each status poll.
|
|
247
|
+
* @param options.waitForSummaries If true, keeps polling until AI summaries are fully populated before returning.
|
|
248
|
+
*/
|
|
249
|
+
async waitForCompletion(intervalMs = 2000, callback, options) {
|
|
250
|
+
while (true) {
|
|
251
|
+
const status = await this.getStatus();
|
|
252
|
+
if (callback)
|
|
253
|
+
callback(status);
|
|
254
|
+
if (status.status === 'COMPLETED' || status.status === 'APPROVED') {
|
|
255
|
+
if (options?.waitForSummaries) {
|
|
256
|
+
if (status.summaryStatus !== 'PENDING' && status.summaryStatus !== 'PROCESSING') {
|
|
257
|
+
return status;
|
|
258
|
+
}
|
|
259
|
+
}
|
|
260
|
+
else {
|
|
261
|
+
return status;
|
|
262
|
+
}
|
|
263
|
+
}
|
|
264
|
+
if (status.status === 'FAILED')
|
|
265
|
+
throw new Error(`Job Failed: ${status.error}`);
|
|
266
|
+
await new Promise(resolve => setTimeout(resolve, intervalMs));
|
|
267
|
+
}
|
|
268
|
+
}
|
|
269
|
+
}
|
|
270
|
+
exports.JobHandle = JobHandle;
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 🛡️ Security Utilities
|
|
3
|
+
* Centralized logic for sanitization, protocol validation, and secure network requests.
|
|
4
|
+
*/
|
|
5
|
+
/**
|
|
6
|
+
* Sanitizes a string for use as a filename or directory segment.
|
|
7
|
+
* Replaces any character not in [a-zA-Z0-9_] with an underscore.
|
|
8
|
+
*/
|
|
9
|
+
export declare function sanitizeFilename(name: string): string;
|
|
10
|
+
/**
|
|
11
|
+
* Converts a URL into a clean, flat string representing its path.
|
|
12
|
+
* e.g. https://example.com/ai/jules-agent -> ai_google_jules_coding_agent_review
|
|
13
|
+
*/
|
|
14
|
+
export declare function sanitizeUrlToPath(urlStr: string): string;
|
|
15
|
+
/**
|
|
16
|
+
* 🛡️ SECURITY: Warn about unencrypted data transmission (HTTP vs HTTPS).
|
|
17
|
+
*/
|
|
18
|
+
export declare function warnIfInsecure(url: string, context?: string): void;
|
|
19
|
+
/**
|
|
20
|
+
* 🛡️ SECURITY: Prevent SSRF and local file reads by enforcing HTTP(S) protocol.
|
|
21
|
+
*/
|
|
22
|
+
export declare function validateProtocol(url: string, context?: string): void;
|
|
23
|
+
/**
|
|
24
|
+
* 🛡️ SECURITY: Redact sensitive info and limit length of error messages.
|
|
25
|
+
*/
|
|
26
|
+
export declare function handleApiError(response: Response, apiKey?: string): Promise<never>;
|
|
27
|
+
/**
|
|
28
|
+
* 🛡️ SECURITY: Fetch with a mandatory timeout and forced redirect: 'error' for safety.
|
|
29
|
+
*/
|
|
30
|
+
export declare function fetchWithTimeout(url: string, options?: RequestInit, timeoutMs?: number): Promise<Response>;
|
package/dist/security.js
ADDED
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* 🛡️ Security Utilities
|
|
4
|
+
* Centralized logic for sanitization, protocol validation, and secure network requests.
|
|
5
|
+
*/
|
|
6
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
7
|
+
exports.sanitizeFilename = sanitizeFilename;
|
|
8
|
+
exports.sanitizeUrlToPath = sanitizeUrlToPath;
|
|
9
|
+
exports.warnIfInsecure = warnIfInsecure;
|
|
10
|
+
exports.validateProtocol = validateProtocol;
|
|
11
|
+
exports.handleApiError = handleApiError;
|
|
12
|
+
exports.fetchWithTimeout = fetchWithTimeout;
|
|
13
|
+
/**
|
|
14
|
+
* Sanitizes a string for use as a filename or directory segment.
|
|
15
|
+
* Replaces any character not in [a-zA-Z0-9_] with an underscore.
|
|
16
|
+
*/
|
|
17
|
+
function sanitizeFilename(name) {
|
|
18
|
+
if (!name)
|
|
19
|
+
return 'unknown';
|
|
20
|
+
// Allow alphanumeric and underscore. Replace everything else with underscore.
|
|
21
|
+
return name.replace(/[^a-zA-Z0-9_]/g, '_');
|
|
22
|
+
}
|
|
23
|
+
/**
|
|
24
|
+
* Converts a URL into a clean, flat string representing its path.
|
|
25
|
+
* e.g. https://example.com/ai/jules-agent -> ai_google_jules_coding_agent_review
|
|
26
|
+
*/
|
|
27
|
+
function sanitizeUrlToPath(urlStr) {
|
|
28
|
+
try {
|
|
29
|
+
const url = new URL(urlStr);
|
|
30
|
+
let path = url.pathname;
|
|
31
|
+
try {
|
|
32
|
+
path = decodeURIComponent(path);
|
|
33
|
+
}
|
|
34
|
+
catch (e) {
|
|
35
|
+
// Ignore malformed URIs
|
|
36
|
+
}
|
|
37
|
+
if (path === '/')
|
|
38
|
+
return 'root';
|
|
39
|
+
// 🛡️ SECURITY: Sanitize to prevent path traversal via URL pathname (e.g. data:../..)
|
|
40
|
+
// Remove leading/trailing slashes and replace all non-alphanumeric chars with underscores
|
|
41
|
+
return path.replace(/^\/|\/$/g, '').replace(/[^a-zA-Z0-9_]/g, '_');
|
|
42
|
+
}
|
|
43
|
+
catch (e) {
|
|
44
|
+
return sanitizeFilename(urlStr);
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
/**
|
|
48
|
+
* 🛡️ SECURITY: Warn about unencrypted data transmission (HTTP vs HTTPS).
|
|
49
|
+
*/
|
|
50
|
+
function warnIfInsecure(url, context = 'API URL') {
|
|
51
|
+
const lowerUrl = url.toLowerCase();
|
|
52
|
+
if (lowerUrl.startsWith('http://')) {
|
|
53
|
+
try {
|
|
54
|
+
const parsedUrl = new URL(url);
|
|
55
|
+
if (parsedUrl.hostname !== 'localhost' && parsedUrl.hostname !== '127.0.0.1') {
|
|
56
|
+
console.warn(`Security Warning: ${context} is using HTTP (${url}). It is highly recommended to use HTTPS to prevent exposing sensitive data.`);
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
catch (e) {
|
|
60
|
+
// Ignore parsing errors for warning
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
else if (!lowerUrl.startsWith('https://')) {
|
|
64
|
+
console.warn(`Security Warning: ${context} is using an unrecognized protocol (${url}). It is highly recommended to use HTTPS.`);
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
/**
|
|
68
|
+
* 🛡️ SECURITY: Prevent SSRF and local file reads by enforcing HTTP(S) protocol.
|
|
69
|
+
*/
|
|
70
|
+
function validateProtocol(url, context = 'URL') {
|
|
71
|
+
let parsed;
|
|
72
|
+
try {
|
|
73
|
+
parsed = new URL(url);
|
|
74
|
+
}
|
|
75
|
+
catch (e) {
|
|
76
|
+
throw new Error(`Invalid ${context}: ${url}`);
|
|
77
|
+
}
|
|
78
|
+
if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
|
|
79
|
+
throw new Error(`Security Error: ${context} must use HTTP or HTTPS. Provided: ${parsed.protocol}`);
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
/**
|
|
83
|
+
* 🛡️ SECURITY: Redact sensitive info and limit length of error messages.
|
|
84
|
+
*/
|
|
85
|
+
async function handleApiError(response, apiKey) {
|
|
86
|
+
let errorText = await response.text();
|
|
87
|
+
// 🛡️ SECURITY: Redact API key to prevent exposure in CI logs
|
|
88
|
+
if (apiKey && errorText.includes(apiKey)) {
|
|
89
|
+
errorText = errorText.split(apiKey).join('***REDACTED***');
|
|
90
|
+
}
|
|
91
|
+
// 🛡️ SECURITY: Limit error text length to prevent log flooding (DoS)
|
|
92
|
+
if (errorText.length > 500) {
|
|
93
|
+
errorText = errorText.substring(0, 500) + '...';
|
|
94
|
+
}
|
|
95
|
+
throw new Error(`API Error ${response.status}: ${errorText}`);
|
|
96
|
+
}
|
|
97
|
+
/**
|
|
98
|
+
* 🛡️ SECURITY: Fetch with a mandatory timeout and forced redirect: 'error' for safety.
|
|
99
|
+
*/
|
|
100
|
+
async function fetchWithTimeout(url, options = {}, timeoutMs = 10000) {
|
|
101
|
+
const timeoutSignal = AbortSignal.timeout(timeoutMs);
|
|
102
|
+
const combinedSignal = options.signal
|
|
103
|
+
? AbortSignal.any([options.signal, timeoutSignal])
|
|
104
|
+
: timeoutSignal;
|
|
105
|
+
const response = await fetch(url, {
|
|
106
|
+
...options,
|
|
107
|
+
signal: combinedSignal,
|
|
108
|
+
// 🛡️ SECURITY: Prevent cross-origin credential leakage via redirects
|
|
109
|
+
redirect: options.redirect || 'error'
|
|
110
|
+
});
|
|
111
|
+
response._signal = combinedSignal;
|
|
112
|
+
return response;
|
|
113
|
+
}
|
package/dist/types.d.ts
ADDED
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
export interface ProjectPath {
|
|
2
|
+
path: string;
|
|
3
|
+
label?: string;
|
|
4
|
+
}
|
|
5
|
+
export interface ProjectScan {
|
|
6
|
+
pattern: string;
|
|
7
|
+
options?: {
|
|
8
|
+
limit?: number;
|
|
9
|
+
exclude?: string[];
|
|
10
|
+
};
|
|
11
|
+
}
|
|
12
|
+
export interface ProjectConfig {
|
|
13
|
+
orgId?: string;
|
|
14
|
+
name: string;
|
|
15
|
+
testOrigin?: string;
|
|
16
|
+
baseOrigin?: string;
|
|
17
|
+
sitemapUrl?: string;
|
|
18
|
+
paths?: ProjectPath[];
|
|
19
|
+
scans?: ProjectScan[];
|
|
20
|
+
devices?: string[];
|
|
21
|
+
masks?: string[];
|
|
22
|
+
concurrency?: number;
|
|
23
|
+
createdAt?: string;
|
|
24
|
+
updatedAt?: string;
|
|
25
|
+
lastRunAt?: string;
|
|
26
|
+
lastJobId?: string;
|
|
27
|
+
baselineInvalidatedAt?: string;
|
|
28
|
+
}
|
|
29
|
+
export interface VRConfig {
|
|
30
|
+
apiKey?: string;
|
|
31
|
+
apiUrl?: string;
|
|
32
|
+
}
|
|
33
|
+
export interface Viewport {
|
|
34
|
+
width: number;
|
|
35
|
+
height: number;
|
|
36
|
+
}
|
|
37
|
+
export declare const Viewports: {
|
|
38
|
+
readonly DESKTOP: {
|
|
39
|
+
readonly width: 1920;
|
|
40
|
+
readonly height: 1080;
|
|
41
|
+
};
|
|
42
|
+
readonly LAPTOP: {
|
|
43
|
+
readonly width: 1366;
|
|
44
|
+
readonly height: 768;
|
|
45
|
+
};
|
|
46
|
+
readonly TABLET: {
|
|
47
|
+
readonly width: 768;
|
|
48
|
+
readonly height: 1024;
|
|
49
|
+
};
|
|
50
|
+
readonly MOBILE: {
|
|
51
|
+
readonly width: 375;
|
|
52
|
+
readonly height: 667;
|
|
53
|
+
};
|
|
54
|
+
};
|
|
55
|
+
/**
|
|
56
|
+
* Result for a single URL + device comparison.
|
|
57
|
+
*
|
|
58
|
+
* Returned by both getStatus() and getSummary(). Pre-signed image URLs
|
|
59
|
+
* (baselineUrl, currentUrl, diffUrl) are only populated by getSummary() —
|
|
60
|
+
* they are absent when reading results from getStatus().
|
|
61
|
+
*/
|
|
62
|
+
export interface PageResult {
|
|
63
|
+
url: string;
|
|
64
|
+
/** Device variant tested (e.g. "desktop_chrome", "iphone_12"). */
|
|
65
|
+
variantName: string;
|
|
66
|
+
/** Percentage of pixels that differed from the baseline (0 = identical). */
|
|
67
|
+
diffPercentage: number;
|
|
68
|
+
/** Raw count of differing pixels. */
|
|
69
|
+
diffCount: number;
|
|
70
|
+
/** Perceptual similarity 0-100 (SSIM). */
|
|
71
|
+
visualMatchScore: number;
|
|
72
|
+
/** Plain-English description of what visually changed, generated by RegressionBot. */
|
|
73
|
+
regressionbotSummary?: string;
|
|
74
|
+
/** Pre-signed URL for the stored baseline screenshot. */
|
|
75
|
+
baselineUrl?: string;
|
|
76
|
+
/** Pre-signed URL for the newly captured screenshot. */
|
|
77
|
+
currentUrl?: string;
|
|
78
|
+
/** Pre-signed URL for the side-by-side annotated diff image. */
|
|
79
|
+
diffUrl?: string;
|
|
80
|
+
}
|
|
81
|
+
export interface JobProgress {
|
|
82
|
+
total: number;
|
|
83
|
+
completed: number;
|
|
84
|
+
percent: string;
|
|
85
|
+
}
|
|
86
|
+
export interface JobStatus {
|
|
87
|
+
jobId: string;
|
|
88
|
+
status: 'INITIALIZING' | 'PROCESSING' | 'FINISHING' | 'SUMMARIZING' | 'COMPLETED' | 'APPROVED' | 'FAILED';
|
|
89
|
+
summaryStatus?: 'PENDING' | 'PROCESSING' | 'COMPLETE' | 'NONE';
|
|
90
|
+
error?: string;
|
|
91
|
+
progress?: JobProgress;
|
|
92
|
+
executionTime?: number;
|
|
93
|
+
createdAt?: string;
|
|
94
|
+
/** Partial or complete results. Present once workers start completing. Pre-signed image URLs are not included — call getSummary() for those. */
|
|
95
|
+
results?: PageResult[];
|
|
96
|
+
}
|
|
97
|
+
export interface JobSummary {
|
|
98
|
+
jobId: string;
|
|
99
|
+
status: string;
|
|
100
|
+
summaryStatus?: 'PENDING' | 'PROCESSING' | 'COMPLETE' | 'NONE';
|
|
101
|
+
error?: string | null;
|
|
102
|
+
totalUrls: number;
|
|
103
|
+
completedCount: number;
|
|
104
|
+
/** Overall quality score 0–100 across all tested pages. */
|
|
105
|
+
overallScore: number;
|
|
106
|
+
executionTime: number;
|
|
107
|
+
regressionCount: number;
|
|
108
|
+
matchCount: number;
|
|
109
|
+
newBaselineCount: number;
|
|
110
|
+
errorCount: number;
|
|
111
|
+
/** Pages where a visual regression was detected. Includes pre-signed image URLs. */
|
|
112
|
+
regressions: PageResult[];
|
|
113
|
+
/** Pages that matched the baseline. Includes pre-signed image URLs. */
|
|
114
|
+
matches: PageResult[];
|
|
115
|
+
/** Pages captured for the first time — no baseline existed to compare against. */
|
|
116
|
+
newBaselines: Array<{
|
|
117
|
+
url: string;
|
|
118
|
+
variantName: string;
|
|
119
|
+
}>;
|
|
120
|
+
/** Pages that failed to capture or compare. */
|
|
121
|
+
errors: Array<{
|
|
122
|
+
url: string;
|
|
123
|
+
variantName: string;
|
|
124
|
+
errorMessage: string;
|
|
125
|
+
}>;
|
|
126
|
+
}
|
|
127
|
+
export interface JobAiSummary {
|
|
128
|
+
message: string;
|
|
129
|
+
jobId: string;
|
|
130
|
+
summaries: Array<{
|
|
131
|
+
url: string;
|
|
132
|
+
variantName: string;
|
|
133
|
+
regressionbotSummary: string;
|
|
134
|
+
}>;
|
|
135
|
+
}
|
package/dist/types.js
ADDED
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.Viewports = void 0;
|
|
4
|
+
exports.Viewports = {
|
|
5
|
+
DESKTOP: { width: 1920, height: 1080 },
|
|
6
|
+
LAPTOP: { width: 1366, height: 768 },
|
|
7
|
+
TABLET: { width: 768, height: 1024 },
|
|
8
|
+
MOBILE: { width: 375, height: 667 }
|
|
9
|
+
};
|
package/package.json
ADDED
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@regressionbot/sdk",
|
|
3
|
+
"version": "1.2.1",
|
|
4
|
+
"description": "The official SDK for regressionbot.com - the simplest way to automate visual regression testing.",
|
|
5
|
+
"homepage": "https://regressionbot.com",
|
|
6
|
+
"repository": {
|
|
7
|
+
"type": "git",
|
|
8
|
+
"url": "git+https://github.com/RegressionBot/regressionbot-sdk.git"
|
|
9
|
+
},
|
|
10
|
+
"bugs": {
|
|
11
|
+
"url": "https://github.com/RegressionBot/regressionbot-sdk/issues"
|
|
12
|
+
},
|
|
13
|
+
"main": "dist/index.js",
|
|
14
|
+
"types": "dist/index.d.ts",
|
|
15
|
+
"bin": {
|
|
16
|
+
"regressionbot": "dist/cli.js"
|
|
17
|
+
},
|
|
18
|
+
"files": [
|
|
19
|
+
"dist"
|
|
20
|
+
],
|
|
21
|
+
"scripts": {
|
|
22
|
+
"build": "tsc",
|
|
23
|
+
"dev": "tsc -w",
|
|
24
|
+
"test": "node tests/test_adhoc_url.js && node tests/test_sanitization.js && node tests/test_api_integration.js && node tests/test_sdk_unit.js",
|
|
25
|
+
"prepublishOnly": "npm run build"
|
|
26
|
+
},
|
|
27
|
+
"keywords": [
|
|
28
|
+
"visual-regression",
|
|
29
|
+
"testing",
|
|
30
|
+
"sdk",
|
|
31
|
+
"cli"
|
|
32
|
+
],
|
|
33
|
+
"author": "RegressionBot (https://regressionbot.com)",
|
|
34
|
+
"license": "ISC",
|
|
35
|
+
"publishConfig": {
|
|
36
|
+
"access": "public"
|
|
37
|
+
},
|
|
38
|
+
"engines": {
|
|
39
|
+
"node": ">=18.0.0"
|
|
40
|
+
},
|
|
41
|
+
"devDependencies": {
|
|
42
|
+
"@types/node": "^20.0.0",
|
|
43
|
+
"typescript": "^5.0.0"
|
|
44
|
+
}
|
|
45
|
+
}
|