This module should be used in acceptance tests, see levels of testing for more information.

This module extends the WebDriver module adding WordPress-specific configuration parameters and methods.

The module simulates a user interaction with the site with Javascript support; if you don't need to test your project with Javascript support use the WPBrowser module.

Module requirements for Codeception 4.0+

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

To install the package run:

composer require --dev codeception/module-webdriver:^1.0

Configuration

Due to the combination of possible browsers, capabilities and configurations, it's not possible to provide an exhaustive coverage of all the possible configuration parameteters here.

Please refer to WebDriver documentation for more information.

• url required - Start URL of your WordPress project, e.g. http://wp.test.

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

• browser - The browser to use for the tests, e.g. chrome or firefox.

• capabilities - Depending on the browser set in browser this is a list of browser-specific capabilities.

Example configuration

modules:
  enabled:
    - WPWebDriver
  config:
    WPWebDriver:
      url: 'http://wp.test'
      adminUsername: 'admin'
      adminPassword: 'password'
      adminPath: '/wp-admin'
      browser: chrome
      host: localhost
      port: 4444
      window_size: false #disabled for Chrome driver
      capabilities:
        chromeOptions:
          args: ["--headless", "--disable-gpu", "--proxy-server='direct://'", "--proxy-bypass-list=*"]

Public API

• activatePlugin​

• amEditingPostWithId​

• amOnAdminAjaxPage​

• amOnAdminPage​

• amOnCronPage​

• amOnPagesPage​

• amOnPluginsPage​

• deactivatePlugin​

• dontSeePluginInstalled​

• grabCookiesWithPattern​

• grabFullUrl​

• grabWordPressTestCookie​

• loginAs​

• loginAsAdmin​

• seeErrorMessage​

• seeMessage​

• seePluginActivated​

• seePluginDeactivated​

• seePluginInstalled​

• seeWpDiePage​

• waitForJqueryAjax​

activatePlugin

In the plugin administration screen activates one or more plugins clicking the "Activate" link. The method will not handle authentication and navigation to the plugins administration page.

// Activate a plugin.
  $I->loginAsAdmin();
  $I->amOnPluginsPage();
  $I->activatePlugin('hello-dolly');
  // Activate a list of plugins.
  $I->loginAsAdmin();
  $I->amOnPluginsPage();
  $I->activatePlugin(['hello-dolly','another-plugin']);

Parameters

• string/array $pluginSlug - The plugin slug, like "hello-dolly" or a list of plugin slugs.

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

• array/string $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. This method will not handle authentication to the administration area.

$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

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

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');

deactivatePlugin

In the plugin administration screen deactivate a plugin clicking the "Deactivate" link. The method will not handle authentication and navigation to the plugins administration page.

// Deactivate one plugin.
  $I->loginAsAdmin();
  $I->amOnPluginsPage();
  $I->deactivatePlugin('hello-dolly');
  // Deactivate a list of plugins.
  $I->loginAsAdmin();
  $I->amOnPluginsPage();
  $I->deactivatePlugin(['hello-dolly', 'my-plugin']);

Parameters

• string/array $pluginSlug - The plugin slug, like "hello-dolly", or a list of plugin slugs.

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

grabCookiesWithPattern

Returns all the cookies whose name matches a regex pattern.

$I->loginAs('customer','password');
  $I->amOnPage('/shop');
  $cartCookies = $I->grabCookiesWithPattern("#^shop_cart\\.*#");

Parameters

• string $cookiePattern - The regular expression pattern to use for the matching.

grabFullUrl

Grabs the current page full URL including the query vars.

$today = date('Y-m-d');
  $I->amOnPage('/concerts?date=' . $today);
  $I->assertRegExp('#\\/concerts$#', $I->grabFullUrl());

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.

loginAs

Login as the specified user. The method will not follow redirection, after the login, to any page. Depending on the driven browser the login might be "too fast" and the server might have not replied with valid cookies yet; in that case the method will re-attempt the login to obtain the cookies.

$I->loginAs('user', 'password');
  $I->amOnAdminPage('/');
  $I->see('Dashboard');

Parameters

• string $username - The user login name.

• string $password - The user password in plain text.

• int $timeout - The max time, in seconds, to try to login.

• int $maxAttempts - The max number of attempts to try to login.

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');

Parameters

• int $timeout - The max time, in seconds, to try to login.

• int $maxAttempts - The max number of attempts to try to login.

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.

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

Parameters

• string/array/string $classes - A list of classes the notice should have other than the .notice.notice-error ones.

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()ja
  $I->amOnAdminPage('/');
  $I->seeMessage('.missing-api-token.my-plugin');

Parameters

• string/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 adminstration 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();

waitForJqueryAjax

Waits for any jQuery triggered AJAX request to be resolved.

$I->amOnPage('/triggering-ajax-requests');
  $I->waitForJqueryAjax();
  $I->see('From AJAX');

Parameters

• int $time - The max time to wait for AJAX requests to complete.

This class extends \Codeception\Module\WebDriver

This class implements \Codeception\Lib\Interfaces\RequiresPackage, \Codeception\Lib\Interfaces\ConflictsWithModule, \Codeception\Lib\Interfaces\ElementLocator, \Codeception\Lib\Interfaces\PageSourceSaver, \Codeception\Lib\Interfaces\ScreenshotSaver, \Codeception\Lib\Interfaces\SessionSnapshot, \Codeception\Lib\Interfaces\MultiSession, \Codeception\Lib\Interfaces\Remote, \Codeception\Lib\Interfaces\Web