Check that a page fits a small phone without scrolling sideways. The check retries until the page settles, compares against the viewport’s clientWidth, so content under a classic scrollbar still fails, and names up to 8 elements past the right edge:
ts
import { test } from '@playwright/test';import { expectNoHorizontalOverflow } from 'jg-playwright';test('the pricing page fits a small phone', async ({ page }) => { await page.setViewportSize({ width: 320, height: 640 }); await page.goto('/pricing'); await expectNoHorizontalOverflow(page);});
Scan a page, or part of it, for WCAG 2.0 and 2.1 level A and AA violations. A failure lists each rule with its impact and how many elements break it:
ruleSet picks other rules: 'wcag22aa' adds WCAG 2.2 level AA, such as targets of at least 24 by 24 pixels, and 'axe-default' runs every rule axe runs by default, its best practices included, such as headings that aren’t empty:
Wait until web fonts and every image have loaded, and layout has settled, before a screenshot. A broken image fails it, by its URL:
ts
import { waitForPageAssets } from 'jg-playwright';await waitForPageAssets(page);await expect(page).toHaveScreenshot();
Check that reduced motion stops everything that moves or resizes. Fades and color changes are left out, because they’re safe with reduced motion:
ts
import { inspectMotion } from 'jg-playwright';test.use({ reducedMotion: 'reduce' });const { prefersReducedMotion, movingAnimations } = await inspectMotion(page);expect(movingAnimations).toStrictEqual([]); // each entry names the element and what it animates
Fill a password or a one-time code without a failure printing it. Playwright’s error for a failed fill carries a call log that can repeat the value, so the error keeps only its first line, with the value redacted, and has no cause:
ts
import { fillProtectedField } from 'jg-playwright';await fillProtectedField(page.getByLabel('Password'), password, 'The password field');
Record from a fake microphone. getUserMedia returns a steady tone, while the page’s own MediaRecorder still records and encodes it:
ts
import { installFakeMicrophone, waitForRecordedAudio } from 'jg-playwright';await installFakeMicrophone(page); // or { rejectFirstRequest: true } to test a refused permissionawait page.goto('/notes/new');await page.getByRole('button', { name: 'Record' }).click();await waitForRecordedAudio(page);
Errors
fillProtectedField throws an Exception with the code PROTECTED_FIELD_FILL_FAILED when the fill fails, and expectNoAxeViolations one with INVALID_AXE_OPTIONS for a ruleSet it doesn’t know, before it scans anything. The other failures go through Playwright’s expect, so they read like any other assertion’s.
Browser limits
Headless Chromium hides scrollbars unless its --hide-scrollbars default argument is dropped with launchOptions: { ignoreDefaultArgs: ['--hide-scrollbars'] }, and WebKit and Firefox may draw overlay scrollbars, which take no width.
Playwright’s WebKit on Linux has no MediaRecorder, so a page there can use the fake microphone but can’t record it.
The fake microphone’s tone plays through an audio context, which needs an audio output device. Without one, such as Firefox on a Linux CI runner, the microphone’s track is live but silent, so waitForRecordedAudio times out.
Generated from TSDoc
API reference
Every export of [email protected], 14 in all, with its signature, its errors, and an example.
Asserts that the page doesn't scroll sideways, retrying until it settles. It compares the document's width with the viewport's clientWidth, which leaves out a classic scrollbar, so an overflow a scrollbar hides still fails. A failure names up to 8 elements past the right edge, by tag and classes.
Fills a field that holds a secret, such as a password or a one-time code, without letting a failure print it. Playwright's error for a failed fill carries a call log that can repeat the value, so the error thrown instead keeps only the first line of Playwright's message, with any copy of the value replaced by [redacted], and deliberately has no cause.
Lists the animations running in the page that move or resize an element, with whether the page sees prefers-reduced-motion: reduce, so a test can check that reduced motion stops them. An animation counts when it changes transform, translate, scale, rotate, width, or height. Fades and color changes don't, because they're safe with reduced motion.
Gives the page a fake microphone in every document it loads from now on: getUserMedia returns a steady tone from an oscillator, while the page's own MediaRecorder still records and encodes it, so a test exercises the real recording path without a device or a permission prompt. Call it before page.goto. The tone needs an audio output device: without one, such as Firefox on a Linux CI runner, the track is live but silent.
Waits until the page looks finished, before a screenshot or a layout check: its web fonts are loaded, every <img> has loaded an image it can draw, and two animation frames have passed, so layout that depends on them has settled. A broken image fails it, naming the image. A lazy image below the fold never loads, so scroll it into view first.
Signature
waitForPageAssets(page: Page): Promise<void>
Parameters
pagePage
The page.
Returns
Promise<void>
A promise that resolves once the page's assets are ready, or rejects with Playwright's assertion error after its expect timeout.
Example
import { expect, test } from '@playwright/test';import { waitForPageAssets } from 'jg-playwright';test('the home page matches its screenshot', async ({ page }) => { await page.goto('/'); await waitForPageAssets(page); await expect(page).toHaveScreenshot();});
Waits until the page's latest MediaRecorder, started after installFakeMicrophone, emits a chunk with bytes, so a test knows audio was captured before it stops the recording.
Signature
waitForRecordedAudio(page: Page): Promise<void>
Parameters
pagePage
The page.
Returns
Promise<void>
A promise that resolves once audio was recorded, or rejects with Playwright's assertion error after its expect timeout.
Example
import { test } from '@playwright/test';import { installFakeMicrophone, waitForRecordedAudio } from 'jg-playwright';test('transcribes a recording', async ({ page }) => { await installFakeMicrophone(page); await page.goto('/dictation'); await page.getByRole('button', { name: 'Start dictation' }).click(); await waitForRecordedAudio(page);});
Scans the page with axe-core for violations, and fails with one line per violation, naming the rule, its impact, how many elements break it, and its help text. It runs the WCAG 2.0 and 2.1 level A and AA rules unless ruleSet asks for WCAG 2.2 level AA too, 'wcag22aa', or for every rule axe runs by default, best practices included, 'axe-default'. Install @axe-core/playwright, an optional peer this function loads when it's first called, so the rest of the package works without it. Any other ruleSet, such as 'wcag22AA', throws before anything is scanned.
the rules a scan runs: 'wcag21aa', WCAG 2.0 and 2.1 levels A and AA; 'wcag22aa', those and WCAG 2.2 level AA; or 'axe-default', every rule axe runs by default, best practices included
Declaration
type IAxeRuleSet = 'wcag21aa' | 'wcag22aa' | 'axe-default';