@a11y-pulse/browser-adaptor 0.4.0 → 0.5.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/README.md +7 -1
- package/dist/adaptor.d.ts +6 -4
- package/dist/adaptors/playwright.d.ts +11 -0
- package/dist/adaptors/playwright.js +8 -1
- package/dist/adaptors/playwright.js.map +1 -1
- package/dist/adaptors/puppeteer.d.ts +10 -0
- package/dist/adaptors/puppeteer.js +39 -13
- package/dist/adaptors/puppeteer.js.map +1 -1
- package/dist/chunk-QUDMCLZ7.js +13 -0
- package/dist/chunk-QUDMCLZ7.js.map +1 -0
- package/dist/paint.d.ts +4 -0
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -65,6 +65,12 @@ Consumers may ignore methods they do not need. `ensureFocusReporting` is best-ef
|
|
|
65
65
|
|
|
66
66
|
`PuppeteerAdaptor` wraps a Puppeteer `Page`. Its CDP session is cached per page, so reusing a page across audit runs does not open extra sessions.
|
|
67
67
|
|
|
68
|
+
Clipped screenshots go over that CDP session with `captureBeyondViewport` off, so only what is inside the current viewport is captured. Chromium honours `captureBeyondViewport` by shrinking the emulated viewport to 1x1 and resizing it for the clip before restoring it, and the page sees each of those as a real resize: `resize` fires and media queries flip to their narrowest breakpoint, which can collapse a responsive layout and blur the focused element mid-capture. The tab-driven audits scroll each element into view before capturing. Pass `captureBeyondViewport: true` only for evidence of regions you cannot scroll to, where the page's state does not matter:
|
|
69
|
+
|
|
70
|
+
```js
|
|
71
|
+
new PuppeteerAdaptor(page, { captureBeyondViewport: true });
|
|
72
|
+
```
|
|
73
|
+
|
|
68
74
|
## Playwright adaptor
|
|
69
75
|
|
|
70
76
|
`PlaywrightAdaptor` wraps a Playwright `Page`, and works with either `playwright` or `playwright-core`.
|
|
@@ -88,7 +94,7 @@ Two differences from the Puppeteer adaptor are worth knowing about.
|
|
|
88
94
|
|
|
89
95
|
**`evaluate` needs `unsafe-eval`.** Playwright's `evaluate` takes a single argument, so the adaptor packs the page function's source and its arguments into one tuple and rebuilds the function in the page with `new Function`. A page whose Content-Security-Policy omits `unsafe-eval` from `script-src` will reject that; the adaptor throws a message naming CSP as the cause rather than letting it read as a page failure. Puppeteer is unaffected, because CDP serialises the function itself.
|
|
90
96
|
|
|
91
|
-
**Screenshot scale depends on the engine.** On Chromium the adaptor screenshots over CDP, which honours `screenshotClipScale` per capture
|
|
97
|
+
**Screenshot scale depends on the engine.** On Chromium the adaptor screenshots over CDP, which honours `screenshotClipScale` per capture, so evidence images match Puppeteer's; it takes the same `captureBeyondViewport` option, off by default for the same reason. Firefox and WebKit expose no CDP, so the adaptor falls back to a full-page capture at the context's own `deviceScaleFactor`, which those engines take without resizing the viewport. There, create the context with a `deviceScaleFactor` matching `screenshotClipScale` (2 by default), or pass the scale you want:
|
|
92
98
|
|
|
93
99
|
```js
|
|
94
100
|
new PlaywrightAdaptor(page, { screenshotClipScale: 1 });
|
package/dist/adaptor.d.ts
CHANGED
|
@@ -35,10 +35,12 @@ export interface BrowserAdaptor {
|
|
|
35
35
|
*/
|
|
36
36
|
pressEnter(): Promise<void>;
|
|
37
37
|
/**
|
|
38
|
-
* Screenshot a clipped region of the page defined by `clip
|
|
39
|
-
* (bitmap pixels per CSS pixel), multiplied against whatever
|
|
40
|
-
* currently has. The caller is responsible for the page being
|
|
41
|
-
* invoking this
|
|
38
|
+
* Screenshot a clipped region of the page defined by `clip`, in document coordinates. `scale` is
|
|
39
|
+
* the device scale factor (bitmap pixels per CSS pixel), multiplied against whatever
|
|
40
|
+
* deviceScaleFactor the page itself currently has. The caller is responsible for the page being
|
|
41
|
+
* at a known deviceScaleFactor before invoking this, and for the clip lying inside the current
|
|
42
|
+
* viewport: what falls outside it may come back blank. The capture must not change anything the
|
|
43
|
+
* page can observe, such as its viewport size. This function must return PNG bytes.
|
|
42
44
|
*/
|
|
43
45
|
screenshotClip(clip: Rect, scale?: number): Promise<Uint8Array>;
|
|
44
46
|
/** Device scale factor for evidence screenshots stored on failure. */
|
|
@@ -7,11 +7,22 @@ export type PlaywrightAdaptorOptions = {
|
|
|
7
7
|
* with, because Playwright's public screenshot API cannot rescale a single capture.
|
|
8
8
|
*/
|
|
9
9
|
screenshotClipScale?: number;
|
|
10
|
+
/**
|
|
11
|
+
* Let a Chromium clip capture content outside the current viewport. Defaults to false: to honour
|
|
12
|
+
* it Chromium shrinks the emulated viewport to 1x1 and then resizes it for the clip before
|
|
13
|
+
* restoring it, and the page observes each of those as a real resize (`resize` fires, media
|
|
14
|
+
* queries flip to their narrowest breakpoint), which can collapse a responsive layout and blur
|
|
15
|
+
* the focused element mid-capture. Only enable it for evidence of regions the caller cannot
|
|
16
|
+
* scroll into view, where the page's state does not matter. Firefox and WebKit capture the full
|
|
17
|
+
* page without resizing the viewport, so they ignore this.
|
|
18
|
+
*/
|
|
19
|
+
captureBeyondViewport?: boolean;
|
|
10
20
|
};
|
|
11
21
|
/** A BrowserAdaptor backed by a Playwright Page. */
|
|
12
22
|
export declare class PlaywrightAdaptor implements BrowserAdaptor {
|
|
13
23
|
private readonly page;
|
|
14
24
|
readonly screenshotClipScale: number;
|
|
25
|
+
private readonly captureBeyondViewport;
|
|
15
26
|
constructor(page: Page, options?: PlaywrightAdaptorOptions);
|
|
16
27
|
evaluate<T>(fn: (...args: any[]) => T | Promise<T>, ...args: unknown[]): Promise<T>;
|
|
17
28
|
evaluateHandle(fn: () => Element | null): Promise<ElementRef>;
|
|
@@ -1,3 +1,7 @@
|
|
|
1
|
+
import {
|
|
2
|
+
nextPaintScript
|
|
3
|
+
} from "../chunk-QUDMCLZ7.js";
|
|
4
|
+
|
|
1
5
|
// src/adaptors/playwright.ts
|
|
2
6
|
var cdpSessions = /* @__PURE__ */ new WeakMap();
|
|
3
7
|
var focusEmulatedPages = /* @__PURE__ */ new WeakSet();
|
|
@@ -23,9 +27,11 @@ var PlaywrightAdaptor = class {
|
|
|
23
27
|
constructor(page, options = {}) {
|
|
24
28
|
this.page = page;
|
|
25
29
|
this.screenshotClipScale = options.screenshotClipScale ?? DEFAULT_SCREENSHOT_CLIP_SCALE;
|
|
30
|
+
this.captureBeyondViewport = options.captureBeyondViewport ?? false;
|
|
26
31
|
}
|
|
27
32
|
page;
|
|
28
33
|
screenshotClipScale;
|
|
34
|
+
captureBeyondViewport;
|
|
29
35
|
async evaluate(fn, ...args) {
|
|
30
36
|
try {
|
|
31
37
|
return await this.page.evaluate(
|
|
@@ -56,11 +62,12 @@ var PlaywrightAdaptor = class {
|
|
|
56
62
|
await this.page.keyboard.press("Enter");
|
|
57
63
|
}
|
|
58
64
|
async screenshotClip(clip, scale = 1) {
|
|
65
|
+
await this.page.evaluate(nextPaintScript);
|
|
59
66
|
const session = await cdpSession(this.page);
|
|
60
67
|
if (session) {
|
|
61
68
|
const { data } = await session.send("Page.captureScreenshot", {
|
|
62
69
|
format: "png",
|
|
63
|
-
captureBeyondViewport:
|
|
70
|
+
captureBeyondViewport: this.captureBeyondViewport,
|
|
64
71
|
clip: { ...clip, scale }
|
|
65
72
|
});
|
|
66
73
|
return Buffer.from(data, "base64");
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../../src/adaptors/playwright.ts"],"sourcesContent":["import type { CDPSession, JSHandle, Page } from \"playwright-core\";\nimport type { BrowserAdaptor, ElementRef, Rect } from \"../adaptor\";\n\n// The CDP session for each page, shared by focus emulation and clipped screenshots. A fresh adaptor\n// is created per audit run, but a page often outlives one run, so without this each run would open\n// another session that is never detached. The session is kept attached for the page's lifetime:\n// Chrome clears focus emulation when the CDP client disconnects. Resolves to null on Firefox and\n// WebKit, where Playwright offers no CDP.\nconst cdpSessions = new WeakMap<Page, Promise<CDPSession | null>>();\n\n// Pages that have had focus emulation enabled at least once.\nconst focusEmulatedPages = new WeakSet<Page>();\n\nconst DEFAULT_SCREENSHOT_CLIP_SCALE = 2;\n\nconst EVAL_BLOCKED = /EvalError|unsafe-eval|Content Security Policy/i;\n\nfunction cdpSession(page: Page): Promise<CDPSession | null> {\n\tconst existing = cdpSessions.get(page);\n\n\tif (existing) {\n\t\treturn existing;\n\t}\n\n\tconst session = page\n\t\t.context()\n\t\t.newCDPSession(page)\n\t\t.catch(() => null);\n\tcdpSessions.set(page, session);\n\n\treturn session;\n}\n\nfunction isChromium(page: Page): boolean {\n\ttry {\n\t\treturn page.context().browser()?.browserType().name() === \"chromium\";\n\t} catch {\n\t\treturn false;\n\t}\n}\n\nexport type PlaywrightAdaptorOptions = {\n\t/**\n\t * Device scale factor for evidence screenshots. Defaults to 2. On Chromium any value is honoured\n\t * per capture. Elsewhere this must match the `deviceScaleFactor` the browser context was created\n\t * with, because Playwright's public screenshot API cannot rescale a single capture.\n\t */\n\tscreenshotClipScale?: number;\n};\n\n/** A BrowserAdaptor backed by a Playwright Page. */\nexport class PlaywrightAdaptor implements BrowserAdaptor {\n\treadonly screenshotClipScale: number;\n\n\tconstructor(\n\t\tprivate readonly page: Page,\n\t\toptions: PlaywrightAdaptorOptions = {},\n\t) {\n\t\tthis.screenshotClipScale = options.screenshotClipScale ?? DEFAULT_SCREENSHOT_CLIP_SCALE;\n\t}\n\n\tasync evaluate<T>(\n\t\t// biome-ignore lint/suspicious/noExplicitAny: the page-evaluated fn accepts arbitrary serialised args and element handles.\n\t\tfn: (...args: any[]) => T | Promise<T>,\n\t\t...args: unknown[]\n\t): Promise<T> {\n\t\ttry {\n\t\t\t// Playwright takes a single argument, so the function source and its args travel packed\n\t\t\t// into one tuple. Handles nested in that tuple are still resolved to live elements.\n\t\t\treturn (await this.page.evaluate(\n\t\t\t\t([source, packed]) => new Function(`return (${source})`)()(...(packed as unknown[])),\n\t\t\t\t[fn.toString(), args] as [string, unknown[]],\n\t\t\t)) as T;\n\t\t} catch (error) {\n\t\t\tconst message = error instanceof Error ? error.message : String(error);\n\n\t\t\tif (EVAL_BLOCKED.test(message)) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t\"The Playwright adaptor rebuilds page functions with new Function(), which this page's Content-Security-Policy blocks. Allow 'unsafe-eval' in script-src, or use the Puppeteer adaptor.\",\n\t\t\t\t\t{ cause: error },\n\t\t\t\t);\n\t\t\t}\n\n\t\t\tthrow error;\n\t\t}\n\t}\n\n\tevaluateHandle(fn: () => Element | null): Promise<ElementRef> {\n\t\treturn this.page.evaluateHandle(fn);\n\t}\n\n\tasync disposeRef(ref: ElementRef): Promise<void> {\n\t\tawait (ref as JSHandle).dispose();\n\t}\n\n\tasync pressTab(): Promise<void> {\n\t\tawait this.page.keyboard.press(\"Tab\");\n\t}\n\n\tasync pressEnter(): Promise<void> {\n\t\tawait this.page.keyboard.press(\"Enter\");\n\t}\n\n\tasync screenshotClip(clip: Rect, scale = 1): Promise<Uint8Array> {\n\t\tconst session = await cdpSession(this.page);\n\n\t\tif (session) {\n\t\t\t// The public API cannot scale one capture, and its `clip` is only honoured inside the\n\t\t\t// viewport. CDP is what Puppeteer drives too, so evidence images stay pixel-comparable.\n\t\t\tconst { data } = await session.send(\"Page.captureScreenshot\", {\n\t\t\t\tformat: \"png\",\n\t\t\t\tcaptureBeyondViewport:
|
|
1
|
+
{"version":3,"sources":["../../src/adaptors/playwright.ts"],"sourcesContent":["import type { CDPSession, JSHandle, Page } from \"playwright-core\";\nimport type { BrowserAdaptor, ElementRef, Rect } from \"../adaptor\";\nimport { nextPaintScript } from \"../paint\";\n\n// The CDP session for each page, shared by focus emulation and clipped screenshots. A fresh adaptor\n// is created per audit run, but a page often outlives one run, so without this each run would open\n// another session that is never detached. The session is kept attached for the page's lifetime:\n// Chrome clears focus emulation when the CDP client disconnects. Resolves to null on Firefox and\n// WebKit, where Playwright offers no CDP.\nconst cdpSessions = new WeakMap<Page, Promise<CDPSession | null>>();\n\n// Pages that have had focus emulation enabled at least once.\nconst focusEmulatedPages = new WeakSet<Page>();\n\nconst DEFAULT_SCREENSHOT_CLIP_SCALE = 2;\n\nconst EVAL_BLOCKED = /EvalError|unsafe-eval|Content Security Policy/i;\n\nfunction cdpSession(page: Page): Promise<CDPSession | null> {\n\tconst existing = cdpSessions.get(page);\n\n\tif (existing) {\n\t\treturn existing;\n\t}\n\n\tconst session = page\n\t\t.context()\n\t\t.newCDPSession(page)\n\t\t.catch(() => null);\n\tcdpSessions.set(page, session);\n\n\treturn session;\n}\n\nfunction isChromium(page: Page): boolean {\n\ttry {\n\t\treturn page.context().browser()?.browserType().name() === \"chromium\";\n\t} catch {\n\t\treturn false;\n\t}\n}\n\nexport type PlaywrightAdaptorOptions = {\n\t/**\n\t * Device scale factor for evidence screenshots. Defaults to 2. On Chromium any value is honoured\n\t * per capture. Elsewhere this must match the `deviceScaleFactor` the browser context was created\n\t * with, because Playwright's public screenshot API cannot rescale a single capture.\n\t */\n\tscreenshotClipScale?: number;\n\n\t/**\n\t * Let a Chromium clip capture content outside the current viewport. Defaults to false: to honour\n\t * it Chromium shrinks the emulated viewport to 1x1 and then resizes it for the clip before\n\t * restoring it, and the page observes each of those as a real resize (`resize` fires, media\n\t * queries flip to their narrowest breakpoint), which can collapse a responsive layout and blur\n\t * the focused element mid-capture. Only enable it for evidence of regions the caller cannot\n\t * scroll into view, where the page's state does not matter. Firefox and WebKit capture the full\n\t * page without resizing the viewport, so they ignore this.\n\t */\n\tcaptureBeyondViewport?: boolean;\n};\n\n/** A BrowserAdaptor backed by a Playwright Page. */\nexport class PlaywrightAdaptor implements BrowserAdaptor {\n\treadonly screenshotClipScale: number;\n\n\tprivate readonly captureBeyondViewport: boolean;\n\n\tconstructor(\n\t\tprivate readonly page: Page,\n\t\toptions: PlaywrightAdaptorOptions = {},\n\t) {\n\t\tthis.screenshotClipScale = options.screenshotClipScale ?? DEFAULT_SCREENSHOT_CLIP_SCALE;\n\t\tthis.captureBeyondViewport = options.captureBeyondViewport ?? false;\n\t}\n\n\tasync evaluate<T>(\n\t\t// biome-ignore lint/suspicious/noExplicitAny: the page-evaluated fn accepts arbitrary serialised args and element handles.\n\t\tfn: (...args: any[]) => T | Promise<T>,\n\t\t...args: unknown[]\n\t): Promise<T> {\n\t\ttry {\n\t\t\t// Playwright takes a single argument, so the function source and its args travel packed\n\t\t\t// into one tuple. Handles nested in that tuple are still resolved to live elements.\n\t\t\treturn (await this.page.evaluate(\n\t\t\t\t([source, packed]) => new Function(`return (${source})`)()(...(packed as unknown[])),\n\t\t\t\t[fn.toString(), args] as [string, unknown[]],\n\t\t\t)) as T;\n\t\t} catch (error) {\n\t\t\tconst message = error instanceof Error ? error.message : String(error);\n\n\t\t\tif (EVAL_BLOCKED.test(message)) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t\"The Playwright adaptor rebuilds page functions with new Function(), which this page's Content-Security-Policy blocks. Allow 'unsafe-eval' in script-src, or use the Puppeteer adaptor.\",\n\t\t\t\t\t{ cause: error },\n\t\t\t\t);\n\t\t\t}\n\n\t\t\tthrow error;\n\t\t}\n\t}\n\n\tevaluateHandle(fn: () => Element | null): Promise<ElementRef> {\n\t\treturn this.page.evaluateHandle(fn);\n\t}\n\n\tasync disposeRef(ref: ElementRef): Promise<void> {\n\t\tawait (ref as JSHandle).dispose();\n\t}\n\n\tasync pressTab(): Promise<void> {\n\t\tawait this.page.keyboard.press(\"Tab\");\n\t}\n\n\tasync pressEnter(): Promise<void> {\n\t\tawait this.page.keyboard.press(\"Enter\");\n\t}\n\n\tasync screenshotClip(clip: Rect, scale = 1): Promise<Uint8Array> {\n\t\tawait this.page.evaluate(nextPaintScript);\n\n\t\tconst session = await cdpSession(this.page);\n\n\t\tif (session) {\n\t\t\t// The public API cannot scale one capture, and its `clip` is only honoured inside the\n\t\t\t// viewport. CDP is what Puppeteer drives too, so evidence images stay pixel-comparable.\n\t\t\t//\n\t\t\t// `captureBeyondViewport: false` ensures that Chromium does not resize the viewport before\n\t\t\t// capturing the screenshot, which can trigger media queries and hide the element we are\n\t\t\t// trying to capture.\n\t\t\tconst { data } = await session.send(\"Page.captureScreenshot\", {\n\t\t\t\tformat: \"png\",\n\t\t\t\tcaptureBeyondViewport: this.captureBeyondViewport,\n\t\t\t\tclip: { ...clip, scale },\n\t\t\t});\n\n\t\t\treturn Buffer.from(data, \"base64\");\n\t\t}\n\n\t\t// Clips are document coordinates, and Playwright renders anything outside the viewport blank\n\t\t// unless the capture is full-page. Firefox and WebKit capture a full page without resizing\n\t\t// the viewport, so the page does not observe this.\n\t\treturn (await this.page.screenshot({\n\t\t\ttype: \"png\",\n\t\t\tfullPage: true,\n\t\t\tclip,\n\t\t\tscale: \"device\",\n\t\t})) as Uint8Array;\n\t}\n\n\tasync ensureFocusReporting(): Promise<void> {\n\t\t// Pages only report focus while they are the foreground tab. Since this browser instance is\n\t\t// likely running in the background, we need to enable focus emulation to get accurate results.\n\t\t//\n\t\t// Note this function does not throw if enabling emulation fails; it is a best-effort.\n\t\tconst session = await cdpSession(this.page);\n\n\t\tif (!session) {\n\t\t\t// Playwright emulates focus on Firefox and WebKit itself, so there is nothing to assert\n\t\t\t// and nothing worth warning about.\n\t\t\tif (isChromium(this.page)) {\n\t\t\t\tconsole.warn(\"Could not open a CDP session for the browser adaptor\");\n\t\t\t}\n\n\t\t\treturn;\n\t\t}\n\n\t\ttry {\n\t\t\tif (focusEmulatedPages.has(this.page)) {\n\t\t\t\t// Chromium ignores a redundant enable, so re-asserting has to toggle.\n\t\t\t\tawait session.send(\"Emulation.setFocusEmulationEnabled\", {\n\t\t\t\t\tenabled: false,\n\t\t\t\t});\n\t\t\t}\n\n\t\t\tawait session.send(\"Emulation.setFocusEmulationEnabled\", {\n\t\t\t\tenabled: true,\n\t\t\t});\n\t\t\tfocusEmulatedPages.add(this.page);\n\t\t} catch (error) {\n\t\t\tconsole.warn(\"Could not enable focus emulation for the browser adaptor\", {\n\t\t\t\terror,\n\t\t\t});\n\t\t}\n\t}\n}\n"],"mappings":"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","names":[]}
|
|
@@ -8,12 +8,22 @@ export type PuppeteerAdaptorOptions = {
|
|
|
8
8
|
* size of each capture without changing a single pixel.
|
|
9
9
|
*/
|
|
10
10
|
optimizeForSpeed?: boolean;
|
|
11
|
+
/**
|
|
12
|
+
* Let a clip capture content outside the current viewport. Defaults to false: to honour it
|
|
13
|
+
* Chromium shrinks the emulated viewport to 1x1 and then resizes it for the clip before
|
|
14
|
+
* restoring it, and the page observes each of those as a real resize (`resize` fires, media
|
|
15
|
+
* queries flip to their narrowest breakpoint), which can collapse a responsive layout and blur
|
|
16
|
+
* the focused element mid-capture. Only enable it for evidence of regions the caller cannot
|
|
17
|
+
* scroll into view, where the page's state does not matter.
|
|
18
|
+
*/
|
|
19
|
+
captureBeyondViewport?: boolean;
|
|
11
20
|
};
|
|
12
21
|
/** A BrowserAdaptor backed by a Puppeteer Page. */
|
|
13
22
|
export declare class PuppeteerAdaptor implements BrowserAdaptor {
|
|
14
23
|
private readonly page;
|
|
15
24
|
readonly screenshotClipScale: number;
|
|
16
25
|
private readonly optimizeForSpeed;
|
|
26
|
+
private readonly captureBeyondViewport;
|
|
17
27
|
constructor(page: Page, options?: PuppeteerAdaptorOptions);
|
|
18
28
|
evaluate<T>(fn: (...args: any[]) => T | Promise<T>, ...args: unknown[]): Promise<T>;
|
|
19
29
|
evaluateHandle(fn: () => Element | null): Promise<ElementRef>;
|
|
@@ -1,15 +1,31 @@
|
|
|
1
|
+
import {
|
|
2
|
+
nextPaintScript
|
|
3
|
+
} from "../chunk-QUDMCLZ7.js";
|
|
4
|
+
|
|
1
5
|
// src/adaptors/puppeteer.ts
|
|
2
|
-
var
|
|
6
|
+
var cdpSessions = /* @__PURE__ */ new WeakMap();
|
|
7
|
+
var focusEmulatedPages = /* @__PURE__ */ new WeakSet();
|
|
3
8
|
var DEFAULT_SCREENSHOT_CLIP_SCALE = 2;
|
|
9
|
+
function cdpSession(page) {
|
|
10
|
+
const existing = cdpSessions.get(page);
|
|
11
|
+
if (existing) {
|
|
12
|
+
return existing;
|
|
13
|
+
}
|
|
14
|
+
const session = page.createCDPSession().catch(() => null);
|
|
15
|
+
cdpSessions.set(page, session);
|
|
16
|
+
return session;
|
|
17
|
+
}
|
|
4
18
|
var PuppeteerAdaptor = class {
|
|
5
19
|
constructor(page, options = {}) {
|
|
6
20
|
this.page = page;
|
|
7
21
|
this.screenshotClipScale = options.screenshotClipScale ?? DEFAULT_SCREENSHOT_CLIP_SCALE;
|
|
8
22
|
this.optimizeForSpeed = options.optimizeForSpeed ?? true;
|
|
23
|
+
this.captureBeyondViewport = options.captureBeyondViewport ?? false;
|
|
9
24
|
}
|
|
10
25
|
page;
|
|
11
26
|
screenshotClipScale;
|
|
12
27
|
optimizeForSpeed;
|
|
28
|
+
captureBeyondViewport;
|
|
13
29
|
evaluate(fn, ...args) {
|
|
14
30
|
return this.page.evaluate(fn, ...args);
|
|
15
31
|
}
|
|
@@ -26,29 +42,39 @@ var PuppeteerAdaptor = class {
|
|
|
26
42
|
await this.page.keyboard.press("Enter");
|
|
27
43
|
}
|
|
28
44
|
async screenshotClip(clip, scale = 1) {
|
|
29
|
-
|
|
30
|
-
|
|
45
|
+
await this.page.evaluate(nextPaintScript);
|
|
46
|
+
const session = await cdpSession(this.page);
|
|
47
|
+
if (!session) {
|
|
48
|
+
return await this.page.screenshot({
|
|
49
|
+
type: "png",
|
|
50
|
+
optimizeForSpeed: this.optimizeForSpeed,
|
|
51
|
+
captureBeyondViewport: this.captureBeyondViewport,
|
|
52
|
+
clip: { ...clip, scale }
|
|
53
|
+
});
|
|
54
|
+
}
|
|
55
|
+
const { data } = await session.send("Page.captureScreenshot", {
|
|
56
|
+
format: "png",
|
|
31
57
|
optimizeForSpeed: this.optimizeForSpeed,
|
|
58
|
+
captureBeyondViewport: this.captureBeyondViewport,
|
|
32
59
|
clip: { ...clip, scale }
|
|
33
60
|
});
|
|
61
|
+
return Buffer.from(data, "base64");
|
|
34
62
|
}
|
|
35
63
|
async ensureFocusReporting() {
|
|
36
64
|
try {
|
|
37
|
-
const
|
|
38
|
-
if (
|
|
39
|
-
|
|
65
|
+
const session = await cdpSession(this.page);
|
|
66
|
+
if (!session) {
|
|
67
|
+
throw new Error("Could not open a CDP session");
|
|
68
|
+
}
|
|
69
|
+
if (focusEmulatedPages.has(this.page)) {
|
|
70
|
+
await session.send("Emulation.setFocusEmulationEnabled", {
|
|
40
71
|
enabled: false
|
|
41
72
|
});
|
|
42
|
-
await existing.send("Emulation.setFocusEmulationEnabled", {
|
|
43
|
-
enabled: true
|
|
44
|
-
});
|
|
45
|
-
return;
|
|
46
73
|
}
|
|
47
|
-
|
|
48
|
-
await client.send("Emulation.setFocusEmulationEnabled", {
|
|
74
|
+
await session.send("Emulation.setFocusEmulationEnabled", {
|
|
49
75
|
enabled: true
|
|
50
76
|
});
|
|
51
|
-
|
|
77
|
+
focusEmulatedPages.add(this.page);
|
|
52
78
|
} catch (error) {
|
|
53
79
|
console.warn("Could not enable focus emulation for the browser adaptor", {
|
|
54
80
|
error
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../../src/adaptors/puppeteer.ts"],"sourcesContent":["import type { CDPSession, JSHandle, Page } from \"puppeteer\";\nimport type { BrowserAdaptor, ElementRef, Rect } from \"../adaptor\";\n\n//
|
|
1
|
+
{"version":3,"sources":["../../src/adaptors/puppeteer.ts"],"sourcesContent":["import type { CDPSession, JSHandle, Page } from \"puppeteer\";\nimport type { BrowserAdaptor, ElementRef, Rect } from \"../adaptor\";\nimport { nextPaintScript } from \"../paint\";\n\n// Keep track of the CDP session for each page so that we can reuse it. The session is kept\n// attached for the page's lifetime: Chrome clears focus emulation when the CDP client disconnects.\n// Resolves to null when a session cannot be opened, so the failure is not retried on every call.\nconst cdpSessions = new WeakMap<Page, Promise<CDPSession | null>>();\n\n// Pages that have had focus emulation enabled at least once.\nconst focusEmulatedPages = new WeakSet<Page>();\n\nconst DEFAULT_SCREENSHOT_CLIP_SCALE = 2;\n\nfunction cdpSession(page: Page): Promise<CDPSession | null> {\n\tconst existing = cdpSessions.get(page);\n\n\tif (existing) {\n\t\treturn existing;\n\t}\n\n\tconst session = page.createCDPSession().catch(() => null);\n\tcdpSessions.set(page, session);\n\n\treturn session;\n}\n\nexport type PuppeteerAdaptorOptions = {\n\t/** Device scale factor for evidence screenshots. Defaults to 2, applied per capture. */\n\tscreenshotClipScale?: number;\n\n\t/**\n\t * Trade PNG compression for capture speed. Defaults to true, which roughly doubles the encoded\n\t * size of each capture without changing a single pixel.\n\t */\n\toptimizeForSpeed?: boolean;\n\n\t/**\n\t * Let a clip capture content outside the current viewport. Defaults to false: to honour it\n\t * Chromium shrinks the emulated viewport to 1x1 and then resizes it for the clip before\n\t * restoring it, and the page observes each of those as a real resize (`resize` fires, media\n\t * queries flip to their narrowest breakpoint), which can collapse a responsive layout and blur\n\t * the focused element mid-capture. Only enable it for evidence of regions the caller cannot\n\t * scroll into view, where the page's state does not matter.\n\t */\n\tcaptureBeyondViewport?: boolean;\n};\n\n/** A BrowserAdaptor backed by a Puppeteer Page. */\nexport class PuppeteerAdaptor implements BrowserAdaptor {\n\treadonly screenshotClipScale: number;\n\n\tprivate readonly optimizeForSpeed: boolean;\n\n\tprivate readonly captureBeyondViewport: boolean;\n\n\tconstructor(\n\t\tprivate readonly page: Page,\n\t\toptions: PuppeteerAdaptorOptions = {},\n\t) {\n\t\tthis.screenshotClipScale = options.screenshotClipScale ?? DEFAULT_SCREENSHOT_CLIP_SCALE;\n\t\tthis.optimizeForSpeed = options.optimizeForSpeed ?? true;\n\t\tthis.captureBeyondViewport = options.captureBeyondViewport ?? false;\n\t}\n\n\tevaluate<T>(\n\t\t// biome-ignore lint/suspicious/noExplicitAny: the page-evaluated fn accepts arbitrary serialised args and element handles.\n\t\tfn: (...args: any[]) => T | Promise<T>,\n\t\t...args: unknown[]\n\t): Promise<T> {\n\t\t// Puppeteer resolves any JSHandle passed as an arg to the live element.\n\t\treturn this.page.evaluate(fn as never, ...(args as never[])) as Promise<T>;\n\t}\n\n\tevaluateHandle(fn: () => Element | null): Promise<ElementRef> {\n\t\treturn this.page.evaluateHandle(fn);\n\t}\n\n\tasync disposeRef(ref: ElementRef): Promise<void> {\n\t\tawait (ref as JSHandle).dispose();\n\t}\n\n\tasync pressTab(): Promise<void> {\n\t\tawait this.page.keyboard.press(\"Tab\");\n\t}\n\n\tasync pressEnter(): Promise<void> {\n\t\tawait this.page.keyboard.press(\"Enter\");\n\t}\n\n\tasync screenshotClip(clip: Rect, scale = 1): Promise<Uint8Array> {\n\t\tawait this.page.evaluate(nextPaintScript);\n\n\t\tconst session = await cdpSession(this.page);\n\n\t\tif (!session) {\n\t\t\t// Without CDP the public API is all there is. With captureBeyondViewport off it intersects\n\t\t\t// the clip with the viewport, so a clip that does not fit comes back smaller than asked\n\t\t\t// for, with a shifted origin.\n\t\t\treturn (await this.page.screenshot({\n\t\t\t\ttype: \"png\",\n\t\t\t\toptimizeForSpeed: this.optimizeForSpeed,\n\t\t\t\tcaptureBeyondViewport: this.captureBeyondViewport,\n\t\t\t\tclip: { ...clip, scale },\n\t\t\t})) as Uint8Array;\n\t\t}\n\n\t\t// Straight to CDP rather than page.screenshot(): with captureBeyondViewport off, Puppeteer\n\t\t// intersects the clip with the visual viewport and silently moves the origin that callers\n\t\t// align element rects against. Keeping captureBeyondViewport off ensures that Chromium does\n\t\t// not resize the viewport, which can trigger media queries and hide the element we are\n\t\t// trying to capture.\n\t\tconst { data } = await session.send(\"Page.captureScreenshot\", {\n\t\t\tformat: \"png\",\n\t\t\toptimizeForSpeed: this.optimizeForSpeed,\n\t\t\tcaptureBeyondViewport: this.captureBeyondViewport,\n\t\t\tclip: { ...clip, scale },\n\t\t});\n\n\t\treturn Buffer.from(data, \"base64\");\n\t}\n\n\tasync ensureFocusReporting(): Promise<void> {\n\t\t// Pages only report focus while they are the foreground tab. Since this browser instance is\n\t\t// likely running in the background, we need to enable focus emulation to get accurate results.\n\t\t//\n\t\t// Note this function does not throw if enabling emulation fails; it is a best-effort.\n\t\ttry {\n\t\t\tconst session = await cdpSession(this.page);\n\n\t\t\tif (!session) {\n\t\t\t\tthrow new Error(\"Could not open a CDP session\");\n\t\t\t}\n\n\t\t\tif (focusEmulatedPages.has(this.page)) {\n\t\t\t\t// Chromium ignores a redundant enable, so re-asserting has to toggle.\n\t\t\t\tawait session.send(\"Emulation.setFocusEmulationEnabled\", {\n\t\t\t\t\tenabled: false,\n\t\t\t\t});\n\t\t\t}\n\n\t\t\tawait session.send(\"Emulation.setFocusEmulationEnabled\", {\n\t\t\t\tenabled: true,\n\t\t\t});\n\t\t\tfocusEmulatedPages.add(this.page);\n\t\t} catch (error) {\n\t\t\tconsole.warn(\"Could not enable focus emulation for the browser adaptor\", {\n\t\t\t\terror,\n\t\t\t});\n\t\t}\n\t}\n}\n"],"mappings":";;;;;AAOA,IAAM,cAAc,oBAAI,QAA0C;AAGlE,IAAM,qBAAqB,oBAAI,QAAc;AAE7C,IAAM,gCAAgC;AAEtC,SAAS,WAAW,MAAwC;AAC3D,QAAM,WAAW,YAAY,IAAI,IAAI;AAErC,MAAI,UAAU;AACb,WAAO;AAAA,EACR;AAEA,QAAM,UAAU,KAAK,iBAAiB,EAAE,MAAM,MAAM,IAAI;AACxD,cAAY,IAAI,MAAM,OAAO;AAE7B,SAAO;AACR;AAwBO,IAAM,mBAAN,MAAiD;AAAA,EAOvD,YACkB,MACjB,UAAmC,CAAC,GACnC;AAFgB;AAGjB,SAAK,sBAAsB,QAAQ,uBAAuB;AAC1D,SAAK,mBAAmB,QAAQ,oBAAoB;AACpD,SAAK,wBAAwB,QAAQ,yBAAyB;AAAA,EAC/D;AAAA,EANkB;AAAA,EAPT;AAAA,EAEQ;AAAA,EAEA;AAAA,EAWjB,SAEC,OACG,MACU;AAEb,WAAO,KAAK,KAAK,SAAS,IAAa,GAAI,IAAgB;AAAA,EAC5D;AAAA,EAEA,eAAe,IAA+C;AAC7D,WAAO,KAAK,KAAK,eAAe,EAAE;AAAA,EACnC;AAAA,EAEA,MAAM,WAAW,KAAgC;AAChD,UAAO,IAAiB,QAAQ;AAAA,EACjC;AAAA,EAEA,MAAM,WAA0B;AAC/B,UAAM,KAAK,KAAK,SAAS,MAAM,KAAK;AAAA,EACrC;AAAA,EAEA,MAAM,aAA4B;AACjC,UAAM,KAAK,KAAK,SAAS,MAAM,OAAO;AAAA,EACvC;AAAA,EAEA,MAAM,eAAe,MAAY,QAAQ,GAAwB;AAChE,UAAM,KAAK,KAAK,SAAS,eAAe;AAExC,UAAM,UAAU,MAAM,WAAW,KAAK,IAAI;AAE1C,QAAI,CAAC,SAAS;AAIb,aAAQ,MAAM,KAAK,KAAK,WAAW;AAAA,QAClC,MAAM;AAAA,QACN,kBAAkB,KAAK;AAAA,QACvB,uBAAuB,KAAK;AAAA,QAC5B,MAAM,EAAE,GAAG,MAAM,MAAM;AAAA,MACxB,CAAC;AAAA,IACF;AAOA,UAAM,EAAE,KAAK,IAAI,MAAM,QAAQ,KAAK,0BAA0B;AAAA,MAC7D,QAAQ;AAAA,MACR,kBAAkB,KAAK;AAAA,MACvB,uBAAuB,KAAK;AAAA,MAC5B,MAAM,EAAE,GAAG,MAAM,MAAM;AAAA,IACxB,CAAC;AAED,WAAO,OAAO,KAAK,MAAM,QAAQ;AAAA,EAClC;AAAA,EAEA,MAAM,uBAAsC;AAK3C,QAAI;AACH,YAAM,UAAU,MAAM,WAAW,KAAK,IAAI;AAE1C,UAAI,CAAC,SAAS;AACb,cAAM,IAAI,MAAM,8BAA8B;AAAA,MAC/C;AAEA,UAAI,mBAAmB,IAAI,KAAK,IAAI,GAAG;AAEtC,cAAM,QAAQ,KAAK,sCAAsC;AAAA,UACxD,SAAS;AAAA,QACV,CAAC;AAAA,MACF;AAEA,YAAM,QAAQ,KAAK,sCAAsC;AAAA,QACxD,SAAS;AAAA,MACV,CAAC;AACD,yBAAmB,IAAI,KAAK,IAAI;AAAA,IACjC,SAAS,OAAO;AACf,cAAQ,KAAK,4DAA4D;AAAA,QACxE;AAAA,MACD,CAAC;AAAA,IACF;AAAA,EACD;AACD;","names":[]}
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
// src/paint.ts
|
|
2
|
+
function nextPaintScript() {
|
|
3
|
+
return new Promise((resolve) => {
|
|
4
|
+
requestAnimationFrame(() => {
|
|
5
|
+
requestAnimationFrame(() => resolve());
|
|
6
|
+
});
|
|
7
|
+
});
|
|
8
|
+
}
|
|
9
|
+
|
|
10
|
+
export {
|
|
11
|
+
nextPaintScript
|
|
12
|
+
};
|
|
13
|
+
//# sourceMappingURL=chunk-QUDMCLZ7.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"sources":["../src/paint.ts"],"sourcesContent":["/**\n * A doubleRAF that aims to wait until the page has painted the next frame.\n */\nexport function nextPaintScript(): Promise<void> {\n\treturn new Promise((resolve) => {\n\t\trequestAnimationFrame(() => {\n\t\t\trequestAnimationFrame(() => resolve());\n\t\t});\n\t});\n}\n"],"mappings":";AAGO,SAAS,kBAAiC;AAChD,SAAO,IAAI,QAAQ,CAAC,YAAY;AAC/B,0BAAsB,MAAM;AAC3B,4BAAsB,MAAM,QAAQ,CAAC;AAAA,IACtC,CAAC;AAAA,EACF,CAAC;AACF;","names":[]}
|
package/dist/paint.d.ts
ADDED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@a11y-pulse/browser-adaptor",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.5.0",
|
|
4
4
|
"description": "Shared browser adaptor primitives and DOM helpers for A11y Pulse accessibility audits.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
@@ -66,7 +66,7 @@
|
|
|
66
66
|
},
|
|
67
67
|
"peerDependencies": {
|
|
68
68
|
"playwright-core": ">=1.40",
|
|
69
|
-
"puppeteer": "^25.
|
|
69
|
+
"puppeteer": "^25.11.0"
|
|
70
70
|
},
|
|
71
71
|
"peerDependenciesMeta": {
|
|
72
72
|
"playwright-core": {
|
|
@@ -77,8 +77,8 @@
|
|
|
77
77
|
}
|
|
78
78
|
},
|
|
79
79
|
"devDependencies": {
|
|
80
|
-
"happy-dom": "^20.
|
|
80
|
+
"happy-dom": "^20.14.5",
|
|
81
81
|
"playwright-core": "^1.63.0",
|
|
82
|
-
"puppeteer": "^25.
|
|
82
|
+
"puppeteer": "^25.11.0"
|
|
83
83
|
}
|
|
84
84
|
}
|