Skip to main content

Integration Testing with Codeception

Learn how to use the Codeception testing framework and the wp-test command to verify your WordPress site's functionality. See instructions for writing custom acceptance tests and whitelisting browser console warnings on Seravo.

Tested updates are a core part of Seravo's WordPress hosting service. Keeping software up to date is essential for both security and functionality, yet new releases can occasionally introduce unexpected compatibility issues. At Seravo, automated tests are run before and after updates to ensure changes do not break your site.

You can run these same tests yourself at any time and extend them with site-specific custom tests using the Codeception testing framework.

How Seravo's Testing Works

Seravo's tests are acceptance (integration) tests that evaluate your site as a whole from a real visitor's perspective rather than testing isolated code functions. Tests are executed in a real browser (Headless Google Chrome and ChromeDriver), catching the same issues an actual user would encounter.

The default test suite verifies that:

  • Your site's front page loads without errors.

  • The login page (/wp-login.php) opens and logging into the WordPress admin dashboard with a temporary test user succeeds (including rendering the admin toolbar).

  • The web server does not return HTTP error status codes (such as 500 or 404).

  • PHP execution completes without fatal errors and the page renders properly in the browser.

  • Stylesheets (CSS), images, and other frontend assets load successfully.

  • No JavaScript errors or warnings are logged to the browser console.

If any test fails during an automated update, the update is rolled back automatically. In addition, wp-test captures screenshots of your site for visual regression checks.

Note: For critical security updates, Seravo may proceed with installing the update regardless of test results to keep your site protected. Please also note that acceptance tests are a separate testing tool and are not part of Seravo's 24/7 server monitoring.

Running Tests (wp-test)

You can run the test suite in any environment (production, staging, and the local Docker development environment) with:

wp-test

Example output of a successful test run:

I: Starting wp-test...
I: Using URL 'https://www.example.com' for pre-flight checks.
I: Pre-flight test for https://www.example.com returned HTTP code 200
I: Executing ChromeDriver...
I: Ensure test user exists...
I: Updated permission and password for existing test user...
I: Running Codecept test suite 1/1..
Codeception PHP Testing Framework
Acceptance Tests (2) ----------------------------------------------------
⏺ Recording ⏺ step-by-step screenshots will be saved to /data/reports/tests/
✔ SeravoCheckWPHomeCest: Try to open home (1.86s)
✔ SeravoCheckWPLoginCest: Try to login and access wp admin (10.60s)
--------------------------------------------------------------------------
⏺ Records saved into: file:///data/reports/tests/records.html
OK (2 tests, 3 assertions)
I: Lower test user privileges as test ended...
I: Finished running wp-test

Screenshots and step-by-step HTML execution reports are saved on the server in /data/reports/tests/.

Seravo's default tests are completely safe to run in production: the runner creates a temporary test user strictly for the duration of the test and revokes its privileges immediately afterward.

Tip: Make wp-test part of your deployment workflow by running the test suite in your staging environment after deploying code changes, before pushing updates to production.

Writing Custom Tests

The wp-test command automatically executes any custom tests located in /data/wordpress/tests/codeception/. If this directory does not exist in your project yet, you can create it and track your custom tests directly in your site's Git repository.

Three formats are supported for custom tests:

1. Simple Procedural Tests (*Cept.php)

Procedural *Cept.php files are well suited for quick, single-purpose checks. Create a file at /data/wordpress/tests/codeception/acceptance/ExampleCept.php:

<?php
$I = new AcceptanceTester($scenario);
$I->amOnPage('/');
$I->checkBrowserConsole();
$I->see('WordPress');

2. Class-Based Tests (*Cest.php)

Object-oriented *Cest.php classes are the recommended approach for organizing larger test suites. Each file must contain a single PHP class whose name matches the filename (for example, /data/wordpress/tests/codeception/acceptance/UserCheckWPHomeCest.php):

<?php

class UserCheckWPHomeCest
{
/**
* Test submitting the search form on the front page
*/
public function trySubmittingSearch(\AcceptanceTester $I)
{
// Navigate to the front page
$I->amOnPage('/');

// Verify the browser console has no errors
$I->checkBrowserConsole();

// Check page content and elements
$I->see('Welcome');
$I->seeElement('h1#maintitle');
$I->seeElement('form[name=searchform]');

// Fill in and submit the search form
$I->fillField('input[name=search]', 'searchterm');
$I->click('#submitSearchForm');

// Verify search results and capture a screenshot
$I->see('Search results:');
$I->makeScreenshot('searchresults');
}

/**
* Check for hidden elements in the DOM
*/
public function tryIfNonVisibleElementExists(\AcceptanceTester $I)
{
$I->amOnPage('/example-page');
$I->seeElementInDOM('#myhiddenelement');

$I->amOnPage('/second-page');
$I->dontSeeElementInDOM('h3#thisshouldnotexist');
}
}

You can run and debug a newly written test with verbose output and halt on the first failure using:

wp-test --debug --fail-fast

