wp-browser

A WordPress specific set of extensions for Codeception.

Installation

To install simply require the package in the composer.json file like this:

  "require-dev":
    {
      "lucatume/wp-browser": "~1.21"
    }

and then use composer update to fetch the package.
After that follow the configuration instructions below. Note: there is no need to require codeception/codeception in the composer.json file as it is required by lucatume/wp-browser itself.

Setup and usage

The fastest way to get up and running with Codeception and wp-browser is running the initialization command:

codecept init wpbrowser

After answering a bunch of questions the suites will be set up for you; wp-browser will not take care of setting up the required databases and WordPress installations for you though so do your homework.

Updating existing projects

If a project was set up before the latest version of the package there are two steps to take:

stop using the wpcept command to generate and run tests, use codecept (Codeception default binary) instead.
to have wp-browser specific commands aliased on the codecept binary follow Codeception guide to add custom commands; in the codecepion.yml file add:

extensions:
    commands:
        - 'Codeception\Command\GenerateWPUnit'
        - 'Codeception\Command\GenerateWPRestApi'
        - 'Codeception\Command\GenerateWPRestController'
        - 'Codeception\Command\GenerateWPRestPostTypeController'
        - 'Codeception\Command\GenerateWPAjax'
        - 'Codeception\Command\GenerateWPCanonical'
        - 'Codeception\Command\GenerateWPXMLRPC'
        - 'Codeception\Command\DbSnapshot'
        - 'tad\Codeception\Command\SearchReplace'

A word of caution

Due to WordPress dependency on globals and constants the suites should not be ran at the same time; this means that in place of this:

codecept run

This is probably a better idea:

codecept run acceptance && codecept run functional && codecept run ...

Doing otherwise will result in fatal errors due to constants, globals and/or classes and methods attempted redefinition.

Modules

While the package name is the same as the first module added to it ("WPBrowser") the package will add more than one module to Codeception to ease WordPress testing.
Not every module will make sense or work in any suite or type of test case but here's an high level view:

WPBrowser - a PHP based, JavaScript-less and headless browser for acceptance testing not requiring JavaScript support
WPWebDriver - a Guzzle based, JavaScript capable web driver; to be used in conjunction with a Selenium server, PhantomJS or any real web browser for acceptance testing requiring JavaScript support
WPDb - an extension of the default codeception Db module that will interact with a WordPress database to be used in functional and acceptance testing
WPLoader - loads and configures a blank WordPress installation to use as a base to set up fixtures and access WordPress defined functions and classes in integration tests; a wrapping of the WordPress PhpUnit based test suite provided in the WordPress repository; alternatively it cane be used to bootstrap the WordPress installation under test in the test variable scope.
WPBootstrapper - bootstraps an existing WordPress installation in the same variable scope of the calling function to have access to its methods.
WPQueries - allows for assertions to be made on WordPress database access in integration tests.
WordPress - to be used in functional tests it allows sending GET, POST, PUT and DELETE requests to the WordPress installation index without requiring a web server.
WPCLI - allows accessing the wp-cli tool in acceptance and functional tests.
WPFilesystem - an extension of the default Filesystem module providing methods specific to WordPress projects.

WPBrowser configuration

WPBrowser extends PHPBrowser module hence any parameter required and available to that module is required and available in WPBrowser as well.
In the suite .yml configuration file add the module among the loaded ones

  modules:
      enabled:
          - WPBrowser
      config:
          WPBrowser:
              url: 'http://example.local'
              adminUsername: 'root'
              adminPassword: 'root'
              adminPath: '/wp-core/wp-admin'

and configure PHPBrowser parameters and the additional ones available to the WPBrowser module:

adminUsername - the site administrator username (required)
adminPassword - the site administrator login name (required)
adminPath - the path, relative to the WordPress installation folder, to the admin area

WPWebDriver configuration

WPWebDriver extends WebDriver module hence any parameter required and available to that module is required and available in WPWebDriver as well. In the suite .yml configuration file add the module among the loaded ones

  modules:
      enabled:
          - WPWebDriver
      config:
          WPWebDriver:
              url: 'http://example.local'
              browser: phantomjs
              port: 4444
              window_size: 1024x768
              adminUsername: 'root'
              adminPassword: 'root'
              adminPath: '/wp-core/wp-admin'

and configure WPWebDriver parameters and the additional ones available to the WPWebDriver module:

adminUsername - the site administrator username (required)
adminPassword - the site administrator login name (required)
adminPath - the path, relative to the WordPress installation folder, to the admin area

