Build/Test Tools: Run the full PHPUnit matrix by label.

Allow reviewers to trigger the weekly PHP and database matrix on eligible pull requests by adding the Full PHPUnit Matrix label. Keep full coverage on subsequent commits while the label remains.

Use a separate label-triggered workflow so unrelated labels do not replace PHPUnit checks or cancel active runs. Preserve the existing path filters and document the manual request process for contributors without label access.

Developed in: #13448

Props lucatume, adrianmoldovanwp.
Fixes #66071.


git-svn-id: https://develop.svn.wordpress.org/trunk@63585 602fd350-edb4-49c9-b593-d223f7449a82

Author: lancewillett

.github/workflows/phpunit-tests-full-matrix.yml

@@ -0,0 +1,65 @@
+name: PHPUnit Tests (label)
+run-name: PHPUnit Tests${{ github.event.label.name == 'Full PHPUnit Matrix' && ' (full matrix)' || ' (ignored label)' }}
+
+on:
+  pull_request:
+    types: [ labeled ]
+    branches:
+      - trunk
+      - '3.[7-9]'
+      - '[4-9].[0-9]'
+    # Keep these paths in sync with phpunit-tests.yml.
+    paths:
+      - '**'
+      # Documentation and repository metadata.
+      - '!**.md'
+      - '!.devcontainer/**'
+      - '!.editorconfig'
+      - '!.git-blame-ignore-revs'
+      - '!.gitignore'
+      - '!.mailmap'
+      - '!typings/**'
+      # Configuration for unrelated checks.
+      - '!.eslintrc-jsdoc.js'
+      - '!.prettierrc.js'
+      - '!.version-support-*.json'
+      - '!eslint.config.js'
+      - '!jsdoc.conf.json'
+      - '!phpcompat.xml.dist'
+      - '!phpcs.xml.dist'
+      - '!phpstan.neon.dist'
+      - '!tsconfig.json'
+      # Other test suites, tools, and workflows do not affect these tests.
+      - '!tests/**'
+      - '!tools/**'
+      - '!.github/**'
+      # Re-include documentation, tests, tools, and workflows used here.
+      - 'SECURITY.md'
+      - 'src/license.txt'
+      - 'tests/phpunit/**'
+      - 'tools/gutenberg/**'
+      - 'tools/local-env/**'
+      - 'tools/vendors/**'
+      - 'tools/webpack/**'
+      - 'phpunit.xml.dist'
+      - '.github/workflows/phpunit-tests.yml'
+      - '.github/workflows/phpunit-tests-full-matrix.yml'
+      - '.github/workflows/reusable-phpunit-tests-*.yml'
+      - '.github/workflows/reusable-prepare-gutenberg.yml'
+
+# Disable permissions for all available scopes by default.
+permissions: {}
+
+# The called workflow manages concurrency. Unrelated labels never enter it.
+jobs:
+  full-matrix:
+    if: github.event.label.name == 'Full PHPUnit Matrix'
+    permissions:
+      # Required by the called workflow's recovery job, which is skipped on PR events.
+      actions: write
+      contents: read
+    uses: ./.github/workflows/phpunit-tests.yml
+    secrets:
+      CODEVITALS_PROJECT_TOKEN: ${{ secrets.CODEVITALS_PROJECT_TOKEN }}
+      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+      WPT_REPORT_API_KEY: ${{ secrets.WPT_REPORT_API_KEY }}

.github/workflows/phpunit-tests.yml

@@ -1,4 +1,5 @@
 name: PHPUnit Tests
+run-name: PHPUnit Tests${{ ( github.event_name == 'schedule' || ( github.event_name == 'pull_request' && contains( github.event.pull_request.labels.*.name, 'Full PHPUnit Matrix' ) ) ) && ' (full matrix)' || '' }}
 
 on:
   push:
@@ -11,6 +12,7 @@ on:
       - trunk
       - '3.[7-9]'
       - '[4-9].[0-9]'
+    # Keep these paths in sync with phpunit-tests-full-matrix.yml.
     paths:
       - '**'
       # Documentation and repository metadata.
