init-e2e

Scaffold a complete Playwright E2E test suite for any frontend project — project detection, HAR recording, mock factories, summary reporter, and code-driven test outline.

init-e2e is the engineering half of the e2e-generator toolkit. It handles the mechanical, deterministic work so an LLM (or a human) can focus on writing meaningful test cases.

The companion AI Skill lives at skill/ in the same monorepo.

Install

# Global (recommended for ad-hoc use)
npm install -g init-e2e

# One-off via npm init
npm init e2e -- -d /path/to/project --record --url "..."

Requires Node.js >= 18.

Quick start

# Recommended: record real APIs into a HAR, then scaffold everything
init-e2e init -d /path/to/your-app \
  --record \
  --url "http://dev.example.com/app?token=xxx" \
  --sanitize

# Already have a HAR (from Chrome DevTools / Charles / Fiddler)
init-e2e init -d /path/to/your-app \
  --from-har e2e/fixtures/recording.har \
  --sanitize

# Skip recording (mocks will use TODO placeholders — accuracy not guaranteed)
init-e2e init -d /path/to/your-app -y

# Generate the code-driven test outline (run before writing test cases)
init-e2e outline -d /path/to/your-app

Commands

| Command | Purpose | |---------|---------| | init-e2e init | One-shot: detect project → record/import HAR → emit playwright config, mock factories, summary reporter, spec skeletons | | init-e2e record | Only record a HAR via Playwright (interactive Chromium session) | | init-e2e generate-mocks | Re-generate mock factories from an existing HAR | | init-e2e outline | Static-analyse routes + components and produce e2e/code-outline.{md,json} (mind-map style) for use as a test-case checklist |

Run init-e2e <command> --help for full flag details.

What gets generated

your-app/
├── playwright.config.ts                # baseURL, devices (Pixel 5 by default), webServer, html + summary reporter
├── e2e/
│   ├── helpers/
│   │   ├── mock-data.ts                # appUrl(), mockAPIError(), createFactory(), bizOk()
│   │   └── mocks/                      # one file per real endpoint, generated from HAR
│   │       ├── index.ts                # setupAllMocks(page, overrides)
│   │       ├── api-inventory.json      # discovered endpoints + envelope info
│   │       └── <module>.ts
│   ├── reporters/
│   │   └── summary-reporter.ts         # custom Playwright reporter with per-suite summary
│   ├── code-outline.md                 # human-readable code-driven outline
│   ├── code-outline.json               # machine-readable mind-map (compatible with case.json format)
│   └── *.spec.ts                       # one spec per route, four-scenario skeleton
└── package.json                        # test:e2e / test:e2e:ui / test:e2e:report scripts added

Mocks ship as factories — every test can selectively override fields:

test("activity not started shows guard toast", async ({ page }) => {
  await setupAllMocks(page, { tradeInInfo: MOCK_TRADE_IN_NOT_STARTED });
  await page.goto(appUrl("/tradeIn"));
  // ...
});

Design principles

1. Real data first. Mocks must come from recorded HARs; placeholders are an explicit downgrade signalled to the user.
2. Code-driven outline. Test cases are derived from static analysis of routes, UI text, interactive elements, API calls, conditional rendering and entry params — not from a hand-drawn mind map.
3. Four-scenario template. Every spec is split into Display / Branches / Interactions / API states so granularity stays consistent.
4. CLI does engineering, Skill does methodology. No business heuristics in the CLI; no shell scripts in the Skill.

Read the full methodology in skill/SKILL.md and skill/references/methodology.md.

Local development

git clone https://github.com/justb/e2e-generator
cd e2e-generator/cli
npm install
npm run build
npm link              # init-e2e globally points at this checkout
npm test              # node code-outline.test.js

License

MIT © weiyuanbj