WPLoader

WPLoader module

A module to load WordPress and make its code available in tests.

Depending on the value of the loadOnly configuration parameter, the module will behave differently:

loadOnly: false - The module will load WordPress like the Core PHPUnit suite does to run integration tests in a controlled environment. Use the module in this mode with test cases generated using the generate:wpunit command.
loadOnly: true - The module will load WordPress to make it available in the context of tests. Use the module in this mode in Cest, Cept and Codeception unit test cases.

Configuration with loadOnly: false

The module will load WordPress like the Core PHPUnit suite does to run integration tests in a controlled environment.
Together with the test case generated by the generate:wpunit command the module will:

take care of running any test method in a database transaction rolled back after each test
manage and clean up the global environment and context between tests

When used in this mode, the module supports the following configuration parameters:

loadOnly - false to load WordPress and run tests in a controlled environment.
wpRootFolder - required; the path to the WordPress installation root folder. This can be a relative path to the codeception root directory, or an absolute path to the WordPress installation directory. The WordPress installation directory is the directory that contains the wp-load.php file.
dbUrl - required; the URL to the database to use to run tests. The URL must be in the form mysql://username:password@host:port/database to use a MySQL database, or in the form sqlite://path/to/database to use a SQLite database. Alternatively, you can use the dbName, dbUser, dbPassword, dbHost configuration parameters to specify the database connection details.
dump - the path to a database dump, or a set of database dumps, to load before running tests. The dump will be loaded only once, after the tests run.
tablePrefix - the database table prefix to use when loading WordPress, defaults to wp_.
multisite - a boolean value to indicate if WordPress should be loaded and initialized in multisite mode.
dbCharset - the database charset to use when loading WordPress.
dbCollate - the database collate to use when loading WordPress.
domain - the domain to use when loading WordPress. Equivalent to defining the WP_TESTS_DOMAIN constant.
adminEmail - the administrator email to use when loading WordPress. Equivalent to defining the WP_TESTS_EMAIL constant.
title - the site title to use when loading WordPress. Equivalent to defining the WP_TESTS_TITLE constant.
phpBinary - the path to the PHP binary to use to run tests. Defaults to the WP_PHP_BINARY constant.
language - the language to use when loading WordPress. Equivalent to defining the WPLANG constant.
configFile - a configuration file, or a set of configuration files, to load before the tests to further customize and control the WordPress testing environment.
pluginsFolder - the path to the plugins folder to use when loading WordPress. Equivalent to defining the WP_PLUGIN_DIR constant.
plugins - a list of plugins to activate and load in the WordPress installation. Each plugin must be specified in a format like hello.php or my-plugin/my-plugin.php format.
silentlyActivatePlugins - a list of plugins to activate silently, without firing their activation hooks. Depending on the plugin, a silent activation might cause the plugin to not work correctly. The list must be in the same format as the plugins parameter and plugin should be activated silently only if they are not working correctly during normal activation and are known to work correctly when activated silently.
bootstrapActions - a list of actions or callables to call after WordPress is loaded and before the tests run.
theme - the theme to activate and load in the WordPress installation. The theme must be specified in slug format like twentytwentythree.
AUTH_KEY - the AUTH_KEY constant value to use when loading WordPress. If the wpRootFolder path points at a configured installation, containing the wp-config.php file, then the value of the constant in the configuration file will be used, else it will be randomly generated.
SECURE_AUTH_KEY - the SECURE_AUTH_KEY constant value to use when loading WordPress. If the wpRootFolder path points at a configured installation, containing the wp-config.php file, then the value of the constant in the configuration file will be used, else it will be randomly generated.
LOGGED_IN_KEY - the LOGGED_IN_KEY constant value to use when loading WordPress. If the wpRootFolder path points at a configured installation, containing the wp-config.php file, then the value of the constant in the configuration file will be used, else it will be randomly generated.
NONCE_KEY - the NONCE_KEY constant value to use when loading WordPress. If the wpRootFolder path points at a configured installation, containing the wp-config.php file, then the value of the constant in the configuration file will be used, else it will be randomly generated.
AUTH_SALT - the AUTH_SALT constant value to use when loading WordPress. If the wpRootFolder path points at a configured installation, containing the wp-config.php file, then the value of the constant in the configuration file will be used, else it will be randomly generated.
SECURE_AUTH_SALT - the SECURE_AUTH_SALT constant value to use when loading WordPress. If the wpRootFolder path points at a configured installation, containing the wp-config.php file, then the value of the constant in the configuration file will be used, else it will be randomly generated.
LOGGED_IN_SALT - the LOGGED_IN_SALT constant value to use when loading WordPress. If the wpRootFolder path points at a configured installation, containing the wp-config.php file, then the value of the constant in the configuration file will be used, else it will be randomly generated.
NONCE_SALT - the NONCE_SALT constant value to use when loading WordPress. If the wpRootFolder path points at a configured installation, containing the wp-config.php file, then the value of the constant in the configuration file will be used, else it will be randomly generated.
AUTOMATIC_UPDATER_DISABLED - the AUTOMATIC_UPDATER_DISABLED constant value to use when loading WordPress. If the wpRootFolder path points at a configured installation, containing the wp-config.php file, then the value of the constant in the configuration file will be used, else it will be randomly generated.
WP_HTTP_BLOCK_EXTERNAL - the WP_HTTP_BLOCK_EXTERNAL constant value to use when loading WordPress. If the wpRootFolder path points at a configured installation, containing the wp-config.php file, then the value of the constant in the configuration file will be used, else it will be randomly generated.
backupGlobals - a boolean value to indicate if the global environment should be backed up before each test. Defaults to true. The globals' backup involves serialization of the global state, plugins or themes that define classes developed to prevent serialization of the global state will cause the tests to fail. Set this parameter to false to disable the global environment backup, or use a more refined approach setting the backupGlobalsExcludeList parameter below. Note that a test case that is explicitly setting the backupGlobals property will override this configuration parameter.
backupGlobalsExcludeList - a list of global variables to exclude from the global environment backup. The list must be in the form of array, and it will be merged to the list of globals excluded by default.
backupStaticAttributes - a boolean value to indicate if static attributes of classes should be backed up before each test. Defaults to true. The static attributes' backup involves serialization of the global state, plugins or themes that define classes developed to prevent serialization of the global state will cause the tests to fail. Set this parameter to false to disable the static attributes backup, or use a more refined approanch setting the backupStaticAttributesExcludeList parameter below. Note that a test case that is explicitly setting the backupStaticAttributes property will override this configuration parameter.
backupStaticAttributesExcludeList - a list of classes to exclude from the static attributes backup. The list must be in the form of map from class names to the array of method names to exclude from the backup. See an example below.
skipInstall - a boolean value to indicate if the WordPress installation should be skipped between runs, when already installed. Defaults to false. During boot, the WPLoader module will re-install WordPress and activate, on top of the fresh installation, any plugin and theme specified in the plugins and theme configuration parameters: this can be a time-consuming operation. Set this parameter to true to run the WordPress installation once and just load it on the following runs. To force the installation to run again, rerun the suite using the WPLoader module using the --debug flag or delete the _wploader-state.sql file in the suite directory. This configuration parameter is ignored when the loadOnly parameter is set to true.

