Run PHPUnit integration tests in wp-env

.gitattributes

@@ -9,3 +9,6 @@ grumphp.yml export-ignore
 phpcs.xml.dist export-ignore
 /.yarn/releases/** binary
 /.yarn/plugins/** binary
+tests export-ignore
+phpunit.xml.dist export-ignore
+.wp-env.test.json export-ignore

.github/workflows/php-quality.yml

@@ -10,7 +10,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        php-versions: [ '8.3' ]
+        php-versions: [ '8.4' ]
     name: PHP ${{ matrix.php-versions }} Test
     steps:
       - name: Checkout

.github/workflows/tests-php.yml

@@ -0,0 +1,69 @@
+# yaml-language-server: $schema=https://json.schemastore.org/github-workflow
+
+name: PHP Tests
+
+on: # yamllint disable-line rule:truthy
+  workflow_dispatch:
+  pull_request:
+    branches: [ master ]
+    paths:
+      - '**/*.php'
+      - 'tests/**'
+      - 'composer.json'
+      - 'package.json'
+      - 'package-lock.json'
+      - 'phpunit.xml.dist'
+      - '.wp-env.test.json'
+      - '.github/workflows/tests-php.yml'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test-php:
+    name: PHPUnit - WP ${{ matrix.core || 'latest' }} / PHP ${{ matrix.php }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        php: [ '8.4' ]
+        # Minimum supported WordPress (style.css "Requires at least") and latest stable.
+        core: [ 'WordPress/WordPress#6.3', null ]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v7
+        with:
+          node-version-file: package.json
+          cache: npm
+
+      - name: Install npm dependencies
+        run: npm ci
+
+      - name: Set up PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          coverage: none
+
+      - name: Install Composer dependencies
+        run: composer install --no-interaction --prefer-dist
+
+      - name: Check platform requirements
+        run: composer check-platform-reqs
+
+      - name: Launch test environment
+        env:
+          WP_ENV_PHP_VERSION: ${{ matrix.php }}
+          WP_ENV_CORE: ${{ matrix.core }}
+        run: npm run env:start-ci
+
+      - name: Run PHPUnit
+        run: npm run test:php

.gitignore

@@ -91,3 +91,7 @@ theme.json
 
 ### Composer
 composer.lock
+
+### Tests
+.phpunit.result.cache
+/coverage/

.wp-env.json

@@ -1,7 +1,7 @@
 {
 	"$schema": "https://schemas.wp.org/trunk/wp-env.json",
 	"core": null,
-	"phpVersion": "8.3",
+	"phpVersion": "8.4",
 	"testsEnvironment": false,
 	"themes": [
 		"."

.wp-env.test.json

@@ -0,0 +1,16 @@
+{
+	"$schema": "https://schemas.wp.org/trunk/wp-env.json",
+	"core": null,
+	"phpVersion": "8.4",
+	"testsEnvironment": false,
+	"port": 8889,
+	"themes": [
+		"."
+	],
+	"plugins": [
+		".wp-env/plugins/advanced-custom-fields"
+	],
+	"lifecycleScripts": {
+		"afterStart": "./tests/bin/initialize.sh --config=./.wp-env.test.json"
+	}
+}

README.md

@@ -12,7 +12,7 @@
 
 ### PHP et WordPress
 
-- PHP **8.3** ou supérieur
+- PHP **8.4** ou supérieur
 - WordPress **6.3** ou supérieur
 
 ### Composer
@@ -107,7 +107,7 @@ wp-env start
 
 Au premier démarrage, wp-env va :
 
-- Démarrer WordPress (PHP 8.3)
+- Démarrer WordPress (PHP 8.4)
 - Monter ce thème depuis le répertoire courant
 - Installer et activer l’extension [Advanced Custom Fields](https://wordpress.org/plugins/advanced-custom-fields/)
 
@@ -151,6 +151,38 @@ yarn start
 
 Les changements sur les assets PHP, SCSS et JavaScript sont pris en compte après rebuild Webpack. Les modifications PHP du thème sont appliquées immédiatement grâce au volume monté.
 
+## Tests PHP
+
+Les tests PHPUnit (`tests/php/`) sont des tests d’intégration : ils s’exécutent dans un WordPress réel fourni par wp-env, avec le thème actif et ACF chargé (`WP_UnitTestCase`, bibliothèque de tests de WordPress).
+
+Ils utilisent un environnement dédié (`.wp-env.test.json`, port 8889, PHP 8.4), isolé de l’environnement de développement, et leurs propres tables (`wptests_`).
+
+```bash
+composer install
+npm install
+
+# Démarrer l’environnement de test (avec Xdebug pour la couverture)
+npm run env:start-tests
+# ou, sans couverture : npm run env:start-ci
+
+# Lancer les tests
+npm run test:php
+
+# Lancer un seul fichier ou un seul test
+npm run test:php -- tests/php/Services/AssetsTest.php
+npm run test:php -- --filter test_theme_is_active
+
+# Générer le rapport de couverture (coverage/index.html)
+npm run test:php -- --coverage-html=coverage/ --coverage-text
+
+# Arrêter l’environnement de test
+npm run env:stop-tests
+```
+
+Les tests ne dépendent pas du dossier `dist/` : les fichiers attendus sont fournis par les fixtures de `tests/assets/` via les filtres `theme_file_path` / `theme_file_uri`.
+
+En CI, le workflow `.github/workflows/tests-php.yml` lance la suite sur la version minimale de WordPress supportée et sur la dernière version stable.
+
 ## Configuration
 
 Les fichiers de configuration se trouvent dans le dossier `config`.

composer.json

@@ -24,7 +24,9 @@
         "phpro/grumphp-shim": "^2.6",
         "roave/security-advisories": "dev-latest",
         "wp-coding-standards/wpcs": "3.4.1",
-        "wp-plugin/advanced-custom-fields": "6.8.4"
+        "wp-plugin/advanced-custom-fields": "6.8.4",
+        "phpunit/phpunit": "9.6.38",
+        "yoast/phpunit-polyfills": "4.0.0"
     },
     "scripts": {
         "cs": [
@@ -46,7 +48,7 @@
             "composer/installers": true
         },
         "platform": {
-            "php": "8.3.99"
+            "php": "8.4.99"
         }
     }
 }