# Humand E2E

Plugin for **Cursor** and **Claude Code** with Playwright E2E testing skills, rules, and a knowledge base for Humand web projects.

Lives in the [hu-ai-agent-plugin](https://github.com/Humand/hu-ai-agent-plugin) marketplace. The folders `skills/`, `rules/`, and `knowledge/` are the source of truth — edit them in this repo and open PRs here.

## Installation

### From the Humand marketplace (Cursor and Claude Code)

Configure the marketplace in your editor so the plugin is available, then enable `humand-e2e`:

- **Cursor:** Add the hu-ai-agent-plugin marketplace and enable the plugin in Cursor settings.
- **Claude Code:** Add the marketplace and install the plugin:

  ```bash
  /plugin marketplace add <source-to-hu-ai-agent-plugin>
  /plugin install humand-e2e@<marketplace-name>
  ```

### Per-project

Add to `.cursor/settings.json` or `.claude/settings.json`:

```json
{
  "enabledPlugins": {
    "humand-e2e@humand-plugins": true
  }
}
```

## Agent skills

| Skill | When it runs |
|-------|-------------|
| `e2e-setup` | User runs `/e2e-setup` to register where the app repos live on this machine. Run this once per clone (and again if a repo moves) |
| `e2e-plan` | User asks to plan E2E scenarios for a module; explores the app via Playwright MCP |
| `e2e-generate` | User asks to generate tests from a `specs/*.spec.md` file |
| `e2e-heal` | User asks to diagnose or fix failing Playwright tests |
| `e2e-page-object` | User asks to create or update a page object from live UI |

### App context (`.e2e/context.local.json`)

The Humand E2E test repo (e.g. `humand-frontend-testing`) is separate from the app repos (`humand-web`, `humand-backoffice`, `hu-translations`, `material-hu`). Each developer clones those repos to different paths on their machine, so the plugin reads a per-machine config to know where they live:

- `.e2e/context.local.json` — gitignored, written by `/e2e-setup`. Maps app names (`web`, `backoffice`, ...) to absolute `repoPath` plus useful internal sub-paths (`routesPath`, `pagesPath`). Services are not recorded as a top-level path because Humand apps are mid-migration toward per-module services — some modules own their `services.ts` inside the module folder, others still live under a shared `src/services/`. Consumer skills should locate services per-module first and fall back to the shared directory if missing.
- `.e2e/context.example.json` — committed template.

The `e2e-plan`, `e2e-generate`, `e2e-heal`, and `e2e-page-object` skills read this context as **step 0** of their workflow. If it is missing they run in "degraded mode" and skip steps that require app source.

## Rules

| Rule | Applies to |
|------|-----------|
| `playwright-planner` | `**/specs/**/*.md`, `**/tests/**/*.spec.ts` |
| `playwright-generator` | `**/tests/**/*.spec.ts`, `**/pages/**/*Page.ts` |
| `playwright-healer` | `**/tests/**/*.spec.ts`, `**/pages/**/*Page.ts` |

The broader globs let the rules work in both single-app and multi-app workspaces (see "Assumed project layout" below). The `*Page.ts` suffix on the page-object glob keeps the rules from activating on unrelated `pages/` directories (e.g. Next.js routing) and matches Humand's POM naming convention (`GoalsPage.ts`, `BasePage.ts`, ...).

## Knowledge base

The `knowledge/` directory contains Playwright and Humand-specific guides consumed by skills via required/conditional references:

- **writing-tests/** — locators, assertions, fixtures, test organization, forms
- **patterns/** — page objects, authentication, API interception, React/MUI, data management
- **reliability/** — flaky tests, debugging, common pitfalls
- **ci/** — GitHub Actions pipeline, sharding and reporting
- **humand/** — naming conventions, configuration guidance

## MCP

The plugin provides a Playwright MCP server (`mcp.json`) for live browser exploration used by the planning and healing skills.

## Structure

```
humand-e2e/
├── .cursor-plugin/
│   └── plugin.json
├── .claude-plugin/
│   └── plugin.json
├── README.md
├── mcp.json
├── skills/
├── rules/
└── knowledge/
```

## Assumed project layout

Skills and rules support two layouts. Each layout has one or more **E2E workspaces**, each with the same internal structure.

### Single-app

```
<project-root>/
└── e2e/                          # workspace
    ├── specs/                    # Test plan markdown files
    ├── tests/                    # Playwright .spec.ts files
    ├── pages/                    # Page object classes
    ├── fixtures/                 # Playwright fixtures
    ├── auth/                     # Storage state files
    └── playwright.config.ts
```

### Multi-app

Multiple sibling apps under the repo root, each its own workspace. Used by repos like `humand-frontend-testing` that test more than one Humand frontend.

```
<project-root>/
├── web/                          # workspace 1 (humand-web)
│   ├── specs/
│   ├── tests/
│   ├── pages/
│   ├── fixtures/
│   ├── auth/
│   └── playwright.config.ts
├── backoffice/                   # workspace 2 (humand-backoffice)
│   └── ... (same structure)
└── shared/
    └── pages/
        └── BasePage.ts           # cross-workspace base classes
```

Skills detect the layout by probing for `playwright.config.ts`. In multi-app mode, you must specify (or the skill will infer/ask) which workspace to target.

## Stack

Playwright 1.56+ · TypeScript · React 18 · MUI · English locale (en)