Configuration
While wp-browser can be configured manually creating each file the fastest way to bootstrap its configuration is by using its initialization template.
Throughout the steps below I will use the WordPress setup I've prepared before From the root folder of the project,
/Users/luca/Sites/wordpress/wp-content/plugins/acme-plugin
in the example, run the command:vendor/bin/codecept init wpbrowser
Composer installed Codeception binary (
codecept
) in the vendor
folder of my project.With the command above I'm telling Codeception to initialize a wp-browser project in the current folder.
When I click enter I'm presented with a list of questions, each answer will be used to configure the wp-browser project for me; one by one.
In the screenshot the answers I've provided to each question, with reference to the setup above:

codecept init wpbrowser 1

codecept init wpbrowser 2
wp-browser will try to provide a brief explanation of what each question is but below is the long version.
I've tried to condense as much clarity as possible in the questions the
codecept init wpbrowser
command will ask but, for sake of brevity and space, there's no way I could provide inline a deeper explanation of each.Below is a longer explanation of each question:
With reference to the testing levels definition this question provides you with the possibility to change the name of the acceptance-like test suite.
Common, alternative, names are
ui
, rest
and user
.With reference to the testing levels definition this question provides you with the possibility to change the name of the functional-like test suite.
A common alternative name is
service
.With reference to the testing levels definition this question provides you with the possibility to change the name of the suite dedicated to integration and "WordPress unit" tests.
A common alternative name is
integration
.Instead of configuring each module in each suite with the same parameters over and over Codeception supports dynamic configuration via environment files.
wp-browser will scaffold such a configuration for you and will use, by default, a file called
.env
to store the configuration parameters.The file name might not suit all setups especially and this question allows changing that file name; common, alternative, file names are
.env.tests
, .env.codeception
and similar.During tests the test code will need to access WordPress code, precisely wp-browser requires being pointed to the folder that contains the
wp-load.php
file.The answer can be an absolute path, like
/Users/luca/Sites/wordrpress
, or a path relative to the folder where Codeception is installed like vendor/wordpress
.This path should be accessible by the machine that is running the tests; if you're running the tests from your machine (e.g. your laptop) that's just the path to the folder where WordPress is installed,
/Users/luca/Sites/wordpress
in the example configuration above.To make an example:
- on my machine WordPress is installed at
/Users/luca/Sites/wordpress
- I've created a Docker container using the official WordPress image and bound the above folder into the container
- internall the container will put WordPress in the
/var/www/html
folder
If I run the tests from my host machine then WordPress root directory will be
/Users/luca/Sites/wordpress
, if I run the tests from within the Docker container then WordPress root folder will be /var/www/html
.- in the host machine the path to the WordPress root folder will be
/Users/luca/Local\ Sites/wordpress/app/public
- from within the Docker container managed by Local the path will be
/app/public
If you need a solution that will work in both instances use a relative path: wp-browser will accept paths like
./../../../wordpress
and will attempt to resolve them.This is usually
/wp-admin
but you might have the web-server, or a plugin, redirect or hide requests for the administration area to another path.Some examples are
/admin
, /login
and the like.Mind that this is not the path to the login page but the path to the administrationo area; this will be used by wp-browser to find to the administration area in acceptance and functional tests.
In my example setup it's
wordpress
.This is the name of the database that is storing the information used by the site I can reach at
http://localhost:8080
.I want to underline the word "test". Any site and any database you use and expose to wp-browser should be intended for tests; this means that it does not contain any data you care about as it will be lost.
In my example setup it's
127.0.0.1:3306
.Here the same principle valid for Where is WordPress installed? applies: the database host is relative to the machine that is running the tests.
In my example I'm hosting the database locally, on my laptop, and my machine can reach it at the localhost address (
127.0.0.1
) on MySQL default port (3306
).If I am using the database of a Local by Flywheel site from my host machine then it might be something like
192.168.92.100:4050
(from the site "Database" tab); the same principle applies if I am using a Vagrant-based or Docker-based solution.If I am running the tests from within a virtualized machine (a Docker container, a Vagrant box et cetera) then it would probably be
localhost
or 1270.0.0.1
.In my example setup it's
root
as I'm using MySQL server root user to access the database during tests.Depending on your setup it might be different; since wp-browser will need to not only read but write too to the database make sure to use a user that has full access to the database specified in the answer to the What is the host of the test database used by the test site? question.
In my example setup it's empty as I've not set any password for the root account.
In your case it might be different and it should be the password associated with the user specified in the answer to the What is the user of the test database used by the test site? question.
In my example setup it's
wp_
; that value is taken from the WordPress installation configuration file.To have any influence on the site wp-browser will need to modify the same database tables WordPress is using; as I did you can take this value from the
wp-config.php
file directly: it's the value of the $table_prefix
variable.In my example setup it's
tests
.During integration, or WordPress "unit" tests, wp-loader will need to load WordPress code.
Since WordPress code is not meant to be "modular" it does not support auto-loading or loading just parts of it; it's either almost all or nothing.
One of the first things WordPress does, when loading, is trying to connect to a database: if that database is not available then WordPress will not load.
In the answer to the question Where is WordPress installed? I've told wp-browser where to find WordPress code, in this answer I'm telling wp-browser what database it should use to bootstrap WordPress.
This detail will be used by the WPLoader module to bootstrap WordPress. It's highly recommended to use a different database from the one used for functional and acceptance tests.
In my example setup it's
127.0.0.1:3306
.As in the answer to the question What is the name of the test database WPLoader should use? we're providing connection details about the database that should be used to bootstrap WordPress during integration and WordPress "unit" tests.
Again the database host is in relation to the machine running the tests, all the considerations done for What is the host of the test database used by the test site? apply.
In my example it's
root
.Similar to the question What is the user of the test database used by the test site? but in relation to the database specified in the question What is the name of the test database WPLoader should use?.
In my example setup it's empty as I've not set any password for the root account.
Similar to the question What is the password of the test database used by the test site? but in relation to the database specified in the question What is the name of the test database WPLoader should use?.
In my example setup it's
wp_
.Similar to the question What is the table prefix of the test database used by the test site? but in relation to the database specified in the question What is the name of the test database WPLoader should use?.
In my example setup it's
http://localhost:8080
.This is the full URL you would have to enter in the browser, on the machine that is running the tests, to reach the test WordPress site homepage.
In my example setup it's
[email protected]
.This detail will be used by the WPLoader module to bootstrap WordPress and, while required, it's usually not relevant unless you're testing email communications.
In my example setup it's
Acme Plugin Test Site
.This detail will be used by the WPLoader module to bootstrap WordPress and, while required, it's usually not relevant unless you're testing around the site title.
In my example setup it's
admin
.This detail will be used by the WPBrowser or WPWebDriver modules to fill in the login details for the administrator user.
It should be the same as the one that allows you to acccess the site administration area in the WordPress test site,
http://localhost:8080/wp-admin
in my example.In my example setup it's
password
.This detail will be used by the WPBrowser or WPWebDriver modules to fill in the login details for the administrator user.
It should be the same as the one that allows you to acccess the site administration area in the WordPress test site,
http://localhost:8080/wp-admin
in my example.Depending on the answer the WPLoader module will load, during integration or WordPress "unit" tests, your WordPress plugin or theme.
If you replied with
both
(for "a combination of both") then you'll be able to choose the plugins and theme to load in integration and WordPress "unit" tests in the following questions.This question will be asked only if you replied
plugin
to the question Are you testing a plugin, a theme or a combination of both?.
In my example setup it's acme-plugin/plugin.php
.This is the
<folder>/<main-plugin-file>.php
path, relative to the WordPress installation plugins folder, to the plugin you are testing.This detail will be used by the WPLoader module to bootstrap WordPress and load your plugin or theme in integration and WordPress "unit" tests.
This question will be asked only if you replied
theme
to the question Are you testing a plugin, a theme or a combination of both?.
Enter yes
if you are developing a child theme.This detail will be used by the WPLoader module to bootstrap WordPress and load a parent theme along with your theme in integration and WordPress "unit" tests.
Please note that wp-browser will not download and install the parent theme in the WordPress installation for you.
This question will be asked only if you replied
both
to the question Are you testing a plugin, a theme or a combination of both?.
Enter yes
if you are using a child theme.This detail will be used by the WPLoader module to bootstrap WordPress and load a parent theme along with your theme in integration and WordPress "unit" tests.
Please note that wp-browser will not download and install the parent theme in the WordPress installation for you.
This question will be asked only if you replied
yes
to the question Are you developing a child theme?.Reply with the slug of the parent theme, that's usually the name of the folder the parent theme lives in, e.g.
twentyseventeen
.This detail will be used by the WPLoader module to bootstrap WordPress and load a parent theme along with your theme in integration and WordPress "unit" tests.
Please note that wp-browser will not download and install the parent theme in the WordPress installation for you.
This question will be asked only if you replied
theme
to the question Are you testing a plugin, a theme or a combination of both?.
Reply with the slug of the theme, that's usually the name of the folder the theme lives in, e.g. twentyseventeen
.This detail will be used by the WPLoader module to bootstrap WordPress and load your theme in integration and WordPress "unit" tests.
This question will be asked only if you replied
both
to the question Are you testing a plugin, a theme or a combination of both?.
Reply with the slug of the theme you are using, that's usually the name of the folder the theme lives in, e.g. twentyseventeen
.This detail will be used by the WPLoader module to bootstrap WordPress and load the theme integration and WordPress "unit" tests.
Whether you're testing a plugin, a theme or a combination of both you might need some additional plugins to run your tests.
As an example if I'm testing a WooCommerce extension I need the WooCommerce plugin to test it; this is the place where I can define it.
The required plugins follow the same format as the one used in the question What is the folder/plugin.php name of the plugin?:
<plugin-folder>/<plugin-main-file>.php
; in the case of WooCommerce it would be woocommerce/woocommerce.php
.This detail will be used by the WPLoader module to bootstrap WordPress and load the required plugins in integration and WordPress "unit" tests.
Please note that wp-browser will not download and install the required plugins in the WordPress installation for you.
No worries, just correct the value in the environment file or in the suites configuration files.
The environment file will have the name you specified in the answer the question How would you like to call the env configuration file?.
The suites configuration files can be found in
tests/<suite>.suite.yml
; e.g. the wpunit
suite configuration file will be tests/wpunit.suite.yml
file.To complete the setup I have removed any demo content from the site and activated my plugin in the plugins administration page.
In the
tests/acceptance.suite.yml
file and in the tests/functional.suite.yml
file, the configuration file for the acceptance
and functional
suites respectively, the WPDb
module configuration contains a dump
configuration parameter:class_name: AcceptanceTester
modules:
enabled:
- WPDb
config:
WPDb:
dump: 'tests/_data/dump.sql'
The
dump
parameter is inherited by the WPDb
module from the Codeception Db
module and defines the SQL dump file that should be loaded before, and between, tests to reset the testing environment to a base known state.As for any other database-related operation wp-browser will not create the dump for me. I use MySQL binary to export the database state (a dump) with the command:
mysqldump -u root -h 127.0.0.1 -P 3306 wordpress > /Users/luca/Sites/wordpress/wp-content/plugins/acme-plugin/tests/_data/dump.sql
I could use any other combination of tools to produce the dump; using
mysql
binary is not a requirement.There is one last check I need to make before jumping into the creation of tests: making sure all the paths and credentials I've configured wp-browser with are correct.
The bootstrap process generated four suites for me:
acceptance
, functional
, integration
and unit
. If you have modified the default suite names during the setup your suites names might differ though.To test the setup I will run each suite and make sure it can run correctly empty of any test. To run a suite of tests I will use the
codecept run
command:codecept run acceptance
codecept run functional
codecept run integration
codecept run unit
How comes I'm not using the command
codecept run
(without specifying the suite names)? See the FAQ entry.
Pre-flight check
If you cannot run all the suites without issues then check your configuration settings again, read the errors and see If you entered a wrong value
Last modified 3yr ago