feat: add wp-env, PHPUnit and Playwright testing setup with Copilot support

[Alexia-Soare]

The plugin had no runnable local test environment — PHPUnit needed a hand-built MySQL/SVN setup and there was no E2E coverage at all, which made agent-assisted development blind (issue #530). This ports otter-blocks' setup: one wp-env instance serves development, PHPUnit, and Playwright, and a Copilot setup workflow boots coding agents into that environment ready to run both suites.

What changed

• wp-env environment — yarn run env:start reuses a running instance or picks a free port and pins it in the gitignored .wp-env.override.json (the Playwright config reads the same file). An afterStart script provisions permalinks and the plugin's default settings so the classic settings screens are directly testable. PHPUnit runs inside the container pinned to a separate wptests_ table prefix — without it the suite install would wipe the development site, which shares the database.

• PHPUnit suites — the admin-ajax API (subscribe, contact, reset settings, select page, wizard steps, newsletter, subscribers export/empty, notices) is covered at the handler seams; access control (role bypass, exclude list by slug/IP, bot detection), the public helpers (GA-code sanitizer, capability filters, form fields, shortcodes), the page-template integration, the Retry-After backtime, and the v1.8 → v2 settings migration each get their own suite.

• Playwright E2E suite — user journeys across the whole surface: the maintenance lifecycle (visitor 503, admin/wp-login unaffected, the wp-admin warning notice), access rules (excluded URLs, bot bypass both ways, feeds and REST staying reachable, Retry-After and robots meta), Design-tab customization and reset, the countdown/social/contact/GDPR/Google Analytics modules, a subscriber's full journey (client-side validation, subscribing, admin count, CSV export as a real download, emptying the list), and a subscriber-role login that bypasses maintenance only while the frontend-role setting allows it. Specs run with workers: 1 since maintenance mode is site-wide state; tests/e2e/utils.js encodes the headless-browser quirks documented in AGENTS.md.

• CI and Copilot — a new Test E2E workflow runs the Playwright suite on pull requests, and copilot-setup-steps.yml prepares the Copilot coding agent's environment with dependencies installed and wp-env already running. The PHPUnit job moves to PHP 7.4 (the current WordPress test suite refuses 7.2). AGENTS.md documents the commands, environment rules, and testing practices.

• Verify toolchain and PHPStan — the composer dev tools move to current majors (WPCS 3.4, installer ^1, PHPUnit ^9.6, sniffer platform at PHP 7.4; codeinwp/phpcs-ruleset dropped since it pinned WPCS below 3), the handful of violations the newer sniffs surfaced are fixed, and PHPStan runs at level 6 with WordPress stubs — matching otter-blocks — with phpstan-baseline.neon capturing the 110 pre-existing findings so CI only fails on new ones. Stubs for the optional integrations (Otter, Elementor, nginx-helper) and dynamic constants live in tests/static-analysis-stubs/. A PHPStan job joins the Test PHP workflow, and the lint job moves off PHP 7.2/composer 2.1, which cannot install the new stack.

• Node and lockfile hygiene — every yarn install now runs with --ignore-engines (the legacy eslint toolchain caps Node below 20 while the new test tooling needs 18+), the zip/deploy workflows move from Node 14 to 20, package-lock.json is ignored by the repository (an npm install rewrites the tracked yarn.lock into a format yarn 1 cannot parse, which would break the deploy workflow), and the release zip now excludes AGENTS.md and the new dev-only files via .distignore.

Note

The E2E environment pins the classic maintenance screen (wpmm_new_look=0): the modules settings UI only renders in that mode, and the block-based wizard flow needs Otter Blocks — it overlaps PR #524's scope and is intentionally out of this suite. AJAX guard paths written as plain die() are also uncovered by design (they would terminate the PHPUnit process), and the PHP 7.4 bump in test-php.yml also exists in PR #524 — an identical one-line conflict to resolve at merge.

Testing workflow

flowchart LR
    A[Contributor] --> B[New:<br/>yarn run env:start]:::added
    B --> C[New:<br/>single wp-env site,<br/>free port pinned]:::added
    C --> D[New:<br/>PHPUnit in container,<br/>wptests_ tables]:::added
    C --> E[New:<br/>Playwright E2E,<br/>serial specs]:::added
    F[Pull request] --> G[New:<br/>Test E2E workflow]:::added
    G --> E
    H[Copilot coding agent] --> I[New:<br/>copilot-setup-steps]:::added
    I --> B

    classDef added fill:#1a7f37,color:#fff,stroke:#116329,stroke-width:3px

Loading

QA

1. With Docker running, install and start the environment:

   composer install && yarn install --frozen-lockfile --ignore-engines
   npx playwright install chromium
   npm run test:unit:php

   Expect: the wp-env site starts (port printed, default 8888) and the PHPUnit suite finishes green without any local MySQL/SVN setup.

2. Run npm run test:e2e, then open the site in a browser at the printed port and log in (admin/password).

   Expect: the suite finishes green, and the site afterwards is intact — maintenance mode off, homepage public, plugin settings reachable under the LightStart menu.

3. Run the PHPUnit suite twice in a row (npm run test:unit:php:base), then reload the site.

   Expect: the development site is untouched — the suite installs into its own wptests_ tables instead of reinstalling over the site.

4. In the Actions tab, run the "Copilot Setup Steps" workflow manually (workflow_dispatch).

   Expect: the job finishes green, ending with the wp-env environment started.

5. Build a release artifact with bash bin/dist.sh and inspect the zip.

   Expect: no tests/, .wp-env.json, AGENTS.md, or workflow files inside.

🤖 Generated with Claude Code

[pirate-bot]

Plugin build for 24d3ad4 is ready 🛎️!

• Download build

[Soare-Robert-Daniel]

@Alexia-Soare let's update the dev composer tools that verify.

Also, let's add PHPStan along with the baseline for the current issues (check how it is done in Otter & PPOM).