@storysnap/cli 1.2.0 → 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 CHANGED
@@ -116,6 +116,7 @@ Options:
116
116
  -x, --exclude <pattern> Skip stories matching a pattern (repeatable)
117
117
  --changed [ref] Only stories changed since branching off ref (default: main)
118
118
  -b, --browser <browsers> Browsers to test (chromium,firefox,webkit)
119
+ --concurrency <n> Stories to capture at once (default: 4)
119
120
  --ci CI mode - fail on any visual diff or new story
120
121
  --local Force local-only mode without using the API
121
122
  -v, --verbose Verbose output
@@ -134,6 +135,7 @@ Options:
134
135
  -x, --exclude <pattern> Skip stories matching a pattern (repeatable)
135
136
  --changed [ref] Only stories changed since branching off ref (default: main)
136
137
  -b, --browser <browsers> Browsers to test (chromium,firefox,webkit)
138
+ --concurrency <n> Stories to capture at once (default: 4)
137
139
  --dry-run Show what would be updated without making changes
138
140
  --local Force local-only mode without using the API
139
141
  -v, --verbose Verbose output
@@ -3,6 +3,7 @@ export interface TestOptions extends StorySelectionOptions {
3
3
  config?: string;
4
4
  browser?: string;
5
5
  storybookUrl?: string;
6
+ concurrency?: number;
6
7
  branch?: string;
7
8
  commit?: string;
8
9
  ci?: boolean;
@@ -1,6 +1,7 @@
1
1
  import { loadConfig } from '../../config/loader.js';
2
2
  import { loadCredentials } from '../../config/credentials.js';
3
3
  import { captureScreenshots, getScreenshotKey, parseScreenshotKey } from '../../core/screenshot.js';
4
+ import { mapWithConcurrency } from '../../core/concurrency.js';
4
5
  import { compareAllScreenshots, DEFAULT_MAX_DIFF_PERCENT } from '../../core/compare.js';
5
6
  import { createStorage } from '../../storage/index.js';
6
7
  import { createReporter } from '../reporter.js';
@@ -39,6 +40,9 @@ export async function testCommand(options = {}) {
39
40
  config.storybookUrl = options.storybookUrl;
40
41
  config.storybookStaticDir = undefined;
41
42
  }
43
+ if (options.concurrency) {
44
+ config.concurrency = options.concurrency;
45
+ }
42
46
  reporter.succeedSpinner('Configuration loaded');
43
47
  // Determine if we should use API mode
44
48
  const credentials = await loadCredentials();
@@ -111,7 +115,7 @@ async function runApiMode(reporter, config, apiUrl, apiToken, options) {
111
115
  });
112
116
  reporter.succeedSpinner('Tests complete');
113
117
  // Report results
114
- reportApiResults(reporter, completedTestRun, options);
118
+ reportApiResults(reporter, completedTestRun, options, totalTests - uploaded);
115
119
  }