Note: when specifying the window_size parameter avoid using quotes around it.

WPDb configuration

The module extends the Db module hence any parameter required and available by the Db module is required and available in the WPDb module as well.
In the suite .yml configuration file add the module among the loaded ones

  modules:
      enabled:
          - WPDb
      config:
          WPDb:
              dsn: 'mysql:host=localhost;dbname=testdb'
              user: 'root'
              password: ''
              dump: 'tests/_data/dump.sql'
              populate: true
              cleanup: true
              reconnect: true
              url: 'http://example.local'
              urlReplacement: true
              tablePrefix: 'wp_'

and configure Db parameters and the additional ones available to the WPDb module:

url - the site home url (required)
urlReplacement - the module will try to replace the WordPress URL hard-coded in the dump file with the one specified by the url parameter by default; set this to false to prevent this behaviour
tablePrefix - allows specifying the table prefix used in the installation, defaults to wp_ (optional)

Dump file domain replacement

The SQL dump file will be loaded by the module during initialization before each test following the same limitations about size imposed by Codeception Db module.
The problem with WordPress database dumps is that the website URL address is hard-coded in the database itself making dump sharing a search and replace pain. The module will try to replace the domain written in the loaded SQL dump file on the fly to match the one specified in the url config parameter to allow dumps to work locally with no issues.

WPLoader configuration

The module wraps the configuration, installation and loading of a working headless WordPress site for testing purposes or the simple bootstrapping of the WordPress configuration.
Due to WordPress reliance on globally defined variables and constants each suite using the WPLoader module should be run independently of the others; if the suitea and suiteb suites use the WPLoader module with different configuration parameters avoid running all suites at the same time like this:

codecept run

Instead run each suite by itself like this:

codecept run suitea
codecept run suiteb

This table list the differences between the two modes supported by the WPLoader module depending on the value of the loadOnly parameter:

Functionality	`loadOnly = false`	`loadOnly = true`
Works like the Core automated suite	Yes	No
Offers a clean WordPress installation before the tests	Yes	No
Activates and loads specified WordPress plugins before the tests	Yes	No
Works in a transaction	Yes	No
Preserves the database state during and after the tests	No	Yes
Cleans up before and after the tests	Yes	No
Works in test cases extending `WPTestCase`	Yes	No
Works in test cases not extending `WPTestCase`	No	Yes

An adaptation of WordPress automated testing suite the module exposes the suite hard-coded value as configuration parameters.
Since this module takes charge of setting up and cleaning the database used for the tests point it to a database that does not contain sensible data!
Also note that this module cannot be used together with WPDb or DB modules with the cleanup settings set to true.
In the suite .yml configuration file add the module among the loaded ones

  modules:
      enabled:
          - WPLoader
      config:
          WPLoader:
              multisite: false
              wpRootFolder: "/Users/User/www/wordpress"
              dbName: "wpress-tests"
              dbHost: "localhost"
              dbUser: "root"
              dbPassword: "root"
              isolatedInstall: true
              wpDebug: true
              dbCharset: "utf8"
              dbCollate: ""
              tablePrefix: "wptests_"
              domain: "example.org"
              adminEmail: "[email protected]"
              title: "Test Blog"
              phpBinary: "php"
              language: ""
              configFile: ""
              theme: my-theme
              plugins: ['hello.php', 'my-plugin/my-plugin.php']
              activatePlugins: ['hello.php', 'my-plugin/my-plugin.php']
              booststrapActions: ['my-first-action', 'my-second-action']

and configure it using the required parameters:

wpRootFolder - the absolute path to the root folder of the WordPress installation to use for testing, the ABSPATH global value.
dbName - the name of the database to use for the tests, will be trashed during tests so take care, will be the DB_NAME global.
dbHost - the host the database can be found at, will be the DB_HOST global.
dbUser - the database privileged user, should GRANT ALL on the database, will be the DB_USER global.
dbPassword - the password for the user, will be the DB_PASSWORD global.

Optional parameters are available to the module to reproduce the original testing suite possibilities as closely as possible:

