reusable-phpunit-tests-v3.yml

##
# A reusable workflow that runs the PHPUnit test suite with the specified configuration.
#
# This workflow is used by `trunk` and branches >= 5.9.
##
name: Run PHPUnit tests

on:
  workflow_call:
    inputs:
      os:
        description: 'Operating system to run tests on'
        required: false
        type: 'string'
        default: 'ubuntu-24.04'
      repository:
        description: 'The repository to check out and test. Defaults to the repository calling this workflow.'
        required: false
        type: 'string'
        default: ''
      # Also composes the Gutenberg build name, under the producer's constraint: a valid
      # artifact name, so no slashes and none of : < > | * ? "
      ref:
        description: 'The branch, tag, or SHA to check out. Defaults to the ref that triggered the calling workflow.'
        required: false
        type: 'string'
        default: ''
      php:
        description: 'The version of PHP to use, in the format of X.Y'
        required: true
        type: 'string'
      db-type:
        description: 'Database type. Valid types are mysql and mariadb'
        required: false
        type: 'string'
        default: 'mysql'
      db-version:
        description: 'Database version'
        required: false
        type: 'string'
        default: '8.4'
      db-innovation:
        description: 'Whether a database software innovation release is being tested.'
        required: false
        type: 'boolean'
        default: false
      multisite:
        description: 'Whether to run tests as multisite'
        required: false
        type: 'boolean'
        default: false
      memcached:
        description: 'Whether to test with memcached enabled'
        required: false
        type: 'boolean'
        default: false
      phpunit-config:
        description: 'The PHPUnit configuration file to use'
        required: false
        type: 'string'
        default: 'phpunit.xml.dist'
      phpunit-test-groups:
        description: 'A list of test groups to run.'
        required: false
        type: 'string'
        default: ''
      tests-domain:
        description: 'The domain to use for the tests'
        required: false
        type: 'string'
        default: 'example.org'
      coverage-report:
        description: 'Whether to generate a code coverage report.'
        required: false
        type: boolean
        default: false
      report:
        description: 'Whether to report results to WordPress.org Hosting Tests'
        required: false
        type: 'boolean'
        default: false
      allow-errors:
        description: 'Whether to continue when test errors occur.'
        required: false
        type: boolean
        default: false
      gutenberg-artifact:
        description: 'Whether the Gutenberg-sourced assets are sourced from zip artifact.'
        required: false
        type: boolean
        default: false
      gutenberg-sha:
        description: 'The immutable Gutenberg source SHA verified by the calling workflow.'
        required: false
        type: string
        default: ''
      overlay-artifact:
        description: 'The name of a same-workflow artifact whose contents are unpacked over the checkout. Optional: for callers whose test files are not part of the repository being tested.'
        required: false
        type: string
        default: ''
    secrets:
      CODEVITALS_PROJECT_TOKEN:
        description: 'The authorization token for publishing results to CodeVitals.'
        required: false
      CODECOV_TOKEN:
        description: 'The Codecov token required for uploading reports.'
        required: false
      WPT_REPORT_API_KEY:
        description: 'The WordPress.org Hosting Tests API key.'
        required: false

env:
  LOCAL_PHP: ${{ inputs.php }}-fpm
  LOCAL_PHP_XDEBUG: false
  LOCAL_PHP_XDEBUG_MODE: 'develop,debug'
  LOCAL_DB_TYPE: ${{ inputs.db-type }}
  LOCAL_DB_VERSION: ${{ inputs.db-version }}
  LOCAL_PHP_MEMCACHED: ${{ inputs.memcached }}
  LOCAL_WP_TESTS_DOMAIN: ${{ inputs.tests-domain }}
  PHPUNIT_CONFIG: ${{ inputs.phpunit-config }}
  PUPPETEER_SKIP_DOWNLOAD: true

