@e2easy/plugin

Keep e2easy recorded tests in sync with your UI changes — automatically, before every commit.

When you commit inside Cursor or Claude Code, this plugin blocks the commit until staged UI is tagged with stable test attributes, affected e2easy tests are resynced via MCP, and they pass a local Playwright check.

Requirements

• Node.js 20.11 or newer
• An e2easy project with recorded tests
• Cursor or Claude Code with MCP enabled
• Playwright Chromium (one-time install per machine)

Quick start

npm install -D @e2easy/plugin
npx e2easy-init
npx playwright install chromium

Then:

1. Reload your IDE (Cursor or Claude Code).
2. Open MCP settings and complete e2easy OAuth.
3. Stage UI changes, let the agent run the sync workflow, then commit.

What e2easy-init does

Scaffolds project config and IDE hooks. Default installs Cursor + Claude Code files. Use flags to target one IDE:

npx e2easy-init              # shared + Cursor + Claude (default)
npx e2easy-init --cursor     # shared + Cursor only
npx e2easy-init --claude     # shared + Claude only
npx e2easy-init --force      # overwrite scaffold files; refresh merged MCP/hook entries

Cursor

| File | Purpose | |------|---------| | e2easy.config.json | Project config (attribute, globs, local runner) | | .cursor/mcp.json | Adds the e2easy MCP server (merged with existing servers) | | .cursor/hooks.json | Blocks git commit until tests are synced | | .cursor/hooks/e2easy-precommit.sh | Gate launcher | | .cursor/skills/e2easy-test-sync/SKILL.md | Agent workflow for syncing tests | | .cursor/skills/e2easy-config-sync/SKILL.md | Sync attribute and localRunner.baseUrl to e2easy via MCP | | .cursor/commands/sync-tests.md | Manual /sync-tests trigger | | .cursor/commands/sync-config.md | Manual /sync-config trigger |

Claude Code

| File | Purpose | |------|---------| | e2easy.config.json | Project config | | .mcp.json | Adds the e2easy MCP server (merged with existing servers) | | .claude/settings.json | PreToolUse hook on git commit (merged with existing hooks) | | .claude/hooks/e2easy-precommit.sh | Gate launcher |

How it works

1. You stage UI changes and run git commit.
2. The pre-commit gate checks whether staged files match the last successful sync.
3. If not synced, the commit is blocked with a message to run the sync workflow.
4. The agent (or you via /sync-tests in Cursor):
   • Reads the project's test attribute from e2easy MCP (customSelectorAttribute)
   • Inserts missing attributes (e.g. data-qa) on changed interactive elements
   • Resyncs affected recorded tests via e2easy MCP
   • Validates tests locally with Playwright
   • Writes a readiness stamp to .e2easy/.precommit-ok (gitignored)
5. Commit proceeds.

Elements are keyed on a single data attribute — no fingerprints, no DOM snapshots, no selector fallbacks.

Configuration

e2easy.config.json (created by e2easy-init):

{
  "version": 1,
  "attribute": "data-qa",
  "templateGlobs": ["src/**/*.html", "src/**/*.tsx"],
  "localRunner": {
    "baseUrl": "http://localhost:4200",
    "startCommand": "yarn start"
  },
  "unmappedChangePolicy": "run-all",
  "interactiveSelectors": ["button", "a[href]", "input", "select", "textarea", "[role]"]
}

| Field | Description | |-------|-------------| | attribute | Test attribute for this repo; synced to e2easy customSelectorAttribute via MCP | | templateGlobs | Files scanned for UI changes | | localRunner.baseUrl | Local dev server URL; synced to each test's starting URL via update_test | | localRunner.startCommand | Command to start the dev server (if needed) |

When you change attribute or localRunner.baseUrl, run the e2easy-config-sync skill (or /sync-config in Cursor) so the agent calls update_project_settings and update_test on the e2easy MCP.

CLI commands

| Command | Description | |---------|-------------| | npx e2easy-init | Scaffold IDE config and hooks | | npx e2easy-precommit-gate | Run the gate manually (used by hooks) | | npx e2easy-run-local | Run local Playwright validation |

Troubleshooting

Commit blocked — "not synced with e2easy yet"
Run the e2easy-test-sync skill (Cursor) or /e2easy:sync-tests (Claude Code) on your staged changes.

"plugin not installed"
Run npm install -D @e2easy/plugin in the project root.

Local validation fails with browser errors
Run npx playwright install chromium.

MCP errors
Reload the IDE and re-authenticate e2easy in MCP settings.

Links

• e2easy
• GitHub
• Issues

License

MIT