116
120
  /**
117
121
  * Registers each captured screenshot with the API and PUTs the PNG to the
@@ -121,32 +125,33 @@ async function uploadScreenshots(client, testRunId, config, stories, screenshots
121
125
  const total = stories.length * config.browsers.length;
122
126
  let uploaded = 0;
123
127
  let attempted = 0;
124
- for (const story of stories) {
125
- for (const browser of config.browsers) {
128
+ // Two requests per story, so they share the capture concurrency.
129
+ const tasks = stories.flatMap((story) => config.browsers.map((browser) => ({ story, browser })));
130
+ await mapWithConcurrency(tasks, config.concurrency, async ({ story, browser }) => {
131
+ const screenshot = screenshots.get(getScreenshotKey(story.id, browser));
132
+ if (!screenshot || screenshot.buffer.length === 0) {
133
+ reporter.warning(`Failed to capture ${story.id} (${browser}): ${screenshot?.error ?? 'no screenshot'}`);
126
134
  attempted++;
127
- const screenshot = screenshots.get(getScreenshotKey(story.id, browser));
128
- if (!screenshot || screenshot.buffer.length === 0) {
129
- reporter.progress(attempted, total, `${story.title}/${story.name} (${browser}) - capture failed`);
130
- continue;
131
- }
132
- reporter.progress(attempted, total, `${story.title}/${story.name} (${browser})`);
133
- try {
134
- const target = await client.createResult(testRunId, {
135
- storyId: story.id,
136
- storyTitle: story.title,
137
- storyName: story.name,
138
- browser,
139
- viewportWidth: config.viewport.width,
140
- viewportHeight: config.viewport.height,
141
- });
142
- await client.uploadImage(target.uploadUrl, screenshot.buffer);
143
- uploaded++;
144
- }
145
- catch (error) {
146
- reporter.warning(`Failed to upload ${story.id} (${browser}): ${error instanceof Error ? error.message : 'Unknown error'}`);
147
- }
135
+ return;
148
136
  }
149
- }
137
+ try {
138
+ const target = await client.createResult(testRunId, {
139
+ storyId: story.id,
140
+ storyTitle: story.title,
141
+ storyName: story.name,
142
+ browser,
143
+ viewportWidth: config.viewport.width,
144
+ viewportHeight: config.viewport.height,
145
+ });
146
+ await client.uploadImage(target.uploadUrl, screenshot.buffer);
147
+ uploaded++;
148
+ }
149
+ catch (error) {
150
+ reporter.warning(`Failed to upload ${story.id} (${browser}): ${error instanceof Error ? error.message : 'Unknown error'}`);
151
+ }
152
+ attempted++;
153
+ reporter.progress(attempted, total, `${story.title}/${story.name} (${browser})`);
154
+ });
150
155
  return uploaded;
151
156
  }
152
157
  async function runLocalMode(reporter, config, options) {
@@ -162,7 +167,6 @@ async function runLocalMode(reporter, config, options) {
162
167
  if (!stories) {
163
168
  return;
164
169
  }
165
- const totalTests = stories.length * config.browsers.length;
166
170
  // Capture screenshots
167
171
  reporter.startSpinner('Capturing screenshots...');
168
172
  const screenshots = await captureScreenshots(config, stories, (completed, total, story, browser) => {
@@ -176,6 +180,7 @@ async function runLocalMode(reporter, config, options) {
176
180
  maxDiffPercent: config.maxDiffPercent,
177
181
  storage,
178
182
  localSnapshotsDir: config.localSnapshotsDir,
183
+ concurrency: config.concurrency,
179
184
  }, (completed, total, key) => {
180
185
  const { storyId, browser } = parseScreenshotKey(key);
181
186
  reporter.progress(completed, total, `${storyId} (${browser})`);
@@ -228,7 +233,7 @@ function reportLocalResult(story, comparison) {
228
233
  break;
229
234
  }
230
235
  }
231
- function reportApiResults(reporter, testRun, options) {
236
+ function reportApiResults(reporter, testRun, options, missing) {
232
237
  reporter.header('Results');
233
238
  for (const result of testRun.results) {
234
239
  const storyName = result.storyName || result.storyId;
@@ -287,12 +292,17 @@ function reportApiResults(reporter, testRun, options) {
287
292
  if (testRun.status === 'failed') {
288
293
  console.log('\x1b[31mVisual regression tests failed.\x1b[0m', '\x1b[2mReview changes in the dashboard or run "storysnap update" to update baselines.\x1b[0m');
289
294
  }
295
+ else if (missing > 0) {
296
+ console.log(`\x1b[31m${missing} screenshot(s) were not captured or uploaded.\x1b[0m`, '\x1b[2mSee the warnings above.\x1b[0m');
297
+ }
290
298
  else {
291
299
  console.log('\x1b[32mAll visual regression tests passed!\x1b[0m');
292
300
  }
293
301
  // Same rule as local mode: a failure is a failure regardless of --ci. See the
294
- // note there for why this is not gated on the flag.
295
- if (testRun.failedStories > 0 || testRun.errorStories > 0) {
302
+ // note there for why this is not gated on the flag. Stories that never
303
+ // reached the server are absent from the run rather than failed in it, so
304
+ // the server's verdict alone would pass them.
305
+ if (testRun.failedStories > 0 || testRun.errorStories > 0 || missing > 0) {
296
306
  process.exit(1);
297
307
  }
298
308
  if (options.ci && testRun.newStories > 0) {
@@ -3,6 +3,7 @@ export interface UpdateOptions extends StorySelectionOptions {
3
3
  config?: string;
4
4
  browser?: string;
5
5
  storybookUrl?: string;
6
+ concurrency?: number;
6
7
  verbose?: boolean;
7
8
  dryRun?: boolean;
8
9
  local?: boolean;
@@ -2,6 +2,7 @@ import { loadConfig } from '../../config/loader.js';
2
2
  import { loadCredentials } from '../../config/credentials.js';
3
3
  import { getStoryKey } from '../../core/storybook.js';
4
4
  import { captureScreenshots, getScreenshotKey } from '../../core/screenshot.js';
5
+ import { mapWithConcurrency } from '../../core/concurrency.js';
5
6
  import { createStorage } from '../../storage/index.js';
6
7
  import { createReporter } from '../reporter.js';
7
8
  import { selectStories } from '../select-stories.js';
@@ -43,6 +44,9 @@ export async function updateCommand(options = {}) {
43
44
  config.storybookUrl = options.storybookUrl;
44
45
  config.storybookStaticDir = undefined;
45
46
  }
47
+ if (options.concurrency) {
48
+ config.concurrency = options.concurrency;
49
+ }
46
50
  reporter.succeedSpinner('Configuration loaded');
47
51
  // Determine if we should use API mode
48
52
  const credentials = await loadCredentials();
@@ -82,63 +86,43 @@ async function runApiMode(reporter, config, apiUrl, apiToken, options) {
82
86
  // Upload baselines via API
83
87
  reporter.startSpinner('Uploading baselines via API...');
84
88
  let uploaded = 0;
85
- let failed = 0;
86
- for (const story of stories) {
87
- for (const browser of config.browsers) {
88
- const screenshotKey = getScreenshotKey(story.id, browser);
89
- const screenshot = screenshots.get(screenshotKey);
90
- if (!screenshot || screenshot.buffer.length === 0) {
91
- reporter.updateSpinner(`Skipping ${story.title}/${story.name} (${browser}) (capture failed)`);
92
- failed++;
93
- continue;
94
- }
95
- reporter.progress(uploaded + failed + 1, totalTests, `${story.title}/${story.name} (${browser})`);
96
- if (!options.dryRun) {
97
- try {
98
- // Get presigned upload URL from API
99
- const uploadInfo = await client.getBaselineUploadUrl(story.id, browser, config.viewport.width, config.viewport.height);
100
- // Upload directly to S3 using presigned URL
101
- await client.uploadBaseline(uploadInfo.url, screenshot.buffer);
102
- // Record the baseline. The upload alone leaves an orphaned object -
103
- // comparisons look the baseline up in the database, not in S3.
104
- await client.registerBaseline({
105
- storyId: story.id,
106
- browser,
107
- viewportWidth: config.viewport.width,
108
- viewportHeight: config.viewport.height,
109
- storageKey: uploadInfo.storageKey,
110
- });
111
- uploaded++;
112
- }
113
- catch (error) {
114
- failed++;
115
- if (options.verbose) {
116
- reporter.error(`Failed to upload ${story.id} (${browser}): ${error instanceof Error ? error.message : 'Unknown error'}`);
117
- }
118
- }
119
- }
120
- else {
89
+ const failures = [];
90
+ // Uploads are network round trips, so they share the capture concurrency.
91
+ const tasks = stories.flatMap((story) => config.browsers.map((browser) => ({ story, browser })));
92
+ await mapWithConcurrency(tasks, config.concurrency, async ({ story, browser }) => {
93
+ const screenshotKey = getScreenshotKey(story.id, browser);
94
+ const screenshot = screenshots.get(screenshotKey);
95
+ if (!screenshot || screenshot.buffer.length === 0) {
96
+ failures.push(`${story.title}/${story.name} (${browser}): capture failed - ${screenshot?.error ?? 'no screenshot'}`);
97
+ return;
98
+ }
99
+ if (!options.dryRun) {
100
+ try {
101
+ // Get presigned upload URL from API
102
+ const uploadInfo = await client.getBaselineUploadUrl(story.id, browser, config.viewport.width, config.viewport.height);
103
+ // Upload directly to S3 using presigned URL
104
+ await client.uploadBaseline(uploadInfo.url, screenshot.buffer);
105
+ // Record the baseline. The upload alone leaves an orphaned object -
106
+ // comparisons look the baseline up in the database, not in S3.
107
+ await client.registerBaseline({
108
+ storyId: story.id,
109
+ browser,
110
+ viewportWidth: config.viewport.width,
111
+ viewportHeight: config.viewport.height,
112
+ storageKey: uploadInfo.storageKey,
113
+ });
121
114
  uploaded++;
122
115
  }
116
+ catch (error) {
117
+ failures.push(`${story.title}/${story.name} (${browser}): upload failed - ${error instanceof Error ? error.message : 'Unknown error'}`);
118
+ }
123
119
  }
124
- }
125
- if (uploaded === totalTests) {
126
- reporter.succeedSpinner('Baselines uploaded');
127
- }
128
- else {
129
- reporter.succeedSpinner(`Baselines uploaded (${failed} failed)`);
130
- }
131
- // Report summary
132
- reporter.reportUpdateSummary(uploaded, totalTests);
133
- if (failed > 0) {
134
- reporter.warning(`${failed} baselines could not be updated`);
135
- }
136
- if (options.dryRun) {
137
- reporter.info('Dry run complete. No changes were made.');
138
- }
139
- else {
140
- reporter.success('Baselines have been updated successfully!');
141
- }
120
+ else {
121
+ uploaded++;
122
+ }
123
+ reporter.progress(uploaded + failures.length, totalTests, `${story.title}/${story.name} (${browser})`);
124
+ });
125
+ finishUpdate(reporter, uploaded, totalTests, failures, options);
142
126
  }
143
127
  async function runLocalMode(reporter, config, options) {
144
128
  if (options.local) {
@@ -163,46 +147,56 @@ async function runLocalMode(reporter, config, options) {
163
147
  // Upload baselines
164
148
  reporter.startSpinner('Uploading baselines...');
165
149
  let uploaded = 0;
166
- let failed = 0;
167
- for (const story of stories) {
168
- for (const browser of config.browsers) {
169
- const screenshotKey = getScreenshotKey(story.id, browser);
170
- const screenshot = screenshots.get(screenshotKey);
171
- if (!screenshot || screenshot.buffer.length === 0) {
172
- reporter.updateSpinner(`Skipping ${story.title}/${story.name} (${browser}) (capture failed)`);
173
- failed++;
174
- continue;
175
- }
176
- // Use browser-aware storage key
177
- const key = getStoryKey(story.id, browser);
178
- reporter.progress(uploaded + failed + 1, totalTests, `${story.title}/${story.name} (${browser})`);
179
- if (!options.dryRun) {
180
- try {
181
- await storage.upload(key, screenshot.buffer);
182
- uploaded++;
183
- }
184
- catch (error) {
185
- failed++;
186
- if (options.verbose) {
187
- reporter.error(`Failed to upload ${key}: ${error instanceof Error ? error.message : 'Unknown error'}`);
188
- }
189
- }
190
- }
191
- else {
150
+ const failures = [];
151
+ // Writes to S3 are network round trips, so they share the capture
152
+ // concurrency; local writes simply finish sooner.
153
+ const tasks = stories.flatMap((story) => config.browsers.map((browser) => ({ story, browser })));
154
+ await mapWithConcurrency(tasks, config.concurrency, async ({ story, browser }) => {
155
+ const screenshotKey = getScreenshotKey(story.id, browser);
156
+ const screenshot = screenshots.get(screenshotKey);
157
+ if (!screenshot || screenshot.buffer.length === 0) {
158
+ failures.push(`${story.title}/${story.name} (${browser}): capture failed - ${screenshot?.error ?? 'no screenshot'}`);
159
+ return;
160
+ }
161
+ // Use browser-aware storage key
162
+ const key = getStoryKey(story.id, browser);
163
+ if (!options.dryRun) {
164
+ try {
165
+ await storage.upload(key, screenshot.buffer);
192
166
  uploaded++;
193
167
  }
168
+ catch (error) {
169
+ failures.push(`${story.title}/${story.name} (${browser}): upload failed - ${error instanceof Error ? error.message : 'Unknown error'}`);
170
+ }
194
171
  }
195
- }
196
- if (uploaded === totalTests) {
172
+ else {
173
+ uploaded++;
174
+ }
175
+ reporter.progress(uploaded + failures.length, totalTests, `${story.title}/${story.name} (${browser})`);
176
+ });
177
+ finishUpdate(reporter, uploaded, totalTests, failures, options);
178
+ }
179
+ /**
180
+ * Reports the outcome and exits non-zero if any baseline was not saved. A run
181
+ * that quietly drops baselines and exits 0 lets a pipeline go green with an
182
+ * incomplete set, which every later test run is then judged against.
183
+ */
184
+ function finishUpdate(reporter, uploaded, totalTests, failures, options) {
185
+ if (failures.length === 0) {
197
186
  reporter.succeedSpinner('Baselines uploaded');
198
187
  }
199
188
  else {
200
- reporter.succeedSpinner(`Baselines uploaded (${failed} failed)`);
189
+ reporter.failSpinner(`Baselines uploaded (${failures.length} failed)`);
201
190
  }
202
- // Report summary
203
191
  reporter.reportUpdateSummary(uploaded, totalTests);
204
- if (failed > 0) {
205
- reporter.warning(`${failed} baselines could not be updated`);
192
+ if (failures.length > 0) {
193
+ reporter.newLine();
194
+ for (const failure of failures) {
195
+ reporter.error(failure);
196
+ }
197
+ reporter.newLine();
198
+ reporter.error(`${failures.length} baseline(s) could not be updated`);
199
+ process.exit(1);
206
200
  }
207
201
  if (options.dryRun) {
208
202
  reporter.info('Dry run complete. No changes were made.');
package/dist/cli/index.js CHANGED
@@ -1,11 +1,18 @@
1
1
  #!/usr/bin/env node
2
- import { Command } from 'commander';
2
+ import { Command, InvalidArgumentError } from 'commander';
3
3
  import { testCommand } from './commands/test.js';
4
4
  import { updateCommand } from './commands/update.js';
5
5
  import { initCommand } from './commands/init.js';
6
6
  import { loginCommand } from './commands/login.js';
7
7
  import { logoutCommand } from './commands/logout.js';
8
8
  import { collectPatterns } from './select-stories.js';
9
+ function parseConcurrency(value) {
10
+ const n = Number(value);
11
+ if (!Number.isInteger(n) || n < 1) {
12
+ throw new InvalidArgumentError('Must be a whole number of at least 1.');
13
+ }
14
+ return n;
15
+ }
9
16
  const program = new Command();
10
17
  program
11
18
  .name('storysnap')
@@ -53,6 +60,7 @@ program
53
60
  .option('--changed [ref]', 'Only stories whose files changed since branching off <ref> (default: main, then origin/main)')
54
61
  .option('-b, --browser <browsers>', 'Browsers to test (chromium,firefox,webkit)')
55
62
  .option('--storybook-url <url>', 'Storybook URL, overriding the config file')
63
+ .option('--concurrency <n>', 'Stories to capture at once (default: 4)', parseConcurrency)
56
64
  .option('--branch <branch>', 'Branch name to record on the test run (API mode)')
57
65
  .option('--commit <sha>', 'Commit SHA to record on the test run (API mode)')
58
66
  .option('--ci', 'CI mode - fail on any visual diff or new story')
@@ -66,6 +74,7 @@ program
66
74
  changed: options.changed,
67
75
  browser: options.browser,
68
76
  storybookUrl: options.storybookUrl,
77
+ concurrency: options.concurrency,
69
78
  branch: options.branch,
70
79
  commit: options.commit,
71
80
  ci: options.ci,
@@ -82,6 +91,7 @@ program
82
91
  .option('--changed [ref]', 'Only stories whose files changed since branching off <ref> (default: main, then origin/main)')
83
92
  .option('-b, --browser <browsers>', 'Browsers to test (chromium,firefox,webkit)')
84
93
  .option('--storybook-url <url>', 'Storybook URL, overriding the config file')
94
+ .option('--concurrency <n>', 'Stories to capture at once (default: 4)', parseConcurrency)
85
95
  .option('-v, --verbose', 'Verbose output')
86
96
  .option('--dry-run', 'Show what would be updated without making changes')
87
97
  .option('--local', 'Force local-only mode without using the API')
@@ -93,6 +103,7 @@ program
93
103
  changed: options.changed,
94
104
  browser: options.browser,
95
105
  storybookUrl: options.storybookUrl,
106
+ concurrency: options.concurrency,
96
107
  verbose: options.verbose,
97
108
  dryRun: options.dryRun,
98
109
  local: options.local,
@@ -56,6 +56,7 @@ export declare const configSchema: z.ZodEffects<z.ZodObject<{
56
56
  exclude: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
57
57
  waitForSelector: z.ZodDefault<z.ZodString>;
58
58
  waitTimeout: z.ZodDefault<z.ZodNumber>;
59
+ concurrency: z.ZodDefault<z.ZodNumber>;
59
60
  apiUrl: z.ZodOptional<z.ZodString>;
60
61
  apiToken: z.ZodOptional<z.ZodString>;
61
62
  }, "strip", z.ZodTypeAny, {
@@ -78,6 +79,7 @@ export declare const configSchema: z.ZodEffects<z.ZodObject<{
78
79
  browsers: ("chromium" | "firefox" | "webkit")[];
79
80
  waitForSelector: string;
80
81
  waitTimeout: number;
82
+ concurrency: number;
81
83
  storybookUrl?: string | undefined;
82
84
  storybookStaticDir?: string | undefined;
83
85
  threshold?: number | undefined;
@@ -114,6 +116,7 @@ export declare const configSchema: z.ZodEffects<z.ZodObject<{
114
116
  exclude?: string[] | undefined;
115
117
  waitForSelector?: string | undefined;
116
118
  waitTimeout?: number | undefined;
119
+ concurrency?: number | undefined;
117
120
  apiUrl?: string | undefined;
118
121
  apiToken?: string | undefined;
119
122
  }>, {
@@ -136,6 +139,7 @@ export declare const configSchema: z.ZodEffects<z.ZodObject<{
136
139
  browsers: ("chromium" | "firefox" | "webkit")[];
137
140
  waitForSelector: string;
138
141
  waitTimeout: number;
142
+ concurrency: number;
139
143
  storybookUrl?: string | undefined;
140
144
  storybookStaticDir?: string | undefined;
141
145
  threshold?: number | undefined;
@@ -172,6 +176,7 @@ export declare const configSchema: z.ZodEffects<z.ZodObject<{
172
176
  exclude?: string[] | undefined;
173
177
  waitForSelector?: string | undefined;
174
178
  waitTimeout?: number | undefined;
179
+ concurrency?: number | undefined;
175
180
  apiUrl?: string | undefined;
176
181
  apiToken?: string | undefined;
177
182
  }>;
@@ -49,6 +49,10 @@ export const configSchema = z.object({
49
49
  exclude: z.array(z.string()).optional(),
50
50
  waitForSelector: z.string().default('#storybook-root'),
51
51
  waitTimeout: z.number().min(0).default(30000),
52
+ // How many stories are captured at once. Each capture mostly waits on the
53
+ // page settling, so a few in parallel cut the run time almost linearly; the
54
+ // ceiling is the machine running the browsers and the Storybook serving them.
55
+ concurrency: z.number().int().min(1).default(4),
52
56
  // API configuration (optional - can also use ~/.storysnap/credentials)
53
57
  apiUrl: z.string().url().optional(),
54
58
  apiToken: z.string().optional(),
@@ -17,6 +17,8 @@ export interface CompareOptions {
17
17
  maxDiffPercent?: number;
18
18
  storage: StorageProvider;
19
19
  localSnapshotsDir?: string;
20
+ /** How many comparisons run at once; each downloads a baseline first. */
21
+ concurrency?: number;
20
22
  }
21
23
  export declare function compareScreenshot(screenshot: Screenshot, options: CompareOptions): Promise<ComparisonResult>;
22
24
  export declare function compareAllScreenshots(screenshots: Map<string, Screenshot>, options: CompareOptions, onProgress?: (completed: number, total: number, key: string) => void): Promise<Map<string, ComparisonResult>>;
@@ -1,6 +1,7 @@
1
1
  import pixelmatch from 'pixelmatch';
2
2
  import { PNG } from 'pngjs';
3
3
  import { getStoryKey } from './storybook.js';
4
+ import { DEFAULT_CONCURRENCY, mapWithConcurrency } from './concurrency.js';
4
5
  import { ensureDir } from '../storage/local.js';
5
6
  import { writeFile } from 'node:fs/promises';
6
7
  import { join } from 'node:path';
@@ -20,22 +21,23 @@ export async function compareScreenshot(screenshot, options) {
20
21
  storyId: screenshot.storyId,
21
22
  browser: screenshot.browser,
22
23
  status: 'error',
23
- errorMessage: 'Failed to capture screenshot',
24
+ errorMessage: screenshot.error ? `Failed to capture screenshot: ${screenshot.error}` : 'Failed to capture screenshot',
24
25
  };
25
26
  }
26
27
  const threshold = options.threshold ?? DEFAULT_THRESHOLD;
27
28
  const maxDiffPercent = options.maxDiffPercent ?? DEFAULT_MAX_DIFF_PERCENT;
28
- // Try to fetch baseline from storage
29
- const baselineBuffer = await options.storage.download(storyKey);
30
- if (!baselineBuffer) {
31
- // No baseline exists - this is a new story
32
- return {
33
- storyId: screenshot.storyId,
34
- browser: screenshot.browser,
35
- status: 'new',
36
- };
37
- }
38
29
  try {
30
+ // Inside the try so a storage failure - an S3 timeout, say - errors this
31
+ // one story rather than rejecting every comparison in the run.
32
+ const baselineBuffer = await options.storage.download(storyKey);
33
+ if (!baselineBuffer) {
34
+ // No baseline exists - this is a new story
35
+ return {
36
+ storyId: screenshot.storyId,
37
+ browser: screenshot.browser,
38
+ status: 'new',
39
+ };
40
+ }
39
41
  // Parse PNG images
40
42
  const currentPng = PNG.sync.read(screenshot.buffer);
41
43
  const baselinePng = PNG.sync.read(baselineBuffer);
@@ -126,14 +128,16 @@ export async function compareAllScreenshots(screenshots, options, onProgress) {
126
128
  const results = new Map();
127
129
  let completed = 0;
128
130
  const total = screenshots.size;
129
- for (const [key, screenshot] of screenshots) {
131
+ // compareScreenshot turns its own failures into 'error' results, as the
132
+ // pool requires. Results are keyed, so finishing out of order is harmless.
133
+ await mapWithConcurrency([...screenshots], options.concurrency ?? DEFAULT_CONCURRENCY, async ([key, screenshot]) => {
130
134
  const result = await compareScreenshot(screenshot, options);
131
135
  results.set(key, result);
132
136
  completed++;
133
137
  if (onProgress) {
134
138
  onProgress(completed, total, key);
135
139
  }
136
- }
140
+ });
137
141
  return results;
138
142
  }
139
143
  //# sourceMappingURL=compare.js.map
@@ -0,0 +1,7 @@
1
+ export declare const DEFAULT_CONCURRENCY = 4;
2
+ /**
3
+ * Runs `fn` over every item with at most `limit` calls in flight, resolving
4
+ * once all have settled. `fn` is expected to handle its own errors.
5
+ */
6
+ export declare function mapWithConcurrency<T>(items: readonly T[], limit: number, fn: (item: T) => Promise<void>): Promise<void>;
7
+ //# sourceMappingURL=concurrency.d.ts.map
@@ -0,0 +1,15 @@
1
+ export const DEFAULT_CONCURRENCY = 4;
2
+ /**
3
+ * Runs `fn` over every item with at most `limit` calls in flight, resolving
4
+ * once all have settled. `fn` is expected to handle its own errors.
5
+ */
6
+ export async function mapWithConcurrency(items, limit, fn) {
7
+ let next = 0;
8
+ const worker = async () => {
9
+ while (next < items.length) {
10
+ await fn(items[next++]);
11
+ }
12
+ };
13
+ await Promise.all(Array.from({ length: Math.min(Math.max(1, limit), items.length) }, worker));
14
+ }
15
+ //# sourceMappingURL=concurrency.js.map
@@ -10,6 +10,11 @@ export declare class ScreenshotEngine {
10
10
  captureStories(stories: Story[], onProgress?: (completed: number, total: number, story: Story, browser: Browser) => void): Promise<Map<string, Screenshot>>;
11
11
  private waitForStability;
12
12
  }
13
+ /**
14
+ * The first line of a capture error. Playwright appends a multi-line call log
15
+ * to its messages, which buries the actual reason when printed per story.
16
+ */
17
+ export declare function describeCaptureError(error: unknown): string;
13
18
  export declare function getScreenshotKey(storyId: string, browser: Browser): string;
14
19
  export declare function parseScreenshotKey(key: string): {
15
20
  storyId: string;
@@ -1,5 +1,6 @@
1
1
  import { chromium, firefox, webkit } from 'playwright';
2
2
  import { getStoryUrl } from './storybook.js';
3
+ import { DEFAULT_CONCURRENCY, mapWithConcurrency } from './concurrency.js';
3
4
  const BROWSER_MAP = {
4
5
  chromium,
5
6
  firefox,
@@ -69,31 +70,34 @@ export class ScreenshotEngine {
69
70
  }
70
71
  async captureStories(stories, onProgress) {
71
72
  const screenshots = new Map();
72
- const totalTests = stories.length * this.config.browsers.length;
73
+ const tasks = stories.flatMap((story) => this.config.browsers.map((browserName) => ({ story, browserName })));
73
74
  let completed = 0;
74
- for (const story of stories) {
75
- for (const browserName of this.config.browsers) {
76
- const screenshotKey = getScreenshotKey(story.id, browserName);
77
- try {
78
- const screenshot = await this.captureStory(story, browserName);
79
- screenshots.set(screenshotKey, screenshot);
80
- }
81
- catch (error) {
82
- // Store error indicator - will be handled by comparison
83
- screenshots.set(screenshotKey, {
84
- storyId: story.id,
85
- browser: browserName,
86
- buffer: Buffer.alloc(0),
87
- width: 0,
88
- height: 0,
89
- });
90
- }
91
- completed++;
92
- if (onProgress) {
93
- onProgress(completed, totalTests, story, browserName);
94
- }
75
+ // Most of a capture is spent waiting - for the network to go idle, for
76
+ // the settle delay - so several pages run at once. Each still gets a fresh
77
+ // page, keeping stories as isolated from one another as before.
78
+ await mapWithConcurrency(tasks, this.config.concurrency ?? DEFAULT_CONCURRENCY, async ({ story, browserName }) => {
79
+ const screenshotKey = getScreenshotKey(story.id, browserName);
80
+ try {
81
+ const screenshot = await this.captureStory(story, browserName);
82
+ screenshots.set(screenshotKey, screenshot);
95
83
  }
96
- }
84
+ catch (error) {
85
+ // An empty buffer marks the failure for the callers; the reason travels
86
+ // with it so they can say why rather than just that it failed.
87
+ screenshots.set(screenshotKey, {
88
+ storyId: story.id,
89
+ browser: browserName,
90
+ buffer: Buffer.alloc(0),
91
+ width: 0,
92
+ height: 0,
93
+ error: describeCaptureError(error),
94
+ });
95
+ }
96
+ completed++;
97
+ if (onProgress) {
98
+ onProgress(completed, tasks.length, story, browserName);
99
+ }
100
+ });
97
101
  return screenshots;
98
102
  }
99
103
  async waitForStability(page) {
@@ -103,6 +107,14 @@ export class ScreenshotEngine {
103
107
  await page.waitForTimeout(200);
104
108
  }
105
109
  }
110
+ /**
111
+ * The first line of a capture error. Playwright appends a multi-line call log
112
+ * to its messages, which buries the actual reason when printed per story.
113
+ */
114
+ export function describeCaptureError(error) {
115
+ const message = error instanceof Error ? error.message : String(error);
116
+ return message.split('\n')[0].trim() || 'Unknown capture error';
117
+ }
106
118
  export function getScreenshotKey(storyId, browser) {
107
119
  return `${storyId}::${browser}`;
108
120
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@storysnap/cli",
3
- "version": "1.2.0",
3
+ "version": "1.2.1",
4
4
  "description": "Visual regression testing for Storybook - capture screenshots, detect changes, and maintain baselines",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",