WordPress Unit Testing for Beginners: Setup, Examples, and Best Practices

Unit testing is a crucial practice for developers, enabling the automation of code verification to ensure functionalities meet expected behaviors. This article serves as a beginner’s guide, focusing on WordPress unit testing methodologies, from initial setup to writing effective tests. Whether you’re a plugin or theme developer, mastering unit testing can enhance your code quality, mitigate errors, and streamline your development process.

1. Why Unit Testing Matters in WordPress

Unit testing involves creating automated checks for small, focused code segments like functions and methods. Think of unit tests as reliable experiments assessing whether specific parts of your code perform as intended after changes. In WordPress development, the lines between unit and integration tests can blur. Many developers utilize WP_UnitTestCase, which initializes a simplified WordPress environment to validate code interacting with the database, akin to integration testing. This guide will help you explore the benefits tailored for plugin or theme developers:

• Catch regressions early and prevent broken features.
• Make code refactoring safer, as tests act as a safety net.
• Document expected behaviors for future maintainers and reviewers.
• Reduce manual quality assurance time, expediting release cycles.

In this guide, we’ll cover how to set up your testing environment, write your first tests, run them locally and in Continuous Integration (CI), and adhere to best practices for effective unit testing.

2. Prerequisites: What You Need to Get Started

Before diving into testing, ensure you have a functional developer environment and familiarity with PHP and WordPress structures. Key prerequisites include:

• Fundamental knowledge of PHP and WordPress development.
• Composer for dependency management.
• PHPUnit testing framework installed via Composer.
• Git for version control.
• Recommended: WP-CLI, Docker, or a local WordPress setup for more advanced environments.

Development Environment Options

• Local GUI Tools: Local by Flywheel, MAMP, or XAMPP for straightforward setups.
• Docker: Use Docker or Docker Compose for reproducible environments, particularly advantageous for CI compatibility.
• WSL: For Windows users desiring a Linux-like experience, refer to our guide on setting up a Windows development environment with WSL.

Compatibility Notes

• PHPUnit 9 requires PHP 7.3+; PHPUnit 10 needs PHP 8.0+. Refer to the PHPUnit documentation for version matching.
• Utilize Composer to manage PHPUnit versions compatible with your PHP runtime.

3. Types of Tests in WordPress

Understanding various test types helps improve your testing strategy:

Key Notes:

• Opt for unit tests when validating isolated business logic. For dependency on WordPress functions, utilize libraries like WP_Mock.
• Integration tests are prevalent for plugins and themes, aiding in validating code interactions with the WordPress database.
• Acceptance tests are more resource-intensive, ideal for analyzing complete user experiences, like checkouts or form submissions.

Start with unit and integration tests, then consider adding acceptance tests for vital user-oriented workflows.

4. Setting Up Your Testing Environment

Step-by-Step Essentials

1. Initialize Composer: Create or access your plugin/theme repository:

   composer init --name="vendor/my-plugin" --require-dev "phpunit/phpunit:^9.5" -n
   composer require --dev phpunit/phpunit:^9.5
   

   Adjust the PHPUnit version according to your PHP runtime. Check the PHPUnit website for compatibility details.

2. WordPress Test Suite: A separate WordPress installation dedicated exclusively to testing is necessary. Review the authoritative page on WordPress plugin unit testing for guidance on setting up.

   Key points include:

   • The test suite requires wp-tests-config.php, linking to a dedicated test database and your WordPress path.
   • Tests are designed to create and reset tables in the test DB; avoid pointing this to production data.

3. Configuration: Incorporate PHPUnit configuration and bootstrap. Add a minimal phpunit.xml:

   <?xml version="1.0" encoding="UTF-8"?>
   <phpunit bootstrap="tests/bootstrap.php" colors="true">
     <testsuites>
       <testsuite name="Plugin Test Suite">
         <directory>tests</directory>
       </testsuite>
     </testsuites>
   </phpunit>
   

   Create a tests/bootstrap.php to load the WordPress test library.

