test-setup

name

test-setup

description

Set up a frontend project's testing architecture from scratch: unit tests + end-to-end (e2e) tests + a shared mock layer with a single fixtures source, then produce a "how to run" report. Framework-agnostic recommended stack — Vue or React, Vitest, Playwright, MSW — with templates for both monorepo (pnpm/turbo, npm/yarn workspaces) and single-package layouts, and CI templates for GitHub Actions and GitLab CI. 为前端项目从零配置测试架构：单测 + e2e + 共享 mock 层（fixtures 单一数据源），并产出"怎么跑"的接入报告。推荐栈框架无关，支持 monorepo 与单包，附 GitHub Actions 与 GitLab CI 模板。 Use this skill whenever the user wants to: - "/test-setup", "配置测试 / 搭测试架构 / 接入测试 / 配 e2e / 配单测 / 初始化测试" - "set up testing", "add a test framework", "configure Playwright/Vitest for this project" - "give this app/project the same testing setup", "搬一套测试架构过来" - "tests won't run, help me configure it", "测试环境跑不起来" Trigger even when the user doesn't name a runner — any request to bootstrap/replicate a frontend testing foundation should use this skill.

test-setup

Stand up a project's testing foundation (unit + e2e + shared mock kit + incremental CI) and hand the user a report they can follow to run it.

The recommended stack — Vitest + Playwright + MSW with a single fixtures source — is a battle-tested default, but this skill adapts to the project: detect what's already there, fit the framework (Vue/React) and layout (monorepo/single-package), and don't fight existing choices.

Decide the scenario first

Scenario	Looks like	Strategy
A · New package/app in an existing monorepo that already has a shared test kit	Target is a workspace package alongside an existing shared test package	Reuse the existing kit; just write two config files + scripts + first specs. Lightest.
B · Project with no testing foundation	No shared kit; may be monorepo or single package	Build the foundation per the blueprint (shared kit for monorepo, in-project test/ for single package), then wire each app. Heaviest.

If unsure, ask: where's the target, is it a monorepo, which package manager, which framework.

Workflow

This skill expects parallel execution across multiple contexts: reading references, writing several config files, wiring multiple apps, and smoke-running are independent — fan them out with subagents instead of serial waiting.

Step 0 · Detect the target (parallelizable)

Launch read-only subagents in parallel to confirm:

1. Location & type: scenario A or B; monorepo? (pnpm-workspace.yaml/turbo.json/workspaces field); package manager (pnpm/npm/yarn).
2. Current test state: existing vitest/jest/playwright/cypress config, test dirs, deps — don't clobber what's there.
3. Stack alignment: Vue 3 or React? Vite or other bundler? What does the build config look like (the e2e baseURL/https and the unit runner's transform/deps inlining must align to it)?
4. Reference implementation (scenario A): read the existing shared kit + a sibling app's configs as the template.

Summarize into a setup plan; confirm gray areas with the user before writing.

Step 1 · Prepare the shared foundation

• Scenario A: shared kit exists — skip to Step 2.
• Scenario B: build it per references/blueprint.md. Monorepo → a shared test package (packages/test-kit or similar). Single package → an in-project test/ directory. Move in the mock layer, presets, and mount/render helpers. Templates: references/mock-kit.md, references/config-vitest.md, references/config-playwright.md.

Step 2 · Wire each target app (parallelizable)

Each app is an independent artifact — fan out with generalPurpose subagents. Per app:

1. Unit config (vitest.config.ts): merge the app's bundler config with the shared unit preset; add app-specific coverage excludes here.
2. e2e config (playwright.config.ts): the shared e2e preset with baseURL/https aligned to the app.
3. package.json scripts: test / test:unit / test:coverage / test:e2e family (list in references/config-*.md).
4. Dependencies: add the runner + framework test utils + MSW + jsdom etc. — versions per the target's lockfile / existing deps; never invent versions.
5. First specs: create the e2e dir + one smoke spec + helpers.*, and one minimal unit test, to prove the wiring works.

Full templates in references/config-vitest.md and references/config-playwright.md.

Step 3 · Install & smoke (serial)

Back in the main context:

<pm> install                         # install deps
<pm exec> playwright install <browser> --with-deps   # first time
<pm> --filter <app> test             # unit smoke
<pm> --filter <app> test:e2e         # e2e smoke

If red, see the "common pitfalls" table in references/blueprint.md (jsdom missing APIs, transform/deps inlining for workspace source packages, https/baseURL mismatch, unmocked requests failing loudly).

Step 4 · Configure CI (as needed)

• Scenario A where CI auto-discovers (e.g. turbo --affected): no change needed — say so in the report.
• Otherwise: wire e2e + unit-coverage jobs per references/ci.md (GitHub Actions or GitLab CI; incremental for monorepos; coverage report upload).

Step 5 · Produce the setup report (the deliverable)

Always end with a "how to run" report (template below). This is what the user keeps.

Setup report template

## Testing setup report

### Target
- Scenario: A / B; target: <app/repo>; monorepo: yes/no; package manager; framework

### Files added/changed
- shared foundation (scenario B)
- <app>/vitest.config.* / playwright.config.* / package.json (scripts+deps)
- <app>/e2e/ (helpers + smoke spec)
- CI

### Smoke result
- unit: X passed / e2e: X passed

### How to run (hand to the user)
Local:
- install browsers (first time): <cmd>
- unit: <cmd>   # watch / coverage variants
- e2e: <cmd>    # headed / UI-debug variants
CI:
- when it runs / incremental behavior

### Next steps
- Use /test-gen to generate real specs (split unit/e2e)
- Keep all mock data in the shared fixtures (single source)

### Reuse check
Checked <shared kit / sibling configs>; reused ...; did not reuse because ...

Key constraints

1. Never invent dependency versions — use the target's lockfile, packageManager field, existing deps.
2. Single source of mock data: fixtures in the shared kit; no per-app copies.
3. e2e intercepts at the network layer (page.route/cy.intercept), not a Service Worker — SW is unstable under self-signed https + fetch-wrapping monitors. A learned trade-off.
4. No test backdoors in business code: reach special UI via the app's own dev/debug entry.
5. Align to the bundler config: e2e baseURL/https and unit transform/deps-inlining must match the app, or the server won't start / workspace source packages won't transpile.

Reference files

• references/blueprint.md — Full blueprint: shared-kit structure, per-scenario checklists (mono/single, Vue/React), common pitfalls.
• references/config-vitest.md — Vitest config + preset + setup templates (Vue & React).
• references/config-playwright.md — Playwright config + preset + package.json scripts.
• references/mock-kit.md — Shared mock layer: fixtures, MSW handlers, installApiMocks (page.route), mount/render helpers.
• references/ci.md — GitHub Actions and GitLab CI job templates (incremental for monorepos).