@@ -45,9 +47,26 @@ on:
       - 'tools/webpack/**'
       - 'phpunit.xml.dist'
       - '.github/workflows/phpunit-tests.yml'
+      - '.github/workflows/phpunit-tests-full-matrix.yml'
       - '.github/workflows/reusable-phpunit-tests-*.yml'
       - '.github/workflows/reusable-prepare-gutenberg.yml'
   workflow_dispatch:
+  workflow_call:
+    secrets:
+      CODEVITALS_PROJECT_TOKEN:
+        required: false
+      CODECOV_TOKEN:
+        required: false
+      WPT_REPORT_API_KEY:
+        required: false
+      SLACK_GHA_SUCCESS_WEBHOOK:
+        required: false
+      SLACK_GHA_CANCELLED_WEBHOOK:
+        required: false
+      SLACK_GHA_FIXED_WEBHOOK:
+        required: false
+      SLACK_GHA_FAILURE_WEBHOOK:
+        required: false
   # Once weekly On Sundays at 00:00 UTC.
   schedule:
     - cron: '0 0 * * 0'
@@ -110,11 +129,11 @@ jobs:
       fail-fast: false
       matrix:
         os: [ ubuntu-24.04 ]
-        # The scheduled run tests every supported PHP version. Other events test the highest and lowest of each major.
-        php: ${{ github.event_name == 'schedule' && fromJSON('["7.4","8.0","8.1","8.2","8.3","8.4","8.5"]') || fromJSON('["7.4","8.0","8.5"]') }}
+        # Scheduled and labeled runs test every supported PHP version. Other runs test the highest and lowest of each major.
+        php: ${{ ( github.event_name == 'schedule' || ( github.event_name == 'pull_request' && contains( github.event.pull_request.labels.*.name, 'Full PHPUnit Matrix' ) ) ) && fromJSON('["7.4","8.0","8.1","8.2","8.3","8.4","8.5"]') || fromJSON('["7.4","8.0","8.5"]') }}
         db-type: [ 'mysql' ]
-        # The scheduled run tests the full database matrix. Other events retain MySQL 5.7 compatibility and the widely used 8.x releases.
-        db-version: ${{ github.event_name == 'schedule' && fromJSON('["5.7","8.0","8.4","9.7"]') || fromJSON('["5.7","8.0","8.4"]') }}
+        # Scheduled and labeled runs test the full database matrix. Other runs retain MySQL 5.7 compatibility and the widely used 8.x releases.
+        db-version: ${{ ( github.event_name == 'schedule' || ( github.event_name == 'pull_request' && contains( github.event.pull_request.labels.*.name, 'Full PHPUnit Matrix' ) ) ) && fromJSON('["5.7","8.0","8.4","9.7"]') || fromJSON('["5.7","8.0","8.4"]') }}
         tests-domain: [ 'example.org' ]
         multisite: [ false, true ]
         memcached: [ false ]
@@ -174,8 +193,8 @@ jobs:
   #
   # Creates a PHPUnit test job for each PHP/MariaDB combination.
   #
-  # The scheduled run tests all LTS versions of MariaDB supported by WordPress with greater than 1% usage according to
-  # w.org/stats. The exceptions to this rule are the most recent LTS and version 5.5.
+  # Scheduled and labeled runs test all LTS versions of MariaDB supported by WordPress with greater than 1% usage
+  # according to w.org/stats. The exceptions to this rule are the most recent LTS and version 5.5.
   #
   # The 5.5 release was intended as a drop-in replacement for MySQL. Because the MySQL 5.5 Docker containers do not
   # work, this ensures some level of MySQL 5.5 testing.
@@ -203,11 +222,11 @@ jobs:
       fail-fast: false
       matrix:
         os: [ ubuntu-24.04 ]
