e2e-test-narrative-builder
Assembles a multi-step end-to-end user-journey test from a list of high-level user intents - translates each intent ("user signs up", "user adds product to cart", "user completes checkout with promo code") into the corresponding test-runner step (Playwright / Cypress / Selenium / Karate), wires shared state across steps via test fixtures, and emits the resulting test as a single Scenario in the project's E2E framework. Use when scaffolding an E2E test that exercises a complete user flow rather than a single page.
Install with skills.sh (any agent)
npx skills add testland/qa --skill e2e-test-narrative-buildere2e-test-narrative-builder
Overview
This skill takes a high-level intent list and assembles a single narrative test - named user-language intents map to framework-native steps, so one UI refactor updates one mapping, not every test:
1. user_signs_up_with_email
2. user_confirms_email
3. user_creates_workspace
4. user_invites_teammate
5. user_completes_first_task→ One .spec.ts (or .feature) with the canonical sequence.
When to use
Step 1 - Capture the intent list
A typical user-journey test has 5-15 intents:
test:
name: New user onboards and completes first task
fixtures: [seed_workspace, seed_admin_user] # from seed-data-curator
steps:
- intent: user_visits_landing_page
page: /
- intent: user_clicks_signup
- intent: user_fills_signup_form
data:
email: '{{ faker.email }}'
password: '{{ faker.password }}'
- intent: user_submits_signup
- intent: user_confirms_email_via_inbox
- intent: user_creates_workspace
data:
name: 'Test Workspace'
- intent: user_invites_teammate
data:
teammate_email: 'teammate@example.com'
- intent: user_creates_first_task
data:
title: 'Hello world'
- intent: user_marks_task_complete
assertions:
- on_page: /workspace/{workspace_id}
- selector_visible: '[data-testid="task-complete-celebration"]'
- api_called: POST /api/tasks/completeIntents are named verbs in user-language. They abstract over "click the button with text 'Sign up'" - the matching helper function (in step 2) knows how.
Step 2 - Define the intent → step mapping
Once per project, a mapping file translates intents to framework- native code. Each intent is one async function that drives the UI and optionally shares state via ctx:
// e2e/intents/index.ts (Playwright)
export const intents = {
user_clicks_signup: async (page: Page) =>
page.getByRole('link', { name: 'Sign up' }).click(),
user_fills_signup_form: async (page: Page, ctx: any, data: any) => {
await page.getByLabel('Email').fill(data.email);
ctx.email = data.email; // share state with later intents
},
};The mapping is the project's - it knows how the UI is laid out; adding or refactoring an intent is one edit. Full mapping plus the Cypress and Karate variants: references/intent-mapping.md.
Step 3 - Generate the test
The skill emits the matching .spec / .feature file.
Default: Playwright - first-party TypeScript types, built-in fixtures + parallelism, role/label-based selectors that survive UI refactors. Use Cypress when the project already standardizes on it; use Karate for pure-API journeys; use Selenium only for legacy suites already invested in it. Cypress and Karate output shapes: references/intent-mapping.md.
Playwright
// e2e/onboarding.spec.ts
import { test, expect } from '@playwright/test';
import { intents } from './intents';
test('new user onboards and completes first task', async ({ page }) => {
const ctx = { baseUrl: process.env.BASE_URL ?? 'http://localhost:3000' };
await intents.user_visits_landing_page(page, ctx);
await intents.user_clicks_signup(page, ctx);
await intents.user_fills_signup_form(page, ctx, {
email: 'newuser@example.com',
password: 'TestPass123!',
});
await intents.user_submits_signup(page, ctx);
await intents.user_confirms_email_via_inbox(page, ctx);
await intents.user_creates_workspace(page, ctx, { name: 'Test Workspace' });
await intents.user_invites_teammate(page, ctx, { teammate_email: 'teammate@example.com' });
await intents.user_creates_first_task(page, ctx, { title: 'Hello world' });
await intents.user_marks_task_complete(page, ctx);
// Assertions
await expect(page).toHaveURL(/\/workspace\/[a-z0-9-]+/);
await expect(page.locator('[data-testid="task-complete-celebration"]')).toBeVisible();
});Step 4 - Wire fixtures
Each intent may depend on fixtures generated by:
| Fixture source | Skill |
|---|---|
| Seed data (workspaces, admin users) | seed-data-curator. |
| Synthetic field values (emails, passwords) | faker-data etc. |
| Mock external services (email, payment) | wiremock-stubs, msw-handlers, mountebank-imposters. |
The intent file declares fixtures: [...] and the generated test imports them at the top.
Output format
## E2E Narrative Generated - `<test-name>`
**Framework:** Playwright | Cypress | Selenium | Karate
**Intents used:** N
**Test file:** `e2e/<slug>.spec.ts`
**Fixtures referenced:**
- seed_workspace (from seed-data-curator)
- mock_email_inbox (from wiremock-stubs)
**Output preview:**
```typescript
// (the generated test file)
```
### Validation
- All intents have matching entries in `e2e/intents/index.ts`.
- All referenced fixtures exist in the project.
- Test compiles (TypeScript / JS lint pass).
- (Optional) test runs once locally and passes against a seeded env.
### Open intents (require new helpers)
- `user_completes_payment_with_apple_pay` - not yet in the intent
mapping. Add to `e2e/intents/index.ts` before this test will run.
Anti-patterns
| Anti-pattern | Why it fails | Fix |
|---|---|---|
| Inline Playwright calls instead of named intents | Tests break on UI refactors; can't migrate frameworks easily. | Always go through the intent mapping. |
| One mega-intent that does 5 things | Hard to compose with other tests; failure attribution unclear. | One intent per user-observable action. |
Intent names that include implementation details (user_clicks_xpath) | Couples the intent to a selector strategy. | Intent names are user-language: user_signs_up, not user_clicks_signup_button. |
| Sharing context via globals | Cross-test pollution; flaky. | Pass ctx through every intent; per-test scope. |
| Authoring 50-step narrative tests | Single-test failure cascades; hard to debug. | Split into smaller stories; reuse intents across multiple smaller tests. |
Limitations
References
Intent -> step mapping and framework variants
View source (opens in new window)Intent -> step mapping and framework variants
The intent mapping lives once per project and translates each named user-language intent into framework-native code. Adding a new intent or refactoring one is a single edit; every test authored later uses the new shape.
Full Playwright mapping (e2e/intents/index.ts)
import { Page, expect } from '@playwright/test';
export const intents = {
user_visits_landing_page: async (page: Page, ctx: any) => {
await page.goto(ctx.baseUrl);
},
user_clicks_signup: async (page: Page) => {
await page.getByRole('link', { name: 'Sign up' }).click();
},
user_fills_signup_form: async (page: Page, ctx: any, data: any) => {
await page.getByLabel('Email').fill(data.email);
await page.getByLabel('Password').fill(data.password);
ctx.email = data.email; // share state with later intents
ctx.password = data.password;
},
user_submits_signup: async (page: Page) => {
await page.getByRole('button', { name: 'Create account' }).click();
await expect(page).toHaveURL(/\/welcome/);
},
user_confirms_email_via_inbox: async (page: Page, ctx: any) => {
const link = await getEmailConfirmLink(ctx.email); // reads from a Mailpit / Inbucket fixture
await page.goto(link);
},
// ... etc
};Cypress
Same intent set, Cypress chained-command bodies: each intent maps to cy.get(...) / cy.findByRole(...) calls sharing state through a ctx object passed between commands.
Karate (pure-API journeys)
Feature: New user onboards and completes first task
Background:
* url 'http://localhost:3000'
Scenario: Onboarding flow
Given path '/'
When method GET
Then status 200
Given path '/signup'
And request { email: '#{newuser@example.com}', password: 'TestPass123!' }
When method POST
Then status 201
# ... more steps(Per karate-testing.)
Related skills
bogus-data
Authors .NET test fixtures using the Bogus library - fluent typed `Faker` builders with `.RuleFor` per property, generation via `Generate()` / `GenerateBetween(min, max)` / `GenerateLazy()`, and `UseSeed()` for reproducibility. Provides the Bogus equivalent of Python's Faker / Ruby's FactoryBot. Use when the project is C# / F# / VB.NET and the team needs typed fixture creation.
boundary-value-generator
Generates boundary-value test cases from typed input specifications - for each input field, produces the canonical 6-point set (one below, at, and above the lower bound; one below, at, and above the upper bound) plus equivalence-class representatives. Emits cases as parameterized test inputs (pytest @parametrize / Jest test.each / xUnit InlineData / etc.). Use when a function or endpoint has numeric / string-length / collection-size constraints and the team needs systematic edge-case coverage.
factory-bot-data
Authors Ruby FactoryBot factories with traits, associations, sequences, and the three build strategies (build / create / build_stubbed); integrates with RSpec / Minitest test suites; pairs with Faker for randomized field values. Use when the project is Ruby / Rails and needs structured fixture creation with referential integrity.
faker-data
Authors test-data factories using Faker: the Python `faker` library, the `@faker-js/faker` JS port, and the `faker-ruby` gem. Owns the library mechanics end to end: install per language, the provider catalogue (person / internet / location / date / finance / lorem), locale selection and multi-locale mode, and seed-based determinism for reproducible runs. Scope is generating fresh values for tests that start from nothing, not replacing values inside an existing dataset that already holds real records, which raises referential-integrity and re-identification concerns this skill does not address. Prefer this skill when the codebase already uses the Faker family or when cross-language consistency across Python, JS, and Ruby matters; use mimesis-data only when deeper Python locale coverage is the primary requirement. Use when authoring fixtures or factories that need realistic-looking field values.
golden-file-conventions
Reference catalog for snapshot / golden file management - naming conventions, directory layout, when to add / update / remove a baseline, sanitization (timestamps, IDs, PII), per-OS / per-runtime variant strategy, and review workflow for snapshot diffs in PRs. Use when designing a snapshot-testing convention or auditing an existing one for drift.
malicious-payload-bank
Reference catalog of curated adversarial input payloads keyed by attack class - SQL injection, XSS, SSRF, path traversal, command injection, XXE, prototype pollution, regex DoS, Unicode confusables, header injection - plus per-context guidance for which payloads apply (URL parameter / form input / JSON body / file upload). Use when authoring negative-test cases for input validation, fuzz targets, or a security-focused test suite that needs to exercise the OWASP Top 10 attack surface.
mimesis-data
Authors Python test fixtures using mimesis - a fast, type-hinted, locale-aware test-data generator with 46 locales - covering Person / Address / Internet / Datetime providers and the Schema/Field pattern for typed-dict generation. Pairs with factory_boy when referential integrity is needed. Use when the project is Python and the team values speed, type hints, or strong locale coverage over Faker's larger ecosystem.
mountebank-imposters
Authors Mountebank imposters (multi-protocol mock servers - HTTP, HTTPS, TCP, SMTP, LDAP, gRPC, WebSockets, GraphQL, and more) by POSTing JSON definitions to the Mountebank control API on port 2525, configures stubs with predicates and responses, and uses record-playback proxy mode to capture upstream traffic. Use when the project needs a multi-protocol mock server beyond HTTP-only tools like WireMock or MSW.
msw-handlers
Authors Mock Service Worker (MSW) request handlers for both browser and Node.js test environments using the `http.get` / `http.post` / `HttpResponse.json` API, wires them via `setupWorker` (browser) or `setupServer` (Node), and manages the test lifecycle (`server.listen` / `resetHandlers` / `close`). Use when the project uses JavaScript / TypeScript and needs to mock fetch / XHR at the network layer for both Vitest / Jest unit tests and Cypress / Playwright integration tests.
negative-test-generator
Generates negative / error-path test cases that mirror happy-path tests - for each happy-path test, produces companions exercising input validation rejection, missing required fields, type mismatches, authorization failures, rate-limit errors, and adversarial payloads from the malicious-payload-bank. Emits cases as parameterized tests in the project's runner format. Use when a feature has happy-path coverage but the rejection / error / unauthorized paths are untested.
pairwise-test-case-generator
Generates parameterized test inputs combining boundary-value, equivalence-class, and pairwise-combinatorial cases from a typed multi-input specification - produces the cross-product of cases up to a configurable strength (1-wise / 2-wise / N-wise) using all-pairs reduction so the test surface stays tractable. Emits cases in the project's test-runner-native parametrize format. Use when a function or endpoint takes 3+ inputs whose interactions matter and full Cartesian product would explode.
seed-data-curator
Builds a reproducible E2E seed dataset for the project's test environments - picks a representative user / org / data-product cross-section, generates the rows via the project's chosen factory library (FactoryBot / mimesis / Bogus / Faker + factory_boy), persists the dataset as a checked-in fixture (SQL dump / JSON / per-engine seed file), and wires it into the test bootstrap. Use when starting E2E coverage on a project that has no seed strategy, or when an existing seed has drifted.
synthetic-data-tool-selector
Chooses between the four mainstream synthetic test-data generators - Faker (JavaScript), FactoryBot (Ruby), mimesis (Python), Bogus (.NET) - picks the right tool by language and use case (raw value generation vs. typed factory orchestration), shows side-by-side equivalents for the same fixture across all four, and emits the language-appropriate code. Use when starting test-data work on a project and the team wants the "which tool should I use" decision documented.
synthetic-pii-generator
Generates realistic-but-fake personally identifiable information (PII) - emails, phone numbers, SSNs / national IDs, addresses, names, credit-card numbers (test BIN ranges), date-of-birth - for non-production environments. Wraps Faker / mimesis with PII-aware constraints so generated values match real format expectations (Luhn-valid card numbers, region-valid phone formats, ITIN/SSN format) without ever generating real-person data. Use when seeding test environments, building demo data, or replacing real PII in copied datasets.
test-data-patterns
Pure reference catalog of the cross-language object-construction patterns for test data - Test Data Builder (Pryce/Freeman), Factory (with traits and associations), Object Mother, Fixture composition (per-test / per-describe / shared), Snapshot (defers to `golden-file-conventions` for the operational details), and Production-Data Anonymisation. Distinct from per-language data wrappers (`factory-bot-data` Ruby, `faker-data` JS, `mimesis-data` Python, `bogus-data` .NET) which document tool-specific configuration; this catalog is the architecture-tier reference for choosing **which pattern** before reaching for the tool. Use when choosing a test-data construction pattern for a new suite, or auditing an existing suite whose fixtures have drifted into shared mutable state.
wiremock-stubs
Authors WireMock stub mappings for HTTP service mocking - `stubFor` with verb/path/header matchers + `willReturn` response shaping, lifecycle via `WireMockServer` (start / stop) or JUnit `WireMockExtension`, request verification via `verify()`, and dynamic-port allocation for parallel tests. Use when the project is JVM-based and tests need to mock HTTP dependencies (third-party APIs, internal microservices) at the network layer.