E2e Cucumber Playwright

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.
• Browser session behavior comes from features/support/hooks.ts:
  • default: authenticated session with shared storage state
  • @unauthenticated: clean browser context
  • @authenticated: readability/selective-run tag only unless implementation changes
  • @fresh: only for e2e:full* flows
• Do not import Playwright Test runner patterns that bypass the current Cucumber + DifyWorld architecture unless the task is explicitly about changing that architecture.

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.
   • 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}.
   • 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.
5. Validate narrowly.
   • Run the narrowest tagged scenario or flow that exercises the change.
   • Run pnpm -C e2e check.
   • 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?

Lead findings with correctness, flake risk, and architecture drift.

References

• references/playwright-best-practices.md
• references/cucumber-best-practices.md