Essential Addons E2E Automation

Enterprise automation framework for the Essential Addons WordPress plugin ecosystem (FREE + PRO + Elementor + WooCommerce).

Prerequisites

• Node 24 (.nvmrc is honoured by nvm / volta / fnm)
• Docker Desktop (or compatible engine)
• macOS / Linux. Windows works via WSL2.

Quick start

# 1. Drop the FREE and PRO plugin zips into the drop-zone:
#    ea-free*.zip and ea-pro*.zip
#    See plugins-zips/README.md for the naming convention.

# 2. Install dependencies
npm install

# 3. Boot the environment (wp-env start + bootstrap)
npm run env:up

# 4. Run the smoke test
npm run test:smoke

That's it — http://localhost:8889 should now serve a fully configured WordPress with FREE/PRO plugins active.

Useful scripts

Command	What it does
npm run env:up	Starts wp-env + runs scripts/bootstrap.ts. Idempotent.
npm run env:reset	Full nuke + rebuild from scratch.
npm run env:down	Stop containers, keep volumes.
npm run env:destroy	Stop + remove volumes.
npm test	Run all Playwright tests.
npm run test:smoke	Smoke subset only (@smoke tag).
npm run test:unit	Unit tests for scripts/lib/.
npm run lint / npm run typecheck	Static checks.

Performance

Operation	Cold	Warm
npm run env:up	~3 min	~70s
npm run env:reset	~5 min	n/a
npm run test:smoke	<30s	<10s
npm run test:elementor-deep	<4 min	<3 min
npm run test:mcp	<7 min	<5 min
npm run test:visual (warm container)	~3 min	~2 min
npm run test:visual cold image pull	~6 min	n/a
Idempotent npx tsx scripts/bootstrap.ts	n/a	~70s (fully-seeded re-run)

Visual baselines

Visual-regression baselines live under tests/visual/**/*.spec.ts-snapshots/ and are committed to git. All generation + verification runs inside mcr.microsoft.com/playwright:v1.59.1-jammy (see scripts/test-visual.sh) so dev (macOS) and CI (Linux) produce byte-identical output.

Verify against committed baselines

npm run test:visual

Update baselines after an intentional visual change

1. Make the code change that intentionally affects rendering.
2. npm run test:visual to see what breaks.
3. npm run test:visual:update to regenerate the failing baselines.
4. git diff --stat tests/visual/ — confirm only the PNGs you expected changed.
5. Inspect the new PNGs in an image viewer (a Playwright HTML report opens with side-by-side comparisons; or git difftool tests/visual/ -- "*.png").
6. Commit the baselines alongside your code change in the same commit.

Rule: never run --update without inspecting the diffs first. It is easy to accidentally pin a regression as the new baseline.

Architecture note: wp-cli proxy

The Playwright container runs --network=host but has no Docker CLI. To let visual specs call wpCli() (e.g. via seedElementorPage), scripts/test-visual.sh starts a tiny host-side HTTP proxy (scripts/lib/wp-cli-proxy.ts) on port 19999 before launching Docker. Inside the container, wpCli() detects WP_CLI_PROXY_PORT and forwards calls to the proxy via curl. The proxy runs the command via docker exec on the host (faster than wp-env run). Lifecycle is managed by the script — the proxy starts before tests, exits on script teardown.

Upgrading Playwright

When bumping @playwright/test in package.json, also bump the IMAGE constant in scripts/test-visual.sh to match the new version. Expect the upgrade commit to include a full visual-baseline regeneration — Chromium versions affect rendering.

Why not npm test / test:nightly?

npm test and npm run test:nightly run Playwright directly without the Docker container, so any visual test against the Linux-only baselines will fail on macOS with platform-mismatch errors. Use npm run test:visual for visual specs and npm run test:full (which excludes @visual) for everything else.

Plugins drop-zone

This framework does not track plugin source or zips. Drop the zip artifacts you want to test into plugins-zips/ — see plugins-zips/README.md for naming rules. The newest matching file wins; the chosen filename is logged at boot.

Architecture

See the design doc: docs/superpowers/specs/2026-05-10-ea-automation-framework-design.md.

Phase 6 introduces an MCP-driven testing layer (the WordPress MCP Adapter + Elementor MCP plugins) for exercising Elementor's data model programmatically. See docs/superpowers/specs/2026-05-11-phase-6-elementor-deep-design.md.

Phases

This is delivered phase-by-phase per automation-plan.md. Each phase has its own implementation plan in docs/superpowers/plans/.