Skip to content

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.
  • 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.

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

Handling a custom site structure

If you're working on a site project using a custom file structure, e.g. Bedrock, you should use a custom configuration and, together with that, configure the WPLoader module to load WordPress, plugins and themes code from the correct locations. Take care to point the wpRootFolder parameter to the directory containing the wp-load.php file, the /var/my-site/web/wp one in the following example, and the module will read the project configuration file to load the WordPress code from the correct location.

Here's an example of how the module should be configured to run integration tests on a Bedrock installation:

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

In general, pointing the wpRootFolder parameter to the directory containing the wp-load.php file should take care of loading WordPress code from the correct location. Should that not be the case, use the configFile parameter to point the module to the project test configuration file: a PHP file defining the constants and environment variables to use to load WordPress, plugins and themes correctly.

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..