@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.
@@ -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
@@ -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>;
@@ -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
@@ -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>>;
@@ -1,6 +1,7 @@
1
1
  import pixelmatch from 'pixelmatch';
2
2
  import { PNG } from 'pngjs';
3
- import { getStoryKey } from './storybook.js';
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 = getStoryKey(screenshot.storyId, screenshot.browser);
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
- const threshold = options.threshold ?? DEFAULT_THRESHOLD;
28
- const maxDiffPercent = options.maxDiffPercent ?? DEFAULT_MAX_DIFF_PERCENT;
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(screenshot.storyId, screenshot.browser, diffPng, screenshot.buffer, baselineBuffer, options.localSnapshotsDir);
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 = getStoryKey(screenshot.storyId, screenshot.browser).replace('.png', '');
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(storyId, browser, diffPng, currentBuffer, baselineBuffer, localSnapshotsDir) {
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 = getStoryKey(storyId, browser).replace('.png', '');
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);
@@ -1,3 +1,7 @@
1
- /** SHA-256 of a screenshot's PNG bytes, hex encoded. */
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
- /** SHA-256 of a screenshot's PNG bytes, hex encoded. */
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