-        # The scheduled run tests every supported PHP version. Other events test the highest and lowest of each major.
-        php: ${{ github.event_name == 'schedule' && fromJSON('["7.4","8.0","8.1","8.2","8.3","8.4","8.5"]') || fromJSON('["7.4","8.0","8.5"]') }}
+        # Scheduled and labeled runs test every supported PHP version. Other runs test the highest and lowest of each major.
+        php: ${{ ( github.event_name == 'schedule' || ( github.event_name == 'pull_request' && contains( github.event.pull_request.labels.*.name, 'Full PHPUnit Matrix' ) ) ) && fromJSON('["7.4","8.0","8.1","8.2","8.3","8.4","8.5"]') || fromJSON('["7.4","8.0","8.5"]') }}
         db-type: [ 'mariadb' ]
-        # The scheduled run tests the full database matrix. Other events retain MariaDB 5.5 compatibility, 10.6, and newer LTS releases.
-        db-version: ${{ github.event_name == 'schedule' && fromJSON('["5.5","10.3","10.5","10.6","10.11","11.4","11.8"]') || fromJSON('["5.5","10.6","10.11","11.4","11.8"]') }}
+        # Scheduled and labeled runs test the full database matrix. Other runs retain MariaDB 5.5 compatibility, 10.6, and newer LTS releases.
+        db-version: ${{ ( github.event_name == 'schedule' || ( github.event_name == 'pull_request' && contains( github.event.pull_request.labels.*.name, 'Full PHPUnit Matrix' ) ) ) && fromJSON('["5.5","10.3","10.5","10.6","10.11","11.4","11.8"]') || fromJSON('["5.5","10.6","10.11","11.4","11.8"]') }}
         multisite: [ false, true ]
         memcached: [ false ]
 
@@ -271,8 +290,8 @@ jobs:
       fail-fast: false
       matrix:
         os: [ ubuntu-24.04 ]
-        # The scheduled run tests every supported PHP version. Other events test the highest and lowest of each major.
-        php: ${{ github.event_name == 'schedule' && fromJSON('["7.4","8.0","8.1","8.2","8.3","8.4","8.5"]') || fromJSON('["7.4","8.0","8.5"]') }}
+        # Scheduled and labeled runs test every supported PHP version. Other runs test the highest and lowest of each major.
+        php: ${{ ( github.event_name == 'schedule' || ( github.event_name == 'pull_request' && contains( github.event.pull_request.labels.*.name, 'Full PHPUnit Matrix' ) ) ) && fromJSON('["7.4","8.0","8.1","8.2","8.3","8.4","8.5"]') || fromJSON('["7.4","8.0","8.5"]') }}
         db-type: [ 'mysql', 'mariadb' ]
         db-version: [ '12.1' ]
         multisite: [ false, true ]

tests/phpunit/README.md

@@ -5,3 +5,15 @@ PHPUnit is the official testing framework chosen by the core team to test PHP co
 For more information, please review the relevant Core Handbook pages:
 - [PHP: PHPUnit](https://make.wordpress.org/core/handbook/testing/automated-testing/phpunit/)
 - [Writing PHP Tests](https://make.wordpress.org/core/handbook/testing/automated-testing/writing-phpunit-tests/)
+
+## Run the full matrix on a pull request
+
+Add the `Full PHPUnit Matrix` label to a pull request in `WordPress/wordpress-develop` to run the same PHP and database combinations as the weekly scheduled run. The label-triggered workflow uses the same path filters as normal PHPUnit runs.
+
+If you cannot apply labels, leave a PR comment asking a reviewer with triage access to add it. Fork PRs follow GitHub's usual workflow approval requirements.
+
+Adding the label starts a separate run without another code push. An existing reduced-matrix run continues alongside it; its checks and results are preserved. New commits run the full matrix while the label remains. Remove and reapply it to request another run for the current revision, or remove it to return subsequent runs to the reduced matrix.
+
+Unrelated labels skip only the label-triggered workflow's `full-matrix` job and do not replace or cancel PHPUnit checks.
+
+Look for `PHPUnit Tests (full matrix)` in GitHub Actions and the PHPUnit checks on the PR. Each run tests the PR's merge commit and retains its own logs and results, so check the revision before relying on an older run.