@storysnap/cli 2.1.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 +18 -1
- package/dist/api/client.js +2 -1
- package/dist/cli/commands/test.js +103 -59
- package/dist/cli/commands/update.js +55 -30
- package/dist/cli/environment-warning.d.ts +17 -0
- package/dist/cli/environment-warning.js +42 -0
- package/dist/cli/index.js +5 -1
- 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/compare.d.ts +3 -1
- package/dist/core/compare.js +30 -10
- package/dist/core/hash.d.ts +5 -1
- package/dist/core/hash.js +7 -2
- 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
|
@@ -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/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);
|
package/dist/core/hash.d.ts
CHANGED
|
@@ -1,3 +1,7 @@
|
|
|
1
|
-
/**
|
|
1
|
+
/**
|
|
2
|
+
* SHA-256 of a screenshot's PNG bytes, hex encoded, leaving out the capture
|
|
3
|
+
* environment recorded in it: the hash says which pixels were approved, and
|
|
4
|
+
* the same pixels are the same approval wherever they were captured.
|
|
5
|
+
*/
|
|
2
6
|
export declare function hashScreenshot(buffer: Buffer): string;
|
|
3
7
|
//# sourceMappingURL=hash.d.ts.map
|
package/dist/core/hash.js
CHANGED
|
@@ -1,6 +1,11 @@
|
|
|
1
1
|
import { createHash } from 'node:crypto';
|
|
2
|
-
|
|
2
|
+
import { withoutCaptureEnvironment } from './capture-environment.js';
|
|
3
|
+
/**
|
|
4
|
+
* SHA-256 of a screenshot's PNG bytes, hex encoded, leaving out the capture
|
|
5
|
+
* environment recorded in it: the hash says which pixels were approved, and
|
|
6
|
+
* the same pixels are the same approval wherever they were captured.
|
|
7
|
+
*/
|
|
3
8
|
export function hashScreenshot(buffer) {
|
|
4
|
-
return createHash('sha256').update(buffer).digest('hex');
|
|
9
|
+
return createHash('sha256').update(withoutCaptureEnvironment(buffer)).digest('hex');
|
|
5
10
|
}
|
|
6
11
|
//# sourceMappingURL=hash.js.map
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
import type { Page } from 'playwright';
|
|
3
|
+
import type { ModeGlobals, Modes } from '@storysnap/shared';
|
|
4
|
+
/** The globals a mode sets; one level of nesting, as in `backgrounds: { value: 'dark' }`. */
|
|
5
|
+
export declare const modeGlobalsSchema: 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]>>]>>;
|
|
6
|
+
/** Modes in the config: name to globals. */
|
|
7
|
+
export declare const modesSchema: 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]>>]>>>;
|
|
8
|
+
/**
|
|
9
|
+
* Modes in a story's parameters. Storybook merges parameters from preview to
|
|
10
|
+
* story, so `{ disable: true }` takes an inherited mode away again, as in
|
|
11
|
+
* Chromatic.
|
|
12
|
+
*/
|
|
13
|
+
export declare const parameterModesSchema: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
|
|
14
|
+
disable: z.ZodLiteral<true>;
|
|
15
|
+
}, z.core.$strict>, 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]>>]>>]>>;
|
|
16
|
+
export type ParameterModes = z.infer<typeof parameterModesSchema>;
|
|
17
|
+
/** One mode a story is captured in. A story without modes has one, named ''. */
|
|
18
|
+
export interface Mode {
|
|
19
|
+
name: string;
|
|
20
|
+
globals: ModeGlobals;
|
|
21
|
+
}
|
|
22
|
+
export declare const NO_MODE: Mode;
|
|
23
|
+
/**
|
|
24
|
+
* The modes a story is captured in: its own from its parameters, else the
|
|
25
|
+
* configured ones, else the one without a mode. A story with modes is
|
|
26
|
+
* captured only in those, not also without one.
|
|
27
|
+
*/
|
|
28
|
+
export declare function resolveModes(configured: Modes | undefined, fromParameters: ParameterModes | undefined): Mode[];
|
|
29
|
+
export declare function sameMode(a: Mode, b: Mode): boolean;
|
|
30
|
+
/**
|
|
31
|
+
* The mode's globals as Storybook's `globals` URL parameter: `key:value`
|
|
32
|
+
* pairs joined by `;`, nested keys dotted, booleans as `!true`, colours as
|
|
33
|
+
* `!hex(…)`. Storybook drops any value with other characters, so those are
|
|
34
|
+
* refused here, naming the global, rather than silently not applied.
|
|
35
|
+
*/
|
|
36
|
+
export declare function globalsParameter(mode: Mode): string;
|
|
37
|
+
/**
|
|
38
|
+
* The globals of a mode that did not take effect, by dotted key. Storybook
|
|
39
|
+
* only applies a URL global that the project declares in `globalTypes` (or
|
|
40
|
+
* `initialGlobals`); anything else it drops without a word, and the capture
|
|
41
|
+
* would quietly be the default.
|
|
42
|
+
*/
|
|
43
|
+
export declare function unappliedGlobals(mode: Mode, effective: Record<string, unknown>): string[];
|
|
44
|
+
/**
|
|
45
|
+
* Checks that the mode's globals are the ones the rendered story got, and
|
|
46
|
+
* throws naming those that are not. A page without a Storybook preview has no
|
|
47
|
+
* globals to check.
|
|
48
|
+
*/
|
|
49
|
+
export declare function verifyModeApplied(page: Page, mode: Mode): Promise<void>;
|
|
50
|
+
//# sourceMappingURL=modes.d.ts.map
|
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
/**
|
|
3
|
+
* A mode's name: what tells its screenshots apart, in results, baselines and
|
|
4
|
+
* storage keys. Printable, and short enough to read in a list of results.
|
|
5
|
+
*/
|
|
6
|
+
const modeNameSchema = z
|
|
7
|
+
.string()
|
|
8
|
+
.min(1)
|
|
9
|
+
.max(64)
|
|
10
|
+
.refine((name) => [...name].every((ch) => ch.charCodeAt(0) >= 0x20 && ch.charCodeAt(0) !== 0x7f), {
|
|
11
|
+
message: 'Expected printable characters',
|
|
12
|
+
});
|
|
13
|
+
const globalValueSchema = z.union([z.string(), z.boolean()]);
|
|
14
|
+
/** The globals a mode sets; one level of nesting, as in `backgrounds: { value: 'dark' }`. */
|
|
15
|
+
export const modeGlobalsSchema = z.record(z.string().min(1), z.union([globalValueSchema, z.record(z.string().min(1), globalValueSchema)]));
|
|
16
|
+
/** Modes in the config: name to globals. */
|
|
17
|
+
export const modesSchema = z.record(modeNameSchema, modeGlobalsSchema);
|
|
18
|
+
/**
|
|
19
|
+
* Modes in a story's parameters. Storybook merges parameters from preview to
|
|
20
|
+
* story, so `{ disable: true }` takes an inherited mode away again, as in
|
|
21
|
+
* Chromatic.
|
|
22
|
+
*/
|
|
23
|
+
export const parameterModesSchema = z.record(modeNameSchema, z.union([z.object({ disable: z.literal(true) }).strict(), modeGlobalsSchema]));
|
|
24
|
+
export const NO_MODE = { name: '', globals: {} };
|
|
25
|
+
/**
|
|
26
|
+
* The modes a story is captured in: its own from its parameters, else the
|
|
27
|
+
* configured ones, else the one without a mode. A story with modes is
|
|
28
|
+
* captured only in those, not also without one.
|
|
29
|
+
*/
|
|
30
|
+
export function resolveModes(configured, fromParameters) {
|
|
31
|
+
const source = fromParameters ?? configured ?? {};
|
|
32
|
+
const modes = Object.entries(source)
|
|
33
|
+
.filter((entry) => !isDisabled(entry[1]))
|
|
34
|
+
.map(([name, globals]) => ({ name, globals }));
|
|
35
|
+
return modes.length > 0 ? modes : [NO_MODE];
|
|
36
|
+
}
|
|
37
|
+
function isDisabled(value) {
|
|
38
|
+
return 'disable' in value && value.disable === true;
|
|
39
|
+
}
|
|
40
|
+
export function sameMode(a, b) {
|
|
41
|
+
return a.name === b.name && JSON.stringify(a.globals) === JSON.stringify(b.globals);
|
|
42
|
+
}
|
|
43
|
+
/**
|
|
44
|
+
* The mode's globals as Storybook's `globals` URL parameter: `key:value`
|
|
45
|
+
* pairs joined by `;`, nested keys dotted, booleans as `!true`, colours as
|
|
46
|
+
* `!hex(…)`. Storybook drops any value with other characters, so those are
|
|
47
|
+
* refused here, naming the global, rather than silently not applied.
|
|
48
|
+
*/
|
|
49
|
+
export function globalsParameter(mode) {
|
|
50
|
+
const pairs = [];
|
|
51
|
+
for (const [key, value] of Object.entries(mode.globals)) {
|
|
52
|
+
if (typeof value === 'object') {
|
|
53
|
+
for (const [inner, innerValue] of Object.entries(value)) {
|
|
54
|
+
pairs.push(`${key}.${inner}:${encodeGlobalValue(mode, `${key}.${inner}`, innerValue)}`);
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
else {
|
|
58
|
+
pairs.push(`${key}:${encodeGlobalValue(mode, key, value)}`);
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
return pairs.join(';');
|
|
62
|
+
}
|
|
63
|
+
function encodeGlobalValue(mode, key, value) {
|
|
64
|
+
if (typeof value === 'boolean') {
|
|
65
|
+
return `!${value}`;
|
|
66
|
+
}
|
|
67
|
+
const hex = /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/.exec(value);
|
|
68
|
+
if (hex) {
|
|
69
|
+
return `!hex(${hex[1]})`;
|
|
70
|
+
}
|
|
71
|
+
if (/^[A-Za-z0-9 _-]*$/.test(value)) {
|
|
72
|
+
return encodeURIComponent(value);
|
|
73
|
+
}
|
|
74
|
+
throw new Error(`Mode "${mode.name}": global "${key}" is "${value}", which Storybook can't take from a URL - ` +
|
|
75
|
+
'use letters, digits, spaces, "_" and "-", a #hex colour, or true/false');
|
|
76
|
+
}
|
|
77
|
+
/**
|
|
78
|
+
* The globals of a mode that did not take effect, by dotted key. Storybook
|
|
79
|
+
* only applies a URL global that the project declares in `globalTypes` (or
|
|
80
|
+
* `initialGlobals`); anything else it drops without a word, and the capture
|
|
81
|
+
* would quietly be the default.
|
|
82
|
+
*/
|
|
83
|
+
export function unappliedGlobals(mode, effective) {
|
|
84
|
+
const missing = [];
|
|
85
|
+
for (const [key, value] of Object.entries(mode.globals)) {
|
|
86
|
+
if (typeof value === 'object') {
|
|
87
|
+
const actual = effective[key];
|
|
88
|
+
for (const [inner, innerValue] of Object.entries(value)) {
|
|
89
|
+
const actualInner = actual && typeof actual === 'object' ? actual[inner] : undefined;
|
|
90
|
+
if (actualInner !== innerValue)
|
|
91
|
+
missing.push(`${key}.${inner}`);
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
else if (effective[key] !== value) {
|
|
95
|
+
missing.push(key);
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
return missing;
|
|
99
|
+
}
|
|
100
|
+
/**
|
|
101
|
+
* Checks that the mode's globals are the ones the rendered story got, and
|
|
102
|
+
* throws naming those that are not. A page without a Storybook preview has no
|
|
103
|
+
* globals to check.
|
|
104
|
+
*/
|
|
105
|
+
export async function verifyModeApplied(page, mode) {
|
|
106
|
+
if (Object.keys(mode.globals).length === 0) {
|
|
107
|
+
return;
|
|
108
|
+
}
|
|
109
|
+
const effective = await page.evaluate(() => {
|
|
110
|
+
const preview = globalThis
|
|
111
|
+
.__STORYBOOK_PREVIEW__;
|
|
112
|
+
const store = preview?.storyStoreValue ?? preview?.storyStore;
|
|
113
|
+
return (store?.userGlobals ?? store?.globals)?.get() ?? null;
|
|
114
|
+
});
|
|
115
|
+
if (!effective) {
|
|
116
|
+
return;
|
|
117
|
+
}
|
|
118
|
+
const missing = unappliedGlobals(mode, effective);
|
|
119
|
+
if (missing.length > 0) {
|
|
120
|
+
throw new Error(`Mode "${mode.name}": Storybook did not apply ${missing.map((key) => `"${key}"`).join(', ')} - ` +
|
|
121
|
+
'declare each global in globalTypes (or initialGlobals) in .storybook/preview');
|
|
122
|
+
}
|
|
123
|
+
}
|
|
124
|
+
//# sourceMappingURL=modes.js.map
|