@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,75 @@
|
|
|
1
|
+
import { readFile } from 'node:fs/promises';
|
|
2
|
+
import { git, findMergeBase } from './git.js';
|
|
3
|
+
/** CI providers set some of these to an empty string rather than leaving them out. */
|
|
4
|
+
function first(...values) {
|
|
5
|
+
return values.find((value) => value !== undefined && value.trim() !== '')?.trim();
|
|
6
|
+
}
|
|
7
|
+
async function tryGit(args, cwd) {
|
|
8
|
+
try {
|
|
9
|
+
return first(await git(args, cwd));
|
|
10
|
+
}
|
|
11
|
+
catch {
|
|
12
|
+
return undefined;
|
|
13
|
+
}
|
|
14
|
+
}
|
|
15
|
+
/**
|
|
16
|
+
* The head commit of the pull request that triggered a GitHub Actions run.
|
|
17
|
+
* GITHUB_SHA is a merge commit GitHub made for the run, which nothing outside
|
|
18
|
+
* the run knows about - a status posted on it never shows up on the PR.
|
|
19
|
+
*/
|
|
20
|
+
async function githubPullRequestHead(env) {
|
|
21
|
+
if (!env.GITHUB_EVENT_PATH) {
|
|
22
|
+
return undefined;
|
|
23
|
+
}
|
|
24
|
+
try {
|
|
25
|
+
const event = JSON.parse(await readFile(env.GITHUB_EVENT_PATH, 'utf8'));
|
|
26
|
+
return first(event.pull_request?.head?.sha);
|
|
27
|
+
}
|
|
28
|
+
catch {
|
|
29
|
+
return undefined;
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
/**
|
|
33
|
+
* Works out the branch, commit, base branch and merge base of this run, best
|
|
34
|
+
* effort: flags, then CI variables, then git. Nothing here fails a run - with
|
|
35
|
+
* no git at all every field may come back undefined, and the server treats
|
|
36
|
+
* the run as being on the project's default branch.
|
|
37
|
+
*/
|
|
38
|
+
export async function detectGitContext(options = {}) {
|
|
39
|
+
const { overrides = {}, env = process.env, cwd = process.cwd() } = options;
|
|
40
|
+
const branch = first(overrides.branch,
|
|
41
|
+
// Pull request events check out a detached merge commit; this is the PR's branch.
|
|
42
|
+
env.GITHUB_HEAD_REF, env.CI_MERGE_REQUEST_SOURCE_BRANCH_NAME, env.GITHUB_REF_TYPE === 'branch' ? env.GITHUB_REF_NAME : undefined,
|
|
43
|
+
// Unlike CI_COMMIT_REF_NAME, never a tag.
|
|
44
|
+
env.CI_COMMIT_BRANCH) ?? (await tryGit(['symbolic-ref', '--short', '-q', 'HEAD'], cwd));
|
|
45
|
+
const commit = first(overrides.commit, await githubPullRequestHead(env), env.GITHUB_SHA,
|
|
46
|
+
// Set in merged-results pipelines, where CI_COMMIT_SHA is the merge commit.
|
|
47
|
+
env.CI_MERGE_REQUEST_SOURCE_BRANCH_SHA, env.CI_COMMIT_SHA) ?? (await tryGit(['rev-parse', 'HEAD'], cwd));
|
|
48
|
+
const baseBranch = first(overrides.baseBranch, env.GITHUB_BASE_REF, env.CI_MERGE_REQUEST_TARGET_BRANCH_NAME);
|
|
49
|
+
let mergeBase;
|
|
50
|
+
if (baseBranch && baseBranch !== branch) {
|
|
51
|
+
// The remote first: a local copy of the base is often behind it.
|
|
52
|
+
const refs = [`origin/${baseBranch}`, baseBranch];
|
|
53
|
+
// On a GitHub PR, HEAD is the merge commit, whose merge base with the
|
|
54
|
+
// target is the target itself; the PR's own head gives the fork point.
|
|
55
|
+
const heads = [...new Set([commit, 'HEAD'].filter((h) => Boolean(h)))];
|
|
56
|
+
for (const head of heads) {
|
|
57
|
+
mergeBase = (await findMergeBase(refs, cwd, head))?.base;
|
|
58
|
+
if (mergeBase)
|
|
59
|
+
break;
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
return { branch, commit, baseBranch, mergeBase };
|
|
63
|
+
}
|
|
64
|
+
/** "Branch feature/x (compared against main @ abc1234)", or what was not detected. */
|
|
65
|
+
export function describeGitContext(context) {
|
|
66
|
+
if (!context.branch) {
|
|
67
|
+
return "Branch: not detected - using the project's default branch (pass --branch to name one)";
|
|
68
|
+
}
|
|
69
|
+
if (!context.baseBranch || context.baseBranch === context.branch) {
|
|
70
|
+
return `Branch: ${context.branch}`;
|
|
71
|
+
}
|
|
72
|
+
const at = context.mergeBase ? ` @ ${context.mergeBase.slice(0, 7)}` : '';
|
|
73
|
+
return `Branch: ${context.branch} (compared against ${context.baseBranch}${at})`;
|
|
74
|
+
}
|
|
75
|
+
//# sourceMappingURL=git-context.js.map
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
export declare function git(args: string[], cwd: string): Promise<string>;
|
|
2
|
+
/**
|
|
3
|
+
* The commit `head` branched off the first of `refs` that resolves, or
|
|
4
|
+
* undefined when none does (no git, not a repository, or a shallow clone
|
|
5
|
+
* that never fetched the ref).
|
|
6
|
+
*/
|
|
7
|
+
export declare function findMergeBase(refs: string[], cwd: string, head?: string): Promise<{
|
|
8
|
+
ref: string;
|
|
9
|
+
base: string;
|
|
10
|
+
} | undefined>;
|
|
11
|
+
//# sourceMappingURL=git.d.ts.map
|
package/dist/core/git.js
ADDED
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
import { execFile } from 'node:child_process';
|
|
2
|
+
import { promisify } from 'node:util';
|
|
3
|
+
const execFileAsync = promisify(execFile);
|
|
4
|
+
export async function git(args, cwd) {
|
|
5
|
+
const { stdout } = await execFileAsync('git', args, { cwd, maxBuffer: 64 * 1024 * 1024 });
|
|
6
|
+
return stdout;
|
|
7
|
+
}
|
|
8
|
+
/**
|
|
9
|
+
* The commit `head` branched off the first of `refs` that resolves, or
|
|
10
|
+
* undefined when none does (no git, not a repository, or a shallow clone
|
|
11
|
+
* that never fetched the ref).
|
|
12
|
+
*/
|
|
13
|
+
export async function findMergeBase(refs, cwd, head = 'HEAD') {
|
|
14
|
+
for (const ref of refs) {
|
|
15
|
+
try {
|
|
16
|
+
const base = (await git(['merge-base', ref, head], cwd)).trim();
|
|
17
|
+
return { ref, base };
|
|
18
|
+
}
|
|
19
|
+
catch {
|
|
20
|
+
// Try the next candidate
|
|
21
|
+
}
|
|
22
|
+
}
|
|
23
|
+
return undefined;
|
|
24
|
+
}
|
|
25
|
+
//# sourceMappingURL=git.js.map
|
|
@@ -0,0 +1,7 @@
|
|
|
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
|
+
*/
|
|
6
|
+
export declare function hashScreenshot(buffer: Buffer): string;
|
|
7
|
+
//# sourceMappingURL=hash.d.ts.map
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import { createHash } from 'node:crypto';
|
|
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
|
+
*/
|
|
8
|
+
export function hashScreenshot(buffer) {
|
|
9
|
+
return createHash('sha256').update(withoutCaptureEnvironment(buffer)).digest('hex');
|
|
10
|
+
}
|
|
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
|
|
@@ -1,15 +1,71 @@
|
|
|
1
|
-
import
|
|
1
|
+
import { type Page } from 'playwright';
|
|
2
|
+
import type { Story, Screenshot, StorySnapConfig, Browser, Viewport } from '@storysnap/shared';
|
|
2
3
|
export declare class ScreenshotEngine {
|
|
3
4
|
private browsers;
|
|
5
|
+
/** Recorded in each browser's screenshots, for comparing baselines across machines. */
|
|
6
|
+
private environments;
|
|
4
7
|
private config;
|
|
5
8
|
private baseUrl;
|
|
6
9
|
constructor(config: StorySnapConfig);
|
|
7
10
|
initialize(): Promise<void>;
|
|
8
11
|
close(): Promise<void>;
|
|
9
|
-
|
|
12
|
+
/**
|
|
13
|
+
* Captures a story at each of its viewports, trying again up to
|
|
14
|
+
* `captureRetries` times when the capture throws. A story that needed a
|
|
15
|
+
* retry is marked flaky at every viewport.
|
|
16
|
+
*/
|
|
17
|
+
captureStoryWithRetries(story: Story, browserName: Browser): Promise<Screenshot[]>;
|
|
18
|
+
/**
|
|
19
|
+
* Captures a story once per viewport. The story's parameters, which can
|
|
20
|
+
* change the viewports, are only readable once it has rendered, so it is
|
|
21
|
+
* first loaded at the first configured viewport; every other viewport gets
|
|
22
|
+
* a page of its own, loaded at that size, rather than a resized one - a
|
|
23
|
+
* component that measures the window once on mount must look the way it
|
|
24
|
+
* would if opened at that size.
|
|
25
|
+
*/
|
|
26
|
+
captureStory(story: Story, browserName: Browser): Promise<Screenshot[]>;
|
|
27
|
+
/**
|
|
28
|
+
* Opens the story at a viewport, in a mode, and waits for Storybook to
|
|
29
|
+
* finish rendering it - play function included - and for its root to be
|
|
30
|
+
* visible. The mode's globals go in the URL, so the story renders - and its
|
|
31
|
+
* play function runs - in the mode from the start.
|
|
32
|
+
*/
|
|
33
|
+
private openStory;
|
|
34
|
+
/** Waits for a rendered story to settle as its parameters ask, then captures it. */
|
|
35
|
+
private shoot;
|
|
36
|
+
/** A screenshot with no image yet: the shape failures and skips are reported in. */
|
|
37
|
+
private blank;
|
|
38
|
+
private get freeze();
|
|
10
39
|
captureStories(stories: Story[], onProgress?: (completed: number, total: number, story: Story, browser: Browser) => void): Promise<Map<string, Screenshot>>;
|
|
11
|
-
private waitForStability;
|
|
12
40
|
}
|
|
41
|
+
/** Retries for a capture that throws: a timeout, a crashed page. */
|
|
42
|
+
export declare const DEFAULT_CAPTURE_RETRIES = 1;
|
|
43
|
+
/** How long to wait for images to load and decode before capturing anyway. */
|
|
44
|
+
export declare const ASSET_TIMEOUT_MS = 10000;
|
|
45
|
+
/**
|
|
46
|
+
* Waits for web fonts and for the images on the page to load and decode, so a
|
|
47
|
+
* capture never shows fallback glyphs or an empty image box. Lazy images
|
|
48
|
+
* outside the viewport are skipped, and an image that never loads holds the
|
|
49
|
+
* capture up for at most `timeoutMs`.
|
|
50
|
+
*/
|
|
51
|
+
export declare function waitForAssets(page: Page, timeoutMs?: number): Promise<void>;
|
|
52
|
+
export interface StabilityOptions {
|
|
53
|
+
/** Screenshots to take at most before settling for the last one. */
|
|
54
|
+
maxAttempts?: number;
|
|
55
|
+
/** Pause between two screenshots. */
|
|
56
|
+
intervalMs?: number;
|
|
57
|
+
}
|
|
58
|
+
/**
|
|
59
|
+
* Takes screenshots until two in a row are byte-identical and returns that
|
|
60
|
+
* one; if the page never settles, returns the last one taken with `stable`
|
|
61
|
+
* false. With animations frozen most pages match on the second screenshot, so
|
|
62
|
+
* this is usually quicker than a fixed settle delay while still catching late
|
|
63
|
+
* layout shifts.
|
|
64
|
+
*/
|
|
65
|
+
export declare function captureWhenStable(take: () => Promise<Buffer>, { maxAttempts, intervalMs }?: StabilityOptions): Promise<{
|
|
66
|
+
buffer: Buffer;
|
|
67
|
+
stable: boolean;
|
|
68
|
+
}>;
|
|
13
69
|
/**
|
|
14
70
|
* The first line of a capture error. Playwright appends a multi-line call log
|
|
15
71
|
* to its messages, which buries the actual reason when printed per story.
|
|
@@ -20,10 +76,41 @@ export declare const IGNORE_ATTRIBUTE = "data-storysnap-ignore";
|
|
|
20
76
|
export declare const DEFAULT_IGNORE_COLOR = "#808080";
|
|
21
77
|
/** The built-in attribute plus any selectors the config adds, as one selector list. */
|
|
22
78
|
export declare function getIgnoreSelector(extraSelectors?: readonly string[]): string;
|
|
23
|
-
|
|
79
|
+
/**
|
|
80
|
+
* The captures of each story in each browser - one per viewport, or a single
|
|
81
|
+
* failed one - keyed `storyId::browser`, in capture order.
|
|
82
|
+
*/
|
|
83
|
+
export declare function groupCaptures(screenshots: Map<string, Screenshot>): Map<string, Screenshot[]>;
|
|
84
|
+
/** ` @ 375x667` for a capture at a viewport other than the configured one; empty otherwise. */
|
|
85
|
+
export declare function viewportLabel(viewport: Viewport, configured: Viewport): string;
|
|
86
|
+
/** ` [dark] @ 375x667`: what tells a story's captures apart, after its name. */
|
|
87
|
+
export declare function captureLabel(capture: {
|
|
88
|
+
viewport: Viewport;
|
|
89
|
+
mode?: string;
|
|
90
|
+
}, configured: Viewport): string;
|
|
91
|
+
/** Identifies one capture: a story, in a browser, at a viewport, in a mode. */
|
|
92
|
+
export declare function getScreenshotKey(screenshot: {
|
|
93
|
+
storyId: string;
|
|
94
|
+
browser: Browser;
|
|
95
|
+
width: number;
|
|
96
|
+
height: number;
|
|
97
|
+
mode?: string;
|
|
98
|
+
}): string;
|
|
24
99
|
export declare function parseScreenshotKey(key: string): {
|
|
25
100
|
storyId: string;
|
|
26
101
|
browser: Browser;
|
|
102
|
+
viewport: Viewport;
|
|
103
|
+
mode: string;
|
|
104
|
+
};
|
|
105
|
+
/**
|
|
106
|
+
* Takes the stories their parameters disabled out of a capture: out of the
|
|
107
|
+
* story list, so totals and "not captured" counts leave them alone, and out
|
|
108
|
+
* of the screenshots, so nothing downstream mistakes them for failures.
|
|
109
|
+
* Parameters are the same in every browser, so one skip drops the story.
|
|
110
|
+
*/
|
|
111
|
+
export declare function dropSkipped(stories: Story[], screenshots: Map<string, Screenshot>): {
|
|
112
|
+
stories: Story[];
|
|
113
|
+
skipped: Story[];
|
|
27
114
|
};
|
|
28
115
|
export declare function captureScreenshots(config: StorySnapConfig, stories: Story[], onProgress?: (completed: number, total: number, story: Story, browser: Browser) => void): Promise<Map<string, Screenshot>>;
|
|
29
116
|
//# sourceMappingURL=screenshot.d.ts.map
|