Skip to main content

@e2easy/plugin

Tests that stay in sync with every commit

An npm plugin for Cursor and Claude Code. When you commit UI changes, it blocks the commit until your staged UI is tagged with stable test attributes, affected E2Easy tests are resynced via MCP, and they pass a local Playwright check.

Quick start

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

Then reload your IDE, open MCP settings, and complete the E2Easy OAuth sign-in. Requires Node.js 20.11+ and an E2Easy account at app.e2easy.app with a project and recorded tests.

What is @e2easy/plugin?

Recorded browser tests break for one reason more than any other: the UI changed and the tests didn't. The plugin removes that gap. It lives in your repo as a dev dependency, hooks into git commit in Cursor and Claude Code, and makes "tests updated" a precondition for committing UI changes - not an afterthought.

Elements are keyed on a single data attribute (such as data-qa) - no fingerprints, no DOM snapshots, no selector fallbacks. The authoritative attribute name comes from your E2Easy project settings via the same E2Easy MCP server your agent already uses.

What you can do with it

Tag UI with stable attributes

Inserts a single test attribute (e.g. data-qa) on changed interactive elements, so selectors stop breaking on refactors.

Resync recorded tests

Updates affected E2Easy recorded tests through the E2Easy MCP server whenever staged UI changes touch them.

Validate before commit

Runs the affected tests locally with Playwright Chromium against your dev server before the commit is allowed.

Block unsafe commits

A pre-commit gate stops git commit until staged changes are tagged, resynced, and green - no stale tests reach the repo.

Let the agent do the work

In Cursor or Claude Code the agent runs the whole sync workflow itself; in Cursor you can also trigger it manually with /sync-tests.

One command setup

npx e2easy-init scaffolds the MCP server entry, IDE hooks, agent skill, and project config for Cursor and Claude Code.

Install

  1. Register a free account at app.e2easy.app - this is where your tests are managed - and create a project with recorded tests.
  2. Install the plugin and scaffold your IDE config:
npm install -D @e2easy/plugin
npx e2easy-init
npx playwright install chromium
  1. Reload your IDE (Cursor or Claude Code).
  2. Open MCP settings and complete the E2Easy OAuth sign-in with that account.
  3. Stage UI changes, let the agent run the sync workflow, then commit.

By default e2easy-init installs files for both IDEs. Target one with a flag:

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

What e2easy-init scaffolds

Cursor

  • e2easy.config.jsonProject config (attribute, globs, local runner)
  • .cursor/mcp.jsonAdds the E2Easy MCP server (merged with existing servers)
  • .cursor/hooks.jsonBlocks git commit until tests are synced
  • .cursor/hooks/e2easy-precommit.shGate launcher
  • .cursor/skills/e2easy-test-sync/SKILL.mdAgent workflow for syncing tests
  • .cursor/commands/sync-tests.mdManual /sync-tests trigger

Claude Code

  • e2easy.config.jsonProject config
  • .mcp.jsonAdds the E2Easy MCP server (merged with existing servers)
  • .claude/settings.jsonPreToolUse hook on git commit (merged with existing hooks)
  • .claude/hooks/e2easy-precommit.shGate launcher

How it works

  1. 01

    Stage and commit

    You stage UI changes and run git commit as usual.

  2. 02

    Gate checks the sync

    The pre-commit gate compares staged files with the last successful sync; if they differ, the commit is blocked.

  3. 03

    Agent syncs the tests

    The agent reads your test attribute from E2Easy MCP, inserts missing attributes, resyncs affected recorded tests, and validates them locally with Playwright.

  4. 04

    Commit proceeds

    A readiness stamp is written to .e2easy/.precommit-ok (gitignored) and your commit goes through with tests already up to date.

Example: you rename a "Sign in" button and restructure the login form, then run git commit. The gate blocks the commit, the agent tags the new button and fields with data-qa, updates the "Login flow" recorded test through E2Easy MCP, replays it locally against localhost, and only then lets the commit through. In Cursor you can also trigger the same workflow manually with /sync-tests.

Configuration

e2easy.config.json is 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]"]
}
  • 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

CLI commands

npx e2easy-init

Scaffold IDE config and hooks

npx e2easy-precommit-gate

Run the pre-commit 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.

Never commit a broken test again

Create an E2Easy project, record your first tests, and let the plugin keep them green on every commit.

Start freeOpen the MCP guide