@matware/e2e-runner 1.2.1 → 1.3.1

package/OPENCODE.md

@@ -0,0 +1,166 @@
+# OpenCode Integration
+
+This document describes how to use `@matware/e2e-runner` with [OpenCode](https://github.com/anomalyco/opencode).
+
+## Quick Setup
+
+1. **Install the package** (if not already installed):
+   ```bash
+   npm install -g @matware/e2e-runner
+   ```
+
+2. **Copy configuration to your project**:
+   ```bash
+   # Copy opencode.json to your project root
+   cp node_modules/@matware/e2e-runner/opencode.json ./opencode.json
+   
+   # Or merge with existing opencode.json
+   ```
+
+3. **Copy skills and commands** (optional, for skill/command support):
+   ```bash
+   mkdir -p .opencode
+   cp -r node_modules/@matware/e2e-runner/.opencode/* .opencode/
+   ```
+
+## Configuration
+
+### opencode.json
+
+The MCP server is configured as a `local` type:
+
+```json
+{
+  "mcp": {
+    "e2e-runner": {
+      "type": "local",
+      "command": "node",
+      "args": ["node_modules/@matware/e2e-runner/bin/mcp-server.js"],
+      "cwd": "${workspaceFolder}"
+    }
+  }
+}
+```
+
+If installed globally, use the binary name directly:
+```json
+{
+  "mcp": {
+    "e2e-runner": {
+      "type": "local",
+      "command": "e2e-runner-mcp"
+    }
+  }
+}
+```
+
+## Available MCP Tools
+
+All tools are prefixed with `e2e_`:
+
+| Tool | Description |
+|------|-------------|
+| `e2e_pool_status` | Check Chrome pool availability |
+| `e2e_list` | List test suites and modules |
+| `e2e_run` | Execute tests (all, suite, or file) |
+| `e2e_create_test` | Create a new test JSON file |
+| `e2e_create_module` | Create a reusable module |
+| `e2e_screenshot` | Retrieve screenshot by hash |
+| `e2e_capture` | Capture screenshot of any URL |
+| `e2e_network_logs` | Inspect network requests from a run |
+| `e2e_learnings` | Query the learning system |
+| `e2e_issue` | Fetch GitHub/GitLab issue details |
+| `e2e_variables` | Manage test variables |
+| `e2e_dashboard_start` | Start the web dashboard |
+| `e2e_dashboard_stop` | Stop the web dashboard |
+
+## Differences from Claude Code
+
+| Feature | Claude Code | OpenCode |
+|---------|-------------|----------|
+| MCP Config | `.mcp.json` with `mcpServers` | `opencode.json` with `mcp` |
+| MCP Type | `stdio` | `local` or `remote` |
+| Skills Location | `skills/<name>/SKILL.md` | `.opencode/skills/<name>/SKILL.md` |
+| Commands Location | `commands/*.md` | `.opencode/commands/*.md` |
+| Frontmatter | `allowed_tools` array | No `allowed_tools` (tools are auto-detected) |
+| Skill Triggers | Implicit from description | Explicit `triggers` array in frontmatter |
+| Variable Substitution | `${CLAUDE_PLUGIN_ROOT}` | `${workspaceFolder}` |
+
+### Key Differences Explained
+
+1. **MCP Server Configuration**
+   - Claude Code: Uses `mcpServers` key with `type: "stdio"`
+   - OpenCode: Uses `mcp` key with `type: "local"` or `type: "remote"`
+
+2. **Skills**
+   - Both use `SKILL.md` files with YAML frontmatter
+   - OpenCode supports an explicit `triggers` array to activate the skill
+   - Location differs: `.opencode/skills/` vs `skills/`
+
+3. **Commands**
+   - Claude Code: Supports `allowed_tools` to restrict tool access
+   - OpenCode: Tools are auto-detected from the MCP server
+   - Location differs: `.opencode/commands/` vs `commands/`
+
+4. **Variable Expansion**
+   - Claude Code: `${CLAUDE_PLUGIN_ROOT}` points to the package root
+   - OpenCode: `${workspaceFolder}` points to the current workspace
+
+## Directory Structure
+
+```
+your-project/
+├── opencode.json          # OpenCode configuration
+├── .opencode/
+│   ├── skills/
+│   │   └── e2e-testing/
+│   │       ├── SKILL.md
+│   │       └── references/
+│   │           ├── action-types.md
+│   │           ├── auth-strategies.md
+│   │           └── ...
+│   └── commands/
+│       ├── run.md
+│       ├── create-test.md
+│       └── verify-issue.md
+└── e2e/
+    ├── e2e.config.json    # Test configuration
+    ├── tests/             # Test JSON files
+    └── modules/           # Reusable modules
+```
+
+## Global Installation
+
+To make the skill and commands available to all projects:
+
+```bash
+# Copy to global OpenCode config
+mkdir -p ~/.config/opencode/skills
+mkdir -p ~/.config/opencode/commands
+
+cp -r node_modules/@matware/e2e-runner/.opencode/skills/* ~/.config/opencode/skills/
+cp -r node_modules/@matware/e2e-runner/.opencode/commands/* ~/.config/opencode/commands/
+```
+
+## Troubleshooting
+
+### MCP Server Not Starting
+
+1. Check that Node.js >= 20 is installed
+2. Verify the path in `opencode.json` is correct
+3. Try running the server manually:
+   ```bash
+   node node_modules/@matware/e2e-runner/bin/mcp-server.js
+   ```
+
+### Tools Not Available
+
+1. Restart OpenCode after changing `opencode.json`
+2. Check the MCP server logs for errors
+3. Verify the Chrome pool is running: `npx e2e-runner pool status`
+
+### Skill Not Loading
+
+1. Ensure the skill is in `.opencode/skills/e2e-testing/SKILL.md`
+2. Check the frontmatter has `name` and `description`
+3. Try using a trigger word from the `triggers` array

package/README.md

@@ -9,11 +9,16 @@
 </p>
 
 <p align="center">
-  <img src="https://img.shields.io/npm/v/@matware/e2e-runner?color=blue" alt="npm version" />
+  <a href="https://www.npmjs.com/package/@matware/e2e-runner"><img src="https://img.shields.io/npm/v/@matware/e2e-runner?color=blue" alt="npm version" /></a>
   <img src="https://img.shields.io/node/v/@matware/e2e-runner" alt="node version" />
-  <img src="https://img.shields.io/npm/l/@matware/e2e-runner" alt="license" />
+  <a href="https://www.npmjs.com/package/@matware/e2e-runner"><img src="https://img.shields.io/npm/dm/@matware/e2e-runner" alt="npm downloads" /></a>
+  <a href="https://hub.docker.com/r/fastslack/e2e-runner-mcp"><img src="https://img.shields.io/docker/pulls/fastslack/e2e-runner-mcp" alt="Docker pulls" /></a>
+  <a href="https://github.com/fastslack/mtw-e2e-runner/stargazers"><img src="https://img.shields.io/github/stars/fastslack/mtw-e2e-runner" alt="GitHub stars" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/npm/l/@matware/e2e-runner" alt="license" /></a>
   <img src="https://img.shields.io/badge/MCP-compatible-green" alt="MCP compatible" />
   <img src="https://img.shields.io/badge/AI--native-Claude%20Code-blueviolet" alt="AI native" />
+  <img src="https://img.shields.io/badge/AI--native-OpenCode-orange" alt="OpenCode compatible" />
+  <a href="https://skills.sh"><img src="https://img.shields.io/badge/skills.sh-e2e--testing-ff6600" alt="Agent Skills" /></a>
 </p>
 
 <p align="center">
@@ -26,32 +31,6 @@
 
 But what makes it truly different is its **deep AI integration**. With a built-in [MCP server](https://modelcontextprotocol.io/), Claude Code can create tests from a conversation, run them, read the results, capture screenshots, and even visually verify that pages look correct — all without leaving the chat. Paste a GitHub issue URL and get a runnable test back. That's the workflow.
 
-### What you get
-
-🧪 **Zero-code tests** — JSON files that anyone on your team can read and write. No JavaScript, no compilation, no framework lock-in.
-
-🤖 **AI-powered testing** — Claude Code creates, executes, and debugs tests natively through 13 MCP tools. Ask it to "test the checkout flow" and it builds the JSON, runs it, and reports back.
-
-🐛 **Issue-to-Test pipeline** — Paste a GitHub or GitLab issue URL. The runner fetches it, generates E2E tests, runs them, and tells you: *bug confirmed* or *not reproducible*.
-
-👁️ **Visual verification** — Describe what the page should look like in plain English. The AI captures a screenshot and judges pass/fail against your description. No pixel-diffing setup needed.
-
-🧠 **Learning system** — Tracks test stability across runs. Detects flaky tests, unstable selectors, slow APIs, and error patterns — then surfaces actionable insights.
-
-⚡ **Parallel execution** — Run N tests simultaneously against a shared Chrome pool (browserless/chrome). Serial mode available for tests that share state.
-
-📊 **Real-time dashboard** — Live execution view, run history with pass-rate charts, screenshot gallery with hash-based search, expandable network request logs.
-
-🔁 **Smart retries** — Test-level and action-level retries with configurable delays. Flaky tests are detected and flagged automatically.
-
-📦 **Reusable modules** — Extract common flows (login, navigation, setup) into parameterized modules and reference them with `$use`.
-
-🏗️ **CI-ready** — JUnit XML output, exit code 1 on failure, auto-captured error screenshots. Drop-in GitHub Actions example included.
-
-🌐 **Multi-project** — One dashboard aggregates test results from all your projects. One Chrome pool serves them all.
-
-🐳 **Portable** — Chrome runs in Docker, tests are JSON files in your repo. Works on any machine with Node.js and Docker.
-
 ### This is a test
 
 ```json
@@ -74,45 +53,102 @@ No imports. No `describe`/`it`. No compilation step. Just a JSON file that descr
 
 ---
 
-## Quick Start
+## Agent Skills
 
-**One-liner** (requires Node.js >= 20 and Docker):
+Install E2E testing skills for any coding agent (Claude Code, Cursor, Codex, Copilot, and [40+ more](https://github.com/vercel-labs/skills#supported-agents)):
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/fastslack/mtw-e2e-runner/main/scripts/quickstart.sh | bash
+npx skills add fastslack/mtw-e2e-runner
 ```
 
-**Step by step:**
+This gives your agent the knowledge to create, run, and debug JSON-driven E2E tests — no documentation reading required.
+
+> Browse all available skills at [skills.sh](https://skills.sh)
+
+---
+
+## Getting Started
+
+**Prerequisites:** Node.js >= 20, Docker running, your app on a known port.
+
+### Quickstart
 
 ```bash
-# 1. Install
 npm install --save-dev @matware/e2e-runner
+npx e2e-runner init          # creates e2e/tests/ with a sample test
+npx e2e-runner pool start    # starts Chrome in Docker
+npx e2e-runner run --all     # runs the sample test
+```
 
-# 2. Scaffold project structure
-npx e2e-runner init
+Or do it all in one command:
 
-# 3. Start Chrome pool (requires Docker)
-npx e2e-runner pool start
+```bash
+curl -fsSL https://raw.githubusercontent.com/fastslack/mtw-e2e-runner/main/scripts/quickstart.sh | bash
+```
 
-# 4. Run all tests
-npx e2e-runner run --all
+After setup, edit `e2e.config.js` to set your app's port:
 
-# 5. Open the dashboard
-npx e2e-runner dashboard
+```js
+export default {
+  baseUrl: 'http://host.docker.internal:3000', // change 3000 to your port
+};
 ```
 
-**Add to Claude Code** (once, available in all projects):
+> **Why `host.docker.internal`?** Chrome runs inside Docker and can't reach `localhost` on your machine. This hostname bridges the gap. On Linux (Docker Engine, not Desktop), you may need `--add-host=host.docker.internal:host-gateway` or use your LAN IP directly.
+
+### Add Claude Code (optional)
 
 ```bash
-# Full plugin: MCP tools + skills + commands + agents
-claude plugin install npm:@matware/e2e-runner
+claude plugin marketplace add fastslack/mtw-e2e-runner
+claude plugin install e2e-runner@matware
+```
 
-# Or MCP-only (tools without skills/commands/agents):
-claude mcp add --transport stdio --scope user e2e-runner \
-  -- npx -y -p @matware/e2e-runner e2e-runner-mcp
+This gives Claude 13 MCP tools, slash commands, and specialized agents. Just say *"Run all E2E tests"* or *"Create a test for the login flow"*.
+
+### Add OpenCode (optional)
+
+```bash
+cp node_modules/@matware/e2e-runner/opencode.json ./
+mkdir -p .opencode && cp -r node_modules/@matware/e2e-runner/.opencode/* .opencode/
 ```
 
-The **plugin** is the recommended approach — it installs the 13 MCP tools *plus* a skill that teaches Claude the optimal workflow, 3 slash commands (`/e2e-runner:run`, `/e2e-runner:create-test`, `/e2e-runner:verify-issue`), and 2 specialized agents for test analysis and creation.
+See [OPENCODE.md](OPENCODE.md) for details.
+
+### What's next?
+
+- [Test Format](#test-format) — learn the full action vocabulary
+- [Claude Code Integration](#claude-code-integration) — set up AI-powered testing
+- [Visual Verification](#visual-verification) — describe expected pages in plain English
+- [Issue-to-Test](#issue-to-test) — turn bug reports into executable tests
+- [Web Dashboard](#web-dashboard) — monitor tests in real time
+
+---
+
+## What you get
+
+🧪 **Zero-code tests** — JSON files that anyone on your team can read and write. No JavaScript, no compilation, no framework lock-in.
+
+🤖 **AI-powered testing** — Claude Code creates, executes, and debugs tests natively through 13 MCP tools. Ask it to "test the checkout flow" and it builds the JSON, runs it, and reports back.
+
+🐛 **Issue-to-Test pipeline** — Paste a GitHub or GitLab issue URL. The runner fetches it, generates E2E tests, runs them, and tells you: *bug confirmed* or *not reproducible*.
+
+👁️ **Visual verification** — Describe what the page should look like in plain English. The AI captures a screenshot and judges pass/fail against your description. No pixel-diffing setup needed.
+
+🧠 **Learning system** — Tracks test stability across runs. Detects flaky tests, unstable selectors, slow APIs, and error patterns — then surfaces actionable insights.
+
+⚡ **Parallel execution** — Run N tests simultaneously against a shared Chrome pool (browserless/chrome). Serial mode available for tests that share state.
+
+📊 **Real-time dashboard** — Live execution view, run history with pass-rate charts, screenshot gallery with hash-based search, expandable network request logs.
+
+🔁 **Smart retries** — Test-level and action-level retries with configurable delays. Flaky tests are detected and flagged automatically.
+
+📦 **Reusable modules** — Extract common flows (login, navigation, setup) into parameterized modules and reference them with `$use`.
+
+🏗️ **CI-ready** — JUnit XML output, exit code 1 on failure, auto-captured error screenshots. Drop-in GitHub Actions example included.
+
+🌐 **Multi-project** — One dashboard aggregates test results from all your projects. One Chrome pool serves them all.
+
+🐳 **Portable** — Chrome runs in Docker, tests are JSON files in your repo. Works on any machine with Node.js and Docker.
 
 ---
 
@@ -126,8 +162,7 @@ Each `.json` file in `e2e/tests/` contains an array of tests. Each test has a `n
     "name": "homepage-loads",
     "actions": [
       { "type": "goto", "value": "/" },
-      { "type": "wait", "selector": ".hero" },
-      { "type": "assert_text", "text": "Welcome" },
+      { "type": "assert_visible", "selector": "body" },
       { "type": "assert_url", "value": "/" },
       { "type": "screenshot", "value": "homepage.png" }
     ]
@@ -245,22 +280,66 @@ Serial tests run one at a time **after** all parallel tests finish — preventin
 
 ---
 
+## Testing Authenticated Apps
+
+The simplest approach — log in via the UI like a real user:
+
+```json
+{
+  "hooks": {
+    "beforeEach": [
+      { "type": "goto", "value": "/login" },
+      { "type": "type", "selector": "#email", "value": "test@example.com" },
+      { "type": "type", "selector": "#password", "value": "test-password" },
+      { "type": "click", "text": "Sign In" },
+      { "type": "wait", "selector": ".dashboard" }
+    ]
+  },
+  "tests": [...]
+}
+```
+
+For SPAs with JWT, skip the login form by injecting the token directly:
+
+```json
+{ "type": "set_storage", "value": "accessToken=eyJhbGciOiJIUzI1NiIs..." }
+```
+
+Or set it globally in config:
+
+```js
+// e2e.config.js
+export default {
+  authToken: 'eyJhbGciOiJIUzI1NiIs...',
+  authStorageKey: 'accessToken',
+};
+```
+
+Each test runs in a **fresh browser context**, so auth state is automatically clean between tests.
+
+> **More strategies:** Cookie-based auth, HTTP header injection, OAuth/SSO bypasses, reusable auth modules, and role-based testing — see [docs/authentication.md](docs/authentication.md)
+
+---
+
 ## Reusable Modules
 
 Extract common flows into parameterized modules:
 
 ```json
-// e2e/modules/auth.json
+// e2e/modules/login.json
 {
-  "$module": "auth-jwt",
-  "description": "Inject JWT token into localStorage",
+  "$module": "login",
+  "description": "Log in via the UI login form",
   "params": {
-    "token": { "required": true, "description": "JWT token" },
-    "storageKey": { "default": "accessToken" }
+    "email": { "required": true, "description": "User email" },
+    "password": { "required": true, "description": "User password" }
   },
   "actions": [
-    { "type": "evaluate", "value": "localStorage.setItem('{{storageKey}}', '{{token}}')" },
-    { "type": "goto", "value": "/dashboard" }
+    { "type": "goto", "value": "/login" },
+    { "type": "type", "selector": "#email", "value": "{{email}}" },
+    { "type": "type", "selector": "#password", "value": "{{password}}" },
+    { "type": "click", "text": "Sign In" },
+    { "type": "wait", "value": "2000" }
   ]
 }
 ```
@@ -271,7 +350,7 @@ Use in tests:
 {
   "name": "dashboard-loads",
   "actions": [
-    { "$use": "auth-jwt", "params": { "token": "eyJhbG..." } },
+    { "$use": "login", "params": { "email": "user@test.com", "password": "secret" } },
     { "type": "assert_text", "text": "Dashboard" }
   ]
 }
@@ -448,70 +527,52 @@ Every screenshot gets a deterministic hash (`ss:a3f2b1c9`). Use `e2e_screenshot`
 
 ---
 
-## Claude Code Integration
+## AI Integration
 
-The package ships as a **Claude Code plugin** — a single install that gives Claude native access to the test runner, teaches it the optimal workflow, and adds slash commands and specialized agents.
-
-### Install as Plugin (recommended)
+### Claude Code
 
 ```bash
-claude plugin install npm:@matware/e2e-runner
+claude plugin marketplace add fastslack/mtw-e2e-runner
+claude plugin install e2e-runner@matware
 ```
 
-**What you get:**
-
-| Component | Description |
-|-----------|-------------|
-| **13 MCP tools** | Run tests, create test files, capture screenshots, query network logs, manage dashboard, verify issues, query learnings |
-| **Skill** | Teaches Claude the full e2e-runner workflow — how to combine tools, interpret results, debug failures, create tests |
-| **3 Commands** | `/e2e-runner:run` — run & analyze tests<br>`/e2e-runner:create-test` — explore UI and create tests<br>`/e2e-runner:verify-issue <url>` — verify GitHub/GitLab bugs |
-| **2 Agents** | **test-analyzer** — diagnoses failures, analyzes flaky tests, drills into network errors<br>**test-creator** — explores UI, discovers selectors, designs and validates tests |
-
-### Install MCP-only (alternative)
+This gives Claude 13 MCP tools, a workflow skill, 3 slash commands (`/e2e-runner:run`, `/e2e-runner:create-test`, `/e2e-runner:verify-issue`), and 3 specialized agents (test-analyzer, test-creator, test-improver).
 
-If you only want the 13 MCP tools without skills, commands, or agents:
+**MCP-only install** (tools only, no skill/commands/agents):
 
 ```bash
 claude mcp add --transport stdio --scope user e2e-runner \
   -- npx -y -p @matware/e2e-runner e2e-runner-mcp
 ```
 
-### Slash Commands
+### OpenCode
+
+```bash
+cp node_modules/@matware/e2e-runner/opencode.json ./
+mkdir -p .opencode && cp -r node_modules/@matware/e2e-runner/.opencode/* .opencode/
+```
 
-| Command | Description |
-|---------|-------------|
-| `/e2e-runner:run` | Check pool, list suites, run tests, analyze results with screenshots and network drill-down |
-| `/e2e-runner:create-test` | Explore the UI with screenshots, find selectors in source code, design test actions, create and validate |
-| `/e2e-runner:verify-issue <url>` | Fetch a GitHub/GitLab issue, create tests that verify correct behavior, report bug confirmed or not reproducible |
+See [OPENCODE.md](OPENCODE.md) for details.
 
 ### MCP Tools
 
 | Tool | Description |
 |------|-------------|
-| `e2e_run` | Run tests: all suites, by name, or by file. Supports `concurrency`, `baseUrl`, `retries`, `failOnNetworkError` overrides. Returns verification results if tests have `expect`. |
-| `e2e_list` | List available test suites with test names and counts |
-| `e2e_create_test` | Create a new test JSON file with name, tests, and optional hooks |
-| `e2e_create_module` | Create a reusable module with parameterized actions |
-| `e2e_pool_status` | Check Chrome pool availability, running sessions, capacity |
-| `e2e_screenshot` | Retrieve a screenshot by hash (`ss:a3f2b1c9`). Returns image + metadata |
-| `e2e_capture` | Capture screenshot of any URL. Supports `authToken`, `fullPage`, `selector`, `delay` |
-| `e2e_dashboard_start` | Start the web dashboard |
-| `e2e_dashboard_stop` | Stop the web dashboard |
-| `e2e_issue` | Fetch GitHub/GitLab issue and generate tests. `mode: "prompt"` or `mode: "verify"` |
-| `e2e_network_logs` | Query network request/response logs by `runDbId`. Filter by test name, method, status, URL pattern. Supports headers and bodies |
-| `e2e_learnings` | Query the learning system: `summary`, `flaky`, `selectors`, `pages`, `apis`, `errors`, `trends` |
-| `e2e_neo4j` | Manage Neo4j knowledge graph container: `start`, `stop`, `status` |
-
-> **Note:** Pool start/stop are CLI-only (`e2e-runner pool start|stop`) — not exposed via MCP to prevent killing active sessions.
-
-### What You Can Ask Claude Code
-
-> "Run all E2E tests"
-> "Create a test that verifies the checkout flow"
-> "What tests are flaky? Show me the learning summary"
-> "Capture a screenshot of /dashboard with auth"
-> "Fetch issue #42 and create tests for it"
-> "What's the API error rate for the last 7 days?"
+| `e2e_run` | Run tests (all, by suite, or by file) |
+| `e2e_list` | List available test suites |
+| `e2e_create_test` | Create a new test JSON file |
+| `e2e_create_module` | Create a reusable module |
+| `e2e_pool_status` | Check Chrome pool health |
+| `e2e_screenshot` | Retrieve a screenshot by hash |
+| `e2e_capture` | Capture screenshot of any URL |
+| `e2e_dashboard_start` | Start web dashboard |
+| `e2e_dashboard_stop` | Stop web dashboard |
+| `e2e_issue` | Fetch issue and generate tests |
+| `e2e_network_logs` | Query network logs for a run |
+| `e2e_learnings` | Query stability insights |
+| `e2e_neo4j` | Manage Neo4j knowledge graph |
+
+> Pool start/stop are CLI-only — not exposed via MCP.
 
 ---
 

package/agents/test-creator.md

@@ -69,6 +69,17 @@ You are a specialist in creating robust E2E tests for web applications. You expl
 - Clear field → `clear`
 - Submit → `click` on submit button or `press` Enter
 
+### Storage
+- Set localStorage key → `set_storage` with `value: "key=val"`
+- Set sessionStorage key → `set_storage` with `value: "key=val"`, `selector: "session"`
+- Assert storage key exists → `assert_storage` with `value: "key"`
+- Assert storage value → `assert_storage` with `value: "key=expected"`
+
+### Smart Clicks
+- Click icon button → `click_icon` with `value` (icon identifier like "edit", "delete")
+- Click menu item → `click_menu_item` with `text` (after opening the menu)
+- Click element in a specific row/card → `click_in_context` with `text` (row text) + `selector` (child to click)
+
 ### Waiting
 - Element appears → `wait` with `selector`
 - Text appears → `wait` with `text`
@@ -86,12 +97,54 @@ You are a specialist in creating robust E2E tests for web applications. You expl
 - CSS class → `assert_class`
 - URL → `assert_url`
 
+### Naming Rules (CRITICAL)
+- **Suite file names MUST be unique and specific** to the feature, issue, or user flow being tested
+- NEVER use generic names like `all`, `test`, `tests`, `debug`, `new`, `temp`, `main`, `suite`
+- Include the feature or issue context: `login-valid-credentials`, `issue-1743-auth-redirect`, `checkout-payment-flow`
+- If testing a GitHub/GitLab issue, include the issue number: `issue-1743-auth-timeout`, `bug-502-duplicate-submit`
+- Before creating a test, call `e2e_list` and verify your chosen name doesn't already exist
+- Individual test names within a suite must also be unique and descriptive
+
+### Variables
+- Use `{{var.KEY}}` to reference project variables instead of hardcoding sensitive values (tokens, IDs, secrets)
+- Use `{{env.KEY}}` to reference environment variables from `process.env`
+- Variables are stored in SQLite and managed via `e2e_vars` MCP tool or the dashboard UI
+- Suite-scoped variables override project-scoped variables with the same key
+- Example: `{ "type": "set_storage", "value": "accessToken={{var.JWT_TOKEN}}" }`
+- Example: `{ "type": "goto", "value": "/patient/{{var.PATIENT_ID}}" }`
+
+### DRY Patterns (CRITICAL)
+
+Before creating tests, **always check existing modules** with `Glob` on `e2e/modules/*.json`. Reuse existing modules instead of duplicating actions.
+
+**Use `beforeEach` when auth or setup is repeated across tests:**
+When multiple tests in a suite share the same setup (e.g., same auth-jwt call), use the object format with `beforeEach` instead of repeating it in every test:
+
+```json
+{
+  "beforeEach": [
+    { "$use": "auth-jwt", "params": { "token": "{{var.JWT_TOKEN}}", "institutionId": "{{var.INST_ID}}" } }
+  ],
+  "tests": [
+    { "name": "test-one", "actions": [...] },
+    { "name": "test-two", "actions": [...] }
+  ]
+}
+```
+
+**Create modules for repeated action patterns:**
+When 3+ tests repeat the same sequence (e.g., goto → wait → screenshot), create a module first with `e2e_create_module`, then use `$use` in the tests. This reduces test size by 70-80%.
+
+**Use the object format (not array) when hooks are needed:**
+- Array format: `[{ "name": ..., "actions": [...] }]` — no hooks
+- Object format: `{ "beforeEach": [...], "tests": [...] }` — with hooks
+
 ### Best Practices
 - Never use `evaluate` when a built-in action exists
+- **Never hardcode tokens, passwords, or IDs in test files** — use `{{var.KEY}}` variables instead
 - Add `retries` to actions on dynamically loaded elements
 - Mark state-sharing tests as `serial: true`
 - Use `screenshot` actions at key points for debugging
-- Keep test names descriptive and kebab-case (`login-valid-credentials`)
 
 ## Output
 

package/agents/test-improver.md

@@ -73,6 +73,11 @@ When you find an `evaluate` action, check if it matches one of these patterns
 | `MuiAutocomplete-root...input.focus()` | `focus_autocomplete` with `text` |
 | `querySelectorAll('button').filter(regex)...click()` | `click_regex` with `text` + optional `selector` + `value` |
 | `querySelectorAll('[class*="Chip"]')...click()` | `click_chip` with `text` |
+| `localStorage.setItem(key, val)` or `sessionStorage.setItem(...)` | `set_storage` with `value: "key=val"`, `selector: "session"` for session |
+| `localStorage.getItem(key)` check or `sessionStorage.getItem(...)` | `assert_storage` with `value: "key"` or `"key=expected"`, `selector: "session"` for session |
+| `querySelector('svg[data-testid]').closest('button').click()` | `click_icon` with `value` (icon identifier) + optional `selector` (scope) |
+| `querySelectorAll('[role="menuitem"]')...click()` | `click_menu_item` with `text` + optional `selector` (scope) |
+| Container-by-text then child click: `rows.find(r => r.textContent.includes(text))...querySelector(child).click()` | `click_in_context` with `text` (container) + `selector` (child) |
 | `document.title` or simple property read | `get_text` or `evaluate` (keep if no built-in equivalent) |
 
 ### Replacement Examples
@@ -101,6 +106,38 @@ When you find an `evaluate` action, check if it matches one of these patterns
 { "type": "click_option", "text": "Cefalea" }
 ```
 
+```json
+// BEFORE: evaluate for localStorage
+{ "type": "evaluate", "value": "localStorage.setItem('authToken', 'abc123')" }
+
+// AFTER: one action
+{ "type": "set_storage", "value": "authToken=abc123" }
+```
+
+```json
+// BEFORE: evaluate for icon click
+{ "type": "evaluate", "value": "document.querySelector('svg[data-testid=\"EditIcon\"]').closest('button').click()" }
+
+// AFTER: one action
+{ "type": "click_icon", "value": "Edit" }
+```
+
+```json
+// BEFORE: evaluate for menu item click
+{ "type": "evaluate", "value": "const items = [...document.querySelectorAll('[role=\"menuitem\"]')]; items.find(el => el.textContent.includes('Delete')).click();" }
+
+// AFTER: one action
+{ "type": "click_menu_item", "text": "Delete" }
+```
+
+```json
+// BEFORE: evaluate for contextual click
+{ "type": "evaluate", "value": "const rows = [...document.querySelectorAll('tr')]; const row = rows.find(r => r.textContent.includes('John Doe')); row.querySelector('button.edit').click();" }
+
+// AFTER: one action
+{ "type": "click_in_context", "text": "John Doe", "selector": "button.edit" }
+```
+
 ## Duplication Detection
 
 Look for these common duplication patterns: