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.

Installation

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": "3.0.5.1",
		"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

Setup

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:

WPWebDriver:
    url: '%TEST_SITE_WP_URL_WITH_PROTOCOL%'
    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
    capabilities:
        chromeOptions:
            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.