Skip to content

netresearch/typo3-testing-skill / skills/typo3-testing

typo3-testing

Flagged

Use when reproducing defects as failing tests, testing template or rendered output changes, confirming changes on a running TYPO3 instance, or setting up TYPO3 extension tests: unit/functional/E2E, PHPUnit 11-13, mutation testing, final-class mocks (v14), CI matrix across TYPO3 12/13/14.3 LTS, typo3-ci-workflows meta-package, CI failures. Also: transaction rollback, worker crashes, competing requests, testing-framework setup, test matrix, integration/e2e testing, coverage, test generation.

FileKindSize
SKILL.mdskill md6.8 KB
assets/.php-cs-fixer.dist.phpscript7.0 KB
assets/AGENTS.mdmarkdown5.0 KB
assets/Build/Scripts/runTests.shexecutablescript27.5 KB
assets/Build/playwright/.nvmrcother6 B
assets/Build/playwright/package.jsonmanifest535 B
assets/Build/playwright/playwright.config.tsscript1.3 KB
assets/Build/playwright/tests/playwright/accessibility/modules.spec.tsscript2.0 KB
assets/Build/playwright/tests/playwright/config.tsscript712 B
assets/Build/playwright/tests/playwright/e2e/backend-module.spec.tsscript1.9 KB
assets/Build/playwright/tests/playwright/fixtures/setup-fixtures.tsscript2.7 KB
assets/Build/playwright/tests/playwright/helper/login.setup.tsscript975 B
assets/FunctionalTests.xmlconfig1.4 KB
assets/FunctionalTestsBootstrap.phpscript1.6 KB
assets/Makefileother2.3 KB
assets/UnitTests.xmlconfig890 B
assets/UnitTestsBootstrap.phpscript2.1 KB
assets/bootstrap.phpscript1.4 KB
assets/codecov.ymlconfig1.6 KB
assets/docker/codeception.ymlconfig979 B
assets/docker/docker-compose.ymlconfig1.4 KB
assets/example-tests/ExampleAcceptanceCest.phpscript2.2 KB
assets/example-tests/ExampleFunctionalTest.phpscript2.4 KB
assets/example-tests/ExampleUnitTest.phpscript1.6 KB
assets/fixtures/README.mdmarkdown2.0 KB
assets/fixtures/be_users.csvother361 B
assets/fixtures/pages.csvother257 B
assets/fixtures/sys_category.csvother228 B
assets/fixtures/tt_content.csvother338 B
assets/github-actions-e2e.ymlconfig8.8 KB
assets/github-actions-tests.ymlconfig6.3 KB
assets/infection.json5other2.8 KB
assets/phpat.neonother330 B
assets/phpat.phpscript8.4 KB
assets/phpstan-baseline.neonother365 B
assets/phpstan.neonother1.4 KB
assets/rector.phpscript2.9 KB
checkpoints.yamlconfig61.7 KB
references/accessibility-testing.mdmarkdown7.6 KB
references/architecture-testing.mdmarkdown4.4 KB
references/asset-templates-guide.mdmarkdown3.4 KB
references/backend-module-render-verification.mdmarkdown9.7 KB
references/backend-user-access-testing.mdmarkdown9.5 KB
references/captainhook-setup.mdmarkdown2.4 KB
references/ci-cd.mdmarkdown39.5 KB
references/ci-debugging.mdmarkdown20.0 KB
references/ci-workflows-meta-package.mdmarkdown11.6 KB
references/crash-and-concurrency-testing.mdmarkdown4.8 KB
references/crypto-testing.mdmarkdown16.6 KB
references/datahandler-silent-rewrites.mdmarkdown7.2 KB
references/ddev-testing.mdmarkdown1.3 KB
references/e2e-testing.mdmarkdown53.0 KB
references/enforcement-rules.mdmarkdown5.7 KB
references/event-dispatch-testing.mdmarkdown2.8 KB
references/framework-compat-gate.mdmarkdown4.9 KB
references/functional-test-patterns.mdmarkdown11.0 KB
references/functional-testing.mdmarkdown46.3 KB
references/fuzz-testing.mdmarkdown8.6 KB
references/integration-testing.mdmarkdown14.1 KB
references/javascript-testing.mdmarkdown29.3 KB
references/live-instance-verification.mdmarkdown8.6 KB
references/mock-validity.mdmarkdown15.7 KB
references/mutation-testing.mdmarkdown36.0 KB
references/performance-testing.mdmarkdown11.2 KB
references/quality-tools.mdmarkdown25.5 KB
references/release-workflow-validation.mdmarkdown3.6 KB
references/sonarcloud.mdmarkdown18.8 KB
references/synthetic-secret-fixtures.mdmarkdown3.8 KB
references/tdd-discipline.mdmarkdown9.1 KB
references/test-environment-guards.mdmarkdown18.5 KB
references/test-runners.mdmarkdown24.6 KB
references/typo3-ci-config-patterns.mdmarkdown9.0 KB
references/typo3-v14-final-classes.mdmarkdown16.5 KB
references/unit-testing.mdmarkdown59.1 KB
scripts/generate-test.shexecutablescript6.0 KB
scripts/setup-testing.shexecutablescript6.3 KB
scripts/validate-setup.shexecutablescript4.0 KB

references/e2e-testing.md

View on GitHub
<!-- SPDX-License-Identifier: CC-BY-SA-4.0 -->
<!-- SPDX-FileCopyrightText: Netresearch DTT GmbH -->

# E2E Testing with Playwright

TYPO3 Core uses **Playwright** exclusively for end-to-end and accessibility testing. This is the modern standard for browser-based testing in TYPO3 extensions.

