wp-browser removes the setup work from testing WordPress

One tool for site, plugin and theme testing

wp-browser exists to test WordPress sites, plugins and themes, and the pitch is that setup is quick and the default configuration works for most projects, with end-to-end tests, integration tests and unit tests all run with the same tool.

The reason a dedicated module is needed at all is that a WordPress test suite is not just a PHP test suite. A plugin test has to run against a real WordPress installation, with a database, a web server and, for end-to-end work, a browser. Assembling that is the tedious part, and it is the part most projects give up on. wp-browser packages the assembly as a Codeception module, which means the tests themselves are written in the Codeception style and run with the Codeception runner.

The documentation is versioned, and the version matters. The README refers to version 4 of the project, and there is a separate migration and troubleshooting guide for version 3 and version 3.5. That is a signal about the shape of the configuration surface: the project has had a major version, and the defaults changed with it.

The project also documents the support path clearly, pointing at its own documentation site, at the PHPUnit and Codeception documentation, and at the GitHub issues section, and it offers a direct contact for setting up a call about a project.

Where you run the init command decides what gets set up

The requirements section is short but it is the part that catches people, because the directory you run the init command from determines the shape of the project.

For a site project, the command must be run from the root directory of the WordPress site, that directory must contain the WordPress installation files, and the installation must be configured, meaning it should contain a wp-config.php file.

For a plugin, the command must be run from the root of the plugin, which is the directory that contains the PHP file defining the plugin header. For a theme, it is the root of the theme, the directory containing the style.css file that defines the theme header.

That distinction is the whole difference between testing a site and testing a thing that lives inside a site. In the plugin and theme case the project has to obtain a WordPress installation of its own, which the next section explains.

One more requirement applies to the quick installation path: the PHP version needs the sqlite3 extension installed and activated, and the README says you can check with the php -m command and look for sqlite3 among the active extensions. The quick path is therefore not available on every PHP build, and that is worth checking before you plan around it.

Installing with Composer and initializing

wp-browser is added as a development dependency with Composer, from the root of the project:

cd my-wordrpess-project
composer require --dev lucatume/wp-browser

Then the init command from Codeception sets up the project:

vendor/bin/codecept init wpbrowser

The two together are the whole installation for most projects, and the tests are run with the standard Codeception runner, with the `vendor/bin/codecept run` command.

The command name being Codeception's rather than the project's own is a deliberate design choice. wp-browser is a Codeception module, not a standalone test framework, so it inherits the runner, the reporting, the actor model and the configuration format, and a team that already uses Codeception for other projects learns nothing new.

The alternative to the default configuration is the tests/.env file, which the README describes as holding inline documentation that guides you through the configuration process, and it links to the commands documentation for the details of using a custom configuration.

What the default configuration actually spins up

The default configuration runs integration and end-to-end tests using three pieces: SQLite as the database engine, leveraging the SQLite Database Integration plugin, the PHP built-in web server to serve the WordPress site on localhost, with http://localhost:8080 given as an example, and Chromedriver to drive the local version of Chrome installed on your machine.

That third point is the one that saves the most time in practice. Setting up a browser driver for end-to-end tests is a recurring chore, and here it is pointed at the Chrome you already have rather than at a managed browser service.

For a plugin or theme project, the default configuration adds three steps. It installs the latest version of WordPress into the tests/_wordpress directory. It creates a tests/_plugins directory, where any file or directory is symlinked into the WordPress installation in tests/_wordpress/wp-content/plugins. And it creates a tests/_themes directory with the same symlinking behaviour into tests/_wordpress/wp-content/themes.

The symlink approach is the reason the edit-test loop is fast. You edit a file in your plugin and the change is immediately present in the WordPress installation, because they are the same file rather than a copy that has to be refreshed.

The Makefile shows how the project runs its own tests

The repository's Makefile is a compact description of the whole workflow, and it is a good way to understand what the tool expects of a machine.

build:
	composer install
.PHONY: build

test:
	vendor/bin/codecept run
.PHONY: test

The clean target removes vendor, composer.lock and var and recreates var, and clean_tmp removes the output and temp directories along with the SQLite files and the monkeypatch artefact that the run leaves behind. That detail, a var/_output/tmp directory holding sqlite files and a _monkeypatch file, tells you that the module keeps state in the working tree.

