@plan2net/typo3-playwright-toolkit 0.14.0 → 0.16.0

package/README.md

@@ -5,18 +5,22 @@
 <p align="center"><em>Playwright fixtures and content builders for TYPO3, one test database per test file.</em></p>
 <br>
 
-[![npm](https://img.shields.io/npm/v/@plan2net/typo3-playwright-toolkit)](https://www.npmjs.com/package/@plan2net/typo3-playwright-toolkit)
-[![Node](https://img.shields.io/badge/Node-22.12%2B-5fa04e)](https://nodejs.org)
-[![Playwright](https://img.shields.io/badge/Playwright-1.44%2B-2ead33)](https://playwright.dev)
-[![licence](https://img.shields.io/badge/licence-GPL--2.0--or--later-blue)](LICENSE)
+<p align="center">
+  <a href="https://www.npmjs.com/package/@plan2net/typo3-playwright-toolkit"><img src="https://img.shields.io/npm/v/@plan2net/typo3-playwright-toolkit?style=for-the-badge&logo=npm&logoColor=white&labelColor=24273a&color=fff3b0" alt="npm version"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-22.12%2B-a0c4ff?style=for-the-badge&logo=nodedotjs&logoColor=white&labelColor=24273a" alt="Node 22.12 or newer"></a>
+  <a href="https://playwright.dev"><img src="https://img.shields.io/badge/Playwright-1.44%2B-b5ead7?style=for-the-badge&labelColor=24273a&logo=data:image/svg%2Bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI%2BPHBhdGggZmlsbD0iI2ZmZiIgZD0iTTcgNHYxNmwxMy04eiIvPjwvc3ZnPg%3D%3D" alt="Playwright 1.44 or newer"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/licence-GPL--2.0--or--later-ffc6d9?style=for-the-badge&logo=gnu&logoColor=white&labelColor=24273a" alt="GPL-2.0-or-later licence"></a>
+</p>
 
 An npm package. It provides the [Playwright](https://playwright.dev) fixtures, the
 content builders that create [TYPO3](https://typo3.org) records, and the
 accessibility ([axe](https://github.com/dequelabs/axe-core)) and CSP checks.
 
-It needs the [Composer extension](https://github.com/plan2net/typo3-playwright-toolkit/tree/main/packages/playwright-toolkit), which creates the test
-databases, and the [DDEV add-on](https://github.com/plan2net/typo3-playwright-toolkit/tree/main/packages/ddev-typo3-playwright-toolkit), which provides
-the database service and the commands.
+It needs the
+[Composer extension](https://github.com/plan2net/typo3-playwright-toolkit/tree/main/packages/playwright-toolkit),
+which creates the test databases, and the
+[DDEV add-on](https://github.com/plan2net/typo3-playwright-toolkit/tree/main/packages/ddev-typo3-playwright-toolkit),
+which provides the database service and the commands.
 
 > [!IMPORTANT]
 > Setting this up for the first time? Follow
@@ -38,7 +42,7 @@ the database service and the commands.
 You do not need a database client. This package never talks to the database; it asks
 the extension to create and delete them. That is why PHP and Node may run in
 different containers.
-[Where things run](https://github.com/plan2net/typo3-playwright-toolkit#where-things-run)
+[Where things run](https://github.com/plan2net/typo3-playwright-toolkit/blob/main/SETUP.md#where-things-run)
 shows how.
 
 ## Install
@@ -86,9 +90,9 @@ this package uses, because the test database exists nowhere else.
 
 `consumerRoot` is the root of your TYPO3 project. The package derives the state and
 session folders from it, so it works from `node_modules` without knowing its own
-location. Count the `..` from where your config actually sits — the example assumes
+location. Count the `..` from where your config sits: the example assumes
 `<project>/tests/playwright/`, so it climbs two levels. Pointing it at the wrong
-directory is not an error: the run works and writes its state somewhere you did not
+directory is not an error; the run works and writes its state somewhere you did not
 expect. Use `fileURLToPath` rather than `new URL(...).pathname`, which
 percent-encodes a project path containing spaces or non-ASCII characters.
 
@@ -146,11 +150,11 @@ setup, and the other tests wait. If the setup fails, the tests are skipped with
 reason instead of failing because content is missing.
 
 The `slug` you get back is the one the site stored, which is not always the one you
-asked for — a translation and a name already in use are two cases, and an extension
+asked for. A translation and a name already in use are two cases, and an extension
 can add more. Navigate with the returned value, never with the string you passed in.
 
-A save also reports how many records TYPO3 actually wrote, and warns when that is more
-than you asked for:
+A save also reports how many records TYPO3 wrote, and warns when that is more than
+you asked for:
 
 ```
 [typo3-playwright-toolkit] Saving pages wrote 27 records for 1 requested.
@@ -158,7 +162,7 @@ than you asked for:
   A slug change cascades to every descendant page and writes a redirect for each.
 ```
 
-Nothing is wrong — the save succeeded. It is where a slow setup spends its time, and
+Nothing is wrong; the save succeeded. It is where a slow setup spends its time, and
 changing the slug of a page with descendants is the usual cause. The counts are on the
 result as `written`. It never fails a test.
 
@@ -178,7 +182,7 @@ attempts by default. Lower them to hear about a broken setup sooner.
 
 ### When something fails, TYPO3 says why
 
-A failing test now prints what TYPO3 wrote to its log while that test ran, under the
+A failing test prints what TYPO3 wrote to its log while that test ran, under the
 failure itself:
 
 ```
@@ -199,8 +203,10 @@ The same list is attached to the test as `typo3-errors.json`. A message that rep
 is counted, not printed again. A failing setup shows the same list next to its own
 error.
 
-If TYPO3 refuses a record while a builder saves it, the builder stops at that line.
-Before, the save looked fine and the test failed later, somewhere unrelated.
+If TYPO3 refuses a record while a builder saves it, the builder stops at that line,
+so the failure points at the save and not at a later assertion. A `withField()` column
+that TCA does not have fails there too, naming the closest column that exists: TYPO3
+would drop such a field without saying so, leaving the test without its content.
 
 <picture>
   <source media="(max-width: 700px)" srcset="https://raw.githubusercontent.com/plan2net/typo3-playwright-toolkit/main/diagrams/scenario-fan-out-narrow.svg">
@@ -211,9 +217,9 @@ Before, the save looked fine and the test failed later, somewhere unrelated.
 Besides `builders`, the setup receives `testId` (the database this attempt runs
 against), `attempt` (`1` on the first try), `signal` (aborted when the attempt times
 out, so pass it to your own long requests), and a `page` and `request` that already
-carry the toolkit headers. Your tests get `testId` beside `state`, which is the
-database name without its `db` prefix and what the backend shows in brackets behind
-the site name:
+carry the toolkit headers. Your tests get `testId` beside `state`. It is the database
+name without its `db` prefix, and what the backend shows in brackets behind the site
+name:
 
 ```ts
 test('reports which database it used', async ({ page, state, testId }) => {
@@ -334,14 +340,14 @@ const [hero, intro, gallery] = await builders.batch(
 )
 ```
 
-The queued builders get no `.create()` — `batch` saves them. They land on the page in
-the order you list them, you get a uid for each, and their files and child records come
-along in the same request.
+The queued builders get no `.create()`; `batch` saves them. They land on the page in
+the order you list them, you get a uid for each, and their files and child records
+come along in the same request.
 
-All the elements have to belong to one page, because a request positions them after one
-another and that means nothing across pages. They also cannot point at each other: a
-relation needs a uid, and only a save hands one back. Create what is pointed at first,
-then batch the rest:
+All the elements have to belong to one page, because a request positions them after
+one another and that means nothing across pages. They also cannot point at each
+other: a relation needs a uid, and only a save hands one back. Create what is pointed
+at first, then batch the rest:
 
 ```ts
 const container = await builders.content().onPage(page.id).ofType('my_container').create()
@@ -355,21 +361,21 @@ await builders.batch(
 ```
 
 A content type whose children hang off a column of its own needs none of this:
-`withChildren` already writes them in the same request as their parent. Batching is for
-elements that sit side by side on a page.
+`withChildren` already writes them in the same request as their parent. Batching is
+for elements that sit side by side on a page.
 
 ### Calling the site directly
 
-The `request` client — the one `defineScenario` hands your setup, and the `request`
-fixture in your tests — carries the test ID for `testingURL`, so it reads and
-writes the same throwaway database the browser does. Requests to any other host
-get neither toolkit header.
+The `request` client, the one `defineScenario` hands your setup and the `request`
+fixture in your tests, carries the test ID for `testingURL`, so it reads and writes
+the same throwaway database the browser does. Requests to any other host get neither
+toolkit header.
 
 ### Stubbing a third-party script
 
 A cookie banner or a tracking script can swallow the clicks your test makes.
-`prepareContext` runs on every context a test uses, after the toolkit's own
-routes are in place:
+`prepareContext` runs on every context a test uses, after the toolkit's own routes
+are in place:
 
 ```ts
 // playwright.config.ts
@@ -378,10 +384,48 @@ prepareContext: async (context) => {
 },
 ```
 
+### Building your assets
+
+Every run builds your frontend assets before the first test. Tests against a stale
+bundle still pass, and the screenshots they write become the baseline for the next
+run, so no later run reports the problem either.
+
+If you set no `build`, the package runs the `build` script from your project's
+`package.json`, through the package manager your lockfile names: pnpm for
+`pnpm-lock.yaml`, yarn for `yarn.lock`, bun for a bun lockfile, npm otherwise. A
+project without that script builds nothing and starts right away, so a site with
+committed assets needs no setting at all.
+
+Name your own command when the default is wrong:
+
+```ts
+// playwright.config.ts
+build: 'pnpm build:test',           // one command
+build: 'npm run css && npm run js', // several, because it runs through a shell
+build: false,                       // this project never builds
+```
+
+The command runs in `consumerRoot` and writes its output to your terminal. A failing
+build stops the run before the first test, so it costs you no per-test database and
+no state to clean up. Under DDEV the template database is rebuilt earlier, by the
+`ddev playwright` command itself, so that step runs either way.
+
+To skip the build once, set `PW_SKIP_BUILD=1`, which is what
+`ddev playwright test --skip-build` does.
+
 ### Screenshots
 
 `expectScreenshot` waits for fonts, images and animations, hides the selectors from
-`hideBeforeScreenshot`, and then compares against the stored image.
+`hideBeforeScreenshot`, and then compares against the stored image. An image that has
+still not decoded when that wait runs out is named in a warning, because it would
+otherwise be blank in the picture and, on a first run, blank in the new baseline.
+
+For the duration of the shot each image is pinned to the file it resolved to, and released
+again afterwards. Chromium collapses the viewport to 1×1 while it captures anything taller
+than the viewport, and a `<source media="(max-width: …)">` flips while it is collapsed, which
+drops the decoded image and leaves a blank. Pinning it is invisible to a test, including one
+that narrows the viewport between two shots. A `background-image` behind a width query is
+not covered.
 
 ```ts
 import { expectScreenshot } from '@plan2net/typo3-playwright-toolkit'
@@ -410,7 +454,7 @@ Every other option is passed on to `toHaveScreenshot`, and the tolerances come f
 > ```
 
 `expectScreenshot` waits for animations itself. When you interact and then assert
-without a screenshot — an accessibility scan after opening an accordion, say — wait
+without a screenshot, say an accessibility scan after opening an accordion, wait
 first:
 
 ```ts
@@ -499,6 +543,7 @@ Everything else:
 | `accessibility.disabledRules` | `[]` | axe rules turned off for the whole project |
 | `accessibility.projects` | all projects | Projects that run axe checks |
 | `accessibility.tags` | `DEFAULT_SCAN_TAGS` | Which axe rule sets to run |
+| `build` | your `build` script | Command that builds your assets before the run, or `false` for none |
 | `cleanup.failOnLeak` | true in CI | Fail the run if a test database could not be deleted |
 | `cleanup.orphanAgeMs` | 24 hours | How old a leftover database must be before cleanup deletes it |
 | `cleanup.preserveOnFailure` | `failed` | Which test databases to keep after a failure: `failed`, `all` or `none` |
@@ -534,7 +579,7 @@ Every CType of a normal TYPO3 installation has a builder, and you register nothi
 
 All builders share `withHeader`, `withSubheader`, `withHeaderLayout`,
 `withHeaderLink`, `withColPos`, `setHidden`, and `withField(column, value)` for any
-other TCA column. They also share the four relation setters above —
+other TCA column. They also share the four relation setters above:
 `withFileReference`, `withFileReferences`, `withChild` and `withChildren`. Types with
 images add `withFile` and `withFiles` for their own media column, plus `withColumns`,
 `withOrientation` and `withImageSize`.
@@ -588,13 +633,39 @@ export class EventListContent extends CoreContent {
 ```
 
 For a structure with named sheets, or a key outside `settings.`, write the column
-yourself with `flexForm()` — the form posts one field per value, not one for the
+yourself with `flexForm()`. The form posts one field per value, not one for the
 column:
 
 ```ts
 element.withField('pi_flexform', flexForm({ sDEF: {…}, sFilter: {…} }))
 ```
 
+### The doctor command
+
+The package installs `typo3-playwright-doctor`. Run it from the directory holding
+your Playwright config to see whether the project can run tests: browser launch or
+remote connection, access to `testingURL`, API credentials and version
+compatibility, then a throwaway database and its backend session:
+
+```bash
+npx typo3-playwright-doctor
+npx typo3-playwright-doctor --project chromium
+npx typo3-playwright-doctor --config playwright.local.config.ts
+```
+
+Every check prints success, failure or the reason it was skipped. Exit code `0` means
+ready, `1` means a check failed. `--project` accepts wildcards and can be repeated;
+omit it to check every project.
+
+It runs no tests, setup hooks, builds or repairs, and touches neither your existing
+results nor a kept test database. The one database it creates is its own, and it
+drops that again even after a failed check. On DDEV, `ddev playwright doctor` wraps
+it.
+
+It also checks nothing about your installation. The TYPO3 extension has a wizard for
+that, `playwright:setup`, which reads your files, versions and settings and writes
+what is missing.
+
 ### The inspect command
 
 The package installs `typo3-playwright-inspect`. Run it from your project root
@@ -607,24 +678,43 @@ npx typo3-playwright-inspect accordion  # only matching test files
 ```
 
 It reads the API secret from `var/playwright/api-secret` or from
-`PLAYWRIGHT_TOOLKIT_SECRET`. On DDEV, `ddev playwright-inspect` wraps it. The links
+`PLAYWRIGHT_TOOLKIT_SECRET`. On DDEV, `ddev playwright inspect` wraps it. The links
 log in as the pre-seeded backend user and live 15 minutes.
 
 `--replay` prints a link into the database a replay run built, instead of the kept
-test databases. Use it when the link that run printed has expired — it mints a new
+test databases. Use it when the link that run printed has expired; it mints a new
 one rather than rebuilding anything.
 
+### The clean command
+
+The package installs `typo3-playwright-clean`. Run it from your project root after a
+run you stopped, to drop the test databases and run state it left behind:
+
+```bash
+npx typo3-playwright-clean
+```
+
+Teardown reclaims those by itself, but only once they are `cleanup.orphanAgeMs` old,
+a day by default. This does it now. A run whose state was touched in the last 30
+seconds counts as still going: its databases go into the sweep's keep list and its
+run directory stays, so a suite running in another terminal is safe. The template and
+the replay database are never dropped. On DDEV, `ddev playwright clean` wraps it.
+
+Databases kept for `typo3-playwright-inspect` are dropped too, since nothing marks
+them as worth keeping. Read what you need from them first.
+
 ### Replay mode
 
 `PW_REPLAY=1` runs every scenario's setup into one shared database rather than a
 per-test one, so all the content the suite builds ends up in a single place you can
-browse and export. `ddev playwright-replay` sets it, rebuilds that database from the
+browse and export. `ddev playwright replay` sets it, rebuilds that database from the
 template first, and prints a backend link when the run ends.
 
 What changes while it is set: every scenario uses the one fixed test ID
-`REPLAY0000000000`, its content goes into a sysfolder named after it under the
-fixture root, slugs keep no test-ID suffix, setups run once with no retry, the tests
-themselves are skipped, and teardown drops nothing.
+`REPLAY0000000000`, its content, images included, goes into a sysfolder named after
+it under the fixture root, slugs keep no test-ID suffix, setups run once with no
+retry, and teardown drops nothing. The tests themselves are skipped, because their
+assertions and screenshot baselines belong to a per-test database.
 
 ## Troubleshooting
 
@@ -637,11 +727,15 @@ first thing in `playwright.config.ts`.
 **Cleanup refuses a path.** `stateDir` and `sessionDir` must be absolute and inside
 `consumerRoot`, because cleanup deletes files in both.
 
+**The run builds nothing, or builds the wrong thing.** The default reads
+`consumerRoot/package.json`, not the `package.json` next to your Playwright config.
+Point `build` at your real command if the two differ.
+
 **"Timed out after 300000ms waiting for the setup".** A setup that builds a lot of
 content can outgrow the defaults on a slow machine. Raise `setup.attemptTimeoutMs`
-for the setup itself and `setup.waitTimeoutMs` for the tests waiting on it — the
-second has to stay comfortably above the first, since it covers every attempt plus
-the time spent waiting for the lock.
+for the setup itself and `setup.waitTimeoutMs` for the tests waiting on it. The
+second has to stay well above the first, since it covers every attempt plus the time
+spent waiting for the lock.
 
 **Test databases stay after a failed run.** That is intended: the databases of the
 failed test files are kept for debugging, and the run prints a link for each one
@@ -655,5 +749,5 @@ minutes.
 
 ## Related packages
 
-- [`plan2net/playwright-toolkit`](https://github.com/plan2net/typo3-playwright-toolkit/tree/main/packages/playwright-toolkit) — Composer extension
-- [DDEV add-on](https://github.com/plan2net/typo3-playwright-toolkit/tree/main/packages/ddev-typo3-playwright-toolkit) — database service and commands
+- [`plan2net/playwright-toolkit`](https://github.com/plan2net/typo3-playwright-toolkit/tree/main/packages/playwright-toolkit), the Composer extension
+- [DDEV add-on](https://github.com/plan2net/typo3-playwright-toolkit/tree/main/packages/ddev-typo3-playwright-toolkit), the database service and commands

package/dist/build.d.ts

@@ -0,0 +1,8 @@
+import type { ToolkitConfig } from './config.js';
+export declare function resolveBuildCommand(config: ToolkitConfig): string | undefined;
+/**
+ * `shell: true` is safe here: the command comes from the consumer's own config, never
+ * from a request, and `npm run css && npm run js` has to work.
+ */
+export declare function runBuild(config: ToolkitConfig): void;
+//# sourceMappingURL=build.d.ts.map

package/dist/build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAUhD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,GAAG,SAAS,CAqC7E;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAgCpD"}

package/dist/build.js

@@ -0,0 +1,73 @@
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+/** First match wins, so npm is the fallback rather than an entry. */
+const LOCKFILES = [
+    { lockfile: 'pnpm-lock.yaml', packageManager: 'pnpm' },
+    { lockfile: 'yarn.lock', packageManager: 'yarn' },
+    { lockfile: 'bun.lockb', packageManager: 'bun' },
+    { lockfile: 'bun.lock', packageManager: 'bun' },
+];
+export function resolveBuildCommand(config) {
+    if (false === config.build) {
+        return undefined;
+    }
+    if (config.build) {
+        return config.build;
+    }
+    const root = config.paths.consumerRoot;
+    const manifestPath = path.join(root, 'package.json');
+    if (!fs.existsSync(manifestPath)) {
+        return undefined;
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    }
+    catch (error) {
+        throw new Error([
+            `[typo3-playwright-toolkit] Could not read ${manifestPath}, so there is no way`,
+            `to tell whether this project builds: ${error instanceof Error ? error.message : String(error)}`,
+            '',
+            'Fix the file, or say what to do in defineToolkitConfig: build: <your command>,',
+            'or build: false for a project that never builds.',
+        ].join('\n'));
+    }
+    if (!manifest?.scripts?.build) {
+        return undefined;
+    }
+    const found = LOCKFILES.find((entry) => fs.existsSync(path.join(root, entry.lockfile)));
+    return `${found?.packageManager ?? 'npm'} run build`;
+}
+/**
+ * `shell: true` is safe here: the command comes from the consumer's own config, never
+ * from a request, and `npm run css && npm run js` has to work.
+ */
+export function runBuild(config) {
+    if ('1' === process.env.PW_SKIP_BUILD) {
+        return;
+    }
+    const command = resolveBuildCommand(config);
+    if (!command) {
+        return;
+    }
+    process.stdout.write(`[toolkit] Building assets: ${command}\n`);
+    const { status, error } = spawnSync(command, {
+        cwd: config.paths.consumerRoot,
+        shell: true,
+        stdio: 'inherit',
+    });
+    if (error) {
+        throw new Error(`[typo3-playwright-toolkit] The asset build could not start: ${error.message}`);
+    }
+    if (0 !== status) {
+        throw new Error([
+            `[typo3-playwright-toolkit] The asset build failed (exit ${String(status)}): ${command}`,
+            '',
+            'Fix the build, or run without it: PW_SKIP_BUILD=1, which is what',
+            '`ddev playwright test --skip-build` sets. A project that should never',
+            'build wants build: false in defineToolkitConfig instead.',
+        ].join('\n'));
+    }
+}
+//# sourceMappingURL=build.js.map

package/dist/build.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.js","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAC9C,OAAO,KAAK,EAAE,MAAM,SAAS,CAAA;AAC7B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAA;AAGjC,qEAAqE;AACrE,MAAM,SAAS,GAAgE;IAC3E,EAAE,QAAQ,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,EAAE;IACtD,EAAE,QAAQ,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,EAAE;IACjD,EAAE,QAAQ,EAAE,WAAW,EAAE,cAAc,EAAE,KAAK,EAAE;IAChD,EAAE,QAAQ,EAAE,UAAU,EAAE,cAAc,EAAE,KAAK,EAAE;CAClD,CAAA;AAED,MAAM,UAAU,mBAAmB,CAAC,MAAqB;IACrD,IAAI,KAAK,KAAK,MAAM,CAAC,KAAK,EAAE,CAAC;QACzB,OAAO,SAAS,CAAA;IACpB,CAAC;IACD,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QACf,OAAO,MAAM,CAAC,KAAK,CAAA;IACvB,CAAC;IAED,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,YAAY,CAAA;IACtC,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC,CAAA;IAEpD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QAC/B,OAAO,SAAS,CAAA;IACpB,CAAC;IAED,IAAI,QAAqD,CAAA;IACzD,IAAI,CAAC;QACD,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,YAAY,EAAE,MAAM,CAAC,CAAoB,CAAA;IACnF,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACX;YACI,6CAA6C,YAAY,sBAAsB;YAC/E,wCAAwC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE;YAChG,EAAE;YACF,gFAAgF;YAChF,kDAAkD;SACrD,CAAC,IAAI,CAAC,IAAI,CAAC,CACf,CAAA;IACL,CAAC;IAED,IAAI,CAAC,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QAC5B,OAAO,SAAS,CAAA;IACpB,CAAC;IAED,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAA;IAEvF,OAAO,GAAG,KAAK,EAAE,cAAc,IAAI,KAAK,YAAY,CAAA;AACxD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,MAAqB;IAC1C,IAAI,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,aAAa,EAAE,CAAC;QACpC,OAAM;IACV,CAAC;IAED,MAAM,OAAO,GAAG,mBAAmB,CAAC,MAAM,CAAC,CAAA;IAC3C,IAAI,CAAC,OAAO,EAAE,CAAC;QACX,OAAM;IACV,CAAC;IAED,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,8BAA8B,OAAO,IAAI,CAAC,CAAA;IAE/D,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,SAAS,CAAC,OAAO,EAAE;QACzC,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,YAAY;QAC9B,KAAK,EAAE,IAAI;QACX,KAAK,EAAE,SAAS;KACnB,CAAC,CAAA;IAEF,IAAI,KAAK,EAAE,CAAC;QACR,MAAM,IAAI,KAAK,CAAC,+DAA+D,KAAK,CAAC,OAAO,EAAE,CAAC,CAAA;IACnG,CAAC;IACD,IAAI,CAAC,KAAK,MAAM,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CACX;YACI,2DAA2D,MAAM,CAAC,MAAM,CAAC,MAAM,OAAO,EAAE;YACxF,EAAE;YACF,kEAAkE;YAClE,uEAAuE;YACvE,0DAA0D;SAC7D,CAAC,IAAI,CAAC,IAAI,CAAC,CACf,CAAA;IACL,CAAC;AACL,CAAC"}

package/dist/checks/screenshot.d.ts

@@ -28,6 +28,13 @@ export declare function buildHideStyles(selectors: string[]): string;
  */
 export declare function waitForAnimations(page: Page, selector?: string, timeout?: number): Promise<void>;
 export declare function loadLazyElements(page: Page): Promise<void>;
+export declare function freezeResponsiveImages(page: Page): Promise<void>;
+export declare function prepareImagesForCapture(page: Page): Promise<string[]>;
+export declare function restoreResponsiveImages(page: Page): Promise<void>;
+/** @returns the sources of the images that never decoded, empty when all did */
+export declare function waitForImagesDecoded(page: Page, timeout?: number): Promise<string[]>;
+/** An undecoded image is blank, and a first run writes that blank as the baseline. */
+export declare function warnAboutUndecodedImages(stalled: string[], timeout: number): void;
 export declare function resolveScreenshotTarget(target: Page | Locator, include?: string): {
     shot: Page | Locator;
     wholePage: boolean;

package/dist/checks/screenshot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"screenshot.d.ts","sourceRoot":"","sources":["../../src/checks/screenshot.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAA;AAGxD,+CAA+C;AAC/C,MAAM,WAAW,2BAA2B;IACxC,UAAU,CAAC,EAAE,UAAU,GAAG,OAAO,CAAA;IACjC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1B,IAAI,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAA;IAC9D,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,IAAI,CAAC,EAAE,OAAO,EAAE,CAAA;IAChB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,KAAK,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAA;IACxB,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,OAAO,CAAC,EAAE,MAAM,CAAA;CACnB;AAUD,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,MAAM,CAM3D;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,OAAO,SAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAsBpG;AAID,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAMhE;AA6DD,wBAAgB,uBAAuB,CACnC,MAAM,EAAE,IAAI,GAAG,OAAO,EACtB,OAAO,CAAC,EAAE,MAAM,GACjB;IAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAM9C;AAED,MAAM,WAAW,iBAAkB,SAAQ,2BAA2B;IAClE,+BAA+B;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,yEAAyE;IACzE,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;CAClB;AAED,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,SAAS,GAAG,MAAM,EAAE,CAEzG;AAED,wBAAsB,gBAAgB,CAClC,MAAM,EAAE,IAAI,GAAG,OAAO,EACtB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,iBAAsB,GAChC,OAAO,CAAC,IAAI,CAAC,CAuBf;AAED,wBAAgB,iBAAiB,CAC7B,SAAS,EAAE,OAAO,EAClB,OAAO,EAAE,2BAA2B,GACrC,2BAA2B,CAO7B"}
+{"version":3,"file":"screenshot.d.ts","sourceRoot":"","sources":["../../src/checks/screenshot.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAA;AAGxD,+CAA+C;AAC/C,MAAM,WAAW,2BAA2B;IACxC,UAAU,CAAC,EAAE,UAAU,GAAG,OAAO,CAAA;IACjC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1B,IAAI,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAA;IAC9D,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,IAAI,CAAC,EAAE,OAAO,EAAE,CAAA;IAChB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,KAAK,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAA;IACxB,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,OAAO,CAAC,EAAE,MAAM,CAAA;CACnB;AAUD,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,MAAM,CAM3D;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,OAAO,SAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAsBpG;AAID,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAMhE;AAID,wBAAsB,sBAAsB,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAuCtE;AAID,wBAAsB,uBAAuB,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAM3E;AAED,wBAAsB,uBAAuB,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAsBvE;AAID,gFAAgF;AAChF,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,SAAiB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAalG;AA0CD,sFAAsF;AACtF,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAMjF;AAuCD,wBAAgB,uBAAuB,CACnC,MAAM,EAAE,IAAI,GAAG,OAAO,EACtB,OAAO,CAAC,EAAE,MAAM,GACjB;IAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAM9C;AAED,MAAM,WAAW,iBAAkB,SAAQ,2BAA2B;IAClE,+BAA+B;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,yEAAyE;IACzE,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;CAClB;AAED,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,SAAS,GAAG,MAAM,EAAE,CAEzG;AAED,wBAAsB,gBAAgB,CAClC,MAAM,EAAE,IAAI,GAAG,OAAO,EACtB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,iBAAsB,GAChC,OAAO,CAAC,IAAI,CAAC,CA8Bf;AAED,wBAAgB,iBAAiB,CAC7B,SAAS,EAAE,OAAO,EAClB,OAAO,EAAE,2BAA2B,GACrC,2BAA2B,CAO7B"}

package/dist/checks/screenshot.js

@@ -42,12 +42,93 @@ export async function loadLazyElements(page) {
         .querySelectorAll('[loading="lazy"]')
         .forEach((element) => (element.loading = 'eager')));
 }
-async function waitForImagesDecoded(page, timeout = 15000) {
-    await page.evaluate(async (timeout) => {
+// A capture reaching past the viewport collapses it to 1x1 first, and a width-based
+// `media` on a `<source>` flips while it is collapsed, dropping the decoded image.
+export async function freezeResponsiveImages(page) {
+    await page.evaluate(() => {
+        document.querySelectorAll('img').forEach((image) => {
+            const resolved = image.currentSrc;
+            if (!resolved) {
+                return;
+            }
+            image.dataset.toolkitFrozen = JSON.stringify({
+                src: image.getAttribute('src'),
+                srcset: image.getAttribute('srcset'),
+                sizes: image.getAttribute('sizes'),
+                width: image.getAttribute('width'),
+                height: image.getAttribute('height'),
+            });
+            const sources = Array.from(image.closest('picture')?.querySelectorAll('source') ?? []);
+            // width and height on the chosen source lay the img out, and disabling it
+            // would drop them.
+            const chosen = sources.find((source) => !source.media || matchMedia(source.media).matches);
+            for (const dimension of ['width', 'height']) {
+                const value = chosen?.getAttribute(dimension);
+                if (null != value) {
+                    image.setAttribute(dimension, value);
+                }
+            }
+            sources.forEach((source) => {
+                source.dataset.toolkitFrozen = JSON.stringify({ media: source.getAttribute('media') });
+                // Never matches, so selection falls through to the img below.
+                source.media = 'not all';
+            });
+            image.removeAttribute('srcset');
+            image.removeAttribute('sizes');
+            if (image.src !== resolved) {
+                image.src = resolved;
+            }
+        });
+    });
+}
+// Settle first, or a loading image has no currentSrc to pin it to; settle again,
+// because pinning a <picture> starts a load of its own.
+export async function prepareImagesForCapture(page) {
+    const stalled = await waitForImagesDecoded(page);
+    await freezeResponsiveImages(page);
+    await waitForImagesDecoded(page);
+    return stalled;
+}
+export async function restoreResponsiveImages(page) {
+    await page.evaluate(() => {
+        const put = (element, name, value) => null === value ? element.removeAttribute(name) : element.setAttribute(name, value);
+        document.querySelectorAll('img[data-toolkit-frozen]').forEach((image) => {
+            image
+                .closest('picture')
+                ?.querySelectorAll('source[data-toolkit-frozen]')
+                .forEach((source) => {
+                const { media } = JSON.parse(source.dataset.toolkitFrozen ?? '{}');
+                put(source, 'media', media);
+                delete source.dataset.toolkitFrozen;
+            });
+            const frozen = JSON.parse(image.dataset.toolkitFrozen ?? '{}');
+            Object.entries(frozen).forEach(([name, value]) => put(image, name, value));
+            delete image.dataset.toolkitFrozen;
+        });
+    });
+}
+const DECODE_TIMEOUT = 15000;
+/** @returns the sources of the images that never decoded, empty when all did */
+export async function waitForImagesDecoded(page, timeout = DECODE_TIMEOUT) {
+    const deadline = Date.now() + timeout;
+    const stalled = await settleImages(page, timeout);
+    const left = deadline - Date.now();
+    // Out of budget, so a second round would settle nothing and report every image.
+    if (left <= 0) {
+        return stalled;
+    }
+    // A load that starts during a round is not waited for by it, which is how
+    // applyDeferredStylesheets re-selects a source after the image read as complete.
+    return settleImages(page, left);
+}
+function settleImages(page, timeout) {
+    return page.evaluate(async (timeout) => {
         const images = Array.from(document.querySelectorAll('img'));
+        const stalled = new Set(images);
         const settle = (image) => new Promise((resolve) => {
             const finish = async () => {
                 await image.decode().catch(() => { });
+                stalled.delete(image);
                 resolve();
             };
             if (image.complete) {
@@ -55,13 +136,29 @@ async function waitForImagesDecoded(page, timeout = 15000) {
                 return;
             }
             image.addEventListener('load', () => void finish(), { once: true });
-            image.addEventListener('error', () => resolve(), { once: true });
+            image.addEventListener('error', () => {
+                stalled.delete(image);
+                resolve();
+            }, { once: true });
         });
         const timeoutPromise = new Promise((resolve) => setTimeout(resolve, timeout));
         await Promise.race([Promise.all(images.map(settle)), timeoutPromise]);
         await new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(() => resolve())));
+        // The snapshot above predates anything that started loading since.
+        document.querySelectorAll('img').forEach((image) => {
+            if (!image.complete) {
+                stalled.add(image);
+            }
+        });
+        return Array.from(stalled, (image) => image.currentSrc || image.src);
     }, timeout);
 }
+/** An undecoded image is blank, and a first run writes that blank as the baseline. */
+export function warnAboutUndecodedImages(stalled, timeout) {
+    console.warn(`[typo3-playwright-toolkit] ${stalled.length} ${1 === stalled.length ? 'image' : 'images'} ` +
+        `did not decode within ${timeout}ms and will be blank in the screenshot:\n  ` +
+        stalled.join('\n  '));
+}
 /**
  * Finishes the `media="print"` async-CSS trick by hand. A stylesheet loaded as
  * print and swapped to `all` on load is not applied while it is still print, so
@@ -113,11 +210,19 @@ export async function expectScreenshot(target, name, options = {}) {
     await page.evaluate(() => document.fonts.ready);
     await waitForAnimations(page, undefined, 3000);
     await loadLazyElements(page);
-    await waitForImagesDecoded(page);
-    // Playwright creates a missing reference itself and has --update-snapshots
-    // for the rest; hand-building the snapshot path got the platform suffix
-    // wrong off Linux.
-    await expect(shot).toHaveScreenshot(`${name}.png`, comparisonOptions(wholePage, screenshotOptions));
+    const stalled = await prepareImagesForCapture(page);
+    if (stalled.length > 0) {
+        warnAboutUndecodedImages(stalled, DECODE_TIMEOUT);
+    }
+    try {
+        // Playwright creates a missing reference itself and has --update-snapshots
+        // for the rest; hand-building the snapshot path got the platform suffix
+        // wrong off Linux.
+        await expect(shot).toHaveScreenshot(`${name}.png`, comparisonOptions(wholePage, screenshotOptions));
+    }
+    finally {
+        await restoreResponsiveImages(page);
+    }
 }
 export function comparisonOptions(wholePage, perCall) {
     return {