test: characterization suite for every feature and SVG source

[herewithme]

Why

The plugin had no tests. This adds them before the performance work in #42 lands, so that PR can be rebased on top and shown not to change behaviour — rather than asserted not to.

Written against develop as it stands today: 176 tests, 427 assertions, all green on the unmodified plugin.

These are characterization tests

They assert observable behaviour — how many icons come back, with what names, labels, types and contents, and what markup reaches a page — and say nothing about when or how often files are read.

That is the whole design point. A change that alters only the mechanism (lazy loading, different cache keys, a new source type) leaves the suite green. A change that alters what a caller can see does not. That is what makes it a regression net for #42 rather than a cast of the current implementation.

Coverage

file	subject
Icon/CollectionItemsFactoryTest.php	every SVG source: folder, sprite, single file
Icon/CollectionTest.php	the container: lookup, dotted-name keys, count, search
Icon/CollectionItemTest.php	a single icon, and what survives the object cache
BlockRendererTest.php	front-end markup, in full
RegistrationTest.php	the public API a theme calls, plus editor preload paths
Rest/CollectionsControllerTest.php	collection discovery and its permissions
Rest/IconsControllerTest.php	listing, pagination, search, single item, permissions
Helpers/CacheTest.php	the object-cache wrapper every source goes through
Helpers/KsesTest.php	the KSES allowances that keep saved block markup valid

Worth calling out specifically:

• Every SVG source, including icon_map labels, sprite version cache-busting, the public URL a sprite icon resolves to, empty files, unreadable paths, non-SVG files being ignored, and the blockparty_icons_svg_parse_tags filter.
• All colour formats the renderer accepts (hex, short hex, var:preset|color|x, var(--x), var(--x, #fff)) and the ones it must reject (named colours, rgb(), javascript:, expression(), a quote-break injection attempt).
• Permissions at every role on both REST endpoints — anonymous 401, subscriber 403, editor 200.
• That <script> inside an SVG is still stripped by KSES despite the plugin's allowances.
• That an empty cached result is a hit, not a miss — the distinction the factories depend on.

Infrastructure

Integration tests against a real WordPress, not mocks: the plugin leans on WP_Query, the object cache, WP_HTML_Tag_Processor, WP_REST_Controller and a set of filters, and mocking that surface would test the mocks.

Two ways to run, both verified:

# through wp-env, which supplies WordPress, the test library and a database
WP_ENV_PORT=8890 WP_ENV_TESTS_PORT=8891 npx wp-env start
npm run test:php

# anywhere else, against the Composer copy of WordPress — the path CI takes
cp tests/wp-tests-config-sample.php wp-tests-config.php   # then edit credentials
composer test

CI runs the suite on PHP 8.1, 8.2, 8.3 and 8.4 (.github/workflows/test-php.yml).

Findings

Three things surfaced while writing this. None is caused by these tests; all are recorded in tests/README.md.

1. Collection's Iterator never yields anything. It walks an integer $position while add() keys items by name, so valid() asks for $items[0], which never exists — foreach over a populated collection yields nothing. Nothing in the plugin iterates a collection (every caller uses all()), so it is latent. test_known_defect_iteration_yields_nothing_even_when_populated records it and will fail when someone fixes it; update that test then rather than deleting it.

2. BlockRenderer::render() cannot be called outside a block render pass on PHP 8.4. It calls get_block_wrapper_attributes(), which reads WP_Block_Supports::$block_to_render; that is null outside a render pass and PHP 8.4 warns. The tests go through render_block() instead, which is both closer to reality and warning-free. Not a plugin bug — real rendering always has that context — but worth knowing if anyone calls the renderer directly.

3. The development-mode cache bypass is not coverable from a plugin suite. WordPress resolves wp_is_development_mode() from a constant behind a static cache and only lets its own core suite vary it. The suite therefore runs with caching active, which is the production path anyway.

For the reviewer

• composer.json gained phpunit/phpunit ^9.6, yoast/phpunit-polyfills and wp-phpunit/wp-phpunit as dev dependencies. Resolving them needed -W, which moved some sebastian/* versions; Psalm still reports the same 221 errors as before and phpcs is clean, so the toolchain is unaffected.
• PHPUnit 9.6 rather than 10, because the WordPress core test suite still requires 9.x.
• wp-tests-config.php is git-ignored (it holds credentials and machine paths); a sample lives at tests/wp-tests-config-sample.php.
• tests/ is excluded from releases already, via the existing /tests entry in .distignore.
• Note for rebasing perf(icons): load SVG payloads on demand, and add a benchmark to prove it #42: that branch excludes ./tests/ from phpcs.xml.dist for its perf harness, which would also stop linting these test files. Narrow it to ./tests/perf/ on rebase — the PHPUnit suite is phpcs-clean and should stay that way.

Next

Once this is in, #42 rebases onto it. Any behaviour the optimisation changes will show up as a failing test.

🤖 Generated with Claude Code

---

Note

Low Risk
Adds tests and CI only; production plugin code is unchanged, so runtime risk is minimal aside from new dev dependencies and workflow secrets for private Composer repos.

Overview
Introduces a PHPUnit integration test suite (~176 tests) that runs against a real WordPress install via wp-env or Composer + wp-tests-config.php, documented in tests/README.md.

The tests are characterization-style: they lock in observable behaviour for icon loading (folder, sprite, single file), collections, registration APIs, block front-end rendering (including colour validation and escaping), both REST controllers, object-cache helpers, and KSES allowances. Shared fixtures and isolation live in tests/phpunit/TestCase.php; bootstrap enforces compiled build/block.json before rendering tests run.

Tooling and CI: dev dependencies add PHPUnit 9.6, wp-phpunit, and polyfills; composer test and npm run test:php (via tests/bin/phpunit.sh in the wp-env CLI container) run the suite. A new .github/workflows/test-php.yml matrix runs on PHP 8.1–8.4 (build assets, composer install, wp-env start, then PHPUnit). Local PHPUnit config paths are git-ignored; wp-tests-config.php is excluded from dist builds.

^{Reviewed by Cursor Bugbot for commit fc07015. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 6bbf18d. Configure here.}