The target that explains the most is clean_procs, which is what you run when a test run was interrupted:

clean_procs:
	pgrep -f 'php -S' | xargs kill
	-pkill -9 -f chromedriver
	-pkill -9 -f mysqld
	rm -f var/_output/*.pid var/_output/*.running
	set -o allexport && source tests/.env && set +o allexport && docker compose down
.PHONY: clean_procs

It kills the PHP built-in server, Chromedriver and mysqld, removes the pid and running marker files, and brings down the compose stack using the environment from tests/.env. The tool leaves background processes and marker files behind, which is normal for a runner that starts a server, but it is something to know about before a CI job hangs waiting on a port.

The MariaDB service for teams that need MySQL

The repository includes a docker-compose.yml, and it defines a single service, a database, which is the MySQL path through the tool.

services:
  database:
    container_name: wpbrowser_4_database
    image: mariadb:10.8
    environment:
      MYSQL_ROOT_PASSWORD: ${WORDPRESS_DB_PASSWORD}
      MYSQL_USER: ${WORDPRESS_DB_NAME} # Same as db name.
      MYSQL_PASSWORD: ${WORDPRESS_DB_NAME} # Same as db name.
      MYSQL_DATABASE: ${WORDPRESS_DB_NAME} # Same as db name.
    healthcheck:
      test: [ "CMD", "mysqlshow", "-u${WORDPRESS_DB_USER}", "-p${WORDPRESS_DB_PASSWORD}",  "${WORDPRESS_DB_NAME}" ]
      interval: 1s
      timeout: 1s
      retries: 30

The container is mariadb:10.8, the database name doubles as the user and the password, and the healthcheck runs mysqlshow against the configured user every second with a timeout of one second and up to thirty retries. The service is given a tmpfs mount on /var/lib/mysql, so the data lives in memory and the container starts clean.

Two observations. The healthcheck interval of one second with thirty retries means the stack waits for the database in short increments, which is a fast readiness check. And the environment variables come from the same tests/.env file that the clean_procs target sources, so the compose service and the test configuration are driven by one set of values rather than two.

The container name carries the version, wpbrowser_4_database, which is a small reminder that the configuration differs between the 3.x and 4.x lines.

MIT terms, two maintained lines, and a documentation site

The project is released under the MIT Licence, with the LICENSE file at the repository root, and the documentation is published at wpbrowser.wptestkit.dev.

The release list shows two lines moving at once: 4.7.2 and 3.8.2, both published on 2026-08-26, and 3.8.1 on 2026-07-05 before them. That pattern says the 3.x line is still receiving fixes while 4.x is the current one, which matches the README pointing at a dedicated migration guide for version 3 and version 3.5 users. If you are on version 3, the practical question is whether your project still needs whatever version 3 supported, and if it does, the 3.8.x patches are still arriving.

The repository is not archived and the last push was on 2026-09-29, so the work is current.

The repository itself is a full project rather than a library shell. There is src/ and includes/, a codeception.dist.yml, a config/ directory, tests/, a docker-compose.yml, a Makefile, a mkdocs.yml with a docs/ directory, and bin/ with the maintenance scripts, including bin/setup-wp.php for the WordPress install and bin/extract-api.php, which generates the API reference pages for each module. The docs_api_update target runs that extractor for the WPBrowser, WPCLI, WPDb, WPFilesystem, WPLoader, WPQueries and WPWebDriver modules, so the API documentation is generated from the source rather than written by hand, and it cannot drift out of date with the code it describes.

Editorial conclusion

wp-browser fits a plugin or theme team that wants end-to-end and integration tests against a real WordPress install today, without a hand-built database, web server and browser driver stack, and the symlinked tests/_plugins and tests/_themes directories make the edit-test loop immediate. It does not fit a project that needs to test against a specific MySQL configuration out of the box, since the default is SQLite, and it does not fit a team still on version 3, whose configuration differs enough to have its own migration guide. Before adopting version 4, read the migration documentation, check that the PHP build has the sqlite3 extension, and run the clean_procs target if a failed run leaves a web server or Chromedriver behind.

Frequently asked questions

Official sources

1. License: MIT
2. lucatume/wp-browser on GitHub
3. Project website
4. README
5. Releases