# 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 WordPress.
  #
  # Performs the following steps:
  # - Requires a ref when the caller points at another repository.
  # - Sets environment variables.
  # - Checks out the repository.
  # - Unpacks the caller-provided overlay artifact over the checkout, if any.
  # - Downloads the prepared Gutenberg build provided by the calling workflow.
  # - Sets up Node.js.
  # - Sets up PHP.
  # - Installs Composer dependencies.
  # - Installs npm dependencies
  # - Logs general debug information about the runner.
  # - Logs Docker debug information (about the Docker installation within the runner).
  # - Starts the WordPress Docker container.
  # - Logs the running Docker containers.
  # - Logs debug information about what's installed within the WordPress Docker containers.
  # - Install WordPress within the Docker container.
  # - Run the PHPUnit tests.
  # - Flags slow PHPUnit tests with GitHub Actions annotations and a run summary.
  # - Publish PHPUnit timing metrics to CodeVitals.
  # - Upload the code coverage report to Codecov.io.
  # - Ensures version-controlled files are not modified or deleted.
  # - Checks out the WordPress Test reporter repository.
  # - Submit the test results to the WordPress.org host test results.
  phpunit-tests:
    name: ${{ ( inputs.phpunit-test-groups || inputs.coverage-report ) && format( 'PHP {0} with ', inputs.php ) || '' }} ${{ 'mariadb' == inputs.db-type && 'MariaDB' || 'MySQL' }} ${{ inputs.db-version }}${{ inputs.multisite && ' multisite' || '' }}${{ inputs.db-innovation && ' (innovation release)' || '' }}${{ inputs.memcached && ' with memcached' || '' }}${{ inputs.report && ' (test reporting enabled)' || '' }} ${{ 'example.org' != inputs.tests-domain && inputs.tests-domain || '' }}
    runs-on: ${{ vars.RUNNERS_NAME || inputs.os }}
    timeout-minutes: ${{ inputs.coverage-report && 120 || 30 }}
    permissions:
      contents: read

    steps:
      # `ref` otherwise falls back to checkout's own default, which for another repository is
      # its default branch: a "WordPress 6.2" job would test trunk and report green.
      - name: Require a ref when testing another repository
        if: ${{ inputs.repository != '' && inputs.ref == '' }}
        run: |
          echo 'Testing another repository needs an explicit ref.' >&2
          exit 1

      # `ref` also composes the Gutenberg artifact name, so reject what that name cannot carry
      # here rather than at a download step the job only reaches minutes later.
      - name: Require a ref the artifact name accepts
        if: ${{ inputs.ref != '' }}
        env:
          REF: ${{ inputs.ref }}
        run: |
          invalid='[/:<>|*?"\]'
          if [[ "$REF" =~ $invalid ]]; then
            echo "A ref that names an artifact cannot contain / : < > | * ? \" \\ - received: $REF" >&2
            exit 1
          fi

      - name: Configure environment variables
        run: |
          echo "PHP_FPM_UID=$(id -u)" >> "$GITHUB_ENV"
          echo "PHP_FPM_GID=$(id -g)" >> "$GITHUB_ENV"

      - name: Checkout repository
        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
        with:
          repository: ${{ inputs.repository || github.repository }}
          ref: ${{ inputs.ref }}
          show-progress: ${{ runner.debug == '1' && 'true' || 'false' }}
          persist-credentials: false

      # If the caller specifies an overlay artifact then unpack it over the checkout.
      - name: Download overlay artifact
        if: inputs.overlay-artifact != ''
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
        with:
          # Without a run ID, this action reads only from the caller's current workflow run.
          name: ${{ inputs.overlay-artifact }}
          path: .
          digest-mismatch: error

      # Only WordPress 7.0+ include Gutenberg-maintained assets from a built zip file.
      - name: Download prepared Gutenberg build
        if: ${{ inputs.gutenberg-artifact }}
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
        with:
          # Every branch in a run shares one artifact namespace, so the producer names each
          # build after the ref it came from. Compose the same name here rather than taking
          # it as an input: the two sides already agree on `ref`.
          name: gutenberg-build${{ inputs.ref && format( '-{0}', inputs.ref ) || '' }}
          path: gutenberg
          digest-mismatch: error

      - name: Set up Node.js
        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
        with:
          node-version-file: '.nvmrc'
          package-manager-cache: false

      - name: Set up npm
        # Release branches run this workflow from trunk, but some older branches may lack the action.
        if: ${{ hashFiles('.github/actions/setup-npm/action.yml') != '' }}
        uses: ./.github/actions/setup-npm

      ##
      # This allows Composer dependencies to be installed using a single step.
      #
      # Since the tests are currently run within the Docker containers where the PHP version varies,
      # the same PHP version needs to be configured for the action runner machine so that the correct
      # dependency versions are installed and cached.
      ##
      - name: Set up PHP
        uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # 2.37.2
        with:
          php-version: '${{ inputs.php }}'
          coverage: none

      # Since Composer dependencies are installed using `composer update` and no lock file is in version control,
      # passing a custom cache suffix ensures that the cache is flushed at least once per week.
      - name: Install Composer dependencies
        uses: ramsey/composer-install@65e4f84970763564f46a70b8a54b90d033b3bdda # 4.0.0
        with:
          custom-cache-suffix: $(/bin/date -u --date='last Mon' "+%F")

      - name: Install npm dependencies
        run: npm ci

      - name: Build WordPress
        timeout-minutes: 5
        run: npm run build:dev
        env:
          # The producer resolved this once. Matrix jobs must not re-resolve mutable GHCR tags.
          GUTENBERG_EXPECTED_SHA: ${{ inputs.gutenberg-sha }}

      - name: General debug information
        run: |
          npm --version
          node --version
          curl --version
          git --version
          composer --version
          locale -a

      - name: Docker debug information
        run: |
          docker -v

      - name: Pull Docker images
        run: npm run env:pull

      - name: Start Docker environment
        run: |
          npm run env:start

      - name: Log running Docker containers
        run: docker ps -a

      - name: WordPress Docker container debug information
        run: |
          docker compose run --rm mysql "${LOCAL_DB_CMD}" --version
          docker compose run --rm php php --version
          docker compose run --rm php php -m
          docker compose run --rm php php -i
          docker compose run --rm php locale -a
        env:
          LOCAL_DB_CMD: ${{ env.LOCAL_DB_TYPE == 'mariadb' && contains( fromJSON('["5.5", "10.0", "10.1", "10.2", "10.3"]'), env.LOCAL_DB_VERSION ) && 'mysql' || env.LOCAL_DB_TYPE }}

      - name: Install WordPress
        run: npm run env:install

      # Installs PCOV as the code coverage driver for the PHPUnit run below.
      #
      # The INI directives tune PCOV for WordPress's codebase:
      # - `pcov.enabled` keeps the Zend hooks active (this is the default, but
      #   stated explicitly for clarity).
      # - `pcov.directory` restricts instrumentation to `src/`, so PCOV does not
      #   record hits for `vendor/`, `tests/`, or WordPress test fixtures that
      #   PHPUnit would discard at report time anyway.
      # - `pcov.initial.files` pre-sizes the internal file tracking array for
      #   the thousands of files under `src/`, avoiding reallocation churn
      #   during test warmup. The default of 64 is far too low here.
      - name: Install PCOV coverage driver
        if: ${{ inputs.coverage-report }}
        run: |
          docker compose exec -T -u 0 php sh -c '
            pecl install --force pcov-1.0.12 &&
            docker-php-ext-enable pcov &&
            {
              echo "pcov.enabled=1"
              echo "pcov.directory=/var/www/src"
              echo "pcov.initial.files=10000"
            } >> /usr/local/etc/php/conf.d/docker-php-ext-pcov.ini &&
            php -m | grep -i pcov
          '

      - name: Run external HTTP tests
        if: ${{ ! inputs.multisite && ! inputs.phpunit-test-groups && ! inputs.coverage-report }}
        continue-on-error: ${{ inputs.allow-errors }}
        run: node ./tools/local-env/scripts/docker.js run php ./vendor/bin/phpunit --verbose -c "${PHPUNIT_CONFIG}" --group external-http

      # PHPUnit versions used below PHP 7.3 do not support --fail-on-empty-test-suite.
      - name: Run PHPUnit tests${{ inputs.phpunit-test-groups && format( ' ({0} groups)', inputs.phpunit-test-groups ) || '' }}${{ inputs.coverage-report && ' with coverage report' || '' }}
        continue-on-error: ${{ inputs.allow-errors }}
        run: |
          node ./tools/local-env/scripts/docker.js ${{ inputs.coverage-report && 'exec' || 'run' }} \
            php ./vendor/bin/phpunit \
            --verbose \
            -c "${PHPUNIT_CONFIG}" \
            ${{ inputs.phpunit-test-groups && '--group "${TEST_GROUPS}"' || '' }} \
            ${{ inputs.phpunit-test-groups && inputs.php >= '7.3' && '--fail-on-empty-test-suite' || '' }} \
            ${{ inputs.coverage-report && '--coverage-clover "wp-code-coverage-${MULTISITE_FLAG}-${GITHUB_SHA}.xml"' || '' }}
        env:
          TEST_GROUPS: ${{ inputs.phpunit-test-groups }}
          MULTISITE_FLAG: ${{ inputs.multisite && 'multisite' || 'single' }}

      - name: Flag slow PHPUnit tests
        # Runs when the test step succeeds or fails, but skips cancelled jobs.
        # This step never fails the job itself (continue-on-error), because the
        # slow-test signal is advisory only.
        if: >-
          ${{
            ! cancelled() && inputs.report && inputs.php == '8.5' &&
            ( github.event_name == 'pull_request' ||
              ( github.event_name == 'push' && github.ref == 'refs/heads/trunk' ) )
          }}
        continue-on-error: true
        run: |
          if [ -f tests/phpunit/build/logs/junit.xml ]; then
            php tests/phpunit/prepare-slow-test-annotations.php \
              tests/phpunit/build/logs/junit.xml \
              1.0 \
              20 \
              "$RUNNER_TEMP/phpunit-timing-metrics.json"
          else
            echo 'PHPUnit JUnit report not found; skipping slow-test annotations.'
          fi

      - name: Publish PHPUnit timing metrics
        continue-on-error: true
        if: |
          github.event_name == 'push' &&
          github.ref == 'refs/heads/trunk' &&
          inputs.php == '8.5' &&
          inputs.report
        env:
          CODEVITALS_PROJECT_TOKEN: ${{ secrets.CODEVITALS_PROJECT_TOKEN }}
        shell: bash
        run: |
          if [ -z "$CODEVITALS_PROJECT_TOKEN" ]; then
            echo "PHPUnit timing metrics could not be published. 'CODEVITALS_PROJECT_TOKEN' is not set"
            exit 1
          fi
          COMMITTED_AT="$(git show -s "$GITHUB_SHA" --format='%cI')"
          RESPONSE="$(
            php tests/phpunit/prepare-timing-results.php \
              tests/phpunit/build/logs/junit.xml \
              trunk \
              "$GITHUB_SHA" \
              "$COMMITTED_AT" \
              "$RUNNER_TEMP/phpunit-timing-metrics.json" \
              | curl --fail-with-body --silent --show-error \
                --request POST \
                --header 'Content-Type: application/json' \
                --data-binary @- \
                "https://codevitals.run/api/log?token=${CODEVITALS_PROJECT_TOKEN}"
          )"
          if ! php -r "\$d = json_decode(file_get_contents('php://stdin'), true); exit(is_array(\$d) && (\$d['status'] ?? null) === 'ok' && (int) (\$d['count'] ?? 0) === 6 ? 0 : 1);" <<< "$RESPONSE"; then
            echo 'CodeVitals did not accept all six PHPUnit timing metrics.'
            exit 1
          fi
          echo 'Published six PHPUnit timing metrics to CodeVitals.'

      - name: Run AJAX tests
        if: ${{ ! inputs.phpunit-test-groups && ! inputs.coverage-report }}
        continue-on-error: ${{ inputs.allow-errors }}
        run: node ./tools/local-env/scripts/docker.js run php ./vendor/bin/phpunit --verbose -c "${PHPUNIT_CONFIG}" --group ajax

      - name: Run ms-files tests as a multisite install
        if: ${{ inputs.multisite && ! inputs.phpunit-test-groups && ! inputs.coverage-report }}
        continue-on-error: ${{ inputs.allow-errors }}
        run: node ./tools/local-env/scripts/docker.js run php ./vendor/bin/phpunit --verbose -c "${PHPUNIT_CONFIG}" --group ms-files

      # __fakegroup__ is excluded to force PHPUnit to ignore the <exclude> settings in phpunit.xml.dist.
      - name: Run (Xdebug) tests
        if: ${{ ! inputs.phpunit-test-groups && ! inputs.coverage-report }}
        continue-on-error: ${{ inputs.allow-errors }}
        run: LOCAL_PHP_XDEBUG=true node ./tools/local-env/scripts/docker.js run php ./vendor/bin/phpunit -v --group xdebug --exclude-group __fakegroup__

      - name: Upload test coverage report to Codecov
        if: ${{ inputs.coverage-report }}
        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
        with:
          token: ${{ secrets.CODECOV_TOKEN }}
          files: wp-code-coverage${{ inputs.multisite && '-multisite' || '-single' }}-${{ github.sha }}.xml
          flags: ${{ inputs.multisite && 'multisite' || 'single' }},php
          fail_ci_if_error: true

      - name: Ensure version-controlled files are not modified or deleted
        run: git diff --exit-code

      - name: Checkout the WordPress Test Reporter
        if: ${{ github.ref == 'refs/heads/trunk' && inputs.report }}
        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
        with:
          repository: 'WordPress/phpunit-test-runner'
          path: 'test-runner'
          show-progress: ${{ runner.debug == '1' && 'true' || 'false' }}
          persist-credentials: false

      - name: Submit test results to the WordPress.org host test results
        if: ${{ github.ref == 'refs/heads/trunk' && inputs.report }}
        env:
          WPT_REPORT_API_KEY: "${{ secrets.WPT_REPORT_API_KEY }}"
        run: docker compose run --rm -e WPT_REPORT_API_KEY -e WPT_PREPARE_DIR=/var/www -e WPT_TEST_DIR=/var/www -e WPT_DB_HOST=mysql -e WPT_DB_USER=root -e WPT_DB_PASSWORD=password -e WPT_DB_NAME=wordpress_develop_tests php php test-runner/report.php