dmore / chrome-mink-driver

2.10.0 2025-10-03 23:14 UTC

Requires

• php: ^8.1
• ext-curl: *
• ext-json: *
• ext-mbstring: *
• behat/mink: ^1.9
• phrity/websocket: ^1.7.0

Requires (Dev)

• mink/driver-testsuite: dev-master
• phpunit/phpunit: ^8.5.22 || ^9.5.11
• squizlabs/php_codesniffer: ^3.5

MIT

• Dorian More

Published on Packagist.org on 2025-10-03 10:16 UTC

README

Mink driver for controlling Chrome without the overhead of Selenium.

It communicates directly with Google Chrome over HTTP and WebSockets, which allows it to work at least twice as fast as Chrome with Selenium. For Chrome 59+ it supports headless mode, eliminating the need to install a display server, and the overhead that comes with it. This driver is tested and benchmarked against a behat suite of 1800 scenarios and 19000 steps. It can successfully run it in less than 18 minutes with Chrome 60 headless. The same suite running against Chrome 58 with xvfb and Selenium takes ~60 minutes.

Installation

composer require dmore/chrome-mink-driver

Requirements

• Google Chrome or Chromium running, with remote debugging enabled.

Via available images: zenika/alpine-chrome, chromedp/headless-shell, and more options out there ... refer to CI test setup for example usages.

Or, headed Chrome:

google-chrome \
  --disable-client-side-phishing-detection --disable-component-update --disable-default-apps \
  --disable-features=PrivacySandboxSettings4,PrivacySandboxAdsAPIsOverride,PasswordLeakDetection \
  --disable-popup-blocking --disable-prompt-on-repost --disable-search-engine-choice-screen --disable-sync \
  --no-default-browser-check --no-first-run --password-store=basic \
  --remote-allow-origins=* --remote-debugging-address=0.0.0.0 --remote-debugging-port=9222 --use-mock-keychain

Or, headless Chrome (v59+):

google-chrome --disable-gpu --headless \
  --remote-debugging-address=0.0.0.0 --remote-debugging-port=9222 --remote-allow-origins=*

Refer https://www.chrome-flags.com/ for a full list of flags!

• --remote-allow-origins=* disables Chrome's WebSocket origin check (Chrome 111+), which otherwise rejects DevTools connections unless they originate from the same host - relevant whenever Chrome is reached from a different host/container than it's running on. This is separate from the older HTTP Host header check Chrome also applies to the /json/* endpoints; this driver already works around that one itself (see HttpClient).

Headless Chrome doesn't render any UI, so Chrome's own first-run/onboarding dialogs (Privacy Sandbox "Ad privacy" consent, search engine choice, weak/leaked password warnings, ...) and its popup blocker aren't an issue there. When running with a visible window, however, these can open as extra windows or silently swallow window.open() calls, which confuses window/tab handling (including switching back to the main window) since the driver has no way to tell them apart from windows opened by the page under test. The remaining flags in the first example above suppress them; adjust the --disable-features list for your Chrome version if a particular dialog still appears.

It is recommended to start Chrome with the --disable-extensions flag.

See https://gitlab.com/DMore/behat-chrome-skeleton for a fully working example.

Checking Chrome connectivity

To manually test connectivity, you can use curl or similar and request the json/version endpoint:

curl http://chrome:9222/json/version

Contributing

Contributions are welcome! Use the issue queue and merge requests to propose changes. Please refer to Gitlab documentation for how to use the Gitlab interface.

• To report an issue (bug, feature request etc) use the issue queue.
• If you are reporting a potential security issue, please check "This issue is confidential" when reporting the issue to the project.
• To propose code changes or a solution for an issue, use merge requests.
• Test coverage is executed on merge requests. Contributions should extend test coverage where possible and ensure all tests pass.
• Coding standards checks are executed on merge requests. Contributions should maintain coding standards.
• PHP code should adhere to PSR12.
• composer.json should be normalized using composer normalize.

Tests

The base test coverage is that from upstream mink/driver-testsuite, and validates that core DriverInterface functionality is correct per those expectations.

Test execution requires a webserver configured to serve fixtures from minkphp/driver-testsuite, which is provided by a docker image from the related behat-chrome/docker-chrome-headless project.

Tests are executed on each merge request via Gitlab CI. New functionality or bugfixes should seek to expand test or at least maintain existing coverage.

Using make to execute commands in Docker

command	purpose
make install	Install dependencies with composer
make test	Run tests with phpunit
make phpcbf	Tidy code using phpcbf
make phpcs	Check coding standards with phpcs

Docker environment to run commands

To perform these tasks without make, you can execute the same commands as above in a container. To run the tests using phpunit:

docker run --rm -it -v .:/code -e DOCROOT=/code/vendor/mink/driver-testsuite/web-fixtures registry.gitlab.com/behat-chrome/docker-chrome-headless bash

then, in the container shell:

composer install
vendor/bin/phpunit

Versioning & releases

• Releases are distributed through Packagist at https://packagist.org/packages/dmore/chrome-mink-driver
• This project aims to follow Semantic Versioning.
• Releases are coordinated using ("Release" label) issues in Gitlab.
• New releases are created via git tags being pushed to Gitlab.

Making a release

When it's time to release:

1. Ensure a header for the release is added to CHANGELOG.md, retaining the "Unreleased" header at top.
2. A new release should be created using Gitlab's Release UI
   • The release title and tag is the version only.
   • The release notes are the CHANGELOG entries for the version.
3. Packagist will detect the new release and make it available.

Usage

use Behat\Mink\Mink;
use Behat\Mink\Session;
use DMore\ChromeDriver\ChromeDriver;

$mink = new Mink([
  'browser' => new Session(new ChromeDriver('http://localhost:9222', null, 'http://www.google.com'))
]);

Configuration

Option	Value	Description
socketTimeout	int, default: 10	Connection timeout (seconds)
domWaitTimeout	int, default: 3000	DOM ready waiting timeout (milliseconds)
downloadBehavior	allow, default, deny	Chrome switch to permit downloads. (v62+)
downloadPath	e.g. /tmp/ (the default)	Where to download files to, if permitted.

Pass configuration values as the third parameter to new ChromeDriver().

Rendering PDF and Screenshots

Despite the Mink functionality the driver supports printing PDF pages or capturing a screenshot.

use Behat\Mink\Mink;
use Behat\Mink\Session;
use DMore\ChromeDriver\ChromeDriver;
$mink = new Mink(array(
    'browser' => new Session(new ChromeDriver('http://localhost:9222', null, 'http://www.google.com'))
));
$mink->setDefaultSessionName('browser');
$mink->getSession()->visit('https://gitlab.com/behat-chrome/chrome-mink-driver/blob/master/README.md');
$driver = $mink->getSession()->getDriver();
$driver->printToPdf('/tmp/readme.pdf');

The available options are documented here: https://chromedevtools.github.io/devtools-protocol/tot/Page/#method-printToPDF

Screenshots are supported using the Mink driver interface method getScreenshot().

Related projects

Behat extension

To use this driver with Behat, try the dmore/behat-chrome-extension Behat extension.

Chrome containers

This component uses the following Chrome containers for testing:

• zenika/alpine-chrome
• chromedp/headless-shell