test: characterization suite for every feature and SVG source

.distignore

@@ -17,6 +17,7 @@
 grumphp.yml
 phpcs.xml.dist
 phpunit.xml.dist
+wp-tests-config.php
 psalm.xml.dist
 
 # Dependency management

.github/workflows/test-php.yml

@@ -0,0 +1,75 @@
+name: PHP Tests
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+      - develop
+
+# Cancels all previous workflow runs for pull requests that have not completed.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event_name == 'pull_request' && github.head_ref || github.sha }}
+  cancel-in-progress: true
+
+jobs:
+  phpunit:
+    name: PHPUnit (PHP ${{ matrix.php }})
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        # The full range the plugin declares support for. wp-env selects the PHP
+        # version through WP_ENV_PHP_VERSION, which picks the matching upstream
+        # `wordpress:php8.x` image.
+        php: [ '8.1', '8.2', '8.3', '8.4' ]
+
+    env:
+      # Keep off 8888/8889 for no reason other than matching the documented local setup.
+      WP_ENV_PORT: 8890
+      WP_ENV_TESTS_PORT: 8891
+      WP_ENV_PHP_VERSION: ${{ matrix.php }}
+
+    steps:
+      - name: Checkout project
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install npm dependencies
+        run: npm ci
+
+      # The plugin calls register_block_type() on its build/ directory. build/ is
+      # git-ignored, so without this the block never registers and every rendering
+      # test receives an empty string.
+      - name: Build block assets
+        run: npm run build
+
+      - name: Setup Composer
+        run: |
+          composer config --global http-basic.composer.beapi.fr ${{ secrets.COMPOSER_USER }} ${{ secrets.COMPOSER_PASS }}
+          composer config --global http-basic.packages.beapi.fr ${{ secrets.COMPOSER_USER }} ${{ secrets.COMPOSER_PASS }}
+
+      # Installed on the host: the plugin directory is mounted into the wp-env
+      # containers, so vendor/ is visible from inside them. The platform pin in
+      # composer.json keeps resolution identical across the matrix.
+      - name: Install composer dependencies
+        run: composer install --no-interaction --no-progress
+
+      # Supplies WordPress, the WordPress PHPUnit library and a database, so there
+      # is no wp-tests-config.php to hand-roll and the suite runs exactly the way
+      # it does locally.
+      - name: Start wp-env
+        run: npx wp-env start
+
+      - name: Run PHPUnit
+        run: npm run test:php
+
+      - name: Show wp-env logs on failure
+        if: failure()
+        run: npx wp-env logs tests --no-watch

.gitignore

@@ -36,3 +36,8 @@ build/
 .DS_Store
 .nvmrc
 phpcs.xml
+
+# PHPUnit: a local test configuration is per-machine (see tests/wp-tests-config-sample.php)
+/wp-tests-config.php
+/phpunit.xml
+/.phpunit.result.cache

CHANGELOG.md

@@ -6,6 +6,11 @@ This plugin **doesn't run any sanitization on SVGs** before using them. Only use
 
 ## Changelog
 
+### Unreleased
+
+- Add a PHPUnit integration test suite covering every SVG source (folder, sprite, single file), the collection container, the registration API, front-end block rendering, both REST controllers, the object-cache wrapper and the KSES allowances — 176 tests. See `tests/README.md`
+- Run the suite in CI on PHP 8.1 through 8.4
+
 ### 1.1.1 - 2026-08-26
 
 - Fix deprecated warning for nullable string parameters in `CollectionItem`

composer.json

@@ -59,10 +59,13 @@
 		"php-parallel-lint/php-parallel-lint": "^1.3",
 		"phpcompatibility/phpcompatibility-wp": "^2.1",
 		"phpro/grumphp-shim": "^1.5",
+		"phpunit/phpunit": "^9.6",
 		"roave/security-advisories": "dev-latest",
 		"roots/wordpress-no-content": "^6.0",
 		"vimeo/psalm": "^5.20",
-		"wp-coding-standards/wpcs": "^3.0"
+		"wp-coding-standards/wpcs": "^3.0",
+		"wp-phpunit/wp-phpunit": "^6.4",
+		"yoast/phpunit-polyfills": "^2.0"
 	},
 	"autoload": {
 		"psr-4": {
@@ -72,7 +75,8 @@
 	"scripts": {
 		"cs": "./vendor/bin/phpcs",
 		"cb": "./vendor/bin/phpcbf",
-		"psalm": "./vendor/bin/psalm"
+		"psalm": "./vendor/bin/psalm",
+		"test": "./vendor/bin/phpunit"
 	},
 	"scripts-descriptions": {
 		"cs": "Run PHP CodeSniffer on codebase using custom ruleset.",