reusable-phpunit-tests-v2.yml

##
# DEPRECATED
#
# A reusable workflow that runs the PHPUnit test suite with the specified configuration.
#
# This workflow is used by branches 5.2 through 5.8.
##
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: ''
      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'
      multisite:
        description: 'Whether to run tests as multisite'
        required: false
        type: 'boolean'
        default: false
      split_slow:
        description: 'Whether to run slow tests group.'
        required: false
        type: 'boolean'
        default: false
      test_ajax:
        description: 'Whether to run AJAX tests.'
        required: false
        type: 'boolean'
        default: true
      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: ''
      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
      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: ''
env:
  LOCAL_PHP: ${{ inputs.php }}-fpm
  LOCAL_PHP_MEMCACHED: ${{ inputs.memcached }}
  PHPUNIT_CONFIG: ${{ inputs.phpunit-config }}
  PUPPETEER_SKIP_DOWNLOAD: true
  # Controls which npm script to use for running PHPUnit tests. Options ar `php` and `php-composer`.
  PHPUNIT_SCRIPT: php
  SLOW_TESTS: 'external-http,media'

# 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:
  # - Sets environment variables.
  # - Checks out the repository.
  # - Installs Node.js.
  # - Installs npm dependencies
  # - Configures caching for Composer.
  # - Installs Composer dependencies.
  # - Logs Docker debug information (about the Docker installation within the runner).
  # - Starts the WordPress Docker container.
  # - Logs general debug information about the runner.
  # - Logs the running Docker containers.
  # - Logs debug information from inside the WordPress Docker container.
  # - Install WordPress within the Docker container.
  # - Run the PHPUnit tests.
  # - Ensures version-controlled files are not modified or deleted.
  test-php:
    name: PHP ${{ inputs.php }} / ${{ inputs.multisite && ' Multisite' || 'Single Site' }}${{ inputs.split_slow && ' slow tests' || '' }}${{ inputs.memcached && ' with memcached' || '' }}
    runs-on: ${{ vars.RUNNERS_NAME || inputs.os }}
    timeout-minutes: 20
    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

      # Legacy docker.js reparses arguments as shell: allow only group names.
      - name: Validate test groups
        if: ${{ inputs.phpunit-test-groups != '' }}
        env:
          TEST_GROUPS: ${{ inputs.phpunit-test-groups }}
        run: |
          if [[ ! "$TEST_GROUPS" =~ ^[A-Za-z0-9_.-]+(,[A-Za-z0-9_.-]+)*$ ]]; then
            echo 'phpunit-test-groups must be a comma-separated list of group names.' >&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

      - name: Install Node.js
        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
        with:
          node-version-file: '.nvmrc'
          cache: npm

      - name: Install npm dependencies
        run: npm ci

      - name: Get composer cache directory
        id: composer-cache
        run: echo "composer_dir=$(composer config cache-files-dir)" >> "$GITHUB_OUTPUT"

      - name: Cache Composer dependencies
        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
        env:
          cache-name: cache-composer-dependencies
        with:
          path: ${{ steps.composer-cache.outputs.composer_dir }}
          key: ${{ runner.os }}-php-${{ inputs.php }}-composer-${{ hashFiles('**/composer.lock') }}

      - name: Install Composer dependencies
        run: |
          docker compose run --rm php composer --version

          # The PHPUnit 7.x phar is not compatible with PHP 8 and won't be updated,
          # as PHPUnit 7 is no longer supported. The Composer-installed PHPUnit should be
          # used for PHP 8 testing instead.
          if [ "${LOCAL_PHP}" == '8.0-fpm' ]; then
            docker compose run --rm php composer install --ignore-platform-reqs
            echo "PHPUNIT_SCRIPT=php-composer" >> "$GITHUB_ENV"
          elif [ "${LOCAL_PHP}" == '7.1-fpm' ]; then
            docker compose run --rm php composer update
            git checkout -- composer.lock
          elif [[ "${LOCAL_PHP}" == '5.6-fpm' || "${LOCAL_PHP}" == '7.0-fpm' ]]; then
            docker compose run --rm php composer require --dev phpunit/phpunit:"^5.7" --update-with-dependencies
            git checkout -- composer.lock composer.json
          else
            docker compose run --rm php composer install
          fi

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

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

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

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

      - name: WordPress Docker container debug information
        run: |
          docker compose run --rm mysql mysql --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

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

      - name: Run slow PHPUnit tests
        if: ${{ inputs.split_slow && ! inputs.phpunit-test-groups }}
        run: npm run "test:${PHPUNIT_SCRIPT}" -- --verbose -c "${PHPUNIT_CONFIG}" --group "${SLOW_TESTS}"

      - name: Run PHPUnit tests for single site excluding slow tests
        if: ${{ inputs.php < '7.0' && ! inputs.split_slow && ! inputs.multisite && ! inputs.phpunit-test-groups }}
        run: npm run "test:${PHPUNIT_SCRIPT}" -- --verbose -c "${PHPUNIT_CONFIG}" --exclude-group "${SLOW_TESTS},ajax,ms-files,ms-required"

      - name: Run PHPUnit tests for Multisite excluding slow tests
        if: ${{ inputs.php < '7.0' && ! inputs.split_slow && inputs.multisite && ! inputs.phpunit-test-groups }}
        run: npm run "test:${PHPUNIT_SCRIPT}" -- --verbose -c "${PHPUNIT_CONFIG}" --exclude-group "${SLOW_TESTS},ajax,ms-files,ms-excluded,oembed-headers"

      - name: Run PHPUnit tests
        if: ${{ inputs.php >= '7.0' || inputs.phpunit-test-groups }}
        run: npm run "test:${PHPUNIT_SCRIPT}" -- --verbose -c "${PHPUNIT_CONFIG}" ${{ inputs.phpunit-test-groups && '--group "${TEST_GROUPS}"' || '' }}
        env:
          TEST_GROUPS: ${{ inputs.phpunit-test-groups }}

      - name: Run AJAX tests
        if: ${{ ! inputs.split_slow&& inputs.test_ajax && ! inputs.phpunit-test-groups }}
        run: npm run "test:${PHPUNIT_SCRIPT}" -- --verbose -c "${PHPUNIT_CONFIG}" --group ajax

      - name: Run ms-files tests as a multisite install
        if: ${{ inputs.multisite && ! inputs.split_slow && ! inputs.phpunit-test-groups }}
        run: npm run "test:${PHPUNIT_SCRIPT}" -- --verbose -c "${PHPUNIT_CONFIG}" --group ms-files

      - name: Run external HTTP tests
        if: ${{ ! inputs.multisite && ! inputs.split_slow && ! inputs.phpunit-test-groups }}
        run: npm run "test:${PHPUNIT_SCRIPT}" -- --verbose -c phpunit.xml.dist --group external-http

      # __fakegroup__ is excluded to force PHPUnit to ignore the <exclude> settings in phpunit.xml.dist.
      - name: Run (xDebug) tests
        if: ${{ ! inputs.split_slow && ! inputs.phpunit-test-groups }}
        run: LOCAL_PHP_XDEBUG=true npm run "test:${PHPUNIT_SCRIPT}" -- -v --group xdebug --exclude-group __fakegroup__

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