@cappa/core 0.18.0 → 0.20.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/index.cjs +578 -32
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +193 -3
- package/dist/index.d.mts +193 -3
- package/dist/index.mjs +569 -34
- package/dist/index.mjs.map +1 -1
- package/dist/playwright.cjs +77 -0
- package/dist/playwright.cjs.map +1 -0
- package/dist/playwright.d.cts +117 -0
- package/dist/playwright.d.mts +117 -0
- package/dist/playwright.mjs +73 -0
- package/dist/playwright.mjs.map +1 -0
- package/package.json +5 -1
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
|
|
2
|
+
//#region src/playwright.ts
|
|
3
|
+
const DEFAULT_CONTAINER_IMAGE = "mcr.microsoft.com/playwright:v{version}-noble";
|
|
4
|
+
/**
|
|
5
|
+
* Validate `container` and fill in its defaults, or `null` when it is off.
|
|
6
|
+
*/
|
|
7
|
+
function resolveContainerOptions(container, env = process.env) {
|
|
8
|
+
if (container === void 0 || container === false) return null;
|
|
9
|
+
const invalid = (detail) => /* @__PURE__ */ new Error(`Invalid browser config: playwright({ container }) ${detail}.`);
|
|
10
|
+
if (container !== true && (typeof container !== "object" || !container)) throw invalid("must be a boolean or an object");
|
|
11
|
+
const options = container === true ? {} : container;
|
|
12
|
+
const cli = options.cli ?? env.CAPPA_CONTAINER_CLI ?? "docker";
|
|
13
|
+
if (typeof cli !== "string" || cli.trim() === "") throw invalid("cli must be a non-empty string");
|
|
14
|
+
const image = options.image ?? "mcr.microsoft.com/playwright:v{version}-noble";
|
|
15
|
+
if (typeof image !== "string" || image.trim() === "") throw invalid("image must be a non-empty string");
|
|
16
|
+
const runArgs = options.runArgs ?? [];
|
|
17
|
+
if (!Array.isArray(runArgs) || runArgs.some((a) => typeof a !== "string")) throw invalid("runArgs must be an array of strings");
|
|
18
|
+
const keepAlive = options.keepAlive ?? true;
|
|
19
|
+
if (typeof keepAlive !== "boolean") throw invalid("keepAlive must be a boolean");
|
|
20
|
+
const readyTimeout = options.readyTimeout ?? 3e5;
|
|
21
|
+
if (typeof readyTimeout !== "number" || !Number.isFinite(readyTimeout) || readyTimeout <= 0) throw invalid("readyTimeout must be a positive number");
|
|
22
|
+
return {
|
|
23
|
+
cli: cli.trim(),
|
|
24
|
+
image,
|
|
25
|
+
runArgs,
|
|
26
|
+
keepAlive,
|
|
27
|
+
readyTimeout
|
|
28
|
+
};
|
|
29
|
+
}
|
|
30
|
+
/**
|
|
31
|
+
* The Playwright browser provider.
|
|
32
|
+
*
|
|
33
|
+
* @example
|
|
34
|
+
* browser: {
|
|
35
|
+
* provider: playwright({
|
|
36
|
+
* connectOptions: { wsEndpoint: process.env.CAPPA_BROWSER_WS },
|
|
37
|
+
* }),
|
|
38
|
+
* }
|
|
39
|
+
*/
|
|
40
|
+
const playwright = (options = {}) => ({
|
|
41
|
+
name: "playwright",
|
|
42
|
+
options
|
|
43
|
+
});
|
|
44
|
+
const BROWSER_NAMES = [
|
|
45
|
+
"chromium",
|
|
46
|
+
"firefox",
|
|
47
|
+
"webkit"
|
|
48
|
+
];
|
|
49
|
+
/**
|
|
50
|
+
* Fill in `browser` defaults and reject what cappa cannot do yet.
|
|
51
|
+
*
|
|
52
|
+
* Idempotent, so it is safe to run on an already-resolved config.
|
|
53
|
+
*/
|
|
54
|
+
function resolveBrowserConfig(config = {}) {
|
|
55
|
+
const provider = config.provider ?? playwright();
|
|
56
|
+
if (provider.name !== "playwright") throw new Error(`Invalid browser config: unknown provider "${String(provider.name)}". Use playwright() from "@cappa/core/playwright".`);
|
|
57
|
+
const instances = config.instances ?? [{ browser: "chromium" }];
|
|
58
|
+
if (!Array.isArray(instances) || instances.length !== 1) throw new Error(`Invalid browser config: browser.instances must have exactly one entry (got ${Array.isArray(instances) ? instances.length : typeof instances}). Capturing with several browsers in one run is not supported yet.`);
|
|
59
|
+
resolveContainerOptions(provider.options?.container, {});
|
|
60
|
+
const [instance] = instances;
|
|
61
|
+
if (!BROWSER_NAMES.includes(instance.browser)) throw new Error(`Invalid browser config: unsupported browser "${String(instance.browser)}". Use one of ${BROWSER_NAMES.join(", ")}.`);
|
|
62
|
+
return {
|
|
63
|
+
provider: {
|
|
64
|
+
name: "playwright",
|
|
65
|
+
options: provider.options ?? {}
|
|
66
|
+
},
|
|
67
|
+
headless: config.headless ?? true,
|
|
68
|
+
instances: [{ browser: instance.browser }]
|
|
69
|
+
};
|
|
70
|
+
}
|
|
71
|
+
//#endregion
|
|
72
|
+
exports.DEFAULT_CONTAINER_IMAGE = DEFAULT_CONTAINER_IMAGE;
|
|
73
|
+
exports.playwright = playwright;
|
|
74
|
+
exports.resolveBrowserConfig = resolveBrowserConfig;
|
|
75
|
+
exports.resolveContainerOptions = resolveContainerOptions;
|
|
76
|
+
|
|
77
|
+
//# sourceMappingURL=playwright.cjs.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"playwright.cjs","names":[],"sources":["../src/playwright.ts"],"sourcesContent":["import type {\n BrowserContextOptions,\n ConnectOptions,\n LaunchOptions,\n} from \"playwright-core\";\n\n/**\n * Options for the `playwright()` browser provider.\n *\n * Same names and semantics as `@vitest/browser-playwright`, so a\n * `connectOptions` block can be copied between a Vitest browser-mode config\n * and `cappa.config.ts`.\n */\nexport type PlaywrightProviderOptions = {\n /** Passed to `browserType.launch()`. `headless` is ignored — use `browser.headless`. */\n launchOptions?: Omit<LaunchOptions, \"headless\">;\n /**\n * Passed to `browserType.connect()`. Only used when `wsEndpoint` is set;\n * otherwise cappa launches locally. `launchOptions` and `headless` are\n * forwarded via the `x-playwright-launch-options` header (honoured by\n * `playwright run-server`).\n */\n connectOptions?: ConnectOptions & { wsEndpoint?: string };\n /**\n * Passed to `browser.newContext()`, merged over cappa's defaults\n * (`reducedMotion: \"reduce\"`, `deviceScaleFactor: 2`). `viewport` is\n * omitted — use `screenshot.viewport`. A custom `userAgent` keeps cappa's\n * `CappaStorybook` suffix, which `isCappa()` depends on.\n */\n contextOptions?: Omit<BrowserContextOptions, \"viewport\">;\n /** `context.setDefaultTimeout()` for plugin actions. Default: none. */\n actionTimeout?: number;\n /**\n * Run the browser in the official Playwright container image matching the\n * installed `playwright-core` version, started (or reused) by cappa through\n * a container CLI. `true` uses every default. Ignored while\n * `connectOptions.wsEndpoint` is set, so an env var can still point\n * elsewhere. Defaults `connectOptions.exposeNetwork` to `\"<loopback>\"`.\n */\n container?: boolean | ContainerOptions;\n};\n\n/** `PlaywrightProviderOptions.container` as an object. */\nexport type ContainerOptions = {\n /**\n * Container CLI: anything with docker's `run`/`inspect`/`port`/`pull`/\n * `logs`/`rm` subcommands — `docker`, `podman`, `nerdctl`.\n * @default process.env.CAPPA_CONTAINER_CLI ?? \"docker\"\n */\n cli?: string;\n /**\n * Image to run; `{version}` is replaced with the `playwright-core` version.\n * A custom image (extra fonts, say) should be built `FROM` the official one\n * for the same version.\n * @default \"mcr.microsoft.com/playwright:v{version}-noble\"\n */\n image?: string;\n /** Extra arguments for `<cli> run`, placed before the image. */\n runArgs?: string[];\n /**\n * Leave the container running after cappa exits, so the next run connects\n * instantly. `cappa browser down` removes it.\n * @default true\n */\n keepAlive?: boolean;\n /**\n * How long to wait for the server, in ms — the first start pulls the image.\n * @default 300_000\n */\n readyTimeout?: number;\n};\n\n/** `ContainerOptions` with every default filled in. */\nexport type ResolvedContainerOptions = Required<ContainerOptions>;\n\nexport const DEFAULT_CONTAINER_IMAGE =\n \"mcr.microsoft.com/playwright:v{version}-noble\";\n\n/**\n * Validate `container` and fill in its defaults, or `null` when it is off.\n */\nexport function resolveContainerOptions(\n container: PlaywrightProviderOptions[\"container\"],\n env: Record<string, string | undefined> = process.env,\n): ResolvedContainerOptions | null {\n if (container === undefined || container === false) return null;\n const invalid = (detail: string) =>\n new Error(`Invalid browser config: playwright({ container }) ${detail}.`);\n\n if (container !== true && (typeof container !== \"object\" || !container)) {\n throw invalid(\"must be a boolean or an object\");\n }\n const options = container === true ? {} : container;\n\n const cli = options.cli ?? env.CAPPA_CONTAINER_CLI ?? \"docker\";\n if (typeof cli !== \"string\" || cli.trim() === \"\") {\n throw invalid(\"cli must be a non-empty string\");\n }\n const image = options.image ?? DEFAULT_CONTAINER_IMAGE;\n if (typeof image !== \"string\" || image.trim() === \"\") {\n throw invalid(\"image must be a non-empty string\");\n }\n const runArgs = options.runArgs ?? [];\n if (!Array.isArray(runArgs) || runArgs.some((a) => typeof a !== \"string\")) {\n throw invalid(\"runArgs must be an array of strings\");\n }\n const keepAlive = options.keepAlive ?? true;\n if (typeof keepAlive !== \"boolean\") {\n throw invalid(\"keepAlive must be a boolean\");\n }\n const readyTimeout = options.readyTimeout ?? 300_000;\n if (\n typeof readyTimeout !== \"number\" ||\n !Number.isFinite(readyTimeout) ||\n readyTimeout <= 0\n ) {\n throw invalid(\"readyTimeout must be a positive number\");\n }\n\n return { cli: cli.trim(), image, runArgs, keepAlive, readyTimeout };\n}\n\nexport type BrowserProvider = {\n name: \"playwright\";\n options: PlaywrightProviderOptions;\n};\n\nexport type BrowserName = \"chromium\" | \"firefox\" | \"webkit\";\n\nexport type BrowserInstance = { browser: BrowserName };\n\n/** `UserConfig.browser`. */\nexport type BrowserConfig = {\n /** @default playwright() */\n provider?: BrowserProvider;\n /** @default true */\n headless?: boolean;\n /** Exactly one entry for now. @default [{ browser: \"chromium\" }] */\n instances?: [BrowserInstance];\n};\n\n/** `BrowserConfig` with every default filled in. */\nexport type ResolvedBrowserConfig = {\n provider: BrowserProvider;\n headless: boolean;\n instances: [BrowserInstance];\n};\n\n/**\n * The Playwright browser provider.\n *\n * @example\n * browser: {\n * provider: playwright({\n * connectOptions: { wsEndpoint: process.env.CAPPA_BROWSER_WS },\n * }),\n * }\n */\nexport const playwright = (\n options: PlaywrightProviderOptions = {},\n): BrowserProvider => ({ name: \"playwright\", options });\n\nconst BROWSER_NAMES: readonly BrowserName[] = [\"chromium\", \"firefox\", \"webkit\"];\n\n/**\n * Fill in `browser` defaults and reject what cappa cannot do yet.\n *\n * Idempotent, so it is safe to run on an already-resolved config.\n */\nexport function resolveBrowserConfig(\n config: BrowserConfig | undefined = {},\n): ResolvedBrowserConfig {\n const provider = config.provider ?? playwright();\n if (provider.name !== \"playwright\") {\n throw new Error(\n `Invalid browser config: unknown provider \"${String(provider.name)}\". Use playwright() from \"@cappa/core/playwright\".`,\n );\n }\n\n const instances = (config.instances ?? [{ browser: \"chromium\" }]) as\n | BrowserInstance[]\n | undefined;\n if (!Array.isArray(instances) || instances.length !== 1) {\n throw new Error(\n `Invalid browser config: browser.instances must have exactly one entry (got ${\n Array.isArray(instances) ? instances.length : typeof instances\n }). Capturing with several browsers in one run is not supported yet.`,\n );\n }\n\n resolveContainerOptions(provider.options?.container, {});\n\n const [instance] = instances as [BrowserInstance];\n if (!BROWSER_NAMES.includes(instance.browser)) {\n throw new Error(\n `Invalid browser config: unsupported browser \"${String(instance.browser)}\". Use one of ${BROWSER_NAMES.join(\", \")}.`,\n );\n }\n\n return {\n provider: { name: \"playwright\", options: provider.options ?? {} },\n headless: config.headless ?? true,\n instances: [{ browser: instance.browser }],\n };\n}\n"],"mappings":";;AA2EA,MAAa,0BACX;;;;AAKF,SAAgB,wBACd,WACA,MAA0C,QAAQ,KACjB;CACjC,IAAI,cAAc,KAAA,KAAa,cAAc,OAAO,OAAO;CAC3D,MAAM,WAAW,2BACf,IAAI,MAAM,qDAAqD,OAAO,EAAE;CAE1E,IAAI,cAAc,SAAS,OAAO,cAAc,YAAY,CAAC,YAC3D,MAAM,QAAQ,gCAAgC;CAEhD,MAAM,UAAU,cAAc,OAAO,CAAC,IAAI;CAE1C,MAAM,MAAM,QAAQ,OAAO,IAAI,uBAAuB;CACtD,IAAI,OAAO,QAAQ,YAAY,IAAI,KAAK,MAAM,IAC5C,MAAM,QAAQ,gCAAgC;CAEhD,MAAM,QAAQ,QAAQ,SAAA;CACtB,IAAI,OAAO,UAAU,YAAY,MAAM,KAAK,MAAM,IAChD,MAAM,QAAQ,kCAAkC;CAElD,MAAM,UAAU,QAAQ,WAAW,CAAC;CACpC,IAAI,CAAC,MAAM,QAAQ,OAAO,KAAK,QAAQ,MAAM,MAAM,OAAO,MAAM,QAAQ,GACtE,MAAM,QAAQ,qCAAqC;CAErD,MAAM,YAAY,QAAQ,aAAa;CACvC,IAAI,OAAO,cAAc,WACvB,MAAM,QAAQ,6BAA6B;CAE7C,MAAM,eAAe,QAAQ,gBAAgB;CAC7C,IACE,OAAO,iBAAiB,YACxB,CAAC,OAAO,SAAS,YAAY,KAC7B,gBAAgB,GAEhB,MAAM,QAAQ,wCAAwC;CAGxD,OAAO;EAAE,KAAK,IAAI,KAAK;EAAG;EAAO;EAAS;EAAW;CAAa;AACpE;;;;;;;;;;;AAsCA,MAAa,cACX,UAAqC,CAAC,OACjB;CAAE,MAAM;CAAc;AAAQ;AAErD,MAAM,gBAAwC;CAAC;CAAY;CAAW;AAAQ;;;;;;AAO9E,SAAgB,qBACd,SAAoC,CAAC,GACd;CACvB,MAAM,WAAW,OAAO,YAAY,WAAW;CAC/C,IAAI,SAAS,SAAS,cACpB,MAAM,IAAI,MACR,6CAA6C,OAAO,SAAS,IAAI,EAAE,mDACrE;CAGF,MAAM,YAAa,OAAO,aAAa,CAAC,EAAE,SAAS,WAAW,CAAC;CAG/D,IAAI,CAAC,MAAM,QAAQ,SAAS,KAAK,UAAU,WAAW,GACpD,MAAM,IAAI,MACR,8EACE,MAAM,QAAQ,SAAS,IAAI,UAAU,SAAS,OAAO,UACtD,oEACH;CAGF,wBAAwB,SAAS,SAAS,WAAW,CAAC,CAAC;CAEvD,MAAM,CAAC,YAAY;CACnB,IAAI,CAAC,cAAc,SAAS,SAAS,OAAO,GAC1C,MAAM,IAAI,MACR,gDAAgD,OAAO,SAAS,OAAO,EAAE,gBAAgB,cAAc,KAAK,IAAI,EAAE,EACpH;CAGF,OAAO;EACL,UAAU;GAAE,MAAM;GAAc,SAAS,SAAS,WAAW,CAAC;EAAE;EAChE,UAAU,OAAO,YAAY;EAC7B,WAAW,CAAC,EAAE,SAAS,SAAS,QAAQ,CAAC;CAC3C;AACF"}
|
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
import { BrowserContextOptions, ConnectOptions, LaunchOptions } from "playwright-core";
|
|
2
|
+
//#region src/playwright.d.ts
|
|
3
|
+
/**
|
|
4
|
+
* Options for the `playwright()` browser provider.
|
|
5
|
+
*
|
|
6
|
+
* Same names and semantics as `@vitest/browser-playwright`, so a
|
|
7
|
+
* `connectOptions` block can be copied between a Vitest browser-mode config
|
|
8
|
+
* and `cappa.config.ts`.
|
|
9
|
+
*/
|
|
10
|
+
export type PlaywrightProviderOptions = {
|
|
11
|
+
/** Passed to `browserType.launch()`. `headless` is ignored — use `browser.headless`. */
|
|
12
|
+
launchOptions?: Omit<LaunchOptions, "headless">;
|
|
13
|
+
/**
|
|
14
|
+
* Passed to `browserType.connect()`. Only used when `wsEndpoint` is set;
|
|
15
|
+
* otherwise cappa launches locally. `launchOptions` and `headless` are
|
|
16
|
+
* forwarded via the `x-playwright-launch-options` header (honoured by
|
|
17
|
+
* `playwright run-server`).
|
|
18
|
+
*/
|
|
19
|
+
connectOptions?: ConnectOptions & {
|
|
20
|
+
wsEndpoint?: string;
|
|
21
|
+
};
|
|
22
|
+
/**
|
|
23
|
+
* Passed to `browser.newContext()`, merged over cappa's defaults
|
|
24
|
+
* (`reducedMotion: "reduce"`, `deviceScaleFactor: 2`). `viewport` is
|
|
25
|
+
* omitted — use `screenshot.viewport`. A custom `userAgent` keeps cappa's
|
|
26
|
+
* `CappaStorybook` suffix, which `isCappa()` depends on.
|
|
27
|
+
*/
|
|
28
|
+
contextOptions?: Omit<BrowserContextOptions, "viewport">;
|
|
29
|
+
/** `context.setDefaultTimeout()` for plugin actions. Default: none. */
|
|
30
|
+
actionTimeout?: number;
|
|
31
|
+
/**
|
|
32
|
+
* Run the browser in the official Playwright container image matching the
|
|
33
|
+
* installed `playwright-core` version, started (or reused) by cappa through
|
|
34
|
+
* a container CLI. `true` uses every default. Ignored while
|
|
35
|
+
* `connectOptions.wsEndpoint` is set, so an env var can still point
|
|
36
|
+
* elsewhere. Defaults `connectOptions.exposeNetwork` to `"<loopback>"`.
|
|
37
|
+
*/
|
|
38
|
+
container?: boolean | ContainerOptions;
|
|
39
|
+
};
|
|
40
|
+
/** `PlaywrightProviderOptions.container` as an object. */
|
|
41
|
+
export type ContainerOptions = {
|
|
42
|
+
/**
|
|
43
|
+
* Container CLI: anything with docker's `run`/`inspect`/`port`/`pull`/
|
|
44
|
+
* `logs`/`rm` subcommands — `docker`, `podman`, `nerdctl`.
|
|
45
|
+
* @default process.env.CAPPA_CONTAINER_CLI ?? "docker"
|
|
46
|
+
*/
|
|
47
|
+
cli?: string;
|
|
48
|
+
/**
|
|
49
|
+
* Image to run; `{version}` is replaced with the `playwright-core` version.
|
|
50
|
+
* A custom image (extra fonts, say) should be built `FROM` the official one
|
|
51
|
+
* for the same version.
|
|
52
|
+
* @default "mcr.microsoft.com/playwright:v{version}-noble"
|
|
53
|
+
*/
|
|
54
|
+
image?: string;
|
|
55
|
+
/** Extra arguments for `<cli> run`, placed before the image. */
|
|
56
|
+
runArgs?: string[];
|
|
57
|
+
/**
|
|
58
|
+
* Leave the container running after cappa exits, so the next run connects
|
|
59
|
+
* instantly. `cappa browser down` removes it.
|
|
60
|
+
* @default true
|
|
61
|
+
*/
|
|
62
|
+
keepAlive?: boolean;
|
|
63
|
+
/**
|
|
64
|
+
* How long to wait for the server, in ms — the first start pulls the image.
|
|
65
|
+
* @default 300_000
|
|
66
|
+
*/
|
|
67
|
+
readyTimeout?: number;
|
|
68
|
+
};
|
|
69
|
+
/** `ContainerOptions` with every default filled in. */
|
|
70
|
+
export type ResolvedContainerOptions = Required<ContainerOptions>;
|
|
71
|
+
export declare const DEFAULT_CONTAINER_IMAGE = "mcr.microsoft.com/playwright:v{version}-noble";
|
|
72
|
+
/**
|
|
73
|
+
* Validate `container` and fill in its defaults, or `null` when it is off.
|
|
74
|
+
*/
|
|
75
|
+
export declare function resolveContainerOptions(container: PlaywrightProviderOptions["container"], env?: Record<string, string | undefined>): ResolvedContainerOptions | null;
|
|
76
|
+
export type BrowserProvider = {
|
|
77
|
+
name: "playwright";
|
|
78
|
+
options: PlaywrightProviderOptions;
|
|
79
|
+
};
|
|
80
|
+
export type BrowserName = "chromium" | "firefox" | "webkit";
|
|
81
|
+
export type BrowserInstance = {
|
|
82
|
+
browser: BrowserName;
|
|
83
|
+
};
|
|
84
|
+
/** `UserConfig.browser`. */
|
|
85
|
+
export type BrowserConfig = {
|
|
86
|
+
/** @default playwright() */
|
|
87
|
+
provider?: BrowserProvider;
|
|
88
|
+
/** @default true */
|
|
89
|
+
headless?: boolean;
|
|
90
|
+
/** Exactly one entry for now. @default [{ browser: "chromium" }] */
|
|
91
|
+
instances?: [BrowserInstance];
|
|
92
|
+
};
|
|
93
|
+
/** `BrowserConfig` with every default filled in. */
|
|
94
|
+
export type ResolvedBrowserConfig = {
|
|
95
|
+
provider: BrowserProvider;
|
|
96
|
+
headless: boolean;
|
|
97
|
+
instances: [BrowserInstance];
|
|
98
|
+
};
|
|
99
|
+
/**
|
|
100
|
+
* The Playwright browser provider.
|
|
101
|
+
*
|
|
102
|
+
* @example
|
|
103
|
+
* browser: {
|
|
104
|
+
* provider: playwright({
|
|
105
|
+
* connectOptions: { wsEndpoint: process.env.CAPPA_BROWSER_WS },
|
|
106
|
+
* }),
|
|
107
|
+
* }
|
|
108
|
+
*/
|
|
109
|
+
export declare const playwright: (options?: PlaywrightProviderOptions) => BrowserProvider;
|
|
110
|
+
/**
|
|
111
|
+
* Fill in `browser` defaults and reject what cappa cannot do yet.
|
|
112
|
+
*
|
|
113
|
+
* Idempotent, so it is safe to run on an already-resolved config.
|
|
114
|
+
*/
|
|
115
|
+
export declare function resolveBrowserConfig(config?: BrowserConfig | undefined): ResolvedBrowserConfig;
|
|
116
|
+
//#endregion
|
|
117
|
+
//# sourceMappingURL=playwright.d.cts.map
|
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
import { BrowserContextOptions, ConnectOptions, LaunchOptions } from "playwright-core";
|
|
2
|
+
//#region src/playwright.d.ts
|
|
3
|
+
/**
|
|
4
|
+
* Options for the `playwright()` browser provider.
|
|
5
|
+
*
|
|
6
|
+
* Same names and semantics as `@vitest/browser-playwright`, so a
|
|
7
|
+
* `connectOptions` block can be copied between a Vitest browser-mode config
|
|
8
|
+
* and `cappa.config.ts`.
|
|
9
|
+
*/
|
|
10
|
+
export type PlaywrightProviderOptions = {
|
|
11
|
+
/** Passed to `browserType.launch()`. `headless` is ignored — use `browser.headless`. */
|
|
12
|
+
launchOptions?: Omit<LaunchOptions, "headless">;
|
|
13
|
+
/**
|
|
14
|
+
* Passed to `browserType.connect()`. Only used when `wsEndpoint` is set;
|
|
15
|
+
* otherwise cappa launches locally. `launchOptions` and `headless` are
|
|
16
|
+
* forwarded via the `x-playwright-launch-options` header (honoured by
|
|
17
|
+
* `playwright run-server`).
|
|
18
|
+
*/
|
|
19
|
+
connectOptions?: ConnectOptions & {
|
|
20
|
+
wsEndpoint?: string;
|
|
21
|
+
};
|
|
22
|
+
/**
|
|
23
|
+
* Passed to `browser.newContext()`, merged over cappa's defaults
|
|
24
|
+
* (`reducedMotion: "reduce"`, `deviceScaleFactor: 2`). `viewport` is
|
|
25
|
+
* omitted — use `screenshot.viewport`. A custom `userAgent` keeps cappa's
|
|
26
|
+
* `CappaStorybook` suffix, which `isCappa()` depends on.
|
|
27
|
+
*/
|
|
28
|
+
contextOptions?: Omit<BrowserContextOptions, "viewport">;
|
|
29
|
+
/** `context.setDefaultTimeout()` for plugin actions. Default: none. */
|
|
30
|
+
actionTimeout?: number;
|
|
31
|
+
/**
|
|
32
|
+
* Run the browser in the official Playwright container image matching the
|
|
33
|
+
* installed `playwright-core` version, started (or reused) by cappa through
|
|
34
|
+
* a container CLI. `true` uses every default. Ignored while
|
|
35
|
+
* `connectOptions.wsEndpoint` is set, so an env var can still point
|
|
36
|
+
* elsewhere. Defaults `connectOptions.exposeNetwork` to `"<loopback>"`.
|
|
37
|
+
*/
|
|
38
|
+
container?: boolean | ContainerOptions;
|
|
39
|
+
};
|
|
40
|
+
/** `PlaywrightProviderOptions.container` as an object. */
|
|
41
|
+
export type ContainerOptions = {
|
|
42
|
+
/**
|
|
43
|
+
* Container CLI: anything with docker's `run`/`inspect`/`port`/`pull`/
|
|
44
|
+
* `logs`/`rm` subcommands — `docker`, `podman`, `nerdctl`.
|
|
45
|
+
* @default process.env.CAPPA_CONTAINER_CLI ?? "docker"
|
|
46
|
+
*/
|
|
47
|
+
cli?: string;
|
|
48
|
+
/**
|
|
49
|
+
* Image to run; `{version}` is replaced with the `playwright-core` version.
|
|
50
|
+
* A custom image (extra fonts, say) should be built `FROM` the official one
|
|
51
|
+
* for the same version.
|
|
52
|
+
* @default "mcr.microsoft.com/playwright:v{version}-noble"
|
|
53
|
+
*/
|
|
54
|
+
image?: string;
|
|
55
|
+
/** Extra arguments for `<cli> run`, placed before the image. */
|
|
56
|
+
runArgs?: string[];
|
|
57
|
+
/**
|
|
58
|
+
* Leave the container running after cappa exits, so the next run connects
|
|
59
|
+
* instantly. `cappa browser down` removes it.
|
|
60
|
+
* @default true
|
|
61
|
+
*/
|
|
62
|
+
keepAlive?: boolean;
|
|
63
|
+
/**
|
|
64
|
+
* How long to wait for the server, in ms — the first start pulls the image.
|
|
65
|
+
* @default 300_000
|
|
66
|
+
*/
|
|
67
|
+
readyTimeout?: number;
|
|
68
|
+
};
|
|
69
|
+
/** `ContainerOptions` with every default filled in. */
|
|
70
|
+
export type ResolvedContainerOptions = Required<ContainerOptions>;
|
|
71
|
+
export declare const DEFAULT_CONTAINER_IMAGE = "mcr.microsoft.com/playwright:v{version}-noble";
|
|
72
|
+
/**
|
|
73
|
+
* Validate `container` and fill in its defaults, or `null` when it is off.
|
|
74
|
+
*/
|
|
75
|
+
export declare function resolveContainerOptions(container: PlaywrightProviderOptions["container"], env?: Record<string, string | undefined>): ResolvedContainerOptions | null;
|
|
76
|
+
export type BrowserProvider = {
|
|
77
|
+
name: "playwright";
|
|
78
|
+
options: PlaywrightProviderOptions;
|
|
79
|
+
};
|
|
80
|
+
export type BrowserName = "chromium" | "firefox" | "webkit";
|
|
81
|
+
export type BrowserInstance = {
|
|
82
|
+
browser: BrowserName;
|
|
83
|
+
};
|
|
84
|
+
/** `UserConfig.browser`. */
|
|
85
|
+
export type BrowserConfig = {
|
|
86
|
+
/** @default playwright() */
|
|
87
|
+
provider?: BrowserProvider;
|
|
88
|
+
/** @default true */
|
|
89
|
+
headless?: boolean;
|
|
90
|
+
/** Exactly one entry for now. @default [{ browser: "chromium" }] */
|
|
91
|
+
instances?: [BrowserInstance];
|
|
92
|
+
};
|
|
93
|
+
/** `BrowserConfig` with every default filled in. */
|
|
94
|
+
export type ResolvedBrowserConfig = {
|
|
95
|
+
provider: BrowserProvider;
|
|
96
|
+
headless: boolean;
|
|
97
|
+
instances: [BrowserInstance];
|
|
98
|
+
};
|
|
99
|
+
/**
|
|
100
|
+
* The Playwright browser provider.
|
|
101
|
+
*
|
|
102
|
+
* @example
|
|
103
|
+
* browser: {
|
|
104
|
+
* provider: playwright({
|
|
105
|
+
* connectOptions: { wsEndpoint: process.env.CAPPA_BROWSER_WS },
|
|
106
|
+
* }),
|
|
107
|
+
* }
|
|
108
|
+
*/
|
|
109
|
+
export declare const playwright: (options?: PlaywrightProviderOptions) => BrowserProvider;
|
|
110
|
+
/**
|
|
111
|
+
* Fill in `browser` defaults and reject what cappa cannot do yet.
|
|
112
|
+
*
|
|
113
|
+
* Idempotent, so it is safe to run on an already-resolved config.
|
|
114
|
+
*/
|
|
115
|
+
export declare function resolveBrowserConfig(config?: BrowserConfig | undefined): ResolvedBrowserConfig;
|
|
116
|
+
//#endregion
|
|
117
|
+
//# sourceMappingURL=playwright.d.mts.map
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
//#region src/playwright.ts
|
|
2
|
+
const DEFAULT_CONTAINER_IMAGE = "mcr.microsoft.com/playwright:v{version}-noble";
|
|
3
|
+
/**
|
|
4
|
+
* Validate `container` and fill in its defaults, or `null` when it is off.
|
|
5
|
+
*/
|
|
6
|
+
function resolveContainerOptions(container, env = process.env) {
|
|
7
|
+
if (container === void 0 || container === false) return null;
|
|
8
|
+
const invalid = (detail) => /* @__PURE__ */ new Error(`Invalid browser config: playwright({ container }) ${detail}.`);
|
|
9
|
+
if (container !== true && (typeof container !== "object" || !container)) throw invalid("must be a boolean or an object");
|
|
10
|
+
const options = container === true ? {} : container;
|
|
11
|
+
const cli = options.cli ?? env.CAPPA_CONTAINER_CLI ?? "docker";
|
|
12
|
+
if (typeof cli !== "string" || cli.trim() === "") throw invalid("cli must be a non-empty string");
|
|
13
|
+
const image = options.image ?? "mcr.microsoft.com/playwright:v{version}-noble";
|
|
14
|
+
if (typeof image !== "string" || image.trim() === "") throw invalid("image must be a non-empty string");
|
|
15
|
+
const runArgs = options.runArgs ?? [];
|
|
16
|
+
if (!Array.isArray(runArgs) || runArgs.some((a) => typeof a !== "string")) throw invalid("runArgs must be an array of strings");
|
|
17
|
+
const keepAlive = options.keepAlive ?? true;
|
|
18
|
+
if (typeof keepAlive !== "boolean") throw invalid("keepAlive must be a boolean");
|
|
19
|
+
const readyTimeout = options.readyTimeout ?? 3e5;
|
|
20
|
+
if (typeof readyTimeout !== "number" || !Number.isFinite(readyTimeout) || readyTimeout <= 0) throw invalid("readyTimeout must be a positive number");
|
|
21
|
+
return {
|
|
22
|
+
cli: cli.trim(),
|
|
23
|
+
image,
|
|
24
|
+
runArgs,
|
|
25
|
+
keepAlive,
|
|
26
|
+
readyTimeout
|
|
27
|
+
};
|
|
28
|
+
}
|
|
29
|
+
/**
|
|
30
|
+
* The Playwright browser provider.
|
|
31
|
+
*
|
|
32
|
+
* @example
|
|
33
|
+
* browser: {
|
|
34
|
+
* provider: playwright({
|
|
35
|
+
* connectOptions: { wsEndpoint: process.env.CAPPA_BROWSER_WS },
|
|
36
|
+
* }),
|
|
37
|
+
* }
|
|
38
|
+
*/
|
|
39
|
+
const playwright = (options = {}) => ({
|
|
40
|
+
name: "playwright",
|
|
41
|
+
options
|
|
42
|
+
});
|
|
43
|
+
const BROWSER_NAMES = [
|
|
44
|
+
"chromium",
|
|
45
|
+
"firefox",
|
|
46
|
+
"webkit"
|
|
47
|
+
];
|
|
48
|
+
/**
|
|
49
|
+
* Fill in `browser` defaults and reject what cappa cannot do yet.
|
|
50
|
+
*
|
|
51
|
+
* Idempotent, so it is safe to run on an already-resolved config.
|
|
52
|
+
*/
|
|
53
|
+
function resolveBrowserConfig(config = {}) {
|
|
54
|
+
const provider = config.provider ?? playwright();
|
|
55
|
+
if (provider.name !== "playwright") throw new Error(`Invalid browser config: unknown provider "${String(provider.name)}". Use playwright() from "@cappa/core/playwright".`);
|
|
56
|
+
const instances = config.instances ?? [{ browser: "chromium" }];
|
|
57
|
+
if (!Array.isArray(instances) || instances.length !== 1) throw new Error(`Invalid browser config: browser.instances must have exactly one entry (got ${Array.isArray(instances) ? instances.length : typeof instances}). Capturing with several browsers in one run is not supported yet.`);
|
|
58
|
+
resolveContainerOptions(provider.options?.container, {});
|
|
59
|
+
const [instance] = instances;
|
|
60
|
+
if (!BROWSER_NAMES.includes(instance.browser)) throw new Error(`Invalid browser config: unsupported browser "${String(instance.browser)}". Use one of ${BROWSER_NAMES.join(", ")}.`);
|
|
61
|
+
return {
|
|
62
|
+
provider: {
|
|
63
|
+
name: "playwright",
|
|
64
|
+
options: provider.options ?? {}
|
|
65
|
+
},
|
|
66
|
+
headless: config.headless ?? true,
|
|
67
|
+
instances: [{ browser: instance.browser }]
|
|
68
|
+
};
|
|
69
|
+
}
|
|
70
|
+
//#endregion
|
|
71
|
+
export { DEFAULT_CONTAINER_IMAGE, playwright, resolveBrowserConfig, resolveContainerOptions };
|
|
72
|
+
|
|
73
|
+
//# sourceMappingURL=playwright.mjs.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"playwright.mjs","names":[],"sources":["../src/playwright.ts"],"sourcesContent":["import type {\n BrowserContextOptions,\n ConnectOptions,\n LaunchOptions,\n} from \"playwright-core\";\n\n/**\n * Options for the `playwright()` browser provider.\n *\n * Same names and semantics as `@vitest/browser-playwright`, so a\n * `connectOptions` block can be copied between a Vitest browser-mode config\n * and `cappa.config.ts`.\n */\nexport type PlaywrightProviderOptions = {\n /** Passed to `browserType.launch()`. `headless` is ignored — use `browser.headless`. */\n launchOptions?: Omit<LaunchOptions, \"headless\">;\n /**\n * Passed to `browserType.connect()`. Only used when `wsEndpoint` is set;\n * otherwise cappa launches locally. `launchOptions` and `headless` are\n * forwarded via the `x-playwright-launch-options` header (honoured by\n * `playwright run-server`).\n */\n connectOptions?: ConnectOptions & { wsEndpoint?: string };\n /**\n * Passed to `browser.newContext()`, merged over cappa's defaults\n * (`reducedMotion: \"reduce\"`, `deviceScaleFactor: 2`). `viewport` is\n * omitted — use `screenshot.viewport`. A custom `userAgent` keeps cappa's\n * `CappaStorybook` suffix, which `isCappa()` depends on.\n */\n contextOptions?: Omit<BrowserContextOptions, \"viewport\">;\n /** `context.setDefaultTimeout()` for plugin actions. Default: none. */\n actionTimeout?: number;\n /**\n * Run the browser in the official Playwright container image matching the\n * installed `playwright-core` version, started (or reused) by cappa through\n * a container CLI. `true` uses every default. Ignored while\n * `connectOptions.wsEndpoint` is set, so an env var can still point\n * elsewhere. Defaults `connectOptions.exposeNetwork` to `\"<loopback>\"`.\n */\n container?: boolean | ContainerOptions;\n};\n\n/** `PlaywrightProviderOptions.container` as an object. */\nexport type ContainerOptions = {\n /**\n * Container CLI: anything with docker's `run`/`inspect`/`port`/`pull`/\n * `logs`/`rm` subcommands — `docker`, `podman`, `nerdctl`.\n * @default process.env.CAPPA_CONTAINER_CLI ?? \"docker\"\n */\n cli?: string;\n /**\n * Image to run; `{version}` is replaced with the `playwright-core` version.\n * A custom image (extra fonts, say) should be built `FROM` the official one\n * for the same version.\n * @default \"mcr.microsoft.com/playwright:v{version}-noble\"\n */\n image?: string;\n /** Extra arguments for `<cli> run`, placed before the image. */\n runArgs?: string[];\n /**\n * Leave the container running after cappa exits, so the next run connects\n * instantly. `cappa browser down` removes it.\n * @default true\n */\n keepAlive?: boolean;\n /**\n * How long to wait for the server, in ms — the first start pulls the image.\n * @default 300_000\n */\n readyTimeout?: number;\n};\n\n/** `ContainerOptions` with every default filled in. */\nexport type ResolvedContainerOptions = Required<ContainerOptions>;\n\nexport const DEFAULT_CONTAINER_IMAGE =\n \"mcr.microsoft.com/playwright:v{version}-noble\";\n\n/**\n * Validate `container` and fill in its defaults, or `null` when it is off.\n */\nexport function resolveContainerOptions(\n container: PlaywrightProviderOptions[\"container\"],\n env: Record<string, string | undefined> = process.env,\n): ResolvedContainerOptions | null {\n if (container === undefined || container === false) return null;\n const invalid = (detail: string) =>\n new Error(`Invalid browser config: playwright({ container }) ${detail}.`);\n\n if (container !== true && (typeof container !== \"object\" || !container)) {\n throw invalid(\"must be a boolean or an object\");\n }\n const options = container === true ? {} : container;\n\n const cli = options.cli ?? env.CAPPA_CONTAINER_CLI ?? \"docker\";\n if (typeof cli !== \"string\" || cli.trim() === \"\") {\n throw invalid(\"cli must be a non-empty string\");\n }\n const image = options.image ?? DEFAULT_CONTAINER_IMAGE;\n if (typeof image !== \"string\" || image.trim() === \"\") {\n throw invalid(\"image must be a non-empty string\");\n }\n const runArgs = options.runArgs ?? [];\n if (!Array.isArray(runArgs) || runArgs.some((a) => typeof a !== \"string\")) {\n throw invalid(\"runArgs must be an array of strings\");\n }\n const keepAlive = options.keepAlive ?? true;\n if (typeof keepAlive !== \"boolean\") {\n throw invalid(\"keepAlive must be a boolean\");\n }\n const readyTimeout = options.readyTimeout ?? 300_000;\n if (\n typeof readyTimeout !== \"number\" ||\n !Number.isFinite(readyTimeout) ||\n readyTimeout <= 0\n ) {\n throw invalid(\"readyTimeout must be a positive number\");\n }\n\n return { cli: cli.trim(), image, runArgs, keepAlive, readyTimeout };\n}\n\nexport type BrowserProvider = {\n name: \"playwright\";\n options: PlaywrightProviderOptions;\n};\n\nexport type BrowserName = \"chromium\" | \"firefox\" | \"webkit\";\n\nexport type BrowserInstance = { browser: BrowserName };\n\n/** `UserConfig.browser`. */\nexport type BrowserConfig = {\n /** @default playwright() */\n provider?: BrowserProvider;\n /** @default true */\n headless?: boolean;\n /** Exactly one entry for now. @default [{ browser: \"chromium\" }] */\n instances?: [BrowserInstance];\n};\n\n/** `BrowserConfig` with every default filled in. */\nexport type ResolvedBrowserConfig = {\n provider: BrowserProvider;\n headless: boolean;\n instances: [BrowserInstance];\n};\n\n/**\n * The Playwright browser provider.\n *\n * @example\n * browser: {\n * provider: playwright({\n * connectOptions: { wsEndpoint: process.env.CAPPA_BROWSER_WS },\n * }),\n * }\n */\nexport const playwright = (\n options: PlaywrightProviderOptions = {},\n): BrowserProvider => ({ name: \"playwright\", options });\n\nconst BROWSER_NAMES: readonly BrowserName[] = [\"chromium\", \"firefox\", \"webkit\"];\n\n/**\n * Fill in `browser` defaults and reject what cappa cannot do yet.\n *\n * Idempotent, so it is safe to run on an already-resolved config.\n */\nexport function resolveBrowserConfig(\n config: BrowserConfig | undefined = {},\n): ResolvedBrowserConfig {\n const provider = config.provider ?? playwright();\n if (provider.name !== \"playwright\") {\n throw new Error(\n `Invalid browser config: unknown provider \"${String(provider.name)}\". Use playwright() from \"@cappa/core/playwright\".`,\n );\n }\n\n const instances = (config.instances ?? [{ browser: \"chromium\" }]) as\n | BrowserInstance[]\n | undefined;\n if (!Array.isArray(instances) || instances.length !== 1) {\n throw new Error(\n `Invalid browser config: browser.instances must have exactly one entry (got ${\n Array.isArray(instances) ? instances.length : typeof instances\n }). Capturing with several browsers in one run is not supported yet.`,\n );\n }\n\n resolveContainerOptions(provider.options?.container, {});\n\n const [instance] = instances as [BrowserInstance];\n if (!BROWSER_NAMES.includes(instance.browser)) {\n throw new Error(\n `Invalid browser config: unsupported browser \"${String(instance.browser)}\". Use one of ${BROWSER_NAMES.join(\", \")}.`,\n );\n }\n\n return {\n provider: { name: \"playwright\", options: provider.options ?? {} },\n headless: config.headless ?? true,\n instances: [{ browser: instance.browser }],\n };\n}\n"],"mappings":";AA2EA,MAAa,0BACX;;;;AAKF,SAAgB,wBACd,WACA,MAA0C,QAAQ,KACjB;CACjC,IAAI,cAAc,KAAA,KAAa,cAAc,OAAO,OAAO;CAC3D,MAAM,WAAW,2BACf,IAAI,MAAM,qDAAqD,OAAO,EAAE;CAE1E,IAAI,cAAc,SAAS,OAAO,cAAc,YAAY,CAAC,YAC3D,MAAM,QAAQ,gCAAgC;CAEhD,MAAM,UAAU,cAAc,OAAO,CAAC,IAAI;CAE1C,MAAM,MAAM,QAAQ,OAAO,IAAI,uBAAuB;CACtD,IAAI,OAAO,QAAQ,YAAY,IAAI,KAAK,MAAM,IAC5C,MAAM,QAAQ,gCAAgC;CAEhD,MAAM,QAAQ,QAAQ,SAAA;CACtB,IAAI,OAAO,UAAU,YAAY,MAAM,KAAK,MAAM,IAChD,MAAM,QAAQ,kCAAkC;CAElD,MAAM,UAAU,QAAQ,WAAW,CAAC;CACpC,IAAI,CAAC,MAAM,QAAQ,OAAO,KAAK,QAAQ,MAAM,MAAM,OAAO,MAAM,QAAQ,GACtE,MAAM,QAAQ,qCAAqC;CAErD,MAAM,YAAY,QAAQ,aAAa;CACvC,IAAI,OAAO,cAAc,WACvB,MAAM,QAAQ,6BAA6B;CAE7C,MAAM,eAAe,QAAQ,gBAAgB;CAC7C,IACE,OAAO,iBAAiB,YACxB,CAAC,OAAO,SAAS,YAAY,KAC7B,gBAAgB,GAEhB,MAAM,QAAQ,wCAAwC;CAGxD,OAAO;EAAE,KAAK,IAAI,KAAK;EAAG;EAAO;EAAS;EAAW;CAAa;AACpE;;;;;;;;;;;AAsCA,MAAa,cACX,UAAqC,CAAC,OACjB;CAAE,MAAM;CAAc;AAAQ;AAErD,MAAM,gBAAwC;CAAC;CAAY;CAAW;AAAQ;;;;;;AAO9E,SAAgB,qBACd,SAAoC,CAAC,GACd;CACvB,MAAM,WAAW,OAAO,YAAY,WAAW;CAC/C,IAAI,SAAS,SAAS,cACpB,MAAM,IAAI,MACR,6CAA6C,OAAO,SAAS,IAAI,EAAE,mDACrE;CAGF,MAAM,YAAa,OAAO,aAAa,CAAC,EAAE,SAAS,WAAW,CAAC;CAG/D,IAAI,CAAC,MAAM,QAAQ,SAAS,KAAK,UAAU,WAAW,GACpD,MAAM,IAAI,MACR,8EACE,MAAM,QAAQ,SAAS,IAAI,UAAU,SAAS,OAAO,UACtD,oEACH;CAGF,wBAAwB,SAAS,SAAS,WAAW,CAAC,CAAC;CAEvD,MAAM,CAAC,YAAY;CACnB,IAAI,CAAC,cAAc,SAAS,SAAS,OAAO,GAC1C,MAAM,IAAI,MACR,gDAAgD,OAAO,SAAS,OAAO,EAAE,gBAAgB,cAAc,KAAK,IAAI,EAAE,EACpH;CAGF,OAAO;EACL,UAAU;GAAE,MAAM;GAAc,SAAS,SAAS,WAAW,CAAC;EAAE;EAChE,UAAU,OAAO,YAAY;EAC7B,WAAW,CAAC,EAAE,SAAS,SAAS,QAAQ,CAAC;CAC3C;AACF"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@cappa/core",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.20.0",
|
|
4
4
|
"description": "Core Playwright screenshot functionality for Cappa",
|
|
5
5
|
"author": "Tim Richter",
|
|
6
6
|
"repository": {
|
|
@@ -22,6 +22,10 @@
|
|
|
22
22
|
"import": "./dist/index.mjs",
|
|
23
23
|
"require": "./dist/index.cjs"
|
|
24
24
|
},
|
|
25
|
+
"./playwright": {
|
|
26
|
+
"import": "./dist/playwright.mjs",
|
|
27
|
+
"require": "./dist/playwright.cjs"
|
|
28
|
+
},
|
|
25
29
|
"./package.json": "./package.json"
|
|
26
30
|
},
|
|
27
31
|
"peerDependencies": {
|