PlaywrightPHP

Mink Driver

A Mink driver backed by real browsers, validated against the official driver test suite.

The playwright-php/playwright-mink package is a Mink driver powered by Playwright PHP. Existing Mink-based suites keep their Session API and gain real Chromium, Firefox, and WebKit engines, headless or headed.

bash
composer require --dev playwright-php/playwright-mink

Usage

php
use Behat\Mink\Session;
use Playwright\Mink\Driver\PlaywrightDriver;

$driver = new PlaywrightDriver(browserType: 'chromium', headless: true);
$session = new Session($driver);

$session->start();
$session->visit('https://example.org');

echo $session->getPage()->getText();

$session->stop();

The regular browser workflows are covered: navigation, forms, cookies, JavaScript evaluation, iframes, uploads, screenshots, and input. The driver is validated against minkphp/driver-testsuite, with documented exclusions for jQuery UI drag-and-drop and synchronous popup discovery.

Why swap the driver

  • Real engines instead of a headless emulation layer: what fails for a user fails in the suite.
  • WebKit and Firefox coverage from the same suite, by changing browserType.
  • One browser stack for the whole project when other suites already use Playwright PHP.

Version 1.0.0 is published. Repository CI currently runs the official suite with Chromium on PHP 8.3 and 8.4; treat Firefox, WebKit, and PHP 8.2 support as allowed but not continuously verified.

Recommended path

Use the driver as a compatibility bridge. First replace the old driver and keep the suite behavior stable. Then identify the places where native Playwright PHP would make tests clearer: modern locators, trace-first debugging, network routing, browser contexts, or web-first assertions.

Do not force every old test through a rewrite at the same time as the driver migration. That makes failures hard to classify. Driver migration should answer "does the old coverage still run on real browsers?" Test redesign should happen in smaller follow-up steps.

Operational notes

Keep browser engine selection explicit in configuration. Existing Mink suites often assume one browser-like environment. Real Chromium, Firefox, and WebKit may expose timing, focus, layout, or JavaScript differences that were hidden by the old driver.

Upload screenshots and traces when possible. A Mink abstraction can make failures less Playwright-specific in the report, so browser artifacts are important evidence.

Adoption checklist

Before switching drivers, confirm:

  • the existing Mink suite still protects valuable behavior;
  • the current driver is a bottleneck or lacks engine fidelity;
  • CI can install and cache browser binaries;
  • the team can triage real-browser differences;
  • the migration is separated from test redesign.

This reduces ambiguity. If a test fails after the switch, you want to know whether the old test was wrong, the new driver behaved differently, or the product actually fails in a real browser.

What this integration is not

It is not the best abstraction for new Playwright-specific work. Native Playwright PHP gives direct locators, context options, traces, network routing, event handling, and assertions.

Keep Mink where compatibility is valuable. Use native Playwright PHP when the compatibility layer hides the feature you need.

Troubleshooting

  • A form test changed behavior: compare real browser validation with the old driver’s form model.
  • JavaScript timing changed: replace sleeps with stronger visible conditions where the suite allows it.
  • A feature needs Playwright-only APIs: move that flow to a native Playwright PHP test.
  • CI is slower: run the full legacy browser suite less often while migrating high-value flows.

FAQ

Is this a permanent architecture?

It can be, but it is often best as a migration bridge. Keep it where Mink is valuable; use native Playwright PHP where direct browser control is clearer.

Does driver compatibility mean identical failures?

No. Real browsers can expose different layout, focus, validation, and JavaScript behavior than the previous driver.

See also