dmore/chrome-mink-driver

Mink driver for controlling chrome without selenium

2.9.3 2024-05-17 12:26 UTC

Requires

• 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

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.

Example:

google-chrome-stable --remote-debugging-address=0.0.0.0 --remote-debugging-port=9222

or headless (v59+):

google-chrome-unstable --disable-gpu --headless --remote-debugging-address=0.0.0.0 --remote-debugging-port=9222

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://localhost: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

Executing Gitlab CI pipeline locally

You can also run the Gitlab CI pipeline in your local environment, using firecow/gitlab-ci-local!

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.

Docker image

A Docker image is used to execute tests against the targeted browser(s), and includes recent Chrome Stable, Chrome Beta and Chromium.