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:
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 thewp-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
- amOnAdminAjaxPage
- amOnAdminPage
- amOnCronPage
- amOnPage
- amOnPagesPage
- amOnPluginsPage
- dontSeePluginInstalled
- extractCookie
- getResponseContent
- getWpRootFolder
- grabWordPressTestCookie
- logOut
- loginAs
- loginAsAdmin
- seeErrorMessage
- seeMessage
- seePluginActivated
- seePluginDeactivated
- seePluginInstalled
- seeWpDiePage
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.
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.
amOnPluginsPage
Go to the plugins administration screen. The method will not handle authentication.
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.
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
$params - Parameters to filter the cookie value./array
getResponseContent
Returns content of the last response. This method exposes an underlying API for custom assertions.
getWpRootFolder
Returns the absolute path to the WordPress root folder.
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.
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.
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.
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.
Parameters
string/\Codeception\Module\array
$classes - A list of classes the message should have in addition to the/string .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.
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.
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.
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.
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