Note: Tested WordPress updates are included in all Seravo hosting plans. Writing or debugging site-specific custom tests is not included in the monthly hosting fee, though you can commission custom test development from our experts on an hourly basis.

3. Custom Codeception Configuration (custom.yml)

You can also define a fully customized Codeception suite by placing your test files in /data/wordpress/tests/codeception/ alongside a custom.yml configuration file, which can then be executed with codecept run.

Reference of Helper Functions

Seravo Acceptance Helper (SeravoAcceptanceHelper)

Seravo's testing environment includes built-in helper methods for detecting the active environment and inspecting browser console logs:

// Return the current environment (production, development, staging, update)
$I->getEnvironment();

// Check whether tests are running in production or development (true/false)
$I->isProduction();
$I->isDevelopment();

// Return browser console log entries as an array
$I->getConsoleLog();

Tip: If you write tests that submit contact forms or place test orders, skip them in production using if ($I->isProduction()) { return; }.

Common Codeception Actions

// Navigating
$I->amOnPage('/path/to/page?param=1');

// Clicking links and buttons
$I->click('#element-id');
$I->click('a.button-class');
$I->click('input[name=ok]');

// Filling form fields
$I->fillField('field-name', 'value');

// Asserting page content and structure
$I->seeInTitle('Page Title');
$I->see('Expected text');
$I->seeElement('//table/tr'); // XPath selector
$I->seeElement('h1'); // HTML tag
$I->seeElement('#id'); // ID selector
$I->seeElement('.class-name'); // CSS class
$I->seeElement('div#main p.intro'); // Specific CSS selector

// Checking the browser console
$I->checkBrowserConsole();

// Ignore warnings (WARNING) and check only severe errors (SEVERE)
$I->checkBrowserConsole(true);

// Ignore warnings as well as a specific severe error message
$I->checkBrowserConsole(true, array(
array(
"level" => "SEVERE",
"message" => ".* Uncaught DOMException: play\\(\\) failed because the user didn't interact with the document first.",
"regex" => true
)
));

Whitelisting Harmless Browser Console Messages

By default, $I->checkBrowserConsole() treats any error or warning logged to Chrome's developer console as a test failure—whether related to JavaScript execution, missing assets, or mixed-content warnings.

Occasionally, a console message is a harmless notice that should not block updates (such as a jQuery Migrate deprecation warning triggered by a third-party plugin):

WARNING: https://example.com/wp-includes/js/jquery/jquery-migrate.js?ver=1.4.1 44:11 "JQMIGRATE: jQuery.browser is deprecated"

Method 1: Whitelisting via wp-test-whitelist (Recommended)

You can add a message to your site's whitelist directly from the command line:

wp-test-whitelist --add ".* JQMIGRATE: .* is deprecated" --regex

This command automatically updates your site's console-whitelist.json file. View all available flags by running wp-test-whitelist --help.

Method 2: Editing console-whitelist.json Manually

You can also manage whitelisted console messages directly in version control by editing /data/wordpress/tests/codeception/acceptance/console-whitelist.json:

[
{
"level": "WARNING",
"message": ".* JQMIGRATE: .* is deprecated",
"regex": true
}
]
  • message (required): The exact string or regular expression (regex) to allow.

  • regex (optional): Set to true if message uses a regular expression.

  • level (optional): The log severity level, such as WARNING or SEVERE.

Note: Because JSON uses the backslash (\) as an escape character, backslashes inside regular expressions must be doubled. For example, an escaped dot written as jquery\.com in regex must be entered as jquery\\.com in JSON.

Using a site-wide console-whitelist.json file applies your rules to every $I->checkBrowserConsole() call, including checks executed during Seravo's automated update tests.

Common Issues and Troubleshooting

  • wp-test fails with a browser console error: Inspect the error message printed in the test output. If it is a harmless warning from an external script or third-party plugin that cannot be fixed in your own code, allow it using wp-test-whitelist.

  • wp-test fails in staging or on a pre-launch site with a front-page or login error: If the site is protected by HTTP Basic Authentication (.htpasswd) or an active Coming Soon / maintenance mode plugin, Headless Chrome cannot access the front page or /wp-login.php. Temporarily disable password protection or maintenance mode while running tests.

  • Tests fail in the local Docker environment with an SSL or domain error: Ensure the local Docker environment is running (seravo-docker up) and that the site responds at the configured local domain.

  • A custom *Cest.php file is not executed: Confirm that the file is located in /data/wordpress/tests/codeception/acceptance/, ends with Cest.php (for example, CustomTestCest.php), and defines a PHP class whose name matches the filename without the .php extension.

  • How can I inspect what happened in the browser when a test failed? Open the screenshots saved in /data/reports/tests/ or view the step-by-step execution replay in /data/reports/tests/records.html.

See Also

Automated Codeception tests help ensure that both WordPress updates and your own code changes can be deployed with confidence. If you need assistance troubleshooting test failures or implementing custom tests, our support team is happy to help at [email protected].

Did this answer your question?