test: add test workflow support and initial tests

.github/workflows/ci.yml

@@ -35,3 +35,6 @@ jobs:
 
       - name: Lint PHP
         run: composer lint
+
+      - name: Run tests
+        run: composer test

.github/workflows/plugin-ci.yml

@@ -27,6 +27,9 @@ on:
       bun-lint-command:
         type: string
         default: ''
+      test-command:
+        type: string
+        default: ''
       build-command:
         type: string
         default: ''
@@ -86,6 +89,12 @@ jobs:
           BUN_LINT_COMMAND: ${{ inputs.bun-lint-command }}
         run: eval "$BUN_LINT_COMMAND"
 
+      - name: Run tests
+        if: ${{ inputs.test-command != '' }}
+        env:
+          TEST_COMMAND: ${{ inputs.test-command }}
+        run: eval "$TEST_COMMAND"
+
       - name: Build assets
         if: ${{ inputs.build-command != '' }}
         env:

.github/workflows/plugin-release.yml

@@ -36,6 +36,9 @@ on:
       bun-lint-command:
         type: string
         default: ''
+      test-command:
+        type: string
+        default: ''
       build-command:
         type: string
         default: ''
@@ -129,6 +132,12 @@ jobs:
           BUN_LINT_COMMAND: ${{ inputs.bun-lint-command }}
         run: eval "$BUN_LINT_COMMAND"
 
+      - name: Run tests
+        if: ${{ inputs.test-command != '' }}
+        env:
+          TEST_COMMAND: ${{ inputs.test-command }}
+        run: eval "$TEST_COMMAND"
+
       - name: Verify tag matches plugin version
         env:
           PLUGIN_FILE: ${{ inputs.plugin-file }}
@@ -227,12 +236,22 @@ jobs:
 
           unzip -p "$zip_file" "$PLUGIN_SLUG/$PLUGIN_FILE" | grep -qE "^[[:space:]]*\\*[[:space:]]+Version:[[:space:]]+$version$"
 
-          for forbidden in .git .github node_modules vendor composer.json composer.lock package.json package-lock.json bun.lock phpcs.xml; do
-            ! grep -qE "^$PLUGIN_SLUG/$forbidden(/|$)" "$entries_file"
+          for forbidden in .git .github .gitignore .distignore .phpcs-cache .phpunit.cache .phpunit.result.cache node_modules vendor tests scripts stubs composer.json composer.lock package.json package-lock.json bun.lock phpcs.xml phpstan.neon.dist phpunit.xml phpunit.xml.dist AGENTS.md CLAUDE.md CONTRIBUTING.md README.md SECURITY.md; do
+            while IFS= read -r entry; do
+              if [ "$entry" = "$PLUGIN_SLUG/$forbidden" ] || [[ "$entry" == "$PLUGIN_SLUG/$forbidden/"* ]]; then
+                echo "Forbidden release file found: $entry"
+                exit 1
+              fi
+            done < "$entries_file"
           done
 
           if [ "${{ inputs.exclude-src }}" = "true" ]; then
-            ! grep -qE "^$PLUGIN_SLUG/src/" "$entries_file"
+            while IFS= read -r entry; do
+              if [[ "$entry" == "$PLUGIN_SLUG/src/"* ]]; then
+                echo "Forbidden source file found: $entry"
+                exit 1
+              fi
+            done < "$entries_file"
           fi
 
       - name: Upload release zip artifact

.gitignore

@@ -1,4 +1,5 @@
 vendor/
 .phpcs-cache
 .phpstan.cache/
+.phpunit.cache/
 .DS_Store

AGENTS.md

@@ -7,7 +7,7 @@ Agent guidance for this repository. Keep this file focused on non-obvious workfl
 - This repo is public. Do not add credentials, tokens, site-specific hostnames, or private deployment details.
 - Keep plugin-specific behavior in caller repos unless it is truly reusable across the WPVDB plugin suite.
 - Prefer adding workflow inputs over hardcoding one plugin's layout into a reusable workflow.
-- Do not add static analysis just for these helper scripts without a concrete failure mode. The current local check surface consists of Composer and PHPCS.
+- Do not add static analysis just for these helper scripts without a concrete failure mode. The current local check surface consists of Composer, PHPCS, and PHPUnit.
 
 ## Reusable workflow gotchas
 

README.md

@@ -20,7 +20,7 @@ The workflows cover plugin checks and release zip creation. Plugin repositories
 | Workflow | Type | Purpose |
 |---|---|---|
 | `ci.yml` | Repository workflow | Validates `wpvdb-scripts` itself. |
-| `plugin-ci.yml` | Reusable workflow | Runs plugin Composer, Bun, lint, analysis, and build commands. |
+| `plugin-ci.yml` | Reusable workflow | Runs plugin Composer, Bun, lint, analysis, test, and build commands. |
 | `plugin-maintain-main.yml` | Reusable workflow | Bumps plugin versions, regenerates generated plugin files on `main`, and commits them when needed. |
 | `plugin-release.yml` | Reusable workflow | Builds a plugin release zip from a tag and uploads it to GitHub Releases. |
 
@@ -34,6 +34,7 @@ Plugin repositories should call these workflows from thin repo local workflows.
 - List every path the maintenance workflow may commit in `commit-paths`. It defaults to `languages/`.
 - Pass `version-bump: true` when a plugin should bump versions from conventional commits on `main`.
 - Pass the plugin file and any extra version surfaces, such as `version-constant`, `package-file`, `pot-file`, `pot-project`, or `block-json-glob`.
+- Pass `test-command` when a plugin has a local unit test command that should run in CI and release checks. Tests run before `build-command`, so the command should build any artifacts it depends on.
 - Build block plugins before i18n when they generate JavaScript translation JSON.
 - Track `languages/source-map.json` for block plugins that call `wp i18n make-json --use-map`, but exclude it from release zips with `.distignore`.
 - Tag releases only after the maintenance commit has landed on `main`. Commits made by the built in `GITHUB_TOKEN` do not trigger another workflow run, so the release workflow reruns i18n and fails if generated files drift.
@@ -54,6 +55,7 @@ Version bump mapping:
 | `scripts/bump-plugin-version.php` | Updates a plugin header, optional version constant, optional `package.json`, optional POT header, and optional block metadata versions. |
 | `.github/actions/bump-plugin-version/action.yml` | Composite action wrapper for `scripts/bump-plugin-version.php`. |
 | `i18n-command` workflow input | Runs plugin owned i18n generation during maintenance and release workflows. |
+| `test-command` workflow input | Runs caller owned tests during CI and release workflows. |
 
 The bump script can also be run directly with environment variables:
 
@@ -77,4 +79,5 @@ Run the local checks:
 
 ```bash
 composer lint
+composer test
 ```

composer.json

@@ -10,14 +10,19 @@
 		"automattic/vipwpcs": "^3.0",
 		"dealerdirect/phpcodesniffer-composer-installer": "*",
 		"phpcompatibility/phpcompatibility-wp": "*",
+		"phpunit/phpunit": "^12.0",
 		"squizlabs/php_codesniffer": "^3.13",
 		"wp-coding-standards/wpcs": "^3.0"
 	},
 	"scripts": {
 		"lint": "phpcs",
+		"test": "phpunit",
 		"lint:fix": "phpcbf"
 	},
 	"config": {
+		"platform": {
+			"php": "8.3.0"
+		},
 		"allow-plugins": {
 			"dealerdirect/phpcodesniffer-composer-installer": true
 		}