Install latest stable WPBrowser package via Composer (WPBrowser will install Codeception for you):
composer require lucatume/wp-browser --dev
If a dependency resolution issue arises and you have previously installed
codeception/codeception try removing it and requiring just
composer remove codeception/codeception --dev
composer require lucatume/wp-browser --dev
WPBrowser will install the latest version of Codeception for you.
To fully use the WordPress specific modules of the WPBrowser suite you need to setup a local WordPress installation; this is in no way different from what’s required to locally develop a WordPress theme or plugin.
In the examples below I assume that the local WordPress installation root directory is
/var/www/wordpress, that it responds at the
http://wordpress.localhost URL and that I am developing a plugin called “Acme Plugin”.
While it’s possible to start from a default Codeception configuration the WPBrowser package comes with its own initialization template that can be called using:
The command offers the possibility to scaffold an empty suite or to undergo an interactive setup that will end in a ready to run Codeception for WordPress installation; it will create the
tests directory and scaffold the
unit suites creating a
tests sub-directory and a configuration file for each.
If you did not use the step-by-step initialization then edit each suite configuration file (e.g.
tests/functional.suite.yml for the functional suite) to match your local WordPress setup and point the modules to the local WordPress installation folder, the local WordPress URL and so on.
If you are using the
WPLoader module in your tests take care to create a dedicated database for it and not to use the same database the
WPDb modules might use.
The use of the modules defined in the WPBrowser package is not tied to this bootstrap though so feel free to set up Codeception in any other way.
Commonly “WordPress unit tests” (hence the
wpunit default name of the suite) are not related to classical unit tests but to integration tests. The difference is that unit tests are supposed to test a class methods in complete isolation, while integration tests check how components work inside WordPress. That’s why, to prepare WordPress for testing, you should enable
WPLoader module into
WPLoader module: it takes care of loading, installing and configuring a fresh WordPress installation before each test method runs.
To handle the heavy lifting the module requires some information about the local WordPress installation: in the
codeception.yml file configure it to match your local setup; with reference to the example above the module configuration might be:
The module is wrapping and augmenting the WordPress Core automated testing suite and to generate a test case that uses Codeception and the methods provided by the Core testing suite you can use the generation command provided by the package:
codecept generate:wpunit integration "Acme\SomeClass"
The generated test case extends the
WPTestCase class and it exposes all the mehtods defined by
Codeception\Test\Unit test case and the Core suite
Additional test method generation possibilities are available to cover the primitive test cases offered in the Core testing suite using
wpxmlrpc as arguments for the
Any database interaction is wrapped in a transaction to guarantee isolation between tests.
WordPress Functional Tests
Functional tests are meant to test requests handling and end-to-end interactions.
WPBrowser will scaffold functional tests to use the
While the latter is the one defined by the Codeception suite
WPDb modules extend the Codeception framework and
Db modules with WordPress specific methods.
The modules will require some WordPress specific setup parameters:
To generate a functional test use the default
codecept generate:cept functional "PostInsertion"
To test a WordPress theme or plugin functionalities using its UI you should simulate the user interaction with a browser both in the site front-end and back-end.
You can use the
Db modules defined by Codeception but the WPBrowser package extends those modules in the
WPDb modules to add WordPress specific methods to each.
WPWebDriver module drives a real browser in the same way the
The modules require some WordPress specific parameters to work:
WebDriver module the
WPWebDriver module require a Selenium or PhantomJS server to run.
WPDb module allows for quick interactions with the WordPress database API like quick generation of multiple posts, database value fetching and more:
$I->haveManyPostsInDatabase(10, ['post_type' => 'custom_post_type']);
$transient = $I->grabTransientFromDatabase('some_transient');
WPWebDriver methods wrap complex interactions with the WordPress UI into sugar methods like:
If you prefer to describe application with feature files, Codeception can turn them to acceptance or functional tests. It is recommended to store feature files in
features directory (like it does Behat) but symlinking it to
tests/functional/features so they can be treated as tests too. For using BDD with acceptance tests you need to run:
ln -s $PWD/features tests/acceptance
Codeception allows to combine tests written in different formats. If are about to wirite a regression test it probably should not be described as a product’s feature. That’s why feature-files is subset of all acceptance tests, and they are stored in subfolder of
There is no standard Gherkin steps built in. By writing your feature files you can get code snippets which should be added to
composer exec codecept gherkin:snippets
In the same manner features can be set up as functional tests.
Methods defined in WPBrowser
WPDb modules can offer a base to implement the steps:
* @Given I login as administrator
public function iLoginAsAdministrator()
// from WPBrowser or WPWebDriver module
* @Then I see CSS option is set
public function iSeeCssOptionIsSet()
// from WPDb module