Skip to content

This is the documentation for version 3 of the project. The current version is version 4 and the documentation can be found here.

WordPress module

This module requires good knowledge and attention to be used effectively; you can replace it with a combination of the WPBrowser module together with the WPLoader module in loadOnly mode. This module should be used in functional tests, see levels of testing for more information.
This module provides a middle-ground, in terms of testing and effects, between the fully isolated approach of the WPBrowser module and the fully integrated approach of the WPLoader module with loadOnly set to false.
It allows to interact with WordPress on a very high level, using methods like $I->loginAs() or $I->amOnPage() as you could do with the WPBrowser module while also loading WordPress in the same variable scope as the tests as the WPLoader module would. Due to WordPress reliance on constants, globals and side-effects this module will make requests to WordPress in an insulated manner and reproduce WordPress environment (globals and super-globals) after each response in the tests variable scope. The module simulates a user interaction with the site without Javascript support, use the WPWebDriver module for any kind of testing that requires Javascript-based interaction with the site.

Module requirements for Codeception 4.0+

This module requires the codeception/lib-innerbrowser Composer package to work when wp-browser is used with Codeception 4.0.

To install the package run:

composer require --dev codeception/lib-innerbrowser:^1.0

Detecting requests coming from this module

When it runs this module will set the WPBROWSER_HOST_REQUEST environment variable.
You can detect and use that information to, as an example, use the correct database in your test site wp-config.php file:

<?php
if ( 
    // Custom header.
    isset( $_SERVER['HTTP_X_TESTING'] )
    // Custom user agent.
    || ( isset( $_SERVER['HTTP_USER_AGENT'] ) && $_SERVER['HTTP_USER_AGENT'] === 'wp-browser' )
    // The env var set by the WPClIr or WordPress modules.
    || getenv( 'WPBROWSER_HOST_REQUEST' )
) {
    // Use the test database if the request comes from a test.
    define( 'DB_NAME', 'wordpress_test' );
} else {
    // Else use the default one.
    define( 'DB_NAME', 'wordpress' );
}

Configuration

  • wpRootFolder required The absolute, or relative to the project root folder, path to the root WordPress installation folder. The WordPress installation root folder is the one that contains the wp-load.php file.
  • adminUsername required - This is the login name, not the "nice" name, of the administrator user of the WordPress test site. This will be used to fill the username field in WordPress login page.
  • adminPassword required - This is the the password of the administrator use of the WordPress test site. This will be used to fill the password in WordPress login page.
  • adminPath required - The path, relative to the WordPress test site home URL, to the administration area, usually /wp-admin.

Example configuration

  modules:
      enabled:
          - WordPress
      config:
          WordPress:
              wpRootFolder: "/var/www/wordpress"
              adminUsername: 'admin'
              adminPassword: 'password'
              adminPath: '/wp-admin'

Public API

amEditingPostWithId


Go to the admin page to edit the post with the specified ID. The method will not handle authentication the admin area.

$I->loginAsAdmin();
  $postId = $I->havePostInDatabase();
  $I->amEditingPostWithId($postId);
  $I->fillField('post_title', 'Post title');

Parameters

  • int $id - The post ID.

amOnAdminAjaxPage


Go to the admin-ajax.php page to start a synchronous, and blocking, GET AJAX request. The method will not handle authentication, nonces or authorization.

$I->amOnAdminAjaxPage(['action' => 'my-action', 'data' => ['id' => 23], 'nonce' => $nonce]);

Parameters

  • string/\Codeception\Module\array $queryVars - A string or array of query variables to append to the AJAX path.

amOnAdminPage


Go to a page in the admininstration area of the site.

$I->loginAs('user', 'password');
  // Go to the plugins management screen.
  $I->amOnAdminPage('/plugins.php');

Parameters

  • string $page - The path, relative to the admin area URL, to the page.

amOnCronPage


Go to the cron page to start a synchronous, and blocking, GET request to the cron script.

// Triggers the cron job with an optional query argument.
  $I->amOnCronPage('/?some-query-var=some-value');

Parameters

  • string/\Codeception\Module\array $queryVars - A string or array of query variables to append to the AJAX path.

amOnPage


Go to a page on the site. The module will try to reach the page, relative to the URL specified in the module configuration, without applying any permalink resolution.

// Go the the homepage.
  $I->amOnPage('/');
  // Go to the single page of post with ID 23.
  $I->amOnPage('/?p=23');
  // Go to search page for the string "foo".
  $I->amOnPage('/?s=foo');

Parameters

  • string $page - The path to the page, relative to the the root URL.

amOnPagesPage


Go the "Pages" administration screen. The method will not handle authentication.

$I->loginAsAdmin();
  $I->amOnPagesPage();
  $I->see('Add New');

amOnPluginsPage


Go to the plugins administration screen. The method will not handle authentication.

$I->loginAsAdmin();
  $I->amOnPluginsPage();
  $I->activatePlugin('hello-dolly');

dontSeePluginInstalled


Assert a plugin is not installed in the plugins administration screen. The method will not handle authentication and navigation to the plugin administration screen.

