e2e-panther-playwright · diff
git:20261005.042befb to git:20261005.625d3c1
17 added, 12 removed. Audit A to A.
---
name: e2e-panther-playwright
description: Write end-to-end tests with Symfony Panther 2.4 for browser automation or Playwright for complex scenarios
capabilities: [read, search]
tags: [testing]
# projected by `bun run build` — do not edit by hand
allowed-tools:
- Read
- Glob
- Grep
---
# E2e Panther Playwright (Symfony)
## Use when
- - Building regression-safe behavior with TDD/functional/e2e tests.
- - Converting bug reports into executable failing tests.
+ - A flow needs a real browser: JavaScript, multi-page journeys such as login, checkout or signup.
+ - `WebTestCase` cannot see the behavior because it depends on client-side rendering.
+ - Cross-browser needs (WebKit, tracing, video) that WebDriver does not cover: run Playwright separately.
+ - Debugging a browser test that fails only in CI.
## Default workflow
- 1. Write failing test for target behavior and one boundary case.
- 2. Implement minimal code to pass.
- 3. Refactor while preserving green suite.
- 4. Broaden coverage for invalid/unauthorized/not-found paths.
+ 1. Pick the client: `static::createPantherClient()` for a real browser, `static::createClient()` when no JavaScript is needed.
+ 2. Install `symfony/panther` and `dbrekelmans/bdi`, run `vendor/bin/bdi detect drivers`, and register `ServerExtension` in `phpunit.dist.xml`.
+ 3. Extend `PantherTestCase` and drive the flow with explicit waits: `waitFor()`, `waitForVisibility()`, `waitForElementToContain()`.
+ 4. Assert future state with `assertSelectorWillExist()` or `assertSelectorWillContain()`, current state with `assertSelectorIsVisible()`.
+ 5. Keep the suite in `tests/E2E` and reset the database between tests (DAMADoctrineTestBundle or Foundry).
+ 6. Debug with `PANTHER_NO_HEADLESS=1` and `--debug`; set `PANTHER_NO_SANDBOX=1` in CI.
## Guardrails
- - Prefer deterministic fixtures/builders.
- - Assert observable behavior, not internal implementation.
- - Keep tests isolated and stable in CI.
+ - Never rely on implicit timing: every async step gets a `waitFor*` or an `assertSelectorWill*`.
+ - Target `data-testid` attributes, not styling classes.
+ - Delete the PNGs written by `takeScreenshot()` or `PANTHER_ERROR_SCREENSHOT_DIR`; never commit them.
+ - E2E is slow: cover critical paths only and keep it apart from unit tests.
## Progressive disclosure
- Use this file for execution posture and risk controls.
- Open references when deep implementation details are needed.
## Output contract
- - RED/GREEN/REFACTOR trace.
- - Test files changed and executed commands.
- - Coverage and confidence notes.
+ - E2E test files, with the client type and the wait strategy used.
+ - Driver setup, `ServerExtension` registration and the `PANTHER_*` variables needed locally and in CI.
+ - Confirmation that screenshots were cleaned up.
## References
- `reference.md`