bd-companion-plugin
Work on better-data-plugin-test — the companion plugin
Lonsdale201 · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add Lonsdale201/wp-agent-skills --skill bd-companion-pluginAbout this skill
name: bd-companion-plugin description: Work on better-data-plugin-test — the companion plugin that exercises the better-data library against a live WordPress install. Plugin is intentionally NOT part of the library public API, so feel free to break its internals to demonstrate a point. Three test tiers — Smoke (regression; never tolerate FAIL), Stress (deep integration with OK/FAIL/NOTE findings — NOTE is for surfaced quirks worth documenting without blocking), and Admin pages (eyeball-level proof of behaviour, e.g. ShopSettingsPage rendering print_r($dto) to visually confirm Secret redaction). The Widget Shop fixture (bd_widget CPT + bd_order CPT + ShopSettingsDto) is the canonical realistic consumer; extend it rather than inventing a new fixture. CLI is the main driving surface — wp better-data {test, stress, seed, purge, inventory}. Use when changes go under wp-content/plugins/better-data-plugin-test/. Triggers on Smoke / Stress / Runner / Cli files in that path, "wp better-data" CLI invocations, "smoke / stress scenario" mentions. metadata: wp-skills-author: "Soczó Kristóf" wp-skills-contact: "mailto:lonsdale201@hotmail.com" wp-skills-plugin: "better-data" wp-skills-plugin-version-tested: "phase-9" wp-skills-php-min: "8.3" wp-skills-last-updated: "2026-04-29"
better-data: Companion plugin testbed
For library maintainers working in the integration testbed at wp-content/plugins/better-data-plugin-test/. The plugin's job is to verify better-data behavior against real WordPress — things that pure unit tests can't reach (cache primings, metadata_exists semantics, wp_slash round-trips, REST schema actually appearing in WP_REST_Server, locale switching, encryption key constants).
Misconception this skill corrects
"I'll add the new feature's integration test directly inside
better-data/tests/Unit/so everything's in one place."
Wrong. tests/Unit/ is the WP-free zone — every test there must run with composer test against a clean PHP environment, no WP bootstrap, no MySQL. That's intentional: contributors can run the unit suite in seconds. WP-aware behavior goes in the companion plugin, where there's a real WordPress to talk to.
The split:
| Concern | Lives in |
|---|---|
| Pure type coercion, attribute reflection, builder logic | better-data/tests/Unit/ |
wp_slash round-trip, metadata_exists semantics, REST registration | better-data-plugin-test/src/Smoke/ |
| Multi-step scenarios (encrypt → store → fetch → decrypt → reveal), edge-case discovery | better-data-plugin-test/src/Stress/ |
Visual confirmation (admin page renders print_r($dto)) | better-data-plugin-test/src/Admin/ |
Other AI-prone misconceptions:
- "I'll let the plugin depend on WooCommerce since it makes the Order fixture realistic." Wrong — the plugin must run on a clean WP install with NOTHING but better-data. WC, ACF, custom-fields plugins are out. The Widget Shop fixture (
bd_widgetCPT +bd_orderCPT +ShopSettingsDto) IS the realistic consumer because it's self-contained. - "If a stress scenario is flaky, I'll mark it as
NOTEinstead of fixing it." Wrong —NOTEis for documented quirks the library legitimately surfaces (e.g. "WP serializes integer-keyed arrays as objects in some contexts"). A flaky test is aFAILwaiting to happen; fix it. - "I'll move the new behavior into the library after the plugin verifies it." Wrong direction — integration-only behavior STAYS in the plugin. The library stays shape-agnostic.
When to use this skill
Trigger when ANY of the following is true:
- The diff modifies any file under
wp-content/plugins/better-data-plugin-test/. - Adding a new smoke or stress scenario.
- Adding a new CLI subcommand under
bin/wp better-data <subcommand>. - Adding a new admin page, fixture DTO, or seed/purge routine.
- Reviewing a PR that adds WordPress / WC / ACF as a Composer dep on the plugin.
Workflow
1. Three test tiers — pick the right one
Smoke — regression coverage.
src/Smoke/
├── Runner.php ← scenario list + dispatcher
└── Assertion.php ← per-scenario assertions
Smoke scenarios run on every library change. They're short, focused, fast. A FAIL here means a regression — never ship over it. Add a smoke scenario for any new public behavior.
Stress — deep integration.
src/Stress/
├── Runner.php ← scenario list + dispatcher
└── Finding.php ← OK / FAIL / NOTE findings
Stress scenarios are longer-running, multi-step, edge-case-hunting. They produce three outcomes:
| Verdict | Meaning |
|---|---|
OK | Library behaves as expected for this scenario |
FAIL | Bug — blocks the change |
NOTE | Discovery — library surfaces a quirk worth documenting (e.g. "PHP arrays with integer keys round-trip as JSON objects in this context") |
NOTE is the unique value-add: it lets a stress run discover and SURFACE library limits without failing.
Admin pages — visual confirmation.
src/Admin/
├── AdminPage.php ← base
├── ShopSettingsPage.php ← renders print_r($dto) post-hydration
├── …
Admin pages are eyeball-level proof. Use for:
- Visually confirming
Secretrenders as'***'. - Confirming locale-switched email subject lines render in the right language.
- Manually playing with
Presenterchains.
Not test scaffolding — they're for human verification.
2. The Widget Shop fixture is the canonical consumer
The plugin defines:
bd_widgetCPT — products in the fictional shop.bd_orderCPT — orders.ShopSettingsDto— store-level settings (currency, tax, encrypted Stripe key).WidgetDto,LineItemDto,OrderDto,CustomerDto,AddressDto— see src/Dto/.
When you add a new feature:
- Can it fit into the Widget Shop? (Yes for most things — sinks, sources, validation rules, presenter methods.) Extend the existing fixtures.
- Does it genuinely need a ne