humanmade/plugin-tester

Simple Docker image for running unit tests for WordPress plugins.

Supports multiple PHP versions: 7.4, 8.0, 8.1, 8.2, 8.3, 8.4, 8.5

To run the tests for your plugin, run this in your plugin directory:

docker run --rm -v "$PWD:/code" humanmade/plugin-tester

You can also specify a specific WordPress and PHP version combination:

docker run --rm -v "$PWD:/code" humanmade/plugin-tester:wp-7.0-php8.5

Available tags follow the pattern wp-{version}-php{version}, e.g.:

• humanmade/plugin-tester:wp-7.0-php7.4
• humanmade/plugin-tester:wp-6.9-php8.4
• humanmade/plugin-tester:wp-6.8-php8.5
• etc.

WordPress-only tags are also available (defaulting to PHP 7.4):

• humanmade/plugin-tester:wp-7.0
• humanmade/plugin-tester:wp-6.9
• humanmade/plugin-tester:wp-6.8
• etc.

The latest tag uses the newest WordPress version with PHP 7.4.

You will need phpunit/phpunit specified as a Composer dependency of your plugin. Additional arguments can be passed to PHPUnit on the CLI directly, e.g.:

docker run --rm -v "$PWD:/code" humanmade/plugin-tester --stop-on-error

Configuration

To configure PHPUnit, place a phpunit.xml.dist in the plugin root. You can alternatively use the command line arguments for PHPUnit for simpler tests.

Typically your tests directory in your plugin should include a bootstrap.php including at least the following:

<?php
require '/wp-phpunit/includes/functions.php';

tests_add_filter( 'muplugins_loaded', function () {
	require dirname( __FILE__ ) . '/../your-plugin-entry-point.php';
} );

require '/wp-phpunit/includes/bootstrap.php';

Continuous Integration with Github Actions

For Github Actions, you can use a workflow such as:

name: Test

on:
  push:
    branches: [ master ]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Install dependencies
        run: docker run --rm -v $PWD:/code --entrypoint='' humanmade/plugin-tester composer install

      - name: Run tests
        run: docker run --rm -v $PWD:/code humanmade/plugin-tester

Testing Against Multiple WordPress and PHP Versions

To test your plugin against multiple WordPress and PHP versions, you can use a matrix strategy. This will create separate jobs for each combination, ensuring your plugin works across different environments:

name: Test

on:
  push:
    branches: [ master ]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        wp_version: ['6.8', '6.9', '7.0']
        php_version: ['7.4', '8.3', '8.4', '8.5']
        exclude:
          # Exclude PHP 7.4 with WordPress 7.0 for example
          - wp_version: '7.0'
            php_version: '7.4'
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Install dependencies
        run: docker run --rm -v $PWD:/code --entrypoint='' humanmade/plugin-tester:wp-${{ matrix.wp_version }}-php${{ matrix.php_version }} composer install

      - name: Run tests (WP ${{ matrix.wp_version }}, PHP ${{ matrix.php_version }})
        run: docker run --rm -v $PWD:/code humanmade/plugin-tester:wp-${{ matrix.wp_version }}-php${{ matrix.php_version }}

Continuous Integration with Travis

For Travis, the following minimal configuration will get your tests running:

services:
  - docker

before_script:
  - composer install

script:
  - docker run --rm -v "$PWD:/code" humanmade/plugin-tester

We recommend also caching the vendor directory:

cache:
  timeout: 1000
  directories:
    - vendor

Code Coverage

Plugin Tester includes pcov for test coverage, which is natively supported by PHPUnit 8+.

WordPress requires PHPUnit 7, so slight adjustments need to be made to PHPUnit to fix compatibility. Plugin Tester will do this automatically for you, provided you have pcov-clobber installed via Composer:

composer require --dev pcov/clobber

You can then set up coverage in your phpunit.xml.dist, or use the command-line flags:

docker run --rm -v "$PWD:/code" humanmade/plugin-tester --coverage-text --whitelist inc/