loadOnly - if set to true the module will just load WordPress without installing it; useful to access WordPress code outside of unit and integration tests; read the paragraph "WPLoader to bootstrap WordPress"; setting this parameter to true makes all the ones below superfluous.
isolatedInstall - bool, def. true, whether the WordPress installation should happen in a separate process from the tests or not; running the installation in an isolated process is the recommended way and the default one.
multisite - if set to true the WordPress installation will be a multisite one, the WP_TESTS_MULTISITE global value.
wpDebug - bool, def. true, the WP_DEBUG global value.
multisite - bool, def. false, if set to true will create a multisite installation, the WP_TESTS_MULTISITE global value.
dbCharset - string, def. utf8, the DB_CHARSET global value.
dbCollate - string, def. '', the DB_COLLATE global value.
tablePrefix - string, def. wptests_, the WP_TESTS_TABLE_PREFIX value.
domain - string, def. example.org, the root URL of the site, the WP_TESTS_DOMAIN global value.
adminEmail - string, def. [email protected], the admin email, the WP_TEST_EMAIL global value.
title - string, def. Test Blog, the blog title, the WP_TESTS_TITLE global value.
phpBinary - string, def. php, the php bin command, the WP_PHP_BINARY global value.
language - string, def. '', the installation language, the WPLANG global value.
configFile - string or array, def. '', the path, or an array of paths, to custom config file(s) relative to the wpRootFolder folder, no leading slash needed; this is the place where custom wp_tests_options could be set.
pluginsFolder - string, def. '', the relative path to the plugins folder from the wpRootFolder if different from the default one or the one defined by the WP_PLUGIN_DIR constant; if the WP_PLUGIN_DIR constant is defined in a config file (see the configFile parameter) this will be ignored.
plugins - array, def. ['hello.php', 'my-plugin/my-plugin.php'], a list of plugins that should be loaded before any test case runs and after mu-plugins have been loaded; these should be defined in the folder/plugin-file.php format.
activatePlugins - array, def. ['hello.php', 'my-plugin/my-plugin.php'], a list of plugins that will be activated before any test case runs and after WordPress is fully loaded and set up; these should be defined in the folder/plugin-file.php format; when the multisite option is set to true the plugins will be network activated during the installation.
bootstrapActions - array, def. ['my-first-action', 'my-second-action'], a list of actions or static functions that should be called after before any test case runs, after plugins have been loaded and activated; static functions should be defined in the YAML array format:
```
bootstrapActions:
    - action_one
    - action_two
    - [MyClass, myStaticMethod]
```
theme - string|array, def. '', the theme that should be activated for the tests; if a string is passed then both template and stylesheet options will be set to the passed value; if an array is passed then the template and stylesheet will be set in that order:
```
theme: my-theme
```
The theme will be set to my-theme.
```
theme: [ parent, child ]
```
The template will be set to parent, the stylesheet will be set to child.

A word of caution: right now the only way to write tests able to take advantage of the suite is to use the WP_UnitTestCase test case class; while the module will load fine and will raise no problems WP_UnitTestCase will take care of handling the database as intended and using another test case class will almost certainly result in an error if the test case defines more than one test method.

WPLoader to only bootstrap WordPress

If the need is to just bootstrap the WordPress installation in the context of the tests variable scope then the WPLoader module loadOnly parameter should be set to true; this could be the case for functional tests in need to access WordPress provided methods, functions and values.
An example configuration for the module in this mode is this one:

  modules:
      enabled:
          - WPLoader
      config:
          WPLoader:
              loadOnly: true 
              wpRootFolder: "/Users/User/www/wordpress"
              dbName: "wpress-tests"
              dbHost: "localhost"
              dbUser: "root"
              dbPassword: "root"

With reference to the table above the module will not take care of the test WordPress installation state before and after the tests, the installed and activated plugins, and theme.
The module can be used in conjuction with a WPDb module to provide the tests with a WordPress installation suiting the tests at hand.

WPBootstrapper configuration

The module will bootstrap a WordPress installation loading its wp-load.php file.
The configuration will require one parameter only :

wpRootFolder - the absolute path to the root folder of the WordPress installation to use for testing, the ABSPATH global value.

WPQueries configuration

This module requires no configuration.

WordPress module configuration

The module is meant to be used in functional tests and requires the WPDb module to work.
See WPDb module configuration section for more information abou the required module.

modules:
    enabled:
        - WPDb:
            dsn: 'mysql:host=localhost;dbname=wp'
            user: 'root'
            password: 'root'
            dump: 'tests/_data/dump.sql'
            reconnect: false
            url: 'http://wp.dev'
            tablePrefix: 'wp_'
        WordPress:
            depends: WPDb
            wpRootFolder: /var/www/wp
            adminUsername: admin
            adminPassword: password
            adminPath: /some-path/to/wp-admin

