e2e-cucumber-playwright

# Dify E2E Cucumber + Playwright Use this skill for Dify's repository-level E2E suite in `e2e/`. Use [`e2e/AGENTS.md`](../../../e2e/AGENTS.md) as the canonical package guide for local architecture and conventions, then read any feature-scoped `AGENTS.md` that owns the target area. Apply Playwright/Cucumber best practices only where they fit the current suite. ## Scope - Use this skill for `.feature` files, Cucumber step definitions, `DifyWorld`, hooks, tags, and E2E review work under `e2e/`. - Do not use this skill for Vitest or React Testing Library work under `web/`; use `frontend-testing` instead. - Do not use this skill for backend test or API review tasks under `api/`. ## Read Order 1. Read [`e2e/AGENTS.md`](../../../e2e/AGENTS.md) first. 2. Read only the files directly involved in the task: - target `.feature` files under `e2e/features/` - related step files under `e2e/features/step-definitions/` - `e2e/features/support/hooks.ts` and `e2e/features/support/world.ts` when session lifecycle or shared state matters - `e2e/scripts/run-cucumber.ts` and `e2e/cucumber.config.ts` when tags or execution flow matter 3. Read [`references/playwright-best-practices.md`](references/playwright-best-practices.md) only when locator, assertion, isolation, or waiting choices are involved. 4. Read [`references/cucumber-best-practices.md`](references/cucumber-best-practices.md) only when scenario wording, step granularity, tags, or expression design are involved. 5. Re-check official Playwright or Cucumber docs with the available documentation tools before introducing a new framework pattern. Keep this skill focused on Cucumber, Playwright, and package-level E2E guidance. Put feature-specific conventions in the owning feature's `AGENTS.md` instead of adding them here. ## Local Rules - `e2e/` uses Cucumber for scenarios and Playwright as the browser layer. - `DifyWorld` is the per-scenario context object. Type `this` as `DifyWorld` and use `async function`, not arrow functions. - Keep glue organized by capability under `e2e/features/step-definitions/`; use `common/` only for broadly reusable steps. - Treat `e2e/AGENTS.md`, `features/support/hooks.ts`, and the Cucumber configuration as the owners of current session and tag semantics. Verify them when behavior depends on session state instead of copying a tag inventory into this skill. - Do not import Playwright Test runner patterns that bypass the current Cucumber + `DifyWorld` architecture unless the task is explicitly about changing that architecture. - Perform the behavior under test through Playwright. APIs are allowed for setup, seed preparation, persistence polling, and cleanup, but ordinary Console JSON and representable multipart operations must use the scenario- or process-owned generated oRPC client with request and response validation enabled. Keep the setup/cleanup API identity independent from an unauthenticated or logged-out behavior browser. - Consume generated operations directly. Do not add one-to-one API wrappers, handwritten endpoint URLs, response DTO casts, duplicate schemas, global mutable clients, or TanStack Query caching in Cucumber. Keep helpers only for real fixture construction, multi-operation orchestration, invariants, polling, derived test views, or protocol adapters. - Keep SSE, binary, redirect-only, external-service, and readiness exceptions centralized under their protocol owner. A contract mismatch must fail and be fixed at the backend schema owner followed by regeneration; never weaken validation to make E2E pass. ## Workflow 1. Rebuild local context. - Inspect the target feature area. - Reuse an existing step when wording and behavior already match. - Add a new step only for a genuinely new user action or assertion. - Before adding several similar steps, scan the target capability for an existing domain noun that can be parameterized without hiding behavior. - Keep edits close to the current capability folder unless the step is broadly reusable. 2. Write behavior-first scenarios. - Describe user-observable behavior, not DOM mechanics. - Keep each scenario focused on one workflow or outcome. - Keep scenarios independent and re-runnable. 3. Write step definitions in the local style. - Keep one step to one user-visible action or one assertion. - Prefer Cucumber Expressions such as `{string}` and `{int}`. - Use a bounded regex only when the accepted values are a small explicit domain set and Cucumber Expressions would make the Gherkin less natural. - Do not create one-off steps for each case variant when the same domain action or outcome applies to named surfaces, modes, or resources. - Scope locators to stable containers when the page has repeated elements. - Avoid page-object layers or extra helper abstractions unless repeated complexity clearly justifies them. 4. Use Playwright in the local style. - Prefer user-facing locators: `getByRole`, `getByLabel`, `getByPlaceholder`, `getByText`, then `getByTestId` for explicit contracts. - Use web-first `expect(...)` assertions. - Do not use `waitForTimeout`, manual polling, or raw visibility checks when a locator action or retrying assertion already expresses the behavior. - Use `expect.poll` for API persistence, backend eventual consistency, captured browser events, or other non-DOM state; prefer locator assertions for DOM readiness and visible UI state. - If a product element has real user-facing semantics but no accessible name, prefer fixing that accessible contract over adding a test id. 5. Validate narrowly. - Run the narrowest tagged scenario or flow that exercises the change. - Run the package-required static checks documented in `e2e/AGENTS.md`. - Broaden verification only when the change affects hooks, tags, setup, or shared step semantics. ## Review Checklist - Does the scenario describe behavior rather than implementation? - Does it fit the current session model, tags, and `DifyWorld` usage? - Should an existing step be reused instead of adding a new one? - Are locators user-facing and assertions web-first? - Does the change introduce hidden coupling across scenarios, tags, or instance state? - Does it document or implement behavior that differs from the real hooks or configuration? - Does setup/cleanup use the generated client directly, with any remaining helper owning more than a one-to-one endpoint forward? - Is every raw HTTP call a documented protocol or infrastructure exception rather than an ordinary Console operation? Lead findings with correctness, flake risk, and architecture drift. ## References - [`references/playwright-best-practices.md`](references/playwright-best-practices.md) - [`references/cucumber-best-practices.md`](references/cucumber-best-practices.md)