test: add unit test harness and initial tests

.distignore

@@ -7,13 +7,17 @@
 .DS_Store
 Thumbs.db
 .phpcs-cache
+.phpunit.cache
+.phpunit.result.cache
 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
@@ -30,5 +34,6 @@ release
 scripts
 src
 stubs
+tests
 vendor
 node_modules

.github/workflows/ci.yml

@@ -19,4 +19,5 @@ jobs:
       bun-install: true
       php-analyze-command: composer analyze
       bun-lint-command: bun run lint
+      test-command: bun run test
       build-command: bun run build

.github/workflows/release.yml

@@ -25,6 +25,7 @@ jobs:
       bun-install: true
       php-analyze-command: composer analyze
       bun-lint-command: bun run lint
+      test-command: bun run test
       build-command: bun run build
       i18n-command: bun run i18n
       required-artifacts: |

.gitignore

@@ -5,3 +5,4 @@ vendor/
 build/
 release/
 .phpcs-cache
+.phpunit.cache/

.hooks/pre-commit

@@ -2,7 +2,7 @@
 set -eu
 
 staged_files="$(git diff --cached --name-only --diff-filter=ACMR)"
-js_files="$(printf '%s\n' "$staged_files" | grep -E '^src/.*\.(js|jsx)$' || true)"
+js_files="$(printf '%s\n' "$staged_files" | grep -E '^(src/.*\.(js|jsx)|scripts/.*\.m?js)$' || true)"
 scss_files="$(printf '%s\n' "$staged_files" | grep -E '^src/.*\.scss$' || true)"
 
 if printf '%s\n' "$staged_files" | grep -E '\.php$' >/dev/null 2>&1; then

AGENTS.md

@@ -32,4 +32,4 @@ Agent guidance for this repository. Keep this file focused on non-obvious block,
 - Build and lint commands are defined in `package.json` and `composer.json`; prefer those scripts.
 - `stubs/wpvdb-search.stub.php` is for static analysis only. Do not load it at runtime.
 - If adding another block, check the source map generator, release the required artifacts, and add a block registration fallback in the same change.
-- Unit test coverage is still backlog work. When adding it, start with block rendering, search argument mapping, and i18n source map generation.
+- Unit tests cover block rendering and the i18n source map generator. Extend those tests when render output, search argument mapping, or source map behavior changes.

README.md

@@ -46,6 +46,7 @@ Run the local checks:
 ```bash
 bun run lint
 bun run analyze
+bun run test
 ```
 
 The main branch maintenance workflow regenerates translation files and commits them when strings change. This plugin also has block editor JavaScript, so the i18n task rebuilds `languages/source-map.json` and refreshes the hashed JSON files WordPress uses for script translations. Release workflows regenerate translations before staging the zip and fail if generated files are out of date.

composer.json

@@ -21,6 +21,7 @@
 		"automattic/vipwpcs": "^3.0",
 		"dealerdirect/phpcodesniffer-composer-installer": "*",
 		"phpcompatibility/phpcompatibility-wp": "*",
+		"phpunit/phpunit": "^12.0",
 		"phpstan/extension-installer": "^1.4",
 		"phpstan/phpstan": "^2.1",
 		"szepeviktor/phpstan-wordpress": "^2.0",
@@ -30,6 +31,7 @@
 	"scripts": {
 		"lint": "./vendor/bin/phpcs",
 		"analyze": "./vendor/bin/phpstan analyze --memory-limit=512M",
+		"test": "./vendor/bin/phpunit",
 		"fix": "./vendor/bin/phpcbf",
 		"post-install-cmd": [
 			"vendor/bin/cghooks add --no-lock"