@storysnap/cli 2.0.0 → 2.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/api/client.d.ts +34 -1
- package/dist/api/client.js +3 -1
- package/dist/cli/commands/test.d.ts +1 -0
- package/dist/cli/commands/test.js +119 -62
- package/dist/cli/commands/update.d.ts +1 -0
- package/dist/cli/commands/update.js +62 -30
- package/dist/cli/environment-warning.d.ts +17 -0
- package/dist/cli/environment-warning.js +42 -0
- package/dist/cli/index.js +11 -3
- package/dist/cli/review.d.ts +9 -0
- package/dist/cli/review.js +10 -0
- package/dist/cli/select-stories.d.ts +6 -1
- package/dist/cli/select-stories.js +16 -0
- package/dist/cli/verdict.d.ts +17 -0
- package/dist/cli/verdict.js +22 -0
- package/dist/config/schema.d.ts +11 -0
- package/dist/config/schema.js +18 -0
- package/dist/core/capture-environment.d.ts +19 -0
- package/dist/core/capture-environment.js +102 -0
- package/dist/core/changed.js +10 -23
- package/dist/core/compare.d.ts +3 -1
- package/dist/core/compare.js +30 -10
- package/dist/core/git-context.d.ts +25 -0
- package/dist/core/git-context.js +75 -0
- package/dist/core/git.d.ts +11 -0
- package/dist/core/git.js +25 -0
- package/dist/core/hash.d.ts +7 -0
- package/dist/core/hash.js +11 -0
- package/dist/core/modes.d.ts +50 -0
- package/dist/core/modes.js +124 -0
- package/dist/core/screenshot.d.ts +91 -4
- package/dist/core/screenshot.js +266 -47
- package/dist/core/story-parameters.d.ts +48 -0
- package/dist/core/story-parameters.js +122 -0
- package/dist/core/story-render.d.ts +31 -0
- package/dist/core/story-render.js +75 -0
- package/dist/core/storybook.d.ts +16 -2
- package/dist/core/storybook.js +18 -6
- package/dist/core/viewports.d.ts +14 -0
- package/dist/core/viewports.js +27 -0
- package/package.json +9 -10
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
import chalk from 'chalk';
|
|
2
|
+
/**
|
|
3
|
+
* Lines warning that baselines were captured somewhere other than this run,
|
|
4
|
+
* one per pair of environments, or none. Different machines render fonts and
|
|
5
|
+
* edges differently, so failures in such a run may be nothing but that.
|
|
6
|
+
* Baselines from before environments were recorded say nothing either way
|
|
7
|
+
* and are left out.
|
|
8
|
+
*/
|
|
9
|
+
export function describeEnvironmentMismatches(results) {
|
|
10
|
+
const pairs = new Map();
|
|
11
|
+
for (const result of results) {
|
|
12
|
+
const { captureEnvironment: current, baselineCaptureEnvironment: baseline } = result;
|
|
13
|
+
if (!current || !baseline || current === baseline) {
|
|
14
|
+
continue;
|
|
15
|
+
}
|
|
16
|
+
const key = `${baseline}\n${current}`;
|
|
17
|
+
const pair = pairs.get(key) ?? { baseline, current, count: 0, failed: 0 };
|
|
18
|
+
pair.count++;
|
|
19
|
+
if (result.status === 'fail')
|
|
20
|
+
pair.failed++;
|
|
21
|
+
pairs.set(key, pair);
|
|
22
|
+
}
|
|
23
|
+
return [...pairs.values()].map(({ baseline, current, count, failed }) => {
|
|
24
|
+
const subject = `${count} ${count === 1 ? 'baseline was' : 'baselines were'} captured with ${baseline}`;
|
|
25
|
+
const failures = failed > 0 ? ` (${failed} of them failed)` : '';
|
|
26
|
+
return `${subject}, this run with ${current}${failures}`;
|
|
27
|
+
});
|
|
28
|
+
}
|
|
29
|
+
/** Prints the warnings, with what to do about them, if there are any. */
|
|
30
|
+
export function reportEnvironmentMismatches(results) {
|
|
31
|
+
const lines = describeEnvironmentMismatches(results);
|
|
32
|
+
if (lines.length === 0) {
|
|
33
|
+
return;
|
|
34
|
+
}
|
|
35
|
+
for (const line of lines) {
|
|
36
|
+
console.log(chalk.yellow(` ⚠ ${line}`));
|
|
37
|
+
}
|
|
38
|
+
console.log(chalk.dim(' Screenshots from different browsers or machines can differ in every glyph. Capture baselines\n' +
|
|
39
|
+
' and runs in the same place - the storysnap-capture image does this - see\n' +
|
|
40
|
+
' https://github.com/Kosai106/storysnap/blob/main/docs/capture-image.md'));
|
|
41
|
+
}
|
|
42
|
+
//# sourceMappingURL=environment-warning.js.map
|
package/dist/cli/index.js
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
|
+
import { createRequire } from 'node:module';
|
|
2
3
|
import { Command, InvalidArgumentError } from 'commander';
|
|
3
4
|
import { testCommand } from './commands/test.js';
|
|
4
5
|
import { updateCommand } from './commands/update.js';
|
|
@@ -13,11 +14,14 @@ function parseConcurrency(value) {
|
|
|
13
14
|
}
|
|
14
15
|
return n;
|
|
15
16
|
}
|
|
17
|
+
// From dist/cli/index.js - and src/cli/index.ts under tests - the package's
|
|
18
|
+
// own package.json is two levels up; release-please keeps its version current.
|
|
19
|
+
const { version } = createRequire(import.meta.url)('../../package.json');
|
|
16
20
|
const program = new Command();
|
|
17
21
|
program
|
|
18
22
|
.name('storysnap')
|
|
19
23
|
.description('Visual regression testing tool for Storybook')
|
|
20
|
-
.version(
|
|
24
|
+
.version(version);
|
|
21
25
|
program
|
|
22
26
|
.command('init')
|
|
23
27
|
.description('Initialize StorySnap configuration')
|
|
@@ -61,8 +65,9 @@ program
|
|
|
61
65
|
.option('-b, --browser <browsers>', 'Browsers to test (chromium,firefox,webkit)')
|
|
62
66
|
.option('--storybook-url <url>', 'Storybook URL, overriding the config file')
|
|
63
67
|
.option('--concurrency <n>', 'Stories to capture at once (default: 4)', parseConcurrency)
|
|
64
|
-
.option('--branch <branch>', 'Branch
|
|
65
|
-
.option('--commit <sha>', 'Commit SHA
|
|
68
|
+
.option('--branch <branch>', 'Branch of the test run (API mode; default: detected from CI or git)')
|
|
69
|
+
.option('--commit <sha>', 'Commit SHA of the test run (API mode; default: detected from CI or git)')
|
|
70
|
+
.option('--base-branch <branch>', 'Branch to compare against where this one has no baseline (API mode; default: the PR/MR target, else the project default branch)')
|
|
66
71
|
.option('--ci', 'CI mode - fail on any visual diff or new story')
|
|
67
72
|
.option('-v, --verbose', 'Verbose output')
|
|
68
73
|
.option('--local', 'Force local-only mode without using the API')
|
|
@@ -77,6 +82,7 @@ program
|
|
|
77
82
|
concurrency: options.concurrency,
|
|
78
83
|
branch: options.branch,
|
|
79
84
|
commit: options.commit,
|
|
85
|
+
baseBranch: options.baseBranch,
|
|
80
86
|
ci: options.ci,
|
|
81
87
|
verbose: options.verbose,
|
|
82
88
|
local: options.local,
|
|
@@ -92,6 +98,7 @@ program
|
|
|
92
98
|
.option('-b, --browser <browsers>', 'Browsers to test (chromium,firefox,webkit)')
|
|
93
99
|
.option('--storybook-url <url>', 'Storybook URL, overriding the config file')
|
|
94
100
|
.option('--concurrency <n>', 'Stories to capture at once (default: 4)', parseConcurrency)
|
|
101
|
+
.option('--branch <branch>', 'Branch whose baselines to update (API mode; default: detected from CI or git)')
|
|
95
102
|
.option('-v, --verbose', 'Verbose output')
|
|
96
103
|
.option('--dry-run', 'Show what would be updated without making changes')
|
|
97
104
|
.option('--local', 'Force local-only mode without using the API')
|
|
@@ -104,6 +111,7 @@ program
|
|
|
104
111
|
browser: options.browser,
|
|
105
112
|
storybookUrl: options.storybookUrl,
|
|
106
113
|
concurrency: options.concurrency,
|
|
114
|
+
branch: options.branch,
|
|
107
115
|
verbose: options.verbose,
|
|
108
116
|
dryRun: options.dryRun,
|
|
109
117
|
local: options.local,
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Where to review this push, for a run on a branch with a review: its
|
|
3
|
+
* dashboard link, or its id when the server has no DASHBOARD_URL to build one.
|
|
4
|
+
*/
|
|
5
|
+
export declare function describeReview(run: {
|
|
6
|
+
reviewId?: string | null;
|
|
7
|
+
reviewUrl?: string | null;
|
|
8
|
+
}): string | undefined;
|
|
9
|
+
//# sourceMappingURL=review.d.ts.map
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Where to review this push, for a run on a branch with a review: its
|
|
3
|
+
* dashboard link, or its id when the server has no DASHBOARD_URL to build one.
|
|
4
|
+
*/
|
|
5
|
+
export function describeReview(run) {
|
|
6
|
+
if (!run.reviewId)
|
|
7
|
+
return undefined;
|
|
8
|
+
return run.reviewUrl ?? `review ${run.reviewId} (set DASHBOARD_URL on the server for a link)`;
|
|
9
|
+
}
|
|
10
|
+
//# sourceMappingURL=review.js.map
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import type { Story, StorySnapConfig } from '@storysnap/shared';
|
|
1
|
+
import type { Screenshot, Story, StorySnapConfig } from '@storysnap/shared';
|
|
2
2
|
import type { Reporter } from './reporter.js';
|
|
3
3
|
export interface StorySelectionOptions {
|
|
4
4
|
/** --story patterns. They narrow the config's include list rather than replacing it. */
|
|
@@ -22,4 +22,9 @@ export declare function collectPatterns(value: string, previous?: string[]): str
|
|
|
22
22
|
* a mistake instead, so that exits like an empty Storybook does.
|
|
23
23
|
*/
|
|
24
24
|
export declare function selectStories(reporter: Reporter, config: StorySnapConfig, options: StorySelectionOptions, unit: 'tests' | 'baselines'): Promise<Story[] | null>;
|
|
25
|
+
/**
|
|
26
|
+
* Drops the stories whose parameters disabled them from a capture and says so.
|
|
27
|
+
* Returns the rest, or null when nothing is left to test or update.
|
|
28
|
+
*/
|
|
29
|
+
export declare function withoutSkipped(reporter: Reporter, selected: Story[], screenshots: Map<string, Screenshot>): Story[] | null;
|
|
25
30
|
//# sourceMappingURL=select-stories.d.ts.map
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { discoverStories, filterStories } from '../core/storybook.js';
|
|
2
|
+
import { dropSkipped } from '../core/screenshot.js';
|
|
2
3
|
import { getChangedFiles, filterChangedStories } from '../core/changed.js';
|
|
3
4
|
/**
|
|
4
5
|
* Commander collector for options that may be repeated or comma-separated,
|
|
@@ -54,4 +55,19 @@ export async function selectStories(reporter, config, options, unit) {
|
|
|
54
55
|
reporter.succeedSpinner(`${counted} (${total} ${unit} across ${config.browsers.length} browser(s))`);
|
|
55
56
|
return stories;
|
|
56
57
|
}
|
|
58
|
+
/**
|
|
59
|
+
* Drops the stories whose parameters disabled them from a capture and says so.
|
|
60
|
+
* Returns the rest, or null when nothing is left to test or update.
|
|
61
|
+
*/
|
|
62
|
+
export function withoutSkipped(reporter, selected, screenshots) {
|
|
63
|
+
const { stories, skipped } = dropSkipped(selected, screenshots);
|
|
64
|
+
if (skipped.length > 0) {
|
|
65
|
+
reporter.info(`Skipped ${skipped.length} ${skipped.length === 1 ? 'story' : 'stories'} disabled in parameters`);
|
|
66
|
+
}
|
|
67
|
+
if (stories.length === 0) {
|
|
68
|
+
reporter.warning('Every selected story is disabled in its parameters; nothing to do');
|
|
69
|
+
return null;
|
|
70
|
+
}
|
|
71
|
+
return stories;
|
|
72
|
+
}
|
|
57
73
|
//# sourceMappingURL=select-stories.js.map
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
/** A run's result counts, as the server reports them. */
|
|
2
|
+
export interface RunCounts {
|
|
3
|
+
failedStories: number;
|
|
4
|
+
errorStories: number;
|
|
5
|
+
newStories: number;
|
|
6
|
+
}
|
|
7
|
+
/**
|
|
8
|
+
* What an API run's summary line says, worst first. Judged from the counts
|
|
9
|
+
* rather than the run's status: the server marks a run `error` when any
|
|
10
|
+
* result errored, failures and all, so its status alone can't tell a run
|
|
11
|
+
* that passed from one where nothing could be compared.
|
|
12
|
+
*
|
|
13
|
+
* `missing` counts the screenshots that never reached the server - absent
|
|
14
|
+
* from the run, not failed in it.
|
|
15
|
+
*/
|
|
16
|
+
export declare function apiRunVerdict(counts: RunCounts, missing: number): 'failed' | 'missing' | 'new' | 'passed';
|
|
17
|
+
//# sourceMappingURL=verdict.d.ts.map
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What an API run's summary line says, worst first. Judged from the counts
|
|
3
|
+
* rather than the run's status: the server marks a run `error` when any
|
|
4
|
+
* result errored, failures and all, so its status alone can't tell a run
|
|
5
|
+
* that passed from one where nothing could be compared.
|
|
6
|
+
*
|
|
7
|
+
* `missing` counts the screenshots that never reached the server - absent
|
|
8
|
+
* from the run, not failed in it.
|
|
9
|
+
*/
|
|
10
|
+
export function apiRunVerdict(counts, missing) {
|
|
11
|
+
if (counts.failedStories > 0 || counts.errorStories > 0) {
|
|
12
|
+
return 'failed';
|
|
13
|
+
}
|
|
14
|
+
if (missing > 0) {
|
|
15
|
+
return 'missing';
|
|
16
|
+
}
|
|
17
|
+
if (counts.newStories > 0) {
|
|
18
|
+
return 'new';
|
|
19
|
+
}
|
|
20
|
+
return 'passed';
|
|
21
|
+
}
|
|
22
|
+
//# sourceMappingURL=verdict.js.map
|
package/dist/config/schema.d.ts
CHANGED
|
@@ -1,4 +1,8 @@
|
|
|
1
1
|
import { z } from 'zod';
|
|
2
|
+
export declare const viewportInputSchema: z.ZodUnion<readonly [z.ZodNumber, z.ZodObject<{
|
|
3
|
+
width: z.ZodNumber;
|
|
4
|
+
height: z.ZodNumber;
|
|
5
|
+
}, z.core.$strip>]>;
|
|
2
6
|
declare const browserSchema: z.ZodEnum<{
|
|
3
7
|
chromium: "chromium";
|
|
4
8
|
firefox: "firefox";
|
|
@@ -24,6 +28,11 @@ export declare const configSchema: z.ZodObject<{
|
|
|
24
28
|
width: z.ZodDefault<z.ZodNumber>;
|
|
25
29
|
height: z.ZodDefault<z.ZodNumber>;
|
|
26
30
|
}, z.core.$strip>>;
|
|
31
|
+
viewports: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodNumber, z.ZodObject<{
|
|
32
|
+
width: z.ZodNumber;
|
|
33
|
+
height: z.ZodNumber;
|
|
34
|
+
}, z.core.$strip>]>>>;
|
|
35
|
+
modes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodBoolean]>, z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodBoolean]>>]>>>>;
|
|
27
36
|
browsers: z.ZodDefault<z.ZodArray<z.ZodEnum<{
|
|
28
37
|
chromium: "chromium";
|
|
29
38
|
firefox: "firefox";
|
|
@@ -39,6 +48,8 @@ export declare const configSchema: z.ZodObject<{
|
|
|
39
48
|
concurrency: z.ZodDefault<z.ZodNumber>;
|
|
40
49
|
ignoreSelectors: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
41
50
|
ignoreColor: z.ZodOptional<z.ZodString>;
|
|
51
|
+
disableAnimations: z.ZodOptional<z.ZodBoolean>;
|
|
52
|
+
captureRetries: z.ZodOptional<z.ZodNumber>;
|
|
42
53
|
apiUrl: z.ZodOptional<z.ZodString>;
|
|
43
54
|
apiToken: z.ZodOptional<z.ZodString>;
|
|
44
55
|
}, z.core.$strip>;
|
package/dist/config/schema.js
CHANGED
|
@@ -1,8 +1,13 @@
|
|
|
1
1
|
import { z } from 'zod';
|
|
2
|
+
import { modesSchema } from '../core/modes.js';
|
|
2
3
|
const viewportSchema = z.object({
|
|
3
4
|
width: z.number().min(1).default(1280),
|
|
4
5
|
height: z.number().min(1).default(720),
|
|
5
6
|
});
|
|
7
|
+
export const viewportInputSchema = z.union([
|
|
8
|
+
z.number().int().min(1),
|
|
9
|
+
z.object({ width: z.number().int().min(1), height: z.number().int().min(1) }),
|
|
10
|
+
]);
|
|
6
11
|
const browserSchema = z.enum(['chromium', 'firefox', 'webkit']);
|
|
7
12
|
const s3StorageSchema = z.object({
|
|
8
13
|
type: z.literal('s3'),
|
|
@@ -28,6 +33,12 @@ export const configSchema = z.object({
|
|
|
28
33
|
// a cloud-only config does not have to declare storage it never touches.
|
|
29
34
|
storage: storageSchema.default({ type: 'local', directory: '.storysnap/baselines' }),
|
|
30
35
|
viewport: viewportSchema.default({ width: 1280, height: 720 }),
|
|
36
|
+
// Every story is captured at each of these instead of at `viewport` alone.
|
|
37
|
+
// A bare number is a width at `viewport`'s height.
|
|
38
|
+
viewports: z.array(viewportInputSchema).min(1).optional(),
|
|
39
|
+
// Named sets of Storybook globals. Every story is captured in each, at each
|
|
40
|
+
// viewport, instead of once without a mode.
|
|
41
|
+
modes: modesSchema.optional(),
|
|
31
42
|
browsers: z.array(browserSchema).default(['chromium']),
|
|
32
43
|
// The two comparison settings are deliberately left undefined when the config
|
|
33
44
|
// omits them, rather than defaulted here. In API mode an undefined value is
|
|
@@ -60,6 +71,13 @@ export const configSchema = z.object({
|
|
|
60
71
|
ignoreSelectors: z.array(z.string().min(1)).optional(),
|
|
61
72
|
// The colour of that paint. Any CSS colour.
|
|
62
73
|
ignoreColor: z.string().min(1).optional(),
|
|
74
|
+
// Freeze CSS animations and transitions and emulate prefers-reduced-motion,
|
|
75
|
+
// so a capture never lands mid-frame. Turn off to capture motion as it is.
|
|
76
|
+
disableAnimations: z.boolean().optional(),
|
|
77
|
+
// How many times a capture that throws - a timeout, a crashed page - is
|
|
78
|
+
// tried again before the story is reported as an error. Stories that only
|
|
79
|
+
// captured on a retry are marked flaky.
|
|
80
|
+
captureRetries: z.number().int().min(0).max(5).optional(),
|
|
63
81
|
// API configuration (optional - can also use ~/.storysnap/credentials)
|
|
64
82
|
apiUrl: z.string().url().optional(),
|
|
65
83
|
apiToken: z.string().optional(),
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What a screenshot was captured with: browser and version, the official
|
|
3
|
+
* capture image if it ran in one, and the operating system. Two captures from
|
|
4
|
+
* the same environment render pixel for pixel alike; from different ones, fonts
|
|
5
|
+
* and rasterizers can differ everywhere, which is what a baseline from a
|
|
6
|
+
* laptop compared against a run from CI looks like.
|
|
7
|
+
*
|
|
8
|
+
* The CLI version is left out on purpose: upgrading it without changing the
|
|
9
|
+
* browser renders nothing differently, and would only warn about every
|
|
10
|
+
* baseline.
|
|
11
|
+
*/
|
|
12
|
+
export declare function describeCaptureEnvironment(browser: string, browserVersion: string, env?: NodeJS.ProcessEnv): string;
|
|
13
|
+
/** The environment recorded in a screenshot, if it has one. */
|
|
14
|
+
export declare function readCaptureEnvironment(png: Buffer): string | undefined;
|
|
15
|
+
/** The PNG without its environment, which is what its content hash is of. */
|
|
16
|
+
export declare function withoutCaptureEnvironment(png: Buffer): Buffer;
|
|
17
|
+
/** The PNG with `environment` recorded in it, replacing any already there. */
|
|
18
|
+
export declare function withCaptureEnvironment(png: Buffer, environment: string): Buffer;
|
|
19
|
+
//# sourceMappingURL=capture-environment.d.ts.map
|
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
import { readFileSync } from 'node:fs';
|
|
2
|
+
import { arch, platform, release } from 'node:os';
|
|
3
|
+
import { crc32 } from 'node:zlib';
|
|
4
|
+
/**
|
|
5
|
+
* What a screenshot was captured with: browser and version, the official
|
|
6
|
+
* capture image if it ran in one, and the operating system. Two captures from
|
|
7
|
+
* the same environment render pixel for pixel alike; from different ones, fonts
|
|
8
|
+
* and rasterizers can differ everywhere, which is what a baseline from a
|
|
9
|
+
* laptop compared against a run from CI looks like.
|
|
10
|
+
*
|
|
11
|
+
* The CLI version is left out on purpose: upgrading it without changing the
|
|
12
|
+
* browser renders nothing differently, and would only warn about every
|
|
13
|
+
* baseline.
|
|
14
|
+
*/
|
|
15
|
+
export function describeCaptureEnvironment(browser, browserVersion, env = process.env) {
|
|
16
|
+
const image = env.STORYSNAP_CAPTURE_IMAGE;
|
|
17
|
+
return [`${browser} ${browserVersion}`, image, `${operatingSystem()} ${arch()}`].filter(Boolean).join(', ');
|
|
18
|
+
}
|
|
19
|
+
/**
|
|
20
|
+
* The OS as far as it changes rendering: the Linux distribution and release
|
|
21
|
+
* (each ships its own fonts), or the macOS / Windows family. Not the kernel
|
|
22
|
+
* version, which CI runners change without changing a pixel.
|
|
23
|
+
*/
|
|
24
|
+
function operatingSystem() {
|
|
25
|
+
switch (platform()) {
|
|
26
|
+
case 'linux':
|
|
27
|
+
return linuxRelease() ?? 'linux';
|
|
28
|
+
case 'darwin':
|
|
29
|
+
return `darwin ${release().split('.')[0]}`;
|
|
30
|
+
case 'win32':
|
|
31
|
+
return 'windows';
|
|
32
|
+
default:
|
|
33
|
+
return platform();
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
function linuxRelease() {
|
|
37
|
+
try {
|
|
38
|
+
const osRelease = readFileSync('/etc/os-release', 'utf8');
|
|
39
|
+
const field = (name) => new RegExp(`^${name}="?([^"\\n]*)"?$`, 'm').exec(osRelease)?.[1];
|
|
40
|
+
const id = field('ID');
|
|
41
|
+
return id ? [id, field('VERSION_ID')].filter(Boolean).join(' ') : undefined;
|
|
42
|
+
}
|
|
43
|
+
catch {
|
|
44
|
+
return undefined;
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
// The environment travels inside the PNG as a tEXt chunk, so a baseline keeps
|
|
48
|
+
// it wherever it is stored - a local directory, S3 or the server - and is
|
|
49
|
+
// compared against without any record kept beside it.
|
|
50
|
+
const KEYWORD = 'storysnap:environment';
|
|
51
|
+
const SIGNATURE_LENGTH = 8;
|
|
52
|
+
function* chunks(png) {
|
|
53
|
+
let offset = SIGNATURE_LENGTH;
|
|
54
|
+
while (offset + 8 <= png.length) {
|
|
55
|
+
const length = png.readUInt32BE(offset);
|
|
56
|
+
const type = png.toString('latin1', offset + 4, offset + 8);
|
|
57
|
+
const end = offset + 12 + length;
|
|
58
|
+
if (end > png.length) {
|
|
59
|
+
return;
|
|
60
|
+
}
|
|
61
|
+
yield { type, start: offset, end };
|
|
62
|
+
offset = end;
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
function environmentChunk(png) {
|
|
66
|
+
for (const chunk of chunks(png)) {
|
|
67
|
+
if (chunk.type === 'tEXt' && png.toString('latin1', chunk.start + 8, chunk.start + 8 + KEYWORD.length + 1) === `${KEYWORD}\0`) {
|
|
68
|
+
return chunk;
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
return undefined;
|
|
72
|
+
}
|
|
73
|
+
/** The environment recorded in a screenshot, if it has one. */
|
|
74
|
+
export function readCaptureEnvironment(png) {
|
|
75
|
+
const chunk = environmentChunk(png);
|
|
76
|
+
return chunk ? png.toString('latin1', chunk.start + 8 + KEYWORD.length + 1, chunk.end - 4) : undefined;
|
|
77
|
+
}
|
|
78
|
+
/** The PNG without its environment, which is what its content hash is of. */
|
|
79
|
+
export function withoutCaptureEnvironment(png) {
|
|
80
|
+
const chunk = environmentChunk(png);
|
|
81
|
+
return chunk ? Buffer.concat([png.subarray(0, chunk.start), png.subarray(chunk.end)]) : png;
|
|
82
|
+
}
|
|
83
|
+
/** The PNG with `environment` recorded in it, replacing any already there. */
|
|
84
|
+
export function withCaptureEnvironment(png, environment) {
|
|
85
|
+
const bare = withoutCaptureEnvironment(png);
|
|
86
|
+
let iend;
|
|
87
|
+
for (const chunk of chunks(bare)) {
|
|
88
|
+
if (chunk.type === 'IEND')
|
|
89
|
+
iend = chunk;
|
|
90
|
+
}
|
|
91
|
+
if (!iend) {
|
|
92
|
+
return bare;
|
|
93
|
+
}
|
|
94
|
+
const data = Buffer.from(`${KEYWORD}\0${environment}`, 'latin1');
|
|
95
|
+
const typeAndData = Buffer.concat([Buffer.from('tEXt', 'latin1'), data]);
|
|
96
|
+
const chunk = Buffer.alloc(12 + data.length);
|
|
97
|
+
chunk.writeUInt32BE(data.length, 0);
|
|
98
|
+
typeAndData.copy(chunk, 4);
|
|
99
|
+
chunk.writeUInt32BE(crc32(typeAndData), 8 + data.length);
|
|
100
|
+
return Buffer.concat([bare.subarray(0, iend.start), chunk, bare.subarray(iend.start)]);
|
|
101
|
+
}
|
|
102
|
+
//# sourceMappingURL=capture-environment.js.map
|
package/dist/core/changed.js
CHANGED
|
@@ -1,32 +1,11 @@
|
|
|
1
|
-
import { execFile } from 'node:child_process';
|
|
2
1
|
import { posix } from 'node:path';
|
|
3
|
-
import {
|
|
4
|
-
const execFileAsync = promisify(execFile);
|
|
2
|
+
import { git, findMergeBase } from './git.js';
|
|
5
3
|
/** Used by `--changed` with no ref. CI checkouts often only have the remote one. */
|
|
6
4
|
const DEFAULT_REFS = ['main', 'origin/main'];
|
|
7
|
-
async function git(args, cwd) {
|
|
8
|
-
const { stdout } = await execFileAsync('git', args, { cwd, maxBuffer: 64 * 1024 * 1024 });
|
|
9
|
-
return stdout;
|
|
10
|
-
}
|
|
11
5
|
/** Parses `-z` output, which leaves unusual file names unquoted. */
|
|
12
6
|
function splitNul(output) {
|
|
13
7
|
return output.split('\0').filter(Boolean);
|
|
14
8
|
}
|
|
15
|
-
async function findMergeBase(refs, cwd) {
|
|
16
|
-
for (const ref of refs) {
|
|
17
|
-
try {
|
|
18
|
-
const base = (await git(['merge-base', ref, 'HEAD'], cwd)).trim();
|
|
19
|
-
return { ref, base };
|
|
20
|
-
}
|
|
21
|
-
catch {
|
|
22
|
-
// Try the next candidate
|
|
23
|
-
}
|
|
24
|
-
}
|
|
25
|
-
const tried = refs.map((ref) => `"${ref}"`).join(' or ');
|
|
26
|
-
throw new Error(`Could not compare against ${tried}. Make sure this is a git repository and the ref exists - ` +
|
|
27
|
-
'CI checkouts are often shallow, so fetch it first (e.g. "git fetch origin main") ' +
|
|
28
|
-
'or name one explicitly with --changed <ref>.');
|
|
29
|
-
}
|
|
30
9
|
/**
|
|
31
10
|
* Files that differ from the point where HEAD branched off `ref`: committed,
|
|
32
11
|
* staged, unstaged and untracked. Comparing against the merge base rather than
|
|
@@ -36,7 +15,15 @@ async function findMergeBase(refs, cwd) {
|
|
|
36
15
|
* the CLI runs from the directory Storybook runs from.
|
|
37
16
|
*/
|
|
38
17
|
export async function getChangedFiles(ref, cwd = process.cwd()) {
|
|
39
|
-
const
|
|
18
|
+
const refs = ref ? [ref] : DEFAULT_REFS;
|
|
19
|
+
const found = await findMergeBase(refs, cwd);
|
|
20
|
+
if (!found) {
|
|
21
|
+
const tried = refs.map((r) => `"${r}"`).join(' or ');
|
|
22
|
+
throw new Error(`Could not compare against ${tried}. Make sure this is a git repository and the ref exists - ` +
|
|
23
|
+
'CI checkouts are often shallow, so fetch it first (e.g. "git fetch origin main") ' +
|
|
24
|
+
'or name one explicitly with --changed <ref>.');
|
|
25
|
+
}
|
|
26
|
+
const { ref: resolvedRef, base } = found;
|
|
40
27
|
const [tracked, untracked] = await Promise.all([
|
|
41
28
|
git(['diff', '--name-only', '--relative', '-z', base], cwd),
|
|
42
29
|
git(['ls-files', '--others', '--exclude-standard', '-z'], cwd),
|
package/dist/core/compare.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import type { Screenshot, ComparisonResult, StorageProvider } from '@storysnap/shared';
|
|
1
|
+
import type { Screenshot, ComparisonResult, StorageProvider, Viewport } from '@storysnap/shared';
|
|
2
2
|
/**
|
|
3
3
|
* Local-mode fallbacks. In API mode the equivalent defaults live on the
|
|
4
4
|
* `projects` row so they can be changed without editing a config file; there is
|
|
@@ -19,6 +19,8 @@ export interface CompareOptions {
|
|
|
19
19
|
localSnapshotsDir?: string;
|
|
20
20
|
/** How many comparisons run at once; each downloads a baseline first. */
|
|
21
21
|
concurrency?: number;
|
|
22
|
+
/** The configured viewport; captures at any other carry theirs in their file names. */
|
|
23
|
+
viewport?: Viewport;
|
|
22
24
|
}
|
|
23
25
|
export declare function compareScreenshot(screenshot: Screenshot, options: CompareOptions): Promise<ComparisonResult>;
|
|
24
26
|
export declare function compareAllScreenshots(screenshots: Map<string, Screenshot>, options: CompareOptions, onProgress?: (completed: number, total: number, key: string) => void): Promise<Map<string, ComparisonResult>>;
|
package/dist/core/compare.js
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import pixelmatch from 'pixelmatch';
|
|
2
2
|
import { PNG } from 'pngjs';
|
|
3
|
-
import {
|
|
3
|
+
import { getCaptureKey } from './storybook.js';
|
|
4
|
+
import { readCaptureEnvironment } from './capture-environment.js';
|
|
4
5
|
import { DEFAULT_CONCURRENCY, mapWithConcurrency } from './concurrency.js';
|
|
5
6
|
import { ensureDir } from '../storage/local.js';
|
|
6
7
|
import { writeFile } from 'node:fs/promises';
|
|
@@ -13,8 +14,22 @@ import { join } from 'node:path';
|
|
|
13
14
|
export const DEFAULT_THRESHOLD = 0.1;
|
|
14
15
|
export const DEFAULT_MAX_DIFF_PERCENT = 0.1;
|
|
15
16
|
export async function compareScreenshot(screenshot, options) {
|
|
17
|
+
const result = await compareCapture(screenshot, options);
|
|
18
|
+
return {
|
|
19
|
+
...result,
|
|
20
|
+
viewport: { width: screenshot.width, height: screenshot.height },
|
|
21
|
+
...(screenshot.mode && { mode: screenshot.mode }),
|
|
22
|
+
...(screenshot.flaky && { flaky: true }),
|
|
23
|
+
...withEnvironment('captureEnvironment', screenshot.buffer),
|
|
24
|
+
};
|
|
25
|
+
}
|
|
26
|
+
function withEnvironment(field, png) {
|
|
27
|
+
const environment = png.length > 0 ? readCaptureEnvironment(png) : undefined;
|
|
28
|
+
return environment ? { [field]: environment } : {};
|
|
29
|
+
}
|
|
30
|
+
async function compareCapture(screenshot, options) {
|
|
16
31
|
// Use browser-aware storage key
|
|
17
|
-
const storyKey =
|
|
32
|
+
const storyKey = getCaptureKey(screenshot, options.viewport);
|
|
18
33
|
// Check for capture error
|
|
19
34
|
if (screenshot.buffer.length === 0) {
|
|
20
35
|
return {
|
|
@@ -24,8 +39,9 @@ export async function compareScreenshot(screenshot, options) {
|
|
|
24
39
|
errorMessage: screenshot.error ? `Failed to capture screenshot: ${screenshot.error}` : 'Failed to capture screenshot',
|
|
25
40
|
};
|
|
26
41
|
}
|
|
27
|
-
|
|
28
|
-
const
|
|
42
|
+
// A story's own parameters beat the config's.
|
|
43
|
+
const threshold = screenshot.threshold ?? options.threshold ?? DEFAULT_THRESHOLD;
|
|
44
|
+
const maxDiffPercent = screenshot.maxDiffPercent ?? options.maxDiffPercent ?? DEFAULT_MAX_DIFF_PERCENT;
|
|
29
45
|
try {
|
|
30
46
|
// Inside the try so a storage failure - an S3 timeout, say - errors this
|
|
31
47
|
// one story rather than rejecting every comparison in the run.
|
|
@@ -38,14 +54,16 @@ export async function compareScreenshot(screenshot, options) {
|
|
|
38
54
|
status: 'new',
|
|
39
55
|
};
|
|
40
56
|
}
|
|
57
|
+
const baselineEnvironment = withEnvironment('baselineCaptureEnvironment', baselineBuffer);
|
|
41
58
|
// Parse PNG images
|
|
42
59
|
const currentPng = PNG.sync.read(screenshot.buffer);
|
|
43
60
|
const baselinePng = PNG.sync.read(baselineBuffer);
|
|
44
61
|
// Check dimensions match
|
|
45
62
|
if (currentPng.width !== baselinePng.width || currentPng.height !== baselinePng.height) {
|
|
46
63
|
// Dimensions changed - treat as a diff
|
|
47
|
-
const diffImagePath = await saveDiffImage(screenshot, baselineBuffer, options.localSnapshotsDir);
|
|
64
|
+
const diffImagePath = await saveDiffImage(storyKey, screenshot, baselineBuffer, options.localSnapshotsDir);
|
|
48
65
|
return {
|
|
66
|
+
...baselineEnvironment,
|
|
49
67
|
storyId: screenshot.storyId,
|
|
50
68
|
browser: screenshot.browser,
|
|
51
69
|
status: 'fail',
|
|
@@ -63,6 +81,7 @@ export async function compareScreenshot(screenshot, options) {
|
|
|
63
81
|
const diffPercentage = (diffPixels / totalPixels) * 100;
|
|
64
82
|
if (diffPercentage <= maxDiffPercent) {
|
|
65
83
|
return {
|
|
84
|
+
...baselineEnvironment,
|
|
66
85
|
storyId: screenshot.storyId,
|
|
67
86
|
browser: screenshot.browser,
|
|
68
87
|
status: 'pass',
|
|
@@ -71,8 +90,9 @@ export async function compareScreenshot(screenshot, options) {
|
|
|
71
90
|
};
|
|
72
91
|
}
|
|
73
92
|
// Save diff image if there are differences
|
|
74
|
-
const diffImagePath = await saveDiffImageFromPng(
|
|
93
|
+
const diffImagePath = await saveDiffImageFromPng(storyKey, diffPng, screenshot.buffer, baselineBuffer, options.localSnapshotsDir);
|
|
75
94
|
return {
|
|
95
|
+
...baselineEnvironment,
|
|
76
96
|
storyId: screenshot.storyId,
|
|
77
97
|
browser: screenshot.browser,
|
|
78
98
|
status: 'fail',
|
|
@@ -90,13 +110,13 @@ export async function compareScreenshot(screenshot, options) {
|
|
|
90
110
|
};
|
|
91
111
|
}
|
|
92
112
|
}
|
|
93
|
-
async function saveDiffImage(screenshot, baselineBuffer, localSnapshotsDir) {
|
|
113
|
+
async function saveDiffImage(storyKey, screenshot, baselineBuffer, localSnapshotsDir) {
|
|
94
114
|
if (!localSnapshotsDir) {
|
|
95
115
|
return undefined;
|
|
96
116
|
}
|
|
97
117
|
const diffDir = join(localSnapshotsDir, 'diffs');
|
|
98
118
|
await ensureDir(diffDir);
|
|
99
|
-
const baseName =
|
|
119
|
+
const baseName = storyKey.replace('.png', '');
|
|
100
120
|
// Save current screenshot
|
|
101
121
|
const currentPath = join(diffDir, `${baseName}.current.png`);
|
|
102
122
|
await writeFile(currentPath, screenshot.buffer);
|
|
@@ -105,13 +125,13 @@ async function saveDiffImage(screenshot, baselineBuffer, localSnapshotsDir) {
|
|
|
105
125
|
await writeFile(baselinePath, baselineBuffer);
|
|
106
126
|
return currentPath;
|
|
107
127
|
}
|
|
108
|
-
async function saveDiffImageFromPng(
|
|
128
|
+
async function saveDiffImageFromPng(storyKey, diffPng, currentBuffer, baselineBuffer, localSnapshotsDir) {
|
|
109
129
|
if (!localSnapshotsDir) {
|
|
110
130
|
return undefined;
|
|
111
131
|
}
|
|
112
132
|
const diffDir = join(localSnapshotsDir, 'diffs');
|
|
113
133
|
await ensureDir(diffDir);
|
|
114
|
-
const baseName =
|
|
134
|
+
const baseName = storyKey.replace('.png', '');
|
|
115
135
|
// Save diff image
|
|
116
136
|
const diffPath = join(diffDir, `${baseName}.diff.png`);
|
|
117
137
|
const diffBuffer = PNG.sync.write(diffPng);
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
/** Where a run comes from. Anything left undefined the server fills in. */
|
|
2
|
+
export interface GitContext {
|
|
3
|
+
branch?: string;
|
|
4
|
+
commit?: string;
|
|
5
|
+
/** The branch this one will merge into; the server falls back to its baselines. */
|
|
6
|
+
baseBranch?: string;
|
|
7
|
+
/** The commit `branch` forked from `baseBranch` at. */
|
|
8
|
+
mergeBase?: string;
|
|
9
|
+
}
|
|
10
|
+
export interface GitContextOptions {
|
|
11
|
+
/** Explicit flags, which win over anything detected. */
|
|
12
|
+
overrides?: Pick<GitContext, 'branch' | 'commit' | 'baseBranch'>;
|
|
13
|
+
env?: NodeJS.ProcessEnv;
|
|
14
|
+
cwd?: string;
|
|
15
|
+
}
|
|
16
|
+
/**
|
|
17
|
+
* Works out the branch, commit, base branch and merge base of this run, best
|
|
18
|
+
* effort: flags, then CI variables, then git. Nothing here fails a run - with
|
|
19
|
+
* no git at all every field may come back undefined, and the server treats
|
|
20
|
+
* the run as being on the project's default branch.
|
|
21
|
+
*/
|
|
22
|
+
export declare function detectGitContext(options?: GitContextOptions): Promise<GitContext>;
|
|
23
|
+
/** "Branch feature/x (compared against main @ abc1234)", or what was not detected. */
|
|
24
|
+
export declare function describeGitContext(context: GitContext): string;
|
|
25
|
+
//# sourceMappingURL=git-context.d.ts.map
|