wp-browser

A WordPress specific set of extensions for Codeception.

The package includes a class extending Codeception PhpBrowser module that adds WordPress related assertions for cest and cept tests, an extension of Codeception own Db module meant to allow for more comfortable WordPress specific database handling and testing and a class taking care of installing and loading a WordPress installation relying on WordPress automated testing suite. While working on the module I've added some methods to the Codeception\Module\Db class to implement CRUDness into it; see below the ExtendedDb class.

Installation

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

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

and then use composer update to fetch the package.
After that follow the configuration instructions below.

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 - will load and configure 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.
WPBootstrapper - will bootstrap an existing WordPress installation in the same variable scope of the calling function to have access to its methods.
WPQueries - allows for assertments to be made on WordPress database access in integration tests.
WordPress - to be used in functional tests it will load WordPress code in the same variable scope as the tests but will make GET, POST, PUT and DELETE requests to the WordPress installation index without requiring a web server.

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

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 harcoded in the database itself making dump sharing a serch 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. 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:
              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: "admin@example.com"
              title: "Test Blog"
              phpBinary: "php"
              language: ""
              configFile: ""
      			  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:

isolatedInstall - bool, def. true, whether the WordPress installation should happen in a separate process from the tests or not.
wpDebug - bool, def. true, the WP_DEBUG global value.
multisite - bool, def. false, if set to true will create a multisite instllation, 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. admin@example.org, 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 wp-content/plugins default one
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.
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]
```

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.

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

wpcept command

The package will create a link to the bin/wpcept script file; that's an extension of Codeception own codecept CLI application to allow for a WordPress specific setup.

bootstrap

The CLI application adds the bootstrap command argument to allow for a quick WordPress testing environment setup replacing the default bootstrap configuration created by Codeception.

  wpcept bootstrap

The command will generate the "Unit", "Integration", "Functional" and "Acceptance" suites following the same pattern used by Codeception but with WordPress specific modules:

Unit with Asserts and helper modules
Integration with WPLoader and helper modules
Functional with Filesystem, WPDb, WordPress and helper modules
Acceptance with WPBrowser, WPDb and helper modules

Please note that default Codeception suite bootstrapping is available using the codecept bootstrap command.

bootstrap:pyramid

The bootstrap:pyramid command argument allows for a quick WordPress testing environment setup following the test pyramid suite organization.
The command

  wpcept bootstrap:pyramid

will generate the "UI", "Service", "Wpunit" and "Unit" suites and will take care of setting up default modules and their settings for each like:

Unit with Asserts and UnitHelper modules
Integration with WPLoader and helper modules
Functional with Filesystem, WPDb, WordPress and helper modules
Acceptance with WPBrowser, WPDb and helper modules

Please note that default Codeception suite bootstrapping is available using the codecept bootstrap command.