![\"\"](\"https://raw.githubusercontent.com/plan2net/typo3-playwright-toolkit/main/packages/playwright-toolkit/Resources/Public/Icons/Extension.svg\"){kind=icon}
\n\n \n
Playwright fixtures and content builders for TYPO3, one test database per test file.
\n\n ![\"npm](\"https://img.shields.io/npm/v/@plan2net/typo3-playwright-toolkit?style=for-the-badge&logo=npm&logoColor=white&labelColor=24273a&color=fff3b0\")
![\"Node](\"https://img.shields.io/badge/Node-22.12%2B-a0c4ff?style=for-the-badge&logo=nodedotjs&logoColor=white&labelColor=24273a\"){kind=icon}
![\"Playwright](\"https://img.shields.io/badge/Playwright-1.47%2B-b5ead7?style=for-the-badge&labelColor=24273a&logo=data:image/svg%2Bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI%2BPHBhdGggZmlsbD0iI2ZmZiIgZD0iTTcgNHYxNmwxMy04eiIvPjwvc3ZnPg%3D%3D\"){kind=icon}
![\"GPL-2.0-or-later](\"https://img.shields.io/badge/licence-GPL--2.0--or--later-ffc6d9?style=for-the-badge&logo=gnu&logoColor=white&labelColor=24273a\"){kind=icon}
Copy.
'))\n .create()\n\n await builders\n .content()\n .onPage(id)\n // your own CType, registered as shown under \"Your own content types\"\n .ofType('article')\n .configure((element) =>\n element.withField('pi_flexform', flexForm({ 'settings.limit': 3 })),\n )\n .create()\n\n return { slug }\n})\n\ntest('renders the page title', async ({ page, state }) => {\n await page.goto(state.slug)\n\n await expect(page.locator('h1')).toHaveText('My Page')\n})\n```\n\n`state` is whatever your setup returned. The first test that needs it runs the\nsetup, and the other tests wait. If the setup fails, the tests are skipped with the\nreason instead of failing because content is missing.\n\nOn an installation with several sites, name the site the scenario is about:\n\n```ts\nconst test = defineScenario(async ({ builders }) => { /* … */ }, { site: 'shop' })\n```\n\nRelative URLs then go to that site, and a new page goes under its root page. Without\n`site`, a scenario uses the only site, or the one on your testing URL. To open another\nsite, build its URL with `siteURL('corporate', 'about')`.\n\nA slug starts with `/`, so `page.goto(state.slug)` leaves out a path in the site's\nbase. On a site like `https://example.test/shop/`, navigate with\n`page.goto(siteURL('shop', state.slug))`, which keeps it.\n\nThe `slug` you get back is the one the site stored, which is not always the one you\nasked for. A translation and a name already in use are two cases, and an extension\ncan add more. Navigate with the returned value, never with the string you passed in.\n\nA save also reports how many records TYPO3 wrote, and warns when that is more than\nyou asked for:\n\n```\n[typo3-playwright-toolkit] Saving pages wrote 27 records for 1 requested.\n pages 17 (16 not requested), sys_redirect 10 (10 not requested)\n A slug change cascades to every descendant page and writes a redirect for each.\n```\n\nNothing is wrong; the save succeeded. It is where a slow setup spends its time, and\nchanging the slug of a page with descendants is the usual cause. The counts are on the\nresult as `written`. It never fails a test.\n\nThe setup runs once per file, even when the file runs in several browser projects.\nThe other projects use the state and the test database that the first one created.\n\n**Every test in a file shares that one database.** They all read the same records, and so\ndoes the same file under a second browser project. With `fullyParallel: true` they also\nrun at the same time. So when one test writes, the others see it, in an order that is not\nfixed. Keep tests read-only, or put a test that has to write in a file of its own.\n\nThe setup has its own time budget, so a test keeps the full timeout for its own work.\nSetup time is not part of a test's duration; the report carries it as an annotation:\n\n```\nsetup: built in 12.9s\n```\n\nThe tests that reuse the setup say `reused, built in 12.9s`. How long a stuck setup\nruns is `setup.attemptTimeoutMs` and `setup.waitTimeoutMs`, 90s per attempt and two\nattempts by default. Lower them to hear about a broken setup sooner.\n\n### When something fails, TYPO3 says why\n\nA failing test prints what TYPO3 wrote to its log while that test ran, under the\nfailure itself:\n\n```\n Error: expect(locator).toBeVisible() failed\n Locator: locator('.teaser figure img')\n\n Error: [typo3-playwright-toolkit] TYPO3 recorded 2 errors for scenario\n \"tests/teaser.spec.ts\" (test 2C8F069F788D3F20):\n\n 1. log error\n No page configured for type=99999.\n\n 2. DataHandler sys_file_reference\n Attempt to insert a record on page '/gallery' (127) where this table is not allowed\n```\n\nThe same list is attached to the test as `typo3-errors.json`. A message that repeats\nis counted, not printed again. A failing setup shows the same list next to its own\nerror.\n\nIf TYPO3 refuses a record while a builder saves it, the builder stops at that line,\nso the failure points at the save and not at a later assertion. A `withField()` column\nthat TCA does not have fails there too, naming the closest column that exists: TYPO3\nwould drop such a field without saying so, leaving the test without its content.\n\nA save also fails when the backend form would not allow it for the user the test runs\nas: an empty required field, too few or too many items, a number out of range, a value\nshorter than the minimum, or a field the form does not show for the record's type and\nvalues. The message names the field, for example `tt_content NEW1: \"header\" is required.`\nA test that means to create such a record, say to cover an import, says so:\n\n```ts\nawait builders.content().onPage(pageId).ofType('text').withoutFormRules().create()\n```\n\n![\"One](\"https://raw.githubusercontent.com/plan2net/typo3-playwright-toolkit/main/diagrams/scenario-fan-out-narrow.svg\")
\nIntro
')),\n builders.content().onPage(page.id).ofType('textmedia')\n .configure((element) => element.withHeader('Gallery'))\n .withFileReferences('assets', [1, 2]),\n)\n```\n\nThe queued builders get no `.create()`; `batch` saves them. They land on the page in\nthe order you list them, you get a uid for each, and their files and child records\ncome along in the same request.\n\nAll the elements have to belong to one page, because a request positions them after\none another and that means nothing across pages. They also cannot point at each\nother: a relation needs a uid, and only a save hands one back. Create what is pointed\nat first, then batch the rest:\n\n```ts\nconst container = await builders.content().onPage(page.id).ofType('my_container').create()\n\nawait builders.batch(\n builders.content().onPage(page.id).ofType('text')\n .configure((element) => element.inContainer(Number(container.id))),\n builders.content().onPage(page.id).ofType('header')\n .configure((element) => element.inContainer(Number(container.id))),\n)\n```\n\nA content type whose children hang off a column of its own needs none of this:\n`withChildren` already writes them in the same request as their parent. Batching is\nfor elements that sit side by side on a page.\n\n### Calling the site directly\n\nThe `request` client, the one `defineScenario` hands your setup and the `request`\nfixture in your tests, carries the test ID for `testingURL`, so it reads and writes\nthe same throwaway database the browser does. Requests to any other host get neither\ntoolkit header.\n\n### Stubbing a third-party script\n\nA cookie banner or a tracking script can swallow the clicks your test makes.\n`prepareContext` runs on every context a test uses, after the toolkit's own routes\nare in place:\n\n```ts\n// playwright.config.ts\nprepareContext: async (context) => {\n await context.route('**/vendor-widget.js', (route) => route.fulfill({ body: '' }))\n},\n```\n\n### Reusing a scenario's setup\n\nA scenario's setup posts its content through the real backend, which is the slowest\npart of a run. `PW_REUSE_SETUP=1` restores that content from a cached copy instead,\nso a run you repeat while working on templates or stylesheets skips the rebuild:\n\n```bash\nPW_REUSE_SETUP=1 npx playwright test accordion --project=chromium-desktop\n```\n\nThe extension records what the setup wrote as SQL under `var/playwright/setup-cache`,\nkeyed by a digest of your Playwright directory. Editing\na spec, a builder or the config invalidates it, and so does rebuilding the test\ndatabase template.\n\nNothing else does. **A change to your project's PHP — a `processDatamap` hook, a TCA\ndefault, a `TCAdefaults` line in page TSconfig — is not noticed**, and the scenario\nkeeps serving what the old code built. Every run with the variable set prints that\nwarning. Run once without it to rebuild and refresh what is cached, or drop the cache\nwith `typo3-playwright-clean --setup-cache`.\n\nLeave it off in CI, where a fresh checkout has nothing to reuse. It is refused in\nreplay mode, where every scenario shares one database.\nOn DDEV, `ddev playwright test --reuse-setup` sets it.\n\n### Building your assets\n\nEvery run builds your frontend assets before the first test. Tests against a stale\nbundle still pass, and the screenshots they write become the baseline for the next\nrun, so no later run reports the problem either.\n\nIf you set no `build`, the package runs the `build` script from your project's\n`package.json`, through the package manager your lockfile names: pnpm for\n`pnpm-lock.yaml`, yarn for `yarn.lock`, bun for a bun lockfile, npm otherwise. A\nproject without that script builds nothing and starts right away, so a site with\ncommitted assets needs no setting at all.\n\nName your own command when the default is wrong:\n\n```ts\n// playwright.config.ts\nbuild: 'pnpm build:test', // one command\nbuild: 'npm run css && npm run js', // several, because it runs through a shell\nbuild: false, // this project never builds\n```\n\nThe command runs in `consumerRoot` and writes its output to your terminal. A failing\nbuild stops the run before the first test, so it costs you no per-test database and\nno state to clean up. Under DDEV the template database is rebuilt earlier, by the\n`ddev playwright` command itself, so that step runs either way.\n\nTo skip the build once, set `PW_SKIP_BUILD=1`, which is what\n`ddev playwright test --skip-build` does.\n\n### Screenshots\n\n`expectScreenshot` waits for fonts, images and animations, hides the selectors from\n`hideBeforeScreenshot`, and then compares against the stored image. An image that has\nstill not decoded when that wait runs out is named in a warning, because it would\notherwise be blank in the picture and, on a first run, blank in the new baseline.\n\nFor the duration of the shot each image is pinned to the file it resolved to, and released\nagain afterwards. Chromium collapses the viewport to 1×1 while it captures anything taller\nthan the viewport, and a `