This is an example of an integration suite configured to use the module:

actor: IntegrationTester
bootstrap: _bootstrap.php
modules:
  enabled:
    - \Helper\Integration
    - lucatume\WPBrowser\Module\WPLoader:
        wpRootFolder: /var/wordpress
        dbUrl: mysql://root:root@mysql:3306/wordpress
        tablePrefix: test_
        domain: wordpress.test
        adminEmail: admin@wordpress.test
        title: 'Integration Tests'
        plugins:
          - hello.php
          - woocommerce/woocommerce.php
          - my-plugin/my-plugin.php
        theme: twentytwentythree

The following configuration uses dynamic configuration parameters to set the module configuration:

actor: IntegrationTester
bootstrap: _bootstrap.php
modules:
  enabled:
    - \Helper\Integration
    - lucatume\WPBrowser\Module\WPLoader:
        wpRootFolder: '%WP_ROOT_FOLDER%'
        dbUrl: '%WP_DB_URL%'
        tablePrefix: '%WP_TABLE_PREFIX%'
        domain: '%WP_DOMAIN%'
        adminEmail: '%WP_ADMIN_EMAIL%'
        title: '%WP_TITLE%'
        plugins:
          - hello.php
          - woocommerce/woocommerce.php
          - my-plugin/my-plugin.php
        theme: twentytwentythree

The following example configuration uses a SQLite database and loads a database fixture before the tests run:

actor: IntegrationTester
bootstrap: _bootstrap.php
modules:
  enabled:
    - \Helper\Integration
    - lucatume\WPBrowser\Module\WPLoader:
        wpRootFolder: /var/wordpress
        dbUrl: sqlite:///var/wordpress/wp-tests.sqlite
        dump:
          - tests/_data/products.sql
          - tests/_data/users.sql
          - tests/_data/orders.sql
        tablePrefix: test_
        domain: wordpress.test
        adminEmail: admin@wordpress.test
        title: 'Integration Tests'
        plugins:
          - hello.php
          - woocommerce/woocommerce.php
          - my-plugin/my-plugin.php
        theme: twentytwentythree

The follow example configuration prevents the backup of globals and static attributes in all the tests of the suite that are not explicitly overriding the backupGlobals and backupStaticAttributes properties:

actor: IntegrationTester
bootstrap: _bootstrap.php
modules:
  enabled:
    - \Helper\Integration
    - lucatume\WPBrowser\Module\WPLoader:
        wpRootFolder: /var/wordpress
        dbUrl: sqlite:///var/wordpress/wp-tests.sqlite
        dump:
          - tests/_data/products.sql
          - tests/_data/users.sql
          - tests/_data/orders.sql
        tablePrefix: test_
        domain: wordpress.test
        adminEmail: admin@wordpress.test
        title: 'Integration Tests'
        plugins:
          - hello.php
          - woocommerce/woocommerce.php
          - my-plugin/my-plugin.php
        theme: twentytwentythree
        backupGlobals: false
        backupStaticAttributes: false

