plugin-tester

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

★ 24 Open GitHub ↗

Simple Docker image for running unit tests for WordPress plugins

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# humanmade/plugin-tester

[![Docker Pulls](https://img.shields.io/docker/pulls/humanmade/plugin-tester)](https://hub.docker.com/repository/docker/humanmade/plugin-tester) [![Docker Image Size (latest by date)](https://img.shields.io/docker/image-size/humanmade/plugin-tester)](https://hub.docker.com/repository/docker/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:

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

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

```sh
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.:

```sh
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
<?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:

```yaml
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:

```yaml
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:

```yaml
services:
  - docker

before_script:
  - composer install

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

We recommend also [caching the vendor directory](https://docs.travis-ci.com/user/caching/#arbitrary-directories):

```yaml
cache:
  timeout: 1000
  directories:
    - vendor
```

## Code Coverage

Plugin Tester includes [pcov](https://github.com/krakjoe/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](https://github.com/krakjoe/pcov-clobber) installed via Composer:

```sh
composer require --dev pcov/clobber
```

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

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

plugin-tester

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README