Tests automatisés PHP existant : PHPUnit à CI/CD

Le problème concret

Vous rencontrez une suite PHPUnit qui tourne en local mais qui n’est jamais exécutée automatiquement sur votre pipeline CI/CD — chaque merge en production est un pari sur Linux Ubuntu 22.04 / PHP 8.3.

À retenir immédiatement

« Branchez PHPUnit sur votre pipeline CI/CD : chaque push déclenche vos tests automatiquement. »

📋 Prérequis techniques

| Prérequis | Statut |
|———–|——–|
| PHP 8.2+ + Composer 2.x | ✅ Vérifié |
| PHPUnit 11.x (via `phpunit/phpunit`) | ✅ Vérifié |
| Accès en écriture au repo (secrets GitHub / GitLab) | ❌ À configurer |

Étape 1 : Structurer le projet pour la CI

1. Vérifier que phpunit/phpunit est dans require-dev de votre composer.json, pas dans require.
2. Créer ou mettre à jour le fichier phpunit.xml à la racine du projet :

<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
         bootstrap="vendor/autoload.php"
         cacheDirectory=".phpunit.cache">
    <testsuites>
        <testsuite name="Application Test Suite">
            <directory>tests</directory>
        </testsuite>
    </testsuites>
    <source>
        <include>
            <directory>src</directory>
        </include>
    </source>
</phpunit>

3. Valider en local : ./vendor/bin/phpunit --testdox — résultat attendu : OK (42 tests, 138 assertions)

Étape 2 : Créer le workflow GitHub Actions

4. Créer le dossier .github/workflows/ à la racine du projet.
5. Créer le fichier ci.yml avec le contenu suivant :

name: PHPUnit Tests

on:
  push:
    branches: [ "main", "develop" ]
  pull_request:
    branches: [ "main" ]

jobs:
  tests:
    runs-on: ubuntu-latest

    strategy:
      matrix:
        php-version: ["8.2", "8.3"]

    steps:
      - uses: actions/checkout@v4

      - name: Setup PHP ${{ matrix.php-version }}
        uses: shivammathur/setup-php@v2
        with:
          php-version: ${{ matrix.php-version }}
          extensions: mbstring, xml, pdo, sqlite3
          coverage: xdebug

      - name: Cache Composer packages
        uses: actions/cache@v4
        with:
          path: vendor
          key: ${{ runner.os }}-php-${{ hashFiles('**/composer.lock') }}

      - name: Install dependencies
        run: composer install --no-progress --prefer-dist --optimize-autoloader

      - name: Run PHPUnit tests
        run: ./vendor/bin/phpunit --coverage-text --log-junit reports/junit.xml

      - name: Upload test results
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: test-results-php${{ matrix.php-version }}
          path: reports/junit.xml

6. Pousser la branche : git add .github/workflows/ci.yml && git commit -m "ci: add PHPUnit pipeline" && git push

Dépannage : 3 problèmes fréquents

### Problème 1 : `Class not found` en CI mais pas en local

• Le composer.json n’a pas d’autoload PSR-4 configuré pour tests/ — vérifier la section "autoload-dev".
• Terminal : composer dump-autoload --optimize puis relancer la CI.

### Problème 2 : Tests SQLite qui échouent

• Extension sqlite3 absente du workflow — ajouter sqlite3 dans le champ extensions: de setup-php.
• Utiliser une base en mémoire dans phpunit.xml : <env name="DB_CONNECTION" value="sqlite"/> dans le bloc <php>.

### Problème 3 : Coverage Xdebug fait timeout

• Remplacer coverage: xdebug par coverage: pcov dans setup-php — 5× plus rapide sur les gros projets.
• Commande alternative : XDEBUG_MODE=coverage ./vendor/bin/phpunit --coverage-clover coverage.xml

💡 Astuces pro

• Raccourci local : ajouter "test": "./vendor/bin/phpunit" dans les scripts composer.json — lancer avec composer test.
• Bloquer le merge si la couverture descend sous 80% : option --coverage-min 80 native PHPUnit 11.
• Afficher le résumé des tests directement dans les PR GitHub avec l’action EnricoMi/publish-unit-test-result-action.

Bonus : Équivalent GitLab CI

Si votre équipe utilise GitLab, créez le fichier .gitlab-ci.yml à la racine. Le champ artifacts.reports.junit active l’affichage natif des résultats dans l’onglet Tests du pipeline GitLab — aucun plugin tiers nécessaire.

phpunit:
  image: php:8.3-cli
  before_script:
    - apt-get update && apt-get install -y unzip git
    - curl -sS https://getcomposer.org/installer | php
    - php composer.phar install --no-progress
  script:
    - ./vendor/bin/phpunit --log-junit reports/junit.xml
  artifacts:
    reports:
      junit: reports/junit.xml