WP_PHPUnit Testing Architecture

Purpose of WP_PHPUnit

WP_PHPUnit extends PHPUnit to work within the WordPress ecosystem. Its main goal is to validate WordPress-specific behavior that cannot be tested in isolation.

Test Lifecycle in WordPress

Each test follows a predictable lifecycle managed by WP_PHPUnit.

Lifecycle Phases

  1. setUp()

    • Runs before each test method.

    • Used to create test data (users, posts, options).

    • Database transaction begins here.

  2. Test Execution

    • The actual test logic runs.

    • Assertions check expected vs actual behavior.

  3. tearDown()

    • Runs after each test method.

    • Database rollback occurs automatically.

    • Ensures no data leakage between tests.

Configuration Files

phpunit.xml.dist

This file controls how the test suite behaves.

Common Settings:

  • Defines the test bootstrap file

  • Sets WordPress constants (e.g., WP_DEBUG)

  • Specifies test directories

Example Uses:

  • Enabling debug mode for stricter error detection

  • Limiting test execution to a specific folder

Assertions in WP_PHPUnit

Assertions are statements that verify outcomes.

Common WordPress-Specific Assertions

  • assertPostExists( $post_id )

  • assertUserExists( $user_id )

  • assertWPError( $result )

  • assertNotWPError( $result )

These are layered on top of standard PHPUnit assertions like:

  • assertEquals()

  • assertTrue()

  • assertFalse()

Testing Hooks (Actions & Filters)

WordPress relies heavily on hooks, so testing them is critical.

Action Testing

Goal: Verify that an action fires at the correct time.

Method:

  • Attach a temporary callback

  • Trigger the action

  • Confirm the callback executed

Filter Testing

Goal: Ensure data is modified correctly.

Method:

  • Apply the filter

  • Compare returned value to expected output

Option & Settings Testing

Options are stored in the database and commonly used by plugins.

Testing Strategy

  • Use get_option() and update_option()

  • Verify default values

  • Confirm updates persist during the test

  • Rely on rollback to clean the database afterward

Multisite Testing

WordPress Multisite introduces additional complexity.

Special Considerations

  • Sites have separate tables

  • Users can belong to multiple sites

  • Context switching is required

Key Functions

  • switch_to_blog( $blog_id )

  • restore_current_blog()

These allow tests to safely move between sites without breaking global state.