Consistent phpunit runners for local and CI

.distignore

@@ -5,8 +5,9 @@
 bin/
 node_modules/
 tests/
+RELEASE.md
 phpunit.xml.dist
-wp-tests-config-sample.php
+phpunit-*.xml.dist
 phpcs.xml.dist
 phpstan.dist.neon
 composer.json
@@ -18,3 +19,4 @@ package-lock.json
 .gitattributes
 .distignore
 .editorconfig
+.nvmrc

.gitattributes

@@ -6,9 +6,11 @@
 /.cache export-ignore
 /node_modules export-ignore
 /tests export-ignore
+RELEASE.md export-ignore
 phpunit.xml.dist export-ignore
-wp-tests-config-sample.php export-ignore
+phpunit-multisite.xml.dist export-ignore
 phpcs.xml.dist export-ignore
+phpstan.neon.dist export-ignore
 composer.json export-ignore
 composer.lock export-ignore
 package.json export-ignore
@@ -18,3 +20,4 @@ package-lock.json export-ignore
 .gitattributes export-ignore
 .distignore export-ignore
 .editorconfig export-ignore
+.nvmrc export-ignore

.github/workflows/coding-standards.yml

@@ -24,6 +24,8 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: read
+    env:
+      WP_ENV_HOME: .cache/wp-env
 
     steps:
       - name: Checkout
@@ -32,14 +34,29 @@ jobs:
       - name: Setup cache
         uses: actions/cache@v5
         with:
-          key: ${{ runner.os }}-${{ hashFiles('composer.json') }} # Note that lock file will change between runs.
-          path: .cache
+          key: ${{ runner.os }}-${{ hashFiles('composer.json', 'package.json') }}
+          path: |
+            .cache
 
-      - name: Set up PHP
-        uses: shivammathur/setup-php@cf4cade2721270509d5b1c766ab3549210a39a2a # v2.33.0
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          cache: 'npm'
+          node-version-file: '.nvmrc'
 
       - name: Install dependencies
-        run: composer install
+        run: npm install
+
+      - name: Start the development environment
+        run: npm run env start
+
+      - name: Install Composer dependencies
+        run: npm run test:php:install-deps
+
+      - name: Lint PHPCS
+        # TODO: Remove the flag once all warnings are fixed.
+        run: npm run lint:php:phpcs -- -- -- --warning-severity=0
+
+      - name: Run PHPStan
+        run: npm run lint:php:phpstan
 
-      - name: Lint PHP
-        run: composer run lint

.github/workflows/phpunit-tests.yml

@@ -5,8 +5,6 @@ on:
     branches:
       - main
   pull_request:
-    branches:
-      - main
   workflow_dispatch:
 
 # Cancels all previous workflow runs for pull requests that have not completed.
@@ -16,100 +14,122 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.event_name == 'pull_request' && github.head_ref || github.sha }}
   cancel-in-progress: true
 
-permissions:
-  contents: read
+# Disable permissions for all available scopes by default.
+# Any needed permissions should be configured at the job level.
+permissions: {}
 
 jobs:
-  # Runs the PHPUnit tests for FAIR.
-  #
-  # Performs the following steps:
-  # - Checks out the repository.
-  # - Sets up PHP.
-  # - Installs Composer dependencies.
-  # - Installs SVN.
-  # - Installs the test suite.
-  # - Runs the PHPUnit tests.
-  # - Ensures version-controlled files are not modified.
+  generate-matrix:
+    name: Generate PHP and WP version testing matrix
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    outputs:
+      matrix: ${{ steps.generate.outputs.matrix }}
+    steps:
+      - uses: actions/checkout@v6
+      - name: Generate PHP and WP testing matrix
+        id: generate
+        run: echo "matrix=$(node ./bin/github-actions-matrix.js)" >> "$GITHUB_OUTPUT"
+
   phpunit:
     name: Run tests (WP ${{ matrix.wp-version }}, PHP ${{ matrix.php-version }})
     runs-on: ubuntu-latest
+    continue-on-error: ${{ matrix.wp-version == 'trunk' }} # Allow tests to fail for trunk.
+    permissions:
+      contents: read
+    needs: generate-matrix
+    env:
+      WP_ENV_HOME: .cache/wp-env
+      WP_ENV_PHP_VERSION: ${{ matrix.php-version }}
+      WP_ENV_CORE: ${{ matrix.wp-version == 'trunk' && 'WordPress/WordPress' || format( 'https://wordpress.org/wordpress-{0}.zip', matrix.wp-version ) }}
     strategy:
