Setting up wp-browser with WPWebDriver for full site acceptance testing (notes for my future self)

These are my notes on getting WPWebDriver in wp-browser set up to work for me. They supplement rather than replace the wp-browser documentation. If you are having issues and haven’t started there and followed the directions, I highly recommend doing that first. Inifinum also has a super helpful section on setting up wp-browser.


Because I want my tests to cover an entire site, I installed wp-browser in the WordPress site root folder using the following composer.json file. This is the final version of this and also includes the suggested scripts from Inifinum.

	"name": "tharsheblows/my-project",
	"description": "My project",
	"type": "project",
	"authors": [
			"name": "JJ",
			"email": ""
	"require": {},
	"require-dev": {
		"lucatume/wp-browser": "",
		"codeception/module-asserts": "^1.0",
		"codeception/module-phpbrowser": "^1.0",
		"codeception/module-webdriver": "^1.2",
		"codeception/module-db": "^1.0",
		"codeception/module-filesystem": "^1.0",
		"codeception/module-cli": "^1.0",
		"codeception/util-universalframework": "^1.0"
	"scripts": {
		"selenium:start": "selenium-server -port 4444",
		"test:clean": "@php ./vendor/bin/codecept clean",
		"test:acceptance": "@php ./vendor/bin/codecept run acceptance",
		"test:functional": "@php ./vendor/bin/codecept run functional",
		"test:integration": "@php ./vendor/bin/codecept run wpunit",
		"test:coverage": "@php ./vendor/bin/codecept run wpunit --coverage --coverage-xml --coverage-html",
		"test:generate-scenarios": "@php vendor/bin/codecept generate:scenarios"

If you’re already using wp-browser, you can add in the WebDriver dependency:

composer require --dev codeception/module-webdriver

To use WebDriver, I had to install both Selenium and ChromeDriver. I followed these directions from Inifinum for installation. I won’t have to do this again but I’ll need to remember that Selenium server is running for everything to work: brew services start selenium-server-standalone


I went through the configuration process as outlined in the documentation and am not going to detail the steps here, again, the documentation is good.

To my acceptance.suite.yml file, I added the WPWebDriver config as below:

    adminUsername: '%TEST_SITE_ADMIN_USERNAME%'
    adminPassword: '%TEST_SITE_ADMIN_PASSWORD%'
    adminPath: '%TEST_SITE_WP_ADMIN_PATH%'
    browser: chrome
    host: localhost
    port: 4444 # port selenium is using.
    window_size: false #disabled for Chrome driver
            args: ["--disable-gpu", "--no-proxy-server"]

I added a TEST_SITE_WP_URL_WITH_PROTOCOL constant to my .env.testing file as the url requires a protocol, eg it requires “https://example.test” rather than “example.test” which is the TEST_SITE_WP_URL defined during the default setup process. (I wasn’t sure if I could simply add on the protocol to the TEST_SITE_WP_URL constant but decided against messing around with things that were already working.)

The port needs to be the port which Selenium server is using.

I am *not* running headless as it helps me to see it as it goes along. I’m absolutely sure I will change this at some point. When I do, I’ll add “–headless” to the capabilities.chromeOptions.args array.

A note: only one of WPWebDriver or WPBrowser should be enabled per suite. The comments in the default setup say to create a separate suite for the other if you need to use both.

Leave a Reply

Your email address will not be published. Required fields are marked *

By submitting this comment, you are agreeing to the use of Akismet which helps reduce spam. You can view Akismet’s privacy policy here. Your email, website and name are also stored on this site.