The following configuration prevents the backup of some globals and static attributes:

actor: IntegrationTester
bootstrap: _bootstrap.php
modules:
  enabled:
    - \Helper\Integration
    - lucatume\WPBrowser\Module\WPLoader:
        wpRootFolder: /var/wordpress
        dbUrl: sqlite:///var/wordpress/wp-tests.sqlite
        dump:
          - tests/_data/products.sql
          - tests/_data/users.sql
          - tests/_data/orders.sql
        tablePrefix: test_
        domain: wordpress.test
        adminEmail: admin@wordpress.test
        title: 'Integration Tests'
        plugins:
          - hello.php
          - woocommerce/woocommerce.php
          - my-plugin/my-plugin.php
        theme: twentytwentythree
        backupGlobalsExcludeList:
          - my_plugin_will_explode_on_wakeup
          - another_problematic_global
        backupStaticAttributesExcludeList:
          - MyPlugin\MyClass:
              - instance
              - anotherStaticAttributeThatWillExplodeOnWakeup
          - AnotherPlugin\AnotherClass:
              - instance
              - yetAnotherStaticAttributeThatWillExplodeOnWakeup

Handling a custom site structure

The setup process should just work for standard and non-standard WordPress installations alike.

Even if you're working on a site project using a custom file structure, e.g. Bedrock, you will be able to set up your site to run tests using the default configuration based on PHP built-in server, Chromedriver and SQLite database.

Configuration with loadOnly: true

The module will load WordPress from the location specified by the wpRootFodler parameter, relying on the WPDb module to manage the database state.

When used in this mode, the module supports the following configuration parameters:

loadOnly - true to load WordPress and make it available in the context of tests.
wpRootFolder - required; the path to the WordPress installation root folder. This can be a relative path to the codeception root directory, or an absolute path to the WordPress installation directory. The WordPress installation directory is the directory that contains the wp-load.php file.
dbUrl - required; the URL to the database to use to run tests. The URL must be in the form mysql://username:password@host:port/database to use a MySQL database, or in the form sqlite://path/to/database to use a SQLite database. Alternatively, you can use the dbName, dbUser, dbPassword, dbHost configuration parameters to specify the database connection details.
domain - the domain to use when loading WordPress. Equivalent to defining the WP_TESTS_DOMAIN constant.

The following is an example of the module configuration to run end-to-end tests on the site served at http://localhost:8080 URL and served from the /var/wordpress directory:

actor: EndToEndTester
bootstrap: _bootstrap.php
modules:
  enabled:
    - \Helper\Integration
    - lucatume\WPBrowser\Module\WPWebDriver:
        url: 'http://localhost:8080'
        adminUsername: 'admin'
        adminPassword: 'password'
        adminPath: '/wp-admin'
        browser: chrome
        host: 'localhost'
        port: '4444'
        path: '/'
        window_size: false
        capabilities:
          "goog:chromeOptions":
            args:
              - "--headless"
              - "--disable-gpu"
              - "--disable-dev-shm-usage"
              - "--proxy-server='direct://'"
              - "--proxy-bypass-list=*"
              - "--no-sandbox"
    - lucatume\WPBrowser\Module\WPDb:
        dbUrl: 'mysql://root:password@localhost:3306/wordpress'
        url: 'http://localhost:8080'
        tablePrefix: 'wp_'
        dump: 'tests/_data/dump.sql'
        populate: true
        cleanup: true
        reconnect: false
        urlReplacement: true
        originalUrl: http://wordpress.test
        waitlock: 10
        createIfNotExists: true
    - lucatume\WPBrowser\Module\WPLoader:
        loadOnly: true
        wpRootFolder: /var/wordpress
        dbUrl: 'mysql://root:password@localhost:3306/wordpress'
        domain: wordpress.test

Methods

The module provides the following methods:

factory

Signature: factory() : lucatume\WPBrowser\Module\WPLoader\FactoryStore

Accessor method to get the object storing the factories for things. This method gives access to the same factories provided by the Core test suite.

getContentFolder

Signature: getContentFolder([string $path]) : string

Returns the absolute path to the WordPress content directory.

getInstallation

Signature: getInstallation() : lucatume\WPBrowser\WordPress\Installation

getPluginsFolder

Signature: getPluginsFolder([string $path]) : string

Returns the absolute path to the plugins directory.

The value will first look at the WP_PLUGIN_DIR constant, then the pluginsFolder configuration parameter and will, finally, look in the default path from the WordPress root directory.

getThemesFolder

Signature: getThemesFolder([string $path]) : string

Returns the absolute path to the themes directory.

getWpRootFolder

Signature: getWpRootFolder([?string $path]) : string

Returns the absolute path to the WordPress root folder or a path within it..