wpRootFolder - the absolute path to the root folder of the WordPress installation to use for testing, the ABSPATH global value (required)
adminUsername - the site administrator username (required)
adminPassword - the site administrator login name (required)
adminPath - the path, relative to the WordPress installation folder, to the admin area

WPCLI module configuration

This module is meant to be used in functional and acceptance tests to tap into the wp-cli tool during tests.
An embedded wp-cli installation will be used skipping a missing or already defined one, a working local installation of wp-cli is not required for this module.
Calls to wp-cli are synchronous and isolated: wp-cli will run in a separate PHP process and will not share the environment with the test code.
The example configuration below shows the module used in an acceptance test conjunction with the WPBrowser module.

modules:
    enabled:
        WPBrowser:
            url: 'http://wp.dev'
        WPCLI:
            path: /Users/Luca/Sites/wp
            throw: true

path - string, required; the absolute path to the WordPress installation under test; if a [config.yml file] is found here it will be ignored by the module.
throw - bool, optional, defaults to true; whether errors returned from wp-cli execution should cause an exception or not; defaults to
ssh - string, optional; an SSH access string, see wp-cli global parameters.
http - string, optional; an SSH access string, see wp-cli global parameters.
url - string, optional; an SSH access string, see wp-cli global parameters.
user - string, optional; an SSH access string, see wp-cli global parameters.
skip-plugins - string, optional; an SSH access string, see wp-cli global parameters.
skip-themes - string, optional; an SSH access string, see wp-cli global parameters.
skip-packages - string, optional; an SSH access string, see wp-cli global parameters.
require - string, optional; an SSH access string, see wp-cli global parameters.

The module defines two methods wrapping calls to the wp-cli tool:

cli(string $userCommand) - executes $userCommand and returns the command exit status; 0 (shell equivalent of OK) will be cast to true.
```
$deleted = $I->cli('user delete user001');
```
Test wp-cli exit stati as many commands raising warnings will return a 0 status, e.g:
```
$activated = $I->cli('plugin activate existing-plugin');
$activated = $I->cli('plugin activate non-existing-plugin');
```
The $activated var will have a value of true in both cases as the exit status, even if the non-existing-plugin does not exist, will be 0.
cliToArray(string $userCommand) - executes $userCommand and returns the command output cast to array; the command will try to guess if the output should be split by newlines or spaces.
```
$inactiveThemes = $I->cliToArray('theme list --status=active --field=name');
```
Should the default guessing prove wrong the optional $splitCallback argument can be used; the callback function will be passed 3 arguments:
```
function splitCallback(string $output, string $userCommand, WPCLI $wpcli)
```
and is expected to return an array output.

Option overrides

Any option specified in the module configuration will be overridden (save for the require one that will be merged) by options and arguments specified inline in a command.

// Even if the config YAML file for the module defines the 'url' var the one specified inline will be used.
$I->cli('wp post create --post_title=Foo --post_content=Foo --post_excerpt=Foo --url=http://subdomain.wordpress.dev');

Configuration files

Global and local configuration files will be ignored; any additional parameter should be specified inline.
This prevents tests from running commands that would impact the WordPress installation in a way that would not be reversible (e.g. create or modify the .htaccess file); as a general guideline the wrapper is meant to be used to perform database reversible operations.

WPFilesystem module configuration

This module can be used in any level of testing and provides methods to navigate and manipulate the WordPress file and folder structure.
At a minimum the module requires specifying the WordPress installation root folder:

modules:
    enabled:
        WPFilesystem:
            wpRootFolder: "/var/www/wordpress"

wpRootFolder - string, required; the path to the WordPress installation root folder; the folder that contains the wp-load.php file
themes - string, optional; the path, relative to the WordPress root folder or an absolute path, to the themes folder
plugins - string, optional; the path, relative to the WordPress root folder or an absolute path, to the plugins folder.
mu-plugins - string, optional; the path, relative to the WordPress root folder or an absolute path, to the must-use plugins folder
uploads - string, optional; the path, relative to the WordPress root folder or an absolute path, to the uploads folder

If any one of the optional configuration paths (plugins, mu-plugins, themes, uploads) is not specified it will default to the WordPress standard file structure:

wpRootfolder
  \
    wp-content
      \
        themes
        plugins
        mu-plugins
        uploads

To override the default structure specify the optional paths:

modules:
    enabled:
        WPFilesystem:
            wpRootFolder: "/var/www/wp"
            plugins: "/app/plugins" 
            mu-plugins: "/app/mu-plugins" 
            themes: "/themes" 
            uploads: "/content"