$I->loginAsAdmin();
  $I->amOnPluginsPage();
  $I->dontSeePluginInstalled('my-plugin');

Parameters

  • string $pluginSlug - The plugin slug, like "hello-dolly".

extractCookie


Grab a cookie value from the current session, sets it in the $_COOKIE array and returns its value. This method utility is to get, in the scope of test code, the value of a cookie set during the tests.

$id = $I->haveUserInDatabase('user', 'subscriber', ['user_pass' => 'pass']);
  $I->loginAs('user', 'pass');
  // The cookie is now set in the `$_COOKIE` super-global.
  $I->extractCookie(LOGGED_IN_COOKIE);
  // Generate a nonce using WordPress methods (see WPLoader in loadOnly mode) with correctly set context.
  wp_set_current_user($id);
  $nonce = wp_create_nonce('wp_rest');
  // Use the generated nonce to make a request to the the REST API.
  $I->haveHttpHeader('X-WP-Nonce', $nonce);

Parameters

  • string $cookie - The cookie name.
  • array/\Codeception\Module\array/array $params - Parameters to filter the cookie value.

getResponseContent


Returns content of the last response. This method exposes an underlying API for custom assertions.

// In test class.
  $this->assertContains($text, $this->getResponseContent(), "foo-bar");

getWpRootFolder


Returns the absolute path to the WordPress root folder.

$root = $I->getWpRootFolder();
  $this->assertFileExists($root . '/someFile.txt');

grabWordPressTestCookie


Returns WordPress default test cookie object if present.

// Grab the default WordPress test cookie.
  $wpTestCookie = $I->grabWordPressTestCookie();
  // Grab a customized version of the test cookie.
  $myTestCookie = $I->grabWordPressTestCookie('my_test_cookie');

Parameters

  • string $name - Optional, overrides the default cookie name.

logOut


Navigate to the default WordPress logout page and click the logout link.

// Log out using the `wp-login.php` form and return to the current page.
  $I->logOut(true);
  // Log out using the `wp-login.php` form and remain there.
  $I->logOut(false);
  // Log out using the `wp-login.php` form and move to another page.
  $I->logOut('/some-other-page');

Parameters

  • bool/bool/string $redirectTo - Whether to redirect to another (optionally specified) page after the logout.

loginAs


Login as the specified user. The method will not follow redirection, after the login, to any page.

$I->loginAs('user', 'password');
  $I->amOnAdminPage('/');
  $I->seeElement('.admin');

Parameters

  • string $username - The user login name.
  • string $password - The user password in plain text.

loginAsAdmin


Login as the administrator user using the credentials specified in the module configuration. The method will not follow redirection, after the login, to any page.

$I->loginAsAdmin();
  $I->amOnAdminPage('/');
  $I->see('Dashboard');

seeErrorMessage


In an administration screen look for an error admin notice. The check is class-based to decouple from internationalization. The method will not handle authentication and navigation the administration area. .notice.notice-error ones.

$I->loginAsAdmin()
  $I->amOnAdminPage('/');
  $I->seeErrorMessage('.my-plugin');

Parameters

  • string/string/\Codeception\Module\array $classes - A list of classes the notice should have other than the

seeMessage


In an administration screen look for an admin notice. The check is class-based to decouple from internationalization. The method will not handle authentication and navigation the administration area.

$I->loginAsAdmin()
  $I->amOnAdminPage('/');
  $I->seeMessage('.missing-api-token.my-plugin');

Parameters

  • string/\Codeception\Module\array/string $classes - A list of classes the message should have in addition to the .notice one.

seePluginActivated


Assert a plugin is activated in the plugin administration screen. The method will not handle authentication and navigation to the plugin administration screen.

$I->loginAsAdmin();
  $I->amOnPluginsPage();
  $I->seePluginActivated('my-plugin');

Parameters

  • string $pluginSlug - The plugin slug, like "hello-dolly".

seePluginDeactivated


Assert a plugin is not activated in the plugins administration screen. The method will not handle authentication and navigation to the plugin administration screen.

$I->loginAsAdmin();
  $I->amOnPluginsPage();
  $I->seePluginDeactivated('my-plugin');

Parameters

  • string $pluginSlug - The plugin slug, like "hello-dolly".

seePluginInstalled


Assert a plugin is installed, no matter its activation status, in the plugin administration screen. The method will not handle authentication and navigation to the plugin administration screen.

$I->loginAsAdmin();
  $I->amOnPluginsPage();
  $I->seePluginInstalled('my-plugin');

Parameters

  • string $pluginSlug - The plugin slug, like "hello-dolly".

seeWpDiePage


Checks that the current page is one generated by the wp_die function. The method will try to identify the page based on the default WordPress die page HTML attributes.

$I->loginAs('user', 'password');
  $I->amOnAdminPage('/forbidden');
  $I->seeWpDiePage();

This class extends \Codeception\Lib\Framework

This class implements \Codeception\Lib\Interfaces\Web, \Codeception\Lib\Interfaces\PageSourceSaver, \Codeception\Lib\Interfaces\ElementLocator, \Codeception\Lib\Interfaces\ConflictsWithModule, \Codeception\Lib\Interfaces\DependsOnModule