-      matrix:
-        php-version: [ '8.0', '8.1', '8.2', '8.3', '8.4', '8.5' ]
-        wp-version: [ '6.2', '6.3', '6.4', '6.5', '6.6', '6.7', '6.8', '6.9' ]
-        exclude:
-          # PHP 8.5 exclusions
-          - wp-version: '6.8'
-            php-version: '8.5'
-          - wp-version: '6.7'
-            php-version: '8.5'
-          - wp-version: '6.6'
-            php-version: '8.5'
-          - wp-version: '6.5'
-            php-version: '8.5'
-          - wp-version: '6.4'
-            php-version: '8.5'
-          - wp-version: '6.3'
-            php-version: '8.5'
-          - wp-version: '6.2'
-            php-version: '8.5'
-
-          # PHP 8.4 exclusions
-          - wp-version: '6.6'
-            php-version: '8.4'
-          - wp-version: '6.5'
-            php-version: '8.4'
-          - wp-version: '6.4'
-            php-version: '8.4'
-          - wp-version: '6.3'
-            php-version: '8.4'
-          - wp-version: '6.2'
-            php-version: '8.4'
-
-          # PHP 8.3 exclusions
-          - wp-version: '6.3'
-            php-version: '8.3'
-          - wp-version: '6.2'
-            php-version: '8.3'
+      fail-fast: false
+      matrix: ${{ fromJSON( needs.generate-matrix.outputs.matrix ) }}
 
     steps:
       - name: Checkout
-        uses: actions/checkout@master
+        uses: actions/checkout@v6
 
-      - name: Setup MySQL with mysql_native_password
-        uses: shogo82148/actions-setup-mysql@v1
+      - name: Setup Node
+        uses: actions/setup-node@v6
         with:
-          mysql-version: ${{ matrix.wp-version >= '5.0' && '8.0' || '5.6' }}
-          my-cnf: |
-            bind_address=127.0.0.1
-            default-authentication-plugin=mysql_native_password
-          root-password: root
-
-      - name: Set up PHP
-        uses: shivammathur/setup-php@v2
+          cache: 'npm'
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Setup cache
+        uses: actions/cache@v5
         with:
-          php-version: ${{ matrix.php-version }}
-          coverage: none
-          extensions: mysql, mysqli
-          tools: composer, wp-cli, phpunit:${{ matrix.wp-version < '5.1' && '6' || ( matrix.wp-version < '5.9' || matrix.php-version < '8.0' ) && '7' || '9' }}, phpunit-polyfills:^1.1.0
-        env:
-          COMPOSER_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          key: ${{ runner.os }}-${{ hashFiles('composer.json', 'package.json') }}
+          path: |
+            .cache
+            tests/phpunit/cache
 
-      - name: Install Composer dependencies
-        run: composer update --optimize-autoloader --prefer-dist
+      - name: Skip development plugins
+        run: echo '{"plugins":[]}' > .wp-env.override.json
 
-      - name: Install SVN
-        run: sudo apt-get update && sudo apt-get install -y subversion
+      - name: Start the development environment
+        run: npm run env start
 
-      - name: Install test suite
+      - name: Report Versions
         run: |
-          echo "WP_VERSION=${{ matrix.wp-version }}" >> $GITHUB_ENV
-          echo "TMPDIR=${{ runner.temp }}" >> $GITHUB_ENV
-          echo "WP_TESTS_DIR=${{ runner.temp }}/wordpress-tests-lib" >> $GITHUB_ENV
-          echo "WP_CORE_DIR=${{ runner.temp }}/wordpress" >> $GITHUB_ENV
-          TMPDIR=${{ runner.temp }} bash bin/install-wp-tests.sh wordpress_test root root 127.0.0.1 ${{ matrix.wp-version }}
+          npm run env run cli -- php -v
+          npm run env run cli -- wp core version
+
+      - name: Install fresh dependencies for PHP ${{ matrix.php-version }}
+        run: rm composer.lock
+
+      - name: Install dependencies
+        run: npm run cli -- composer require --ignore-platform-req=ext-gmp --dev phpunit/phpunit:^${{ matrix.wp-version < '5.1' && '6' || ( matrix.wp-version < '5.9' || matrix.php-version < '8.0' ) && '7' || '9' }}
 
-      - name: Run PHPUnit tests
+      - name: Run PHPUnit tests (single site)
+        run: npm run test:php
+
+      - name: Run PHPUnit tests (multisite)
+        run: npm run test:php:multisite
+
+  phpunit-coverage:
+    name: PHPUnit Coverage
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    env:
+      WP_ENV_HOME: .cache/wp-env
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup cache
+        uses: actions/cache@v5
+        with:
+          key: ${{ runner.os }}-${{ hashFiles('composer.json', 'package.json') }}
+          path: |
+            .cache
+            tests/phpunit/cache
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          cache: 'npm'
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Start the development environment
+        run: npm run env -- start --xdebug=coverage
+
+      - name: Report Versions
         run: |