4. Useful Shortcuts: WP-CLI scripts can ease test suite installation. Check the WordPress Plugin Unit Testing documentation for example commands.

5. Writing Your First Unit Test: Step-by-Step Example

Let’s build a simple example by creating a plugin with a function myplugin_sanitize_email_localpart() to validate and standardize the local part of an email address.

Project Layout

• my-plugin/
  • composer.json
  • my-plugin.php
  • includes/
    • functions.php
  • tests/
    • bootstrap.php
    • test-sanitize.php
  • phpunit.xml

Example Function in includes/functions.php

<?php
function myplugin_sanitize_email_localpart( $local ) {
    // Normalize the local part: trim, lowercase, remove spaces
    if ( ! is_string( $local ) ) {
        return '';
    }
    $local = trim( $local );
    $local = strtolower( $local );
    $local = str_replace( ' ', '', $local );
    return $local;
}

Creating the Test Class in tests/test-sanitize.php

Using WP_UnitTestCase:

<?php
class Test_Sanitize extends WP_UnitTestCase {
    public function test_sanitize_basic() {
        $this->assertEquals( 'alice', myplugin_sanitize_email_localpart( 'Alice' ) );
        $this->assertEquals( 'bobsmith', myplugin_sanitize_email_localpart( ' bob smith ' ) );
    }

    public function test_sanitize_non_string() {
        $this->assertEquals( '', myplugin_sanitize_email_localpart( null ) );
        $this->assertEquals( '', myplugin_sanitize_email_localpart( 123 ) );
    }
}

For pure unit tests independent from WordPress, inherit from PHPUnit\Framework\TestCase and bypass WordPress test bootstrap; for dependencies on WordPress functions, use the bootstrap or mock them with WP_Mock.

Using the WordPress Factory

If you’re employing WP_UnitTestCase, you can access $this->factory:

$user_id = $this->factory->user->create( ['role' => 'editor'] );
$post_id = $this->factory->post->create( ['post_author' => $user_id] );
$this->assertIsInt( $post_id );

6. Running Tests Locally and Interpreting Results

Execute tests using the vendor binary:

# run the full suite
./vendor/bin/phpunit

# run a specific test class
./vendor/bin/phpunit tests/test-sanitize.php

# run a specific test method
./vendor/bin/phpunit --filter test_sanitize_basic tests/test-sanitize.php

# human-readable output
./vendor/bin/phpunit --testdox

Understanding Results:

• OK: Indicates that all tests passed.
• FAILURES: An assertion failed; verify expected versus actual results.
• ERRORS: Indicates an exception or fatal error occurred, often due to configuration issues.
• RISKY: Tests may lack assertions or utilize incomplete configurations.

Common Setup Challenges and Solutions:

• Missing wp-tests-config.php: Copy from the WP tests library sample and update DB credentials.
• Incorrect DB Credentials: Ensure the test database exists and user privileges are correctly set.
• PHPUnit Version Mismatch: Pin your PHPUnit version in Composer to sync with PHP.

Speed Tips for Local Iteration:

• Focus on running individual test methods while developing.
• Use --filter and --testdox for clear feedback.
• Prefer pure unit tests for logic devoid of WP dependencies for faster execution.

7. CI Integration: Automating Tests on Push and Pull Requests

Why Implement CI Testing:

• Prevent regressions through merges.
• Test across multiple PHP versions and environments.
• Provide artifact test reports for pull requests.

Sample GitHub Actions Workflow:

name: Run PHPUnit Tests

on: [push, pull_request]

jobs:
  phpunit:
    runs-on: ubuntu-latest
    services:
      mysql:
        image: mysql:5.7
        env:
          MYSQL_ROOT_PASSWORD: root
          MYSQL_DATABASE: wp_tests
        ports: ["3306:3306"]
        options: >-
          --health-cmd="mysqladmin ping" --health-interval=10s --health-timeout=5s --health-retries=3

    steps:
      - uses: actions/checkout@v3
      - uses: shivammathur/setup-php@v2
        with:
          php-version: '7.4'
          extensions: mbstring, mysqli

      - name: Install dependencies
        run: composer install

      - name: Prepare WP tests
        run: |
          bash bin/install-wp-tests.sh wordpress_test root '' localhost 5.8

      - name: Run tests
        run: ./vendor/bin/phpunit --configuration=phpunit.xml --log-junit=phpunit-report.xml

      - name: Upload JUnit report
        uses: actions/upload-artifact@v3
        with:
          name: phpunit-report
          path: phpunit-report.xml