**Reference:** [TYPO3 Core Build/tests/playwright](https://github.com/TYPO3/typo3/tree/main/Build/tests/playwright)

## When to Use E2E Tests

- Testing complete user journeys (login, browse, action)
- Frontend functionality validation
- Backend module interaction testing
- JavaScript-heavy interactions
- Visual regression testing
- Cross-browser compatibility

## Requirements

```json
// package.json
{
  "engines": {
    "node": ">=22.18.0 <23.0.0",
    "npm": ">=11.5.2"
  },
  "devDependencies": {
    "@playwright/test": "^1.57.0",
    "@axe-core/playwright": "^4.10.0"
  },
  "scripts": {
    "playwright:install": "playwright install",
    "playwright:open": "playwright test --ui --ignore-https-errors",
    "playwright:run": "playwright test",
    "playwright:codegen": "playwright codegen",
    "playwright:report": "playwright show-report"
  }
}
```

## Directory Structure

```
Build/
├── playwright.config.ts          # Main Playwright configuration
├── package.json                  # Node dependencies
├── .nvmrc                        # Node version (22.18)
└── tests/
    └── playwright/
        ├── config.ts             # TYPO3-specific config (baseUrl, credentials)
        ├── e2e/                   # End-to-end tests
        │   ├── backend/
        │   │   └── module.spec.ts
        │   └── frontend/
        │       └── pages.spec.ts
        ├── accessibility/        # Accessibility tests (axe-core)
        │   └── modules.spec.ts
        ├── fixtures/             # Page Object Models
        │   ├── setup-fixtures.ts
        │   └── backend-page.ts
        └── helper/
            └── login.setup.ts    # Authentication setup
```

## Configuration

### Playwright Config

```typescript
// Build/playwright.config.ts
import { defineConfig } from '@playwright/test';
import config from './tests/playwright/config';

export default defineConfig({
  testDir: './tests/playwright',
  timeout: 30000,
  expect: {
    timeout: 10000,
  },
  fullyParallel: false, // Tests within file run sequentially (safer for state)
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 4 : undefined, // CI: 4 workers, Local: half of CPUs
  reporter: [
    ['list'],
    ['html', { outputFolder: '../typo3temp/var/tests/playwright-reports' }],
  ],
  outputDir: '../typo3temp/var/tests/playwright-results',

  use: {
    baseURL: config.baseUrl,
    ignoreHTTPSErrors: true,
    trace: 'on-first-retry',
  },

  projects: [
    {
      name: 'login setup',
      testMatch: /helper\/login\.setup\.ts/,
    },
    {
      name: 'accessibility',
      testMatch: /accessibility\/.*\.spec\.ts/,
      dependencies: ['login setup'],
      use: {
        storageState: './.auth/login.json',
      },
    },
    {
      name: 'e2e',
      testMatch: /e2e\/.*\.spec\.ts/,
      dependencies: ['login setup'],
      use: {
        storageState: './.auth/login.json',
      },
    },
  ],
});
```

### TYPO3-Specific Config

```typescript
// Build/tests/playwright/config.ts
export default {
  baseUrl: process.env.PLAYWRIGHT_BASE_URL ?? 'http://web:80/typo3/',
  admin: {
    username: process.env.PLAYWRIGHT_ADMIN_USERNAME ?? 'admin',
    password: process.env.PLAYWRIGHT_ADMIN_PASSWORD ?? 'password',
  },
};
```

## Authentication Setup

Store authentication state to avoid repeated logins:

```typescript
// Build/tests/playwright/helper/login.setup.ts
import { test as setup, expect } from '@playwright/test';
import config from '../config';

setup('login', async ({ page }) => {
  await page.goto('/');
  await page.getByLabel('Username').fill(config.admin.username);
  await page.getByLabel('Password').fill(config.admin.password);
  await page.getByRole('button', { name: 'Login' }).click();
  await page.waitForLoadState('networkidle');

  // Verify login succeeded
  await expect(page.locator('.t3js-topbar-button-modulemenu')).toBeVisible();

  // Save authentication state
  await page.context().storageState({ path: './.auth/login.json' });
});
```

## Page Object Model (Fixtures)

Create reusable page objects for TYPO3 backend:

```typescript
// Build/tests/playwright/fixtures/setup-fixtures.ts
import { test as base, type Locator, type Page, expect } from '@playwright/test';

export class BackendPage {
  readonly page: Page;
  readonly moduleMenu: Locator;
  readonly contentFrame: ReturnType<Page['frameLocator']>;

  constructor(page: Page) {
    this.page = page;
    this.moduleMenu = page.locator('#modulemenu');
    this.contentFrame = page.frameLocator('#typo3-contentIframe');
  }

  async gotoModule(identifier: string): Promise<void> {
    const moduleLink = this.moduleMenu.locator(
      `[data-modulemenu-identifier="${identifier}"]`
    );
    await moduleLink.click();
    await expect(moduleLink).toHaveClass(/modulemenu-action-active/);
  }

  async moduleLoaded(): Promise<void> {
    await this.page.evaluate(() => {
      return new Promise<void>((resolve) => {
        document.addEventListener('typo3-module-loaded', () => resolve(), {
          once: true,
        });
      });
    });
  }

  async waitForModuleResponse(urlPattern: string | RegExp): Promise<void> {
    await this.page.waitForResponse((response) => {
      const url = response.url();
      const matches =
        typeof urlPattern === 'string'
          ? url.includes(urlPattern)
          : urlPattern.test(url);
      return matches && response.status() === 200;
    });
  }
}

export class Modal {
  readonly page: Page;
  readonly container: Locator;
  readonly title: Locator;
  readonly closeButton: Locator;

  constructor(page: Page) {
    this.page = page;
    this.container = page.locator('.modal');
    this.title = this.container.locator('.modal-title');
    this.closeButton = this.container.locator('[data-bs-dismiss="modal"]');
  }

  async close(): Promise<void> {
    await this.closeButton.click();
    await expect(this.container).not.toBeVisible();
  }
}

type BackendFixtures = {
  backend: BackendPage;
  modal: Modal;
};

export const test = base.extend<BackendFixtures>({
  backend: async ({ page }, use) => {
    await use(new BackendPage(page));
  },
  modal: async ({ page }, use) => {
    await use(new Modal(page));
  },
});

export { expect, Locator };
```

## Writing E2E Tests

### Basic Test Structure

```typescript
// Build/tests/playwright/e2e/backend/module.spec.ts
import { test, expect } from '../../fixtures/setup-fixtures';

test.describe('My Extension Backend Module', () => {
  test('can access module', async ({ backend }) => {
    await backend.gotoModule('web_myextension');
    await backend.moduleLoaded();

    const contentFrame = backend.contentFrame;
    await expect(contentFrame.locator('h1')).toBeVisible();
  });

  test('can perform action in module', async ({ backend, modal }) => {
    await backend.gotoModule('web_myextension');

    await backend.contentFrame
      .getByRole('button', { name: 'Create new record' })
      .click();

    await expect(modal.container).toBeVisible();
    await expect(modal.title).toContainText('Create');
    await modal.close();
  });

  test('can save form data', async ({ backend }) => {
    await backend.gotoModule('web_myextension');

    const contentFrame = backend.contentFrame;
    await contentFrame.getByLabel('Title').fill('Test Title');
    await contentFrame.getByLabel('Description').fill('Test Description');

    // Register the wait before the click, so a fast response is not missed
    const saved = backend.waitForModuleResponse(/module\/web\/myextension/);
    await contentFrame.getByRole('button', { name: 'Save' }).click();
    await saved;
    await expect(contentFrame.locator('.alert-success')).toBeVisible();
  });
});
```

## Running Tests

```bash
# Install Playwright browsers
npm run playwright:install

# Run all tests
npm run playwright:run

# Run with UI mode (interactive)
npm run playwright:open

# Run specific test file
npx playwright test e2e/backend/module.spec.ts

# Run tests matching pattern
npx playwright test --grep "can access"

# Generate test code (record & playback)
npm run playwright:codegen

# Run in headed mode (see browser)
npx playwright test --headed

# Debug mode
npx playwright test --debug

# Generate HTML report
npm run playwright:report
```

## runTests.sh Integration (Recommended)

The recommended approach is to run E2E tests via `runTests.sh`, which handles Docker networking automatically:

```bash
# Start TYPO3 with ddev, then run E2E tests
ddev start && ./Build/Scripts/runTests.sh -s e2e

# Or with custom TYPO3 URL
TYPO3_BASE_URL=https://my-typo3.local ./Build/Scripts/runTests.sh -s e2e
```

### Playwright Docker Image

Use the official Playwright Docker image with pre-installed browsers:

```bash
IMAGE_PLAYWRIGHT="mcr.microsoft.com/playwright:v1.57.0-noble"
```

**Important**: Keep versions synced between `package.json` and `runTests.sh`:
- `package.json`: `"@playwright/test": "^1.57.0"`
- `runTests.sh`: `IMAGE_PLAYWRIGHT="mcr.microsoft.com/playwright:v1.57.0-noble"`

### ddev Network Integration

When ddev is running, `runTests.sh` automatically:
1. Detects ddev and gets the router IP
2. Connects Playwright container to `ddev_default` network
3. Adds `--add-host` entries for ddev hostname resolution

```bash
# In runTests.sh e2e section:
ROUTER_IP=$(docker inspect ddev-router --format '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}')
DDEV_PARAMS="--network ddev_default"
DDEV_PARAMS="${DDEV_PARAMS} --add-host my-extension.ddev.site:${ROUTER_IP}"
```

### Permission Handling

Pre-create `node_modules` and detect root-owned files:

```bash
mkdir -p node_modules

if [ "$(find node_modules -maxdepth 1 -user root 2>/dev/null | head -1)" ]; then
    echo "Error: node_modules contains root-owned files."
    echo "Please remove: sudo rm -rf node_modules"
    exit 1
fi
```

## DDEV Integration (Alternative)

```yaml
# .ddev/docker-compose.playwright.yaml
services:
  playwright:
    container_name: ddev-${DDEV_SITENAME}-playwright
    image: mcr.microsoft.com/playwright:v1.57.0-noble
    volumes:
      - ../:/var/www/html
    working_dir: /var/www/html/Build
    environment:
      - PLAYWRIGHT_BASE_URL=http://web:80/typo3/
    depends_on:
      - web
```

```bash
# Run Playwright in DDEV
ddev exec -s playwright npx playwright test
```

## CI/CD Integration

> **IMPORTANT: Do NOT use DDEV in CI!**
>
> DDEV is for local development only. For CI, use GitHub Services + PHP built-in server.
> See `assets/github-actions-e2e.yml` for the full template.

### Why NOT DDEV in CI?

| Issue | Impact |
|-------|--------|
| Slow startup | 2-3+ minutes for Docker orchestration |
| Complexity | Docker-in-Docker, networking, volumes |
| Resource heavy | Multiple containers exceed runner limits |
| Fragile | Port conflicts, DNS issues, cert problems |
| Non-standard | TYPO3 Core uses direct PHP, not DDEV |

### Correct CI Pattern: GitHub Services

```yaml
# .github/workflows/e2e.yml
name: E2E Tests

on: [push, pull_request]

jobs:
  e2e:
    runs-on: ubuntu-latest
    timeout-minutes: 20

    # Use GitHub Services for database (NOT DDEV)
    services:
      db:
        image: mariadb:11.4
        env:
          MYSQL_ROOT_PASSWORD: root
          MYSQL_DATABASE: typo3
        ports:
          - 3306:3306
        options: >-
          --health-cmd="healthcheck.sh --connect --innodb_initialized"
          --health-interval=10s
          --health-timeout=5s
          --health-retries=5

    steps:
      - uses: actions/checkout@v4

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.4'
          extensions: mysqli, pdo_mysql, gd, intl

      - name: Install Composer dependencies
        run: composer install --prefer-dist --no-progress

      - name: Setup TYPO3
        run: |
          # Create LocalConfiguration.php with MySQL connection
          mkdir -p .Build/Web/typo3conf
          cat > .Build/Web/typo3conf/LocalConfiguration.php << 'EOF'
          <?php
          return [
              'DB' => ['Connections' => ['Default' => [
                  'driver' => 'mysqli',
                  'host' => '127.0.0.1',
                  'dbname' => 'typo3',
                  'user' => 'root',
                  'password' => 'root',
              ]]],
              'SYS' => [
                  'encryptionKey' => '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef',
                  'trustedHostsPattern' => 'localhost|127\\.0\\.0\\.1',
              ],
          ];
          EOF

          .Build/bin/typo3 extension:setup --no-interaction
          .Build/bin/typo3 backend:user:create --username=admin --password='Joh316!!' --admin --no-interaction
          .Build/bin/typo3 cache:flush

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Playwright
        run: |
          npm ci
          npx playwright install --with-deps chromium

      # Start PHP built-in server (NOT DDEV)
      - name: Start PHP server
        run: |
          php -S 0.0.0.0:8080 -t .Build/Web > /tmp/php-server.log 2>&1 &
          sleep 3

      - name: Run Playwright tests
        env:
          TYPO3_BASE_URL: http://localhost:8080
        run: npm run test:e2e

      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: playwright-report
          path: Tests/E2E/Playwright/reports/
```

### Dual-Mode Playwright Configuration

Configure Playwright to work in both environments:

```typescript
// playwright.config.ts
export default defineConfig({
  use: {
    // DDEV for local, localhost for CI
    baseURL: process.env.TYPO3_BASE_URL || 'https://my-extension.ddev.site',
    ignoreHTTPSErrors: true, // For DDEV self-signed certs
  },
});
```

**Local development:** `npx playwright test` (uses DDEV default)
**CI:** Sets `TYPO3_BASE_URL=http://localhost:8080`

## Naming Conventions

- Pattern: `<feature>.spec.ts`
- Examples: `page-module.spec.ts`, `login.spec.ts`
- Location: `Build/tests/playwright/e2e/<category>/`

## Common Pitfalls

**Backend module DOM lives in an iframe — `page.locator` can't see it**

TYPO3 backend modules render inside a content iframe (`#typo3-contentIframe`;
the frame URL carries a `?token=...`). `page.locator()`, `page.getByText()` and
`page.content()` operate on the **outer shell only** — they do *not* pierce the
iframe. Asserting on module DOM from the page level **silently returns 0 / not
found**, even when the element renders perfectly. This is an easy trap: a green
shell + a failing module assertion reads like a product bug when it is only a
wrong-frame test.

```typescript
// Wrong - matches 0 elements in the outer shell, so this just times out
await expect(page.locator('#my-panel')).toBeVisible();

// Right - enter the module iframe first (see BackendPage.contentFrame above)
const frame = page.frameLocator('#typo3-contentIframe');
await expect(frame.locator('#my-panel')).toBeVisible();
```

Before concluding "the module doesn't render," dump `page.frames()` — you'll see
the shell plus the `?token=` module frame. Assert inside the latter.

**A translated page's `slug` has no language prefix**

The `slug` stored on a translated page record does not contain the site
language's `base` path: a translation served at `/de/kontakt` stores
`/kontakt`. `SlugHelper` builds slugs without the language base. `SiteMatcher`
matches the language base and hands only the rest of the path to
`PageRouter`, which looks it up among the pages of that one language; when
generating, `PageRouter` puts `SiteLanguage::getBase()` back in front
(cms-core 13.4.37 and 14.3.10). A `page.goto()` on the stored slug alone
therefore does not reach the translation. Build the URL from that language's
resolved base (`SiteLanguage::getBase()`): in `config/sites/*/config.yaml` a
language `base` without a host is appended to the site `base`, a matching
`baseVariants` entry replaces either, and a language base may also be a full
URL on another host. In a functional test or a PHP probe, let TYPO3 generate
it:

```php
// $pageUid: the default-language page, i.e. the translation's l10n_parent
$uri = $site->getRouter()->generateUri($pageUid, ['_language' => $languageId]);
```

**A save is finished when its response is in, not when the page is idle**

`page.waitForLoadState('networkidle')` resolves at once on a page that has
already been idle, so after a click on Save it often returns before the form
POST is even sent. A `page.goto()` or `page.reload()` right after it aborts the
POST (`net::ERR_ABORTED`), and the record is stored only if the server received
the request first; a read right after it sees the form as it was before the
save. A fixed `waitForTimeout()` only makes that rarer. In
netresearch/t3x-rte_ckeditor_image#929 the reload then showed the old image
width about once in 45 suite runs. FormEngine posts to `/typo3/record/edit`
(the route in 12.4, 13.4 and 14.3) and answers with a redirect, so wait for
that response, and start waiting before the click so a fast answer cannot be
missed:

```typescript
// Wrong - may return before the POST is sent; the goto can abort it
await frame.locator('button[name="_savedok"]').click();
await page.waitForLoadState('networkidle');
await page.goto(editUrl);

// Right - register the wait first, then click, then await it
const saved = page.waitForResponse(
  (r) => r.request().method() === 'POST' && r.url().includes('/typo3/record/edit'),
);
await frame.locator('button[name="_savedok"]').click();
expect((await saved).status()).toBeLessThan(400);
```

The same order applies to every `waitForResponse()`: a wait started after the
action can miss a response that already arrived and then times out.

**The maintenance modules ask for the password again, in the top document**

In TYPO3 12.4, 13.4 and 14.3 the four maintenance modules (Maintenance,
Settings, Upgrade, Environment) open a sudo-mode dialog before they render.
In 12 and 13 they sit under *Admin Tools* (`tools_toolsmaintenance`,
`tools_toolssettings`, `tools_toolsupgrade`, `tools_toolsenvironment`); in 14
under *System* (`system_maintenance`, `system_settings`, `system_upgrade`,
`system_environment`, with the old identifiers as aliases), per
`typo3/sysext/install/Configuration/Backend/Modules.php`. They require a system
maintainer; in Development context, or when no system maintainers are
configured, every admin counts as one. The dialog is a modal in
the **top** document, not inside `#typo3-contentIframe`, so a test that waits
for the module frame times out behind it. In
`Build/Sources/TypeScript/backend/security/element/sudo-mode.ts` (same
selectors in v12.4.45, v13.4.35 and v14.3.7) the modal carries the class
`modal-sudo-mode-verification`, the form `#verify-sudo-mode` with the field
`#password`, and a button named `verify`; the modal has no shadow root.

The dialog appears asynchronously, so wait for either the dialog or an element
the module renders before deciding, and fill it from the same variable as the
login. `locator.or()` cannot combine a top-document locator with one inside a
frame ("Frame locators are not allowed inside composite locators"), so race the
two waits:

While the dialog is open, the module frame shows a sudo-mode placeholder page
(template `SudoMode/Module` in EXT:backend, no `h1`). Pick a marker that only the real module
renders; a marker the placeholder also shows wins the race and leaves the
dialog open.

```typescript
// moduleMarker: an element the test expects in the module, e.g.
// page.frameLocator('#typo3-contentIframe').getByRole('heading', { name: 'Maintenance' })
async function passSudoMode(page: Page, moduleMarker: Locator): Promise<void> {
  const sudo = page.locator('.modal-sudo-mode-verification');
  const first = await Promise.race([
    sudo.waitFor().then(() => 'sudo'),
    moduleMarker.waitFor().then(() => 'module'),
  ]);
  if (first === 'sudo') {
    await sudo.locator('#password').fill(process.env.PLAYWRIGHT_ADMIN_PASSWORD ?? '');
    await sudo.locator('button[name="verify"]').click();
    await expect(sudo).toBeHidden();
    await moduleMarker.waitFor();
  }
}
```

**A full-page screenshot stops at the module frame**

`page.screenshot({ fullPage: true })` measures the outer shell, whose height is
the viewport; module content below it is not captured. Raise the viewport height
instead, to at least the module document's height
(`page.frameLocator('#typo3-contentIframe').locator('html').evaluate((el) => el.scrollHeight)`
plus the header above the frame). The screenshot rules and the
recipe live in the `typo3-docs` skill (`references/screenshots.md`); checking a
change by hand on a running instance is `live-instance-verification.md`.

**Fields in a non-active settings tab are attached, not visible**

In tabbed backend forms (e.g. the User Settings / Setup module), every tab pane
is rendered into the DOM but inactive panes are hidden via CSS. A field in a
non-default tab is therefore **attached but not visible**. Use `toBeAttached()`
to assert "the field rendered" without driving the (fragile) tab UI; reserve
`toBeVisible()` for when the field's tab is actually active.

```typescript
const frame = page.frameLocator('#typo3-contentIframe');
// Robust: proves the field rendered regardless of which tab is active
await expect(frame.locator('#my-field')).toBeAttached();
```

**WebAuthn needs a secure context, and a container name over http is not one**

Anything touching `navigator.credentials` — passkey login, WebAuthn MFA — is
unavailable unless the page is a secure context. A TYPO3 served from a container
the browser reaches by name over plain http is not: `window.isSecureContext` is
`false`, `window.PublicKeyCredential` is `undefined`, and every ceremony spec
fails on the environment rather than on the code.

Chromium trusts anything under `.localhost`, so point the browser at a name in
that space and resolve it to the container:

```typescript
const target = new URL(process.env.TYPO3_BASE_URL ?? 'http://localhost:8080');

use: {
    baseURL: 'http://typo3.localhost',
    launchOptions: {
        args: [`--host-resolver-rules=MAP typo3.localhost ${target.host}`],
    },
},
```

The replacement in a `MAP` rule may carry a port, and it overrides the
destination port — so `baseURL` stays port-less even when the instance listens
somewhere else. Measured: `MAP typo3.localhost probe-web:8080` with
`page.goto('http://typo3.localhost')` answers 200.

`--unsafely-treat-insecure-origin-as-secure` is the obvious alternative and does
not work here: Chromium honours it only together with `--user-data-dir`, and
`browserType.launch()` rejects that argument outright. Measured in the Playwright
image — plain container name: `isSecureContext=false`; with the flag: still
`false`; with the `.localhost` alias: `true`, and the CDP virtual authenticator
attaches.

The instance then sees `Host: typo3.localhost`, so anything deriving a WebAuthn
rpId or origin from the request host has to be configured to match. Gate the
rewrite on a variable your runner sets, or a run pointed at a real instance via
`TYPO3_BASE_URL` gets sent to a name its vhost never heard of.

**`page.request` resolves through Node, not through Chromium**

`--host-resolver-rules` is a browser flag. `page.request.*` and
`request.newContext()` are Playwright's own HTTP client and resolve with Node,
which knows nothing about it — so browser-driven specs pass while every API spec
dies with `getaddrinfo ENOTFOUND typo3.localhost`. Give the Playwright container
a hosts entry as well:

```bash
# The argument to add, alongside whatever the runner already passes
# (-v "${ROOT_DIR}:${ROOT_DIR}", -w, `npm ci &&`, ${IMAGE_PLAYWRIGHT}):
--add-host "typo3.localhost:${apache_ip}"
```

Read the address off the web container once it is up, since it is per run:

```bash
apache_ip=$(${CONTAINER_BIN} inspect "apache-${SUFFIX}" \
    --format '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}')
```

Measured both ways: without it `page.goto` returns 200 while `page.request` and
`request.newContext` both fail; with it all three answer 200.

**Do not start before the instance answers — and ask for every half you drive**

The provisioner hands over once it has seen one page: the shared runner asserts
that `/` returns 200 and starts the suite. That is the frontend. A suite that
also drives the backend meets the instance again at `/typo3/login`, and that
request can fail on its own — observed once in `t3x-nr-passkeys-fe` as Apache's
`DNS lookup failure for: phpfpm` on two attempts and a TYPO3 503 on the third,
after the `/` check had passed, while the fourteen tests that ran later all
passed. The failure lands on whichever specification runs first and reads as a
defect in the module it happened to open.

A `globalSetup` closes that window: poll the pages the suite needs until each
answers 200, with a deadline, and abort with what you last saw.

```typescript
// playwright.config.ts
export default defineConfig({
    globalSetup: './Tests/E2E/global-setup.ts',
    // …
});
```

Two things decide whether it works:

- **Poll the address the runner published, not the alias the browser uses.**
  `globalSetup` runs in Node, where `--host-resolver-rules` does not apply — the
  same split as `page.request` above. Take `TYPO3_BASE_URL`, and resolve the
  **same fallback the config uses** when it is unset, or a local run polls
  nothing while Playwright drives the DDEV URL. Export both from one module and
  import it in the config and in the setup, rather than repeating the expression:

  ```typescript
  // Tests/E2E/instance-address.ts
  export const target = process.env.TYPO3_BASE_URL ?? 'https://my-extension.ddev.site';
  export const browserBaseUrl = /* the alias, where the runner asks for one */;
  ```
- **Fail loudly, with the last observation.** `did not answer 200 within 120s —
  last seen: connect ECONNREFUSED` names the environment; a silent timeout sends
  the reader into the test.

Seen to fail before it is trusted: point the suite at a dead address and the run
must stop in `globalSetup` with exit 1, before the first test.

What it does not cover: a fault that starts after the suite has begun. Say that
in the file, so the next reader does not take the gate for more than it is.

**`config/system/additional.php` must assign, not return**

TYPO3 `require`s that file for its side effects and discards its return value
(`ConfigurationManager::exportConfiguration()`). A provisioning script that
writes `<?php return ['SYS' => [...]];` configures nothing at all, and the file
is valid PHP either way, so nothing catches it by inspection — the tell is an
exception in an e2e run reported by the `ProductionExceptionHandler` while the
file names the `DebugExceptionHandler`.

```php
<?php
// Wrong: TYPO3 never reads this
return ['SYS' => ['displayErrors' => 1]];

// Right
$GLOBALS['TYPO3_CONF_VARS']['SYS']['displayErrors'] = 1;
```

Worth an executed check rather than a review comment: cut the generated file
out, `require` it, and assert the keys arrive in `TYPO3_CONF_VARS`.

**A router script for `php -S` is a tainted-filename sink**

Some E2E setups start the PHP built-in server with a router script
(`php -S 0.0.0.0:8080 -t .Build/Web Build/Scripts/router.php`). The usual
router appends the request path to the document root and returns `false`
when `is_file()` finds it, so the server delivers the static file itself.
That path comes straight from `REQUEST_URI`, so SAST flags it
(Semgrep/Opengrep `php.lang.security.injection.tainted-filename.tainted-filename`).
With `return false` the built-in server still serves only files inside its
document root, so a request such as `/../secret.txt` falls through to
TYPO3. A router that reads or includes the file itself (`readfile($file)`)
does serve it, and there the traversal is real.

Confine the resolved path to the document root with `realpath()`:

```php
<?php
// Build/Scripts/router.php
declare(strict_types=1);

$path    = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);
$path    = is_string($path) ? $path : '';
$docRoot = realpath(__DIR__ . '/../../.Build/Web');
$file    = $docRoot === false ? false : realpath($docRoot . $path);

// Serve a static file only when its real path stays inside the document root
if (
    $file !== false
    && $docRoot !== false
    && str_starts_with($file, $docRoot . DIRECTORY_SEPARATOR)
    && is_file($file)
) {
    return false;
}

// Everything else goes through TYPO3
$_SERVER['SCRIPT_NAME'] = '/index.php';
$_SERVER['SCRIPT_FILENAME'] = __DIR__ . '/../../.Build/Web/index.php';
require __DIR__ . '/../../.Build/Web/index.php';
```

This clears the finding at its source. Do not suppress it with
`// nosemgrep` instead: the suppression is not reliable, and GitHub code
scanning can mark the existing alert "fixed" while a new alert opens on the
suppressed line. Verify the fix with the scanner version CI pins: one
finding on the unguarded router, zero after the change.

**A server-side file cache usually cannot be reset from the test side**

The instinct — delete the cache directory between tests to clear a counter — hits
two walls in a containerised instance. PHP-FPM typically runs as root there, so
the cache files belong to root in a directory that is not group-writable, and the
Playwright container gets `EACCES` on every attempt. Renaming the directory *is*
permitted when the parent is world-writable and still does not work: PHP-FPM
resolves the old path out of its **realpath cache** until `realpath_cache_ttl`
expires — 120 seconds by default, and configurable — and keeps writing into the
directory that was moved aside, so the counter goes on climbing in a directory
nothing is looking at.

Configure the instance instead — raise the limit, shorten the window — and keep
the deletion only as the path that works when the instance belongs to whoever
runs the suite.

**Do not assert a shared per-IP counter at this level**

Rate limiters key on the client address, and every spec in a run arrives from the
same one. A spec that deliberately exhausts the budget takes it from everything
that runs after it, and the verdicts then follow the execution order rather than
the code: which specs fail changes with the file order. Assert the refusal where
it can be driven deterministically — a unit test over the limiter service — and
keep the e2e assertion to what only this level sees, that the endpoint holds its
contract under a burst instead of answering 500.

## E2E Testing for AJAX Endpoints

Backend modules often use AJAX routes for dynamic functionality. Test these endpoints thoroughly:

### Intercepting AJAX Requests

```typescript
// Build/tests/playwright/e2e/backend/ajax-module.spec.ts
import { test, expect } from '../../fixtures/setup-fixtures';

test.describe('AJAX Endpoint Testing', () => {
  test('validates form via AJAX', async ({ page, backend }) => {
    await backend.gotoModule('web_myextension_wizard');

    // Intercept the AJAX validation request
    const validationPromise = page.waitForResponse(
      (response) =>
        response.url().includes('/ajax/myext/wizard/validate') &&
        response.status() === 200
    );

    // Fill form and trigger validation
    await backend.contentFrame.getByLabel('Provider Name').fill('My Provider');
    await backend.contentFrame.getByLabel('API Key').fill('sk-test-123');
    await backend.contentFrame.getByRole('button', { name: 'Next' }).click();

    // Verify AJAX response
    const response = await validationPromise;
    const json = await response.json();
    expect(json.success).toBe(true);
    expect(json.errors).toEqual({});
  });

  test('handles validation errors from AJAX', async ({ page, backend }) => {
    await backend.gotoModule('web_myextension_wizard');

    // Wait for the error response, registered before the submit
    const responsePromise = page.waitForResponse(
      (r) => r.url().includes('/ajax/myext/wizard/validate')
    );

    // Submit without required fields
    await backend.contentFrame.getByRole('button', { name: 'Next' }).click();

    const response = await responsePromise;
    const json = await response.json();

    expect(json.success).toBe(false);
    expect(json.errors).toHaveProperty('name');

    // Verify error is displayed in UI
    await expect(
      backend.contentFrame.locator('.invalid-feedback')
    ).toBeVisible();
  });
});
```

### Testing Connection/Test Buttons

```typescript
test('tests API connection via AJAX', async ({ page, backend }) => {
  await backend.gotoModule('web_myextension_wizard');

  // Fill connection details
  await backend.contentFrame.getByLabel('API Key').fill('sk-test-123');

  // Mock successful connection response
  await page.route('**/ajax/myext/wizard/test-connection', async (route) => {
    await route.fulfill({
      status: 200,
      contentType: 'application/json',
      body: JSON.stringify({
        success: true,
        message: 'Connection successful',
        models: [
          { id: 'gpt-4o', name: 'GPT-4o' },
          { id: 'gpt-4o-mini', name: 'GPT-4o Mini' },
        ],
      }),
    });
  });

  // Click test button
  const testButton = backend.contentFrame.getByRole('button', {
    name: 'Test Connection',
  });
  await testButton.click();

  // Verify success notification
  await expect(page.locator('.alert-success')).toBeVisible();

  // Verify models were populated
  const modelSelect = backend.contentFrame.getByLabel('Model');
  await expect(modelSelect.locator('option')).toHaveCount(3); // including empty option
});

test('handles connection failure gracefully', async ({ page, backend }) => {
  await backend.gotoModule('web_myextension_wizard');
  await backend.contentFrame.getByLabel('API Key').fill('invalid-key');

  // Mock failed connection
  await page.route('**/ajax/myext/wizard/test-connection', async (route) => {
    await route.fulfill({
      status: 400,
      contentType: 'application/json',
      body: JSON.stringify({
        success: false,
        message: 'Invalid API key',
      }),
    });
  });

  await backend.contentFrame
    .getByRole('button', { name: 'Test Connection' })
    .click();

  // Verify error notification
  await expect(page.locator('.alert-danger')).toBeVisible();
  await expect(page.locator('.alert-danger')).toContainText('Invalid API key');
});
```

### Testing Multi-Step Wizards

```typescript
test('completes multi-step wizard', async ({ page, backend }) => {
  await backend.gotoModule('web_myextension_wizard');

  // Step 1: Provider
  await backend.contentFrame.getByLabel('Provider Name').fill('OpenAI Prod');
  await backend.contentFrame.getByLabel('API Key').fill('sk-test-key');

  // Wait for test to complete (registered before the click)
  const tested = page.waitForResponse((r) =>
    r.url().includes('/ajax/myext/wizard/test-connection')
  );
  await backend.contentFrame
    .getByRole('button', { name: 'Test Connection' })
    .click();
  await tested;
  await backend.contentFrame.getByRole('button', { name: 'Next' }).click();

  // Step 2: Model (verify we advanced)
  await expect(backend.contentFrame.locator('h2')).toContainText('Step 2');
  await backend.contentFrame.getByLabel('Model').selectOption('gpt-4o');
  await backend.contentFrame.getByRole('button', { name: 'Next' }).click();

  // Step 3: Configuration
  await expect(backend.contentFrame.locator('h2')).toContainText('Step 3');
  await backend.contentFrame.getByLabel('Temperature').fill('0.7');

  // Verify completion (wait registered before the click)
  const saveResponsePromise = page.waitForResponse(
    (r) =>
      r.url().includes('/ajax/myext/wizard/save') && r.status() === 200
  );
  await backend.contentFrame.getByRole('button', { name: 'Finish' }).click();
  const saveResponse = await saveResponsePromise;
  const result = await saveResponse.json();
  expect(result.success).toBe(true);

  // Verify redirect or success message
  await expect(backend.contentFrame.locator('.wizard-complete')).toBeVisible();
});
```

### Testing Toggle Actions

```typescript
test('toggles record active state via AJAX', async ({ page, backend }) => {
  await backend.gotoModule('web_myextension');

  // Wait for list to load
  await expect(backend.contentFrame.locator('table tbody tr')).toHaveCount(3);

  // Click toggle button
  const toggleButton = backend.contentFrame
    .locator('tr')
    .first()
    .getByRole('button', { name: 'Toggle' });

  // Verify AJAX call succeeded (wait registered before the click)
  const responsePromise = page.waitForResponse(
    (r) =>
      r.url().includes('/ajax/myext/toggle') && r.status() === 200
  );
  await toggleButton.click();
  const response = await responsePromise;
  const json = await response.json();
  expect(json.success).toBe(true);

  // Verify UI updated
  await expect(toggleButton).toHaveAttribute('data-active', 'false');
});
```

### Network Request Assertions

```typescript
test('sends correct request payload', async ({ page, backend }) => {
  await backend.gotoModule('web_myextension_wizard');

  // Capture the request
  const requestPromise = page.waitForRequest(
    (r) => r.url().includes('/ajax/myext/wizard/validate')
  );

  await backend.contentFrame.getByLabel('Name').fill('Test Provider');
  await backend.contentFrame.getByLabel('Type').selectOption('openai');
  await backend.contentFrame.getByRole('button', { name: 'Validate' }).click();

  const request = await requestPromise;
  const postData = request.postDataJSON();

  expect(postData).toEqual({
    step: 'provider',
    data: {
      name: 'Test Provider',
      type: 'openai',
    },
  });
});
```

### AJAX Timeout and Error Handling

```typescript
test('handles AJAX timeout gracefully', async ({ page, backend }) => {
  await backend.gotoModule('web_myextension_wizard');

  // Simulate slow/timeout response
  await page.route('**/ajax/myext/wizard/test-connection', async (route) => {
    await new Promise((resolve) => setTimeout(resolve, 35000)); // Exceed timeout
    await route.abort('timedout');
  });

  await backend.contentFrame.getByLabel('API Key').fill('sk-test');
  await backend.contentFrame
    .getByRole('button', { name: 'Test Connection' })
    .click();

  // Verify timeout error displayed
  await expect(page.locator('.alert-warning')).toBeVisible({ timeout: 40000 });
  await expect(page.locator('.alert-warning')).toContainText('timed out');
});
```

## Ad-hoc Browser Check Without Playwright (CDP Fallback)

Use this when Playwright is not installed and cannot be added right now
(npm blocked by a proxy, one-off verification on a developer machine) and a
real browser run is still needed, for example a form whose submission depends
on client-side JavaScript or server-side state. Which tool fits, what the
report carries, and rule 4 (read only on shared or production instances;
creating records needs the human's go first) are in
`live-instance-verification.md`; the submit example below writes a record and
sends a mail.

**Why not curl:** a scripted POST to an EXT:form form has to reproduce
`__state`, `__trustedProperties`, the session cookie (the honeypot field has a
random name stored in the session) and every value the page's JavaScript fills
in. A missing `__state` makes the form framework re-render page 1 with HTTP 200
and no error; a tampered `__state` or `__trustedProperties` throws
`BadRequestException` (1581862823 / 1581862822), which shows the generic error
content in production. Reconstructing the request costs more than driving a
browser when JavaScript fills values.

**Why not `--dump-dom`:** `chrome --headless=new --dump-dom` prints the DOM
after JavaScript ran, but it cannot interact with the page, and it does not
exit if the load event never fires (a hung subresource or body).

**What works:** Node.js >= 22 ships a global `WebSocket`, so the Chrome DevTools
Protocol needs no dependency. A minimal runner navigates to a URL and evaluates
one or more JavaScript expressions in order, waiting before each one. It picks
a free debugging port, uses a throwaway profile, and exits non-zero when
Chrome does not start, the DevTools connection fails or drops, navigation fails
(a network error, or an HTTP error status with an empty body), or an expression
throws. DDEV certificates come from mkcert and are trusted once
`mkcert -install` has run, so `CDP_INSECURE=1` (which adds
`--ignore-certificate-errors`) is only for a disposable local instance with an
untrusted certificate. An HTTP error status that comes with a page (TYPO3's
404 or 500 page) is a successful navigation: the runner prints what the
expression returns and exits 0, so the read expression has to check the
content. Expressions travel as command-line arguments, so a
password filled in by an expression ends up in the shell history, the
transcript and `ps`, which breaks rule 5 (no password in the context) of
`live-instance-verification.md`:

```js
// cdp-eval.mjs — [CDP_INSECURE=1] CHROME=/path/to/chrome node cdp-eval.mjs <url> "<expression>" ["<expression>" ...]
import { spawn } from 'node:child_process';
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';

const [url, ...expressions] = process.argv.slice(2);
if (!url || expressions.length === 0) {
  console.error('usage: node cdp-eval.mjs <url> "<expression>" ["<expression>" ...]');
  process.exit(2);
}
const bin = process.env.CHROME ?? 'google-chrome';
const insecure = process.env.CDP_INSECURE === '1' ? ['--ignore-certificate-errors'] : [];
const profile = fs.mkdtempSync(path.join(os.tmpdir(), 'cdp-'));
const chrome = spawn(bin, [
  '--headless=new', '--disable-gpu', ...insecure,
  '--remote-debugging-port=0', `--user-data-dir=${profile}`, 'about:blank',
], { stdio: 'ignore' });
let spawnError;
// created here, not in finally: an 'exit' that already fired would never resolve it
const exited = new Promise((resolve) => {
  chrome.once('exit', resolve);
  chrome.once('error', (error) => { spawnError = error; resolve(); });
});
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

try {
  let port;
  for (let attempt = 0; attempt < 30 && !port && !spawnError; attempt++) {
    try { port = fs.readFileSync(path.join(profile, 'DevToolsActivePort'), 'utf8').split('\n')[0]; } catch { await sleep(300); }
  }
  if (spawnError) throw new Error(`Cannot start Chrome (${bin}): ${spawnError.message}`);
  if (!port) throw new Error(`Chrome (${bin}) did not open a DevTools port`);
  const version = await (await fetch(`http://127.0.0.1:${port}/json/version`)).json();
  const ws = new WebSocket(version.webSocketDebuggerUrl);
  let id = 0;
  const pending = {}; // command id -> reply handler
  await new Promise((resolve, reject) => {
    const timer = setTimeout(() => reject(new Error('DevTools socket did not open within 10 s')), 10_000);
    ws.onopen = () => { clearTimeout(timer); resolve(); };
    ws.onerror = () => { clearTimeout(timer); reject(new Error('DevTools socket failed')); };
    ws.onclose = () => { // also after open: fail every command still waiting for a reply
      clearTimeout(timer);
      reject(new Error('DevTools socket closed'));
      for (const i in pending) pending[i]({ error: { message: 'DevTools socket closed' } });
    };
  });
  ws.onmessage = (event) => { const m = JSON.parse(event.data); if (m.id && pending[m.id]) { pending[m.id](m); delete pending[m.id]; } };
  const send = (method, params = {}, sessionId) => new Promise((resolve, reject) => {
    if (ws.readyState !== WebSocket.OPEN) throw new Error(`${method}: DevTools socket closed`);
    const i = ++id;
    pending[i] = (m) => (m.error ? reject(new Error(`${method}: ${m.error.message}`)) : resolve(m.result));
    ws.send(JSON.stringify({ id: i, method, params, sessionId }));
  });

  const { targetId } = await send('Target.createTarget', { url: 'about:blank' });
  const { sessionId } = await send('Target.attachToTarget', { targetId, flatten: true });
  await send('Page.enable', {}, sessionId);
  const nav = await send('Page.navigate', { url }, sessionId);
  if (nav.errorText) throw new Error(`Navigation to ${url} failed: ${nav.errorText}`);
  for (const expression of expressions) {
    await sleep(3000); // give the page's own JavaScript (or a form POST) time; poll the DOM instead if timing matters
    const { result, exceptionDetails } = await send('Runtime.evaluate', { expression, awaitPromise: true, returnByValue: true }, sessionId);
    if (exceptionDetails) throw new Error(exceptionDetails.exception?.description ?? exceptionDetails.text);
    console.log(result.value);
  }
} catch (error) {
  console.error(error.message);
  process.exitCode = 1;
} finally {
  chrome.kill('SIGKILL');
  await exited; // Chrome still writes to the profile until it has exited
  fs.rmSync(profile, { recursive: true, force: true });
}
```

A standard EXT:form submits with a full page load, and that load destroys the
JavaScript execution context. If the submit and the read happen in one
expression, CDP fails with `Inspected target navigated or closed` after the POST
was already sent. Pass a submit expression and a read expression as separate
arguments; the runner waits before each:

```js
// expression 1: fill and submit; returns before the navigation starts
(() => {
  const form = document.querySelector('form');
  // adapt the selector to the form's identifier
  form.querySelector('[name$="[email]"]').value = `tester@${location.hostname}`; // resolves in DDEV, lands in Mailpit
  const submit = [...form.querySelectorAll('button[type=submit]')].at(-1);
  form.requestSubmit(submit);
})()
```

```js
// expression 2: runs on the result page
document.body.innerText.slice(0, 300)
```

`requestSubmit()` fires the `submit` listeners and runs constraint validation
like a click; passing the button matters for EXT:form because the navigation
buttons carry `__currentPage`, which `requestSubmit()` without an argument does
not send. On page 2 and later of a multi-step form the first `button[type=submit]`
is the *previous* button, so pick the last one (or the specific button) instead.

Then verify the server side, not the screen: the record the finisher wrote,
the mail in the mail catcher (Mailpit in DDEV), the log entry. Two TYPO3
specifics to keep in mind when choosing test data: `MAIL.validators` may
contain `DNSCheckValidation`, which rejects reserved top-level names (`.test`,
`.example`, `.invalid`, `.localhost`, `.local`, `.intranet`, `.internal`, ...)
outright, and `example.com` / `example.org` fail because they publish a null MX
record; an address on the DDEV hostname (`tester@<project>.ddev.site`)
resolves via its A record (127.0.0.1, needs public DNS) and is caught by
Mailpit. EXT:form honeypot fields must stay empty.

## PHP-Based E2E Testing (Alternative)

For extensions that primarily test API interactions without browser UI, PHP-based E2E tests offer a lightweight alternative to Playwright.

### When to Use PHP E2E Tests

- Testing complete workflows without browser interaction
- API endpoint verification with mocked HTTP clients
- Multi-provider integrations (LLM, payment gateways)
- When Playwright overhead is unnecessary

### Directory Structure

```
Tests/
├── E2E/
│   ├── AbstractE2ETestCase.php
│   └── Backend/
│       ├── AbstractBackendE2ETestCase.php
│       └── ConfigurationWorkflowE2ETest.php
```

### Base Test Case

```php
<?php

declare(strict_types=1);

namespace Vendor\Extension\Tests\E2E;

use GuzzleHttp\Psr7\HttpFactory;
use GuzzleHttp\Psr7\Response;
use PHPUnit\Framework\MockObject\Stub;
use PHPUnit\Framework\TestCase;
use Psr\Http\Client\ClientInterface;
use Psr\Http\Message\RequestFactoryInterface;
use Psr\Http\Message\RequestInterface;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\StreamFactoryInterface;

/**
 * Base class for PHP-based End-to-End tests.
 *
 * E2E tests verify complete workflows from service entry point
 * through to response handling, using mocked HTTP clients to
 * simulate external API interactions.
 */
abstract class AbstractE2ETestCase extends TestCase
{
    protected RequestFactoryInterface $requestFactory;
    protected StreamFactoryInterface $streamFactory;

    protected function setUp(): void
    {
        parent::setUp();
        $this->requestFactory = new HttpFactory();
        $this->streamFactory = new HttpFactory();
    }

    /**
     * Create a stub HTTP client that returns sequential responses.
     *
     * @param list<ResponseInterface> $responses
     */
    protected function createMockHttpClient(array $responses): ClientInterface&Stub
    {
        $client = self::createStub(ClientInterface::class);
        $client->method('sendRequest')
            ->willReturnOnConsecutiveCalls(...$responses);

        return $client;
    }

    /**
     * Create a request-capturing HTTP client.
     *
     * @return array{client: ClientInterface&Stub, requests: array<RequestInterface>}
     */
    protected function createCapturingHttpClient(ResponseInterface $response): array
    {
        $requests = [];
        $client = self::createStub(ClientInterface::class);
        $client->method('sendRequest')
            ->willReturnCallback(function (RequestInterface $request) use ($response, &$requests) {
                $requests[] = $request;
                return $response;
            });

        return ['client' => $client, 'requests' => &$requests];
    }

    /**
     * Create a JSON success response.
     *
     * @param array<string, mixed> $data
     */
    protected function createJsonResponse(array $data, int $status = 200): ResponseInterface
    {
        return new Response(
            status: $status,
            headers: ['Content-Type' => 'application/json'],
            body: \json_encode($data, JSON_THROW_ON_ERROR),
        );
    }
}
```

### E2E Test Example

```php
<?php

declare(strict_types=1);

namespace Vendor\Extension\Tests\E2E\Backend;

use Vendor\Extension\Service\ProviderService;
use Vendor\Extension\Service\ConfigurationService;
use Vendor\Extension\Tests\E2E\AbstractE2ETestCase;

/**
 * E2E test for complete provider configuration workflow.
 */
final class ConfigurationWorkflowE2ETest extends AbstractE2ETestCase
{
    /**
     * @test
     * Complete workflow: create provider -> test connection -> save configuration
     */
    public function completeProviderConfigurationWorkflow(): void
    {
        // Arrange: Mock external API responses
        $testConnectionResponse = $this->createJsonResponse([
            'models' => [
                ['id' => 'gpt-4o', 'name' => 'GPT-4o'],
                ['id' => 'gpt-4o-mini', 'name' => 'GPT-4o Mini'],
            ],
        ]);

        $chatResponse = $this->createJsonResponse([
            'id' => 'chatcmpl-123',
            'choices' => [
                ['message' => ['content' => 'Test successful']],
            ],
        ]);

        $httpClient = $this->createMockHttpClient([
            $testConnectionResponse,
            $chatResponse,
        ]);

        // Create services with mocked HTTP client
        $providerService = new ProviderService($httpClient, $this->requestFactory);
        $configService = new ConfigurationService($providerService);

        // Act: Execute complete workflow
        // Step 1: Test connection
        $connectionResult = $providerService->testConnection('sk-test-key');
        self::assertTrue($connectionResult->isSuccessful());
        self::assertCount(2, $connectionResult->getModels());

        // Step 2: Configure provider
        $config = $configService->createProviderConfiguration(
            name: 'Production OpenAI',
            apiKey: 'sk-test-key',
            model: 'gpt-4o',
        );
        self::assertNotNull($config->getId());

        // Step 3: Verify configuration works
        $testResult = $providerService->sendTestMessage($config, 'Hello');
        self::assertSame('Test successful', $testResult->getContent());
    }

    /**
     * @test
     * Workflow handles connection failure gracefully
     */
    public function workflowHandlesConnectionFailure(): void
    {
        // Arrange: Mock failed connection
        $errorResponse = $this->createJsonResponse(
            ['error' => ['message' => 'Invalid API key']],
            401
        );

        $httpClient = $this->createMockHttpClient([$errorResponse]);
        $providerService = new ProviderService($httpClient, $this->requestFactory);

        // Act & Assert
        $result = $providerService->testConnection('invalid-key');

        self::assertFalse($result->isSuccessful());
        self::assertStringContainsString('Invalid API key', $result->getErrorMessage());
    }
}
```

### Combining PHP E2E with Playwright

For comprehensive testing, use both approaches:

| Test Type | PHP E2E | Playwright E2E |
|-----------|---------|----------------|
| API workflows | ✓ | |
| HTTP request/response | ✓ | |
| Multi-provider logic | ✓ | |
| Browser UI interactions | | ✓ |
| JavaScript behavior | | ✓ |
| Accessibility (axe-core) | | ✓ |
| Visual regression | | ✓ |

```bash
# Run PHP E2E tests (fast, no browser)
Build/Scripts/runTests.sh -s unit  # Or separate e2e-php suite

# Run Playwright E2E tests (browser-based)
Build/Scripts/runTests.sh -s e2e
```

## Resources

- [Playwright Documentation](https://playwright.dev/docs/intro)
- [TYPO3 Core Playwright Tests](https://github.com/TYPO3/typo3/tree/main/Build/tests/playwright)
- [Playwright Test API](https://playwright.dev/docs/api/class-test)
- [Page Object Model](https://playwright.dev/docs/pom)
- [Playwright Network Mocking](https://playwright.dev/docs/mock)
- [PSR-18 HTTP Client](https://www.php-fig.org/psr/psr-18/) - For PHP E2E tests
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall