@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/commands/sync-tests.md	Manual /sync-tests 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	Fallback test attribute if MCP is unavailable
templateGlobs	Files scanned for UI changes
localRunner.baseUrl	App URL for local Playwright validation
localRunner.startCommand	Command to start the dev server (if needed)

The authoritative attribute comes from your e2easy project settings via 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
• npm package
• Issues

License

MIT