-          echo "define('WP_TESTS_PHPUNIT_POLYFILLS_PATH', '$HOME/.composer/vendor/yoast/phpunit-polyfills');" >> ${{ runner.temp }}/wordpress-tests-lib/wp-tests-config.php
-          phpunit
+          npm run env run cli -- php -v
+          npm run env run cli -- php -i | grep xdebug
+          npm run env run cli -- wp core version
+
+      - name: Install Composer dependencies
+        run: npm run test:php:install-deps
+
+      - name: Generate coverage report
+        run: npm run coverage:php:full

.gitignore

@@ -8,6 +8,7 @@
 phpunit.xml
 phpcs.xml
 phpstan.neon
+.wp-env.override.json
 /tests/phpunit/cache
 /tests/phpunit/coverage
 wp-tests-config.php

.nvmrc

@@ -0,0 +1 @@
+20

.wp-env.json

@@ -1,5 +1,6 @@
 {
-	"phpVersion": "7.4",
+	"$schema": "https://schemas.wp.org/trunk/wp-env.json",
+	"phpVersion": "8.0",
 	"plugins": [
 		"norcross/airplane-mode",
 		"johnbillion/query-monitor#3.18.0"

CONTRIBUTING.md

@@ -24,7 +24,7 @@ This plugin is ready to use with wp-env for local development, with a default co
 - `npm run env stop` to stop the development server.
 - `npm run cli` to run any CLI commands inside the environment, such as `npm run cli -- wp plugin list`.
 
-By default wp-env is configured with PHP 7.4 (our minimum supported version), as well as Airplane Mode to avoid inadvertent requests.
+By default `wp-env` is configured with PHP 8.0 (our minimum supported version), as well as Airplane Mode to avoid inadvertent requests.
 
 For linting and static analysis:
 
@@ -34,6 +34,17 @@ For linting and static analysis:
 - `npm run format:php:phpstan` to automatically fix PHPStan issues.
 - `npm run cli -- composer phpstan-baseline` to update the PHPStan baseline [`tests/phpstan-baseline.neon`](tests/phpstan-baseline.neon) as you fix the reported issues.
 
+For PHP unit tests:
+
+- `npm run test:php` to run PHPUnit tests for WP single site (configured in [`phpunit.xml.dist`](phpunit.xml.dist)).
+- `npm run test:php:multisite` to run PHPUnit multisite tests (configured in [`phpunit-multisite.xml.dist`](phpunit-multisite.xml.dist)).
+
+To enable test coverage reporting, start the environment with `npm run env start -- --xdebug=coverage` and then:
+
+- `npm run coverage:php:single` for coverage of single site tests.
+- `npm run coverage:php:multisite` for coverage of multisite tests.
+- `npm run coverage:php:full` for coverage of both tests.
+
 ### Configuring PHP and WP Versions
 
 To run a specific version of PHP or WP with your local development environment, create a `.wp-env.override.json` file in the root of the repository with the following contents:
@@ -44,3 +55,5 @@ To run a specific version of PHP or WP with your local development environment,
 	"core": "https://wordpress.org/wordpress-6.9.zip"
 }
 ```
+
+and restart the development environment with `npm run env start`. Alternatively, set the `WP_ENV_PHP_VERSION` and `WP_ENV_CORE` environment variables before starting the environment.

bin/github-actions-matrix.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+
+// PHP versions and their supported WP versions.
+const supported = {
+	"8.0": [ "6.2", "6.3", "6.4", "6.5", "6.6", "6.7", "6.8", "6.9" ],
+	"8.1": [ "6.2", "6.3", "6.4", "6.5", "6.6", "6.7", "6.8", "6.9" ],
+	"8.2": [ "6.2", "6.3", "6.4", "6.5", "6.6", "6.7", "6.8", "6.9" ],
+	"8.3": [ "6.4", "6.5", "6.6", "6.7", "6.8", "6.9" ],
+	"8.4": [ "6.7", "6.8", "6.9" ],
+	"8.5": [ "6.9", "trunk" ],
+};
+
+const include = Object.entries( supported ).flatMap( ( [ php, wps ] ) =>
+	wps.map( ( wp ) => ( { "php-version": php, "wp-version": wp } ) )
+);
+
+process.stdout.write( JSON.stringify( { include } ) );