PicklePantherBundle

A YAML-driven end-to-end testing engine for Symfony, built on top of Symfony Panther.

Write browser scenarios in near-natural language (French or English), mapped to PHP "sentences", and get a self-contained HTML report — without a line of Behat/Gherkin glue.

How it works

Installation

Register the bundle for the test environment (config/bundles.php):

Browser & driver (required, on the machine that runs the tests)

PicklePanther drives a real, local browser through Symfony Panther — there is no remote/Selenium mode. Two binaries must therefore be present on the same machine/container where PHPUnit runs:

1. Chrome or Chromium — the actual browser that gets launched.
2. chromedriver — the WebDriver server Panther talks to.

Their major versions must match (e.g. Chrome 149.x ↔ chromedriver 149.x). A mismatch makes the browser session fail to start (session not created: This version of ChromeDriver only supports Chrome version N).

Install a matching chromedriver the easy way — it lands in ./drivers/, which Panther auto-detects (it searches ./drivers and ./vendor/bin):

Or point to an existing binary explicitly:

Docker / where the browser must live. Because the browser is launched locally by the test process, it must be reachable from wherever PHPUnit runs:

• PHPUnit inside a container → install Chrome and chromedriver in that container (a browser on the host is not usable from inside the container).
• PHPUnit on the host → install them on the host. To still exercise an app served elsewhere (e.g. a Dockerised app on https://localhost:444), point the tests at it with PANTHER_EXTERNAL_BASE_URI instead of letting Panther start its own web server.

HTTPS target with a self-signed certificate. Pass the flag through PANTHER_CHROME_ARGUMENTS (read by Panther's ChromeManager), e.g. PANTHER_CHROME_ARGUMENTS=--ignore-certificate-errors. Chrome arguments set only via PHPUnit/bundle capabilities are not forwarded to the launched browser, so the certificate prompt would otherwise block the page.

PHPUnit configuration

Register Panther's web server and the report extension in phpunit.xml.dist:

output_dir (extension parameter / PICKLE_PANTHER_OUTPUT_DIR) should match pickle_panther.report.output_dir so screenshots and the report land together.

Configuration

All keys are optional; defaults are shown.

Keep credentials out of the repository — read them from environment variables.

Where to put the file. If the bundle is only enabled in dev/test (config/bundles.php), put the config under config/packages/test/ (not the root config/packages/): a root file is also loaded in prod, where the bundle is absent, and Symfony would fail with "no extension able to load pickle_panther".

Real-world example

A complete config/packages/test/pickle_panther.yaml, including registering project-specific sentence providers and a French-named role map:

Writing scenarios

A scenario file holds a scenarios list. Keys are bilingual:

Two ways to pass arguments

1. Placeholder + args (explicit). The action reuses the registered sentence verbatim and values are listed under args:

args are matched to the method parameters by name when the keys match the parameter names (the natural case, since placeholders mirror parameter names); otherwise they are passed positionally in declaration order.

2. Inline values (concise). Write the value directly inside the brackets and drop args — values are bound to the method parameters positionally, in placeholder order:

The exact-placeholder form always wins the lookup, so the two styles coexist freely. Limitation: an inline value must not contain a closing bracket ] (e.g. CSS attribute selectors like [data-x="y"]) — use the explicit args: form for those.

Bundled sentences

CommonSentences (navigation, clicking, typing, waiting, assertions) and AdminSentences (generic back-office menus/datagrids) ship enabled. Browse them for the exact sentence strings — each method is annotated with its FR and EN #[Sentence].

To list every available sentence (bundled and your own) without reading the code, run the console command — it introspects the registered providers:

Adding your own sentences

Create a provider; autoconfiguration registers it automatically:

$this->client() is the current Panther client; $this->testCase() exposes the PHPUnit assertions.

Authentication

Authentication is project-specific, so it is pluggable.

• Form login out of the box: set pickle_panther.auth (above). The bundle wires a FormLoginAuthenticator and aliases it to AuthenticatorInterface.
• Custom flow: implement AuthenticatorInterface (or extend FormLoginAuthenticator) and alias your service:

A scenario then requests a logged-in context:

The HTML report

After the suite finishes, HtmlReportExtension writes a multi-page report next to <output_dir>/report.html:

• report.html — a home page listing each scenario YAML file as a link, with a status icon and per-file scenario/step counts.
• report-N.html — one page per YAML file, containing all its scenarios and steps (status, timing, context badges, screenshots), with a breadcrumb back to the home page.

Screenshots resolve relatively (captures/…), so serving the output directory (or opening report.html) is enough. Set pickle_panther.debug: true (or run with E2E_DEBUG=1) to capture a screenshot on every step, not just failures.

Each report-N.html page also has a slideshow popin to review the captures as a slide deck: the image is centered, the step detail (scenario, title, action with highlighted arguments, OK/FAIL status) sits below with a step counter (e.g. 4 / 48). Open it from the "Diaporama des captures" button or by clicking any capture thumbnail; navigate with the on-screen arrows or the keyboard (←/→), close with the × button, a backdrop click or Esc. It shines with debug enabled (a capture per step) but also works with failure-only captures.

Requirements

• PHP >= 8.2
• Symfony ^7.1 || ^8.0
• Chrome/Chromium and a version-matched chromedriver, both installed on the machine/container that runs the tests (see Browser & driver).

Author

Pascal CESCON (@Amoifr) · [email protected]

Changelog

See CHANGELOG.md. This project follows Semantic Versioning.

License

Released under the MIT License.