Important Notes:

• Utilize shivammathur/setup-php for managing PHP versions on Actions.
• Cache the vendor directory in Composer to maximize speed across runs.
• Ensure CI utilizes a database version aligning with your local tests.

For assistance with Docker networking or Windows-specific CI runners, refer to our guides on container networking and Windows integration.

8. Best Practices and Testing Strategy

Priorities for Testing:

• Focus on business logic and critical code paths.
• Ensure public plugin APIs (functions/classes utilized by others) are thoroughly tested.
• Validate shortcodes, REST endpoints, and hooks effectively.

Testing Design Principles:

• Maintain small, deterministic tests with each asserting a single behavior.
• Aim for speed: favor unit tests over integration tests whenever feasible.
• Keep tests isolated: avoid dependencies on shared global states.

Recommendations for Naming and Fixtures:

• Use descriptive test names like test_registers_shortcode_with_expected_callback().
• Take advantage of $this->factory for user/post fixtures in integration tests.
• Implement setUp() and tearDown() to reset global state and alleviate caching issues.

Coverage Perspective:

• Don’t rush towards 100% coverage; begin with critical sections and gradually expand.
• Treat your tests as living documentation detailing code functionality.

9. Common Issues and Troubleshooting

PHP Compatibility with PHPUnit:

• Resolve issues by altering your composer setup to a PHPUnit version suited for your PHP.

Example Composer Entry for PHPUnit 9 (PHP 7.3+):

"require-dev": {
  "phpunit/phpunit": "^9.5"
}

Errors in wp-tests-config.php:

• Copy and update from the WordPress tests library sample, ensuring DB settings are current.
• Confirm the test database exists and the credentials are accurate.

Performance Issues:

• For slow tests, move logic into pure unit tests that do not require WP.
• For flaky tests, isolate by clearing caches and resetting states; mock time as needed.

Race Conditions:

• Avoid tests relying on shared resources.
• Ensure database services are healthy in CI before initiating tests.

10. Next Steps and Resources

Roadmap to Enhance Your Test Suite:

1. Incorporate tests for essential functions and bug fixes.
2. Develop tests for admin/public REST endpoints and shortcodes.
3. Implement acceptance tests for complex UI interactions as necessary.
4. Integrate code coverage reporting post-stabilization using Xdebug or phpdbg.

Advanced Topics for Future Learning:

• Explore mocking and spies (WP_Mock, Mockery).
• Test REST API endpoints through HTTP or WP_REST_Request objects.
• Visualize coverage within CI and set coverage thresholds to gate merges.

Additional Readings:

• WordPress Plugin Unit Testing
• WordPress Core Automated Testing Handbook
• PHPUnit Getting Started

11. Conclusion: Practical Tips to Maintain Momentum

Key Takeaways:

• Start small by adding one test for each bug fix or feature enhancement; small victories accumulate.
• Utilize Composer and standardized environments (Docker or WSL) to eliminate “works on my machine” issues.
• Prioritize unit tests for pure logic and integration tests for WordPress-specific interactions.
• Automate tests in CI, treating failures as immediate feedback for improvements.

Quick Checklist Before Your First Test Run:

• Composer and PHPUnit installed.
• WordPress test library downloaded.
• wp-tests-config.php configured for test DB.
• phpunit.xml and tests/bootstrap.php correctly set up.
• Execute ./vendor/bin/phpunit and address any discrepancies in output.

Call to Action:

Make it a practice: implement at least one test for every bug fixed or feature added. With time, your test suite will evolve into a crucial asset that enhances development speed and reliability.