wp-testing

WordPress Testing with PHPUnit

Critical Rules

• Always extend WP_UnitTestCase for integration tests. It provides automatic database transactions, factory methods, and WordPress-specific assertions.
• Use WordPress factory methods ($this->factory->post, $this->factory->user, etc.) to create test data. Never insert directly into the database.
• Database cleanup is automatic. WP_UnitTestCase wraps each test in a transaction and rolls back after completion. Do not manually truncate tables.
• Never test WordPress core. Do not write tests to verify that add_action() fires or that get_post() returns a post. Trust core; test YOUR code.
• Use wp-env for a reproducible local test environment. It provides a Docker-based WordPress installation with PHPUnit pre-configured.
• Isolate external dependencies. Mock HTTP requests, emails, file system operations, and third-party APIs. Never let tests hit real external services.
• One assertion concept per test. A test method should verify one logical behavior, even if that requires multiple assert* calls.

Test Bootstrap Setup

tests/bootstrap.php

<?php
/**
 * PHPUnit bootstrap file for the plugin.
 */

// Determine the WordPress test suite location.
$_tests_dir = getenv( 'WP_TESTS_DIR' );

if ( ! $_tests_dir ) {
    $_tests_dir = rtrim( sys_get_temp_dir(), '/\\' ) . '/wordpress-tests-lib';
}

// Verify the test suite exists.
if ( ! file_exists( "{$_tests_dir}/includes/functions.php" ) ) {
    echo "Could not find {$_tests_dir}/includes/functions.php, have you run bin/install-wp-tests.sh?" . PHP_EOL;
    exit( 1 );
}

// Give access to tests_add_filter() function.
require_once "{$_tests_dir}/includes/functions.php";

/**
 * Manually load the plugin being tested.
 */
function _manually_load_plugin() {
    require dirname( dirname( __FILE__ ) ) . '/my-plugin.php';
}
tests_add_filter( 'muplugins_loaded', '_manually_load_plugin' );

// Start up the WP testing environment.
require "{$_tests_dir}/includes/bootstrap.php";