Comparison

A · AGENTS.md · langgenius/dify B · AGENTS.md · langgenius/dify

What each file covers, counted
Dimension	Shared	Only in A	Only in B	Overlap
Sections	0	2	6	0%
Commands	0	0	10	0%
Section tags	2	2	2	33%

What each file covers

Sections

0 shared · 2 only in A · 6 only in B

− Frontend Workflow
− Package Contracts
+ E2E
+ Commands
+ Runtime Ownership
+ Tags And External Runtime
+ Browser, API, And Contract Boundaries
+ Seeds, Cleanup, And Diagnostics

Commands

0 shared · 0 only in A · 10 only in B

+ pnpm install
+ pnpm -C e2e e2e:install
+ pnpm -C e2e e2e
+ pnpm -C e2e e2e:full
+ pnpm -C e2e e2e -- --tags @smoke
+ pnpm -C e2e e2e:headed -- --tags @smoke
+ pnpm -C e2e seed -- --profile <prepared|external-runtime|post-merge>
+ pnpm -C e2e e2e:reset
+ pnpm -C e2e e2e:middleware:up
+ pnpm -C e2e e2e:middleware:down

Section tags

2 shared · 2 only in A · 2 only in B

− test
− agent-behaviour
+ setup
+ api
code-style
testing-strategy

Line diff

+64 added−11 removed4 unchanged5.9% identical

langgenius/dify · web/AGENTS.md

@@ −1 @@

1## Frontend Workflow

3- Read `docs/test.md` only for frontend test work and `docs/lint.md` only when running or changing static checks.

4- Use the repo-local `how-to-write-component` skill when implementation requires component ownership, state, data-flow, effect, or interaction-boundary decisions. Do not load it for test-only, copy-only, or styling-only changes.

5- Use `frontend-code-review` only for explicit frontend review or audit requests, including test reviews. Use `frontend-testing` when writing or changing Vitest or React Testing Library tests.

7## Package Contracts

9- User-facing strings must use `web/i18n/en-US/` keys. When adding or renaming a key, update every supported locale with the correct localized value.

10- For new backend calls and migrated surfaces, use generated `consoleQuery` / `consoleClient` APIs from `@/service/client`. Do not add handwritten REST helpers or DTO mirrors, mock-backed app state, or direct edits to generated contracts.

11- Prefer `@langgenius/dify-ui/*` primitives, data attributes, and design tokens. Preserve a visible focus indicator on the final focusable element.

12- Follow `docs/overlay.md` for overlay selection and migration. Migrate a legacy overlay only when the current behavior change actually involves that overlay boundary.

13- For custom SVG icons, follow `../packages/iconify-collections/README.md`; do not add generated React icons under `app/components/base/icons/src/`.

14- `docs/test.md` is the single source of truth for frontend automated-test policy. Skills may route and execute that policy but must not redefine it.

langgenius/dify · e2e/AGENTS.md

@@ +1 @@

1# E2E

3This package contains Dify's repository-level Cucumber scenarios with Playwright as the browser layer. This file owns current package architecture, runtime, session and tag semantics, seed, protocol, and cleanup contracts. The repo-local `e2e-cucumber-playwright` skill owns authoring and review methodology; feature-specific facts belong in the nearest feature `AGENTS.md`.

5## Commands

7Run commands from the repository root. Install dependencies and browsers once with `pnpm install` and `pnpm -C e2e e2e:install`. Run only one local `pnpm -C e2e e2e*` process at a time because runners share ports, auth state, and log paths.

9- Existing initialized instance: `pnpm -C e2e e2e`

10- Reset, initialize, and run deterministic scenarios: `pnpm -C e2e e2e:full`

11- Prepare and run scenarios backed by shared fixtures: `E2E_START_AGENT_BACKEND=1 pnpm -C e2e e2e:prepared`

12- Tagged subset: `pnpm -C e2e e2e -- --tags @smoke`

13- Headed debugging: `pnpm -C e2e e2e:headed -- --tags @smoke`

14- Prepare and run external runtime scenarios: `E2E_START_AGENT_BACKEND=1 pnpm -C e2e e2e:external`

15- Seed against existing middleware without running Cucumber: `pnpm -C e2e seed -- --profile <prepared|external-runtime|post-merge>`

16- Reset persisted E2E state: `pnpm -C e2e e2e:reset`

17- Middleware lifecycle: `pnpm -C e2e e2e:middleware:up` and `pnpm -C e2e e2e:middleware:down`

18- Scoped static checks: `vp check e2e`

20The runner reuses `web/.next/BUILD_ID` when present. Set `E2E_FORCE_WEB_BUILD=1` to force a frontend rebuild. Use `E2E_BROWSER=webkit` for focused cross-browser runs and `E2E_SLOW_MO=500` with a headed command for local action debugging.

22## Runtime Ownership

24- `scripts/setup.ts` owns reset, middleware, backend, and frontend startup.

25- `scripts/run-cucumber.ts` is the only E2E runtime orchestrator. It owns service lifetime, optional seed execution, Cucumber invocation, and teardown.

26- `scripts/seed-runner.ts` owns fixture creation and verification against an already-running runtime; it never starts services.

27- `support/web-server.ts` owns frontend reuse, readiness, and shutdown.

28- `features/support/hooks.ts` owns shared auth bootstrap, scenario lifecycle, and diagnostics.

29- `features/support/world.ts` owns `DifyWorld`, the per-scenario behavior `BrowserContext`, and its authenticated setup and cleanup client. Browser and API identities remain separate so unauthenticated and logout journeys cannot invalidate fixture ownership.

30- Cross-actor scenarios keep each actor in a separate `BrowserContext` and typed `DifyWorld` state so diagnostics and cleanup cover every actor.

31- `features/step-definitions/` contains capability-oriented glue; `common/` is reserved for genuinely cross-capability steps.

32- Step definitions that access World state use `async function (this: DifyWorld, ...)`; arrow functions cannot receive Cucumber's bound World instance.

34An uninitialized instance is installed and authenticated lazily; an initialized instance signs in and reuses authenticated state. Full runs prove reset and bootstrap during setup rather than through a Gherkin scenario. Cucumber's exit status is the behavior gate, and the runner also requires at least one `testCaseStarted` message so an empty tag selection cannot pass. Do not replace this gate with scenario-count baselines or skipped-scenario allowlists.

36## Tags And External Runtime

38- Default scenarios use shared authenticated storage state. `@unauthenticated` creates a clean context; `@authenticated` is an intent and selection tag only.

39- `@prepared` requires the prepared fixtures; the post-merge seed profile includes them.

40- `@external-model` and `@external-tool` identify scenarios that call real external runtimes. Deterministic commands exclude these tags; external commands are opt-in.

41- `@microphone` uses the checked-in fake audio fixture and an isolated Chromium context.

42- `@browser-smoke` runs focused keyboard and navigation coverage in Chromium and WebKit CI lanes.

43- Feature-owned services use their own tags. Agent v2 runtime scenarios use `@agent-backend-runtime` and require the explicit runtime-availability step. Set `E2E_START_AGENT_BACKEND=1` to start it locally, or provide `E2E_AGENT_BACKEND_URL` / `AGENT_BACKEND_BASE_URL`.

45Seed and Cucumber must share one runtime lifecycle. Combined commands own reset, middleware, services, seed, Cucumber, and teardown; CI must not reproduce that lifecycle in workflow YAML. `E2E_START_AGENT_BACKEND=1` starts a managed local backend before the API; it is mutually exclusive with an explicit Agent backend URL.

47Do not overload runtime tags to imply unrelated services or silently skip behavior when a required fixture is missing.

49## Browser, API, And Contract Boundaries

51The action under test belongs to the browser. APIs may prepare fixtures, poll persistence, and clean up; they do not replace the user's `When` action. Prefer a user-observable browser result unless persisted backend state is the contract under test.

53For ordinary Console JSON and representable multipart operations, use the scenario- or process-owned generated oRPC client with request and response validation enabled. Call generated operations directly. Do not add handwritten endpoint URLs, duplicate DTOs or schemas, response casts, one-to-one forwarding wrappers, mutable cross-scenario clients, or TanStack Query caching.

55Keep helpers only when they own fixture construction, multi-operation orchestration, cleanup registries, invariants, eventual-consistency polling, narrowed test views, or a protocol adapter. SSE, binary downloads, redirect-only flows, external services, and infrastructure readiness may use centralized adapters under their real owner.

57Validation failures are contract failures. Trace them to the backend schema owner, update `api/controllers/API_SCHEMA_GUIDE.md` contracts when required, regenerate `@dify/contracts`, and keep the scenario aligned with the product's real state owner. Do not disable validation or add fallback schemas to make E2E pass.

59## Seeds, Cleanup, And Diagnostics

61- Generate disposable resource names through `support/naming.ts` with an `E2E` prefix.

62- Keep deterministic upload material in `fixtures/test-materials/` and resolve it through `support/test-materials.ts`.

63- Seed scripts own shared long-lived fixtures; scenarios own disposable resources they create and must register cleanup.

64- Use typed `DifyWorld` cleanup fields for known resource types and `registerCleanup(...)` for additional lifecycle owners. Registered callbacks run LIFO after typed cleanup queues.

65- Remove child and referencing resources before owners. Attach cleanup failures to the report instead of swallowing them.

67Failures produce screenshots and HTML captures under `cucumber-report/artifacts/`; the HTML and Cucumber Messages reports live under `cucumber-report/`. Backend and frontend startup logs live under `.logs/`. Additional CI lanes preserve their own report and log directories.

@@ −1 +1 @@

1−## Frontend Workflow

1+# E2E

3−- Read `docs/test.md` only for frontend test work and `docs/lint.md` only when running or changing static checks.

4−- Use the repo-local `how-to-write-component` skill when implementation requires component ownership, state, data-flow, effect, or interaction-boundary decisions. Do not load it for test-only, copy-only, or styling-only changes.

5−- Use `frontend-code-review` only for explicit frontend review or audit requests, including test reviews. Use `frontend-testing` when writing or changing Vitest or React Testing Library tests.

3+This package contains Dify's repository-level Cucumber scenarios with Playwright as the browser layer. This file owns current package architecture, runtime, session and tag semantics, seed, protocol, and cleanup contracts. The repo-local `e2e-cucumber-playwright` skill owns authoring and review methodology; feature-specific facts belong in the nearest feature `AGENTS.md`.

7−## Package Contracts

5+## Commands

9−- User-facing strings must use `web/i18n/en-US/` keys. When adding or renaming a key, update every supported locale with the correct localized value.

10−- For new backend calls and migrated surfaces, use generated `consoleQuery` / `consoleClient` APIs from `@/service/client`. Do not add handwritten REST helpers or DTO mirrors, mock-backed app state, or direct edits to generated contracts.

11−- Prefer `@langgenius/dify-ui/*` primitives, data attributes, and design tokens. Preserve a visible focus indicator on the final focusable element.

12−- Follow `docs/overlay.md` for overlay selection and migration. Migrate a legacy overlay only when the current behavior change actually involves that overlay boundary.

13−- For custom SVG icons, follow `../packages/iconify-collections/README.md`; do not add generated React icons under `app/components/base/icons/src/`.

14−- `docs/test.md` is the single source of truth for frontend automated-test policy. Skills may route and execute that policy but must not redefine it.

7+Run commands from the repository root. Install dependencies and browsers once with `pnpm install` and `pnpm -C e2e e2e:install`. Run only one local `pnpm -C e2e e2e*` process at a time because runners share ports, auth state, and log paths.

9+- Existing initialized instance: `pnpm -C e2e e2e`

10+- Reset, initialize, and run deterministic scenarios: `pnpm -C e2e e2e:full`

11+- Prepare and run scenarios backed by shared fixtures: `E2E_START_AGENT_BACKEND=1 pnpm -C e2e e2e:prepared`

12+- Tagged subset: `pnpm -C e2e e2e -- --tags @smoke`

13+- Headed debugging: `pnpm -C e2e e2e:headed -- --tags @smoke`

14+- Prepare and run external runtime scenarios: `E2E_START_AGENT_BACKEND=1 pnpm -C e2e e2e:external`

15+- Seed against existing middleware without running Cucumber: `pnpm -C e2e seed -- --profile <prepared|external-runtime|post-merge>`

16+- Reset persisted E2E state: `pnpm -C e2e e2e:reset`

17+- Middleware lifecycle: `pnpm -C e2e e2e:middleware:up` and `pnpm -C e2e e2e:middleware:down`

18+- Scoped static checks: `vp check e2e`

19+

20+The runner reuses `web/.next/BUILD_ID` when present. Set `E2E_FORCE_WEB_BUILD=1` to force a frontend rebuild. Use `E2E_BROWSER=webkit` for focused cross-browser runs and `E2E_SLOW_MO=500` with a headed command for local action debugging.

21+

22+## Runtime Ownership

23+

24+- `scripts/setup.ts` owns reset, middleware, backend, and frontend startup.

25+- `scripts/run-cucumber.ts` is the only E2E runtime orchestrator. It owns service lifetime, optional seed execution, Cucumber invocation, and teardown.

26+- `scripts/seed-runner.ts` owns fixture creation and verification against an already-running runtime; it never starts services.

27+- `support/web-server.ts` owns frontend reuse, readiness, and shutdown.

28+- `features/support/hooks.ts` owns shared auth bootstrap, scenario lifecycle, and diagnostics.

29+- `features/support/world.ts` owns `DifyWorld`, the per-scenario behavior `BrowserContext`, and its authenticated setup and cleanup client. Browser and API identities remain separate so unauthenticated and logout journeys cannot invalidate fixture ownership.

30+- Cross-actor scenarios keep each actor in a separate `BrowserContext` and typed `DifyWorld` state so diagnostics and cleanup cover every actor.

31+- `features/step-definitions/` contains capability-oriented glue; `common/` is reserved for genuinely cross-capability steps.

32+- Step definitions that access World state use `async function (this: DifyWorld, ...)`; arrow functions cannot receive Cucumber's bound World instance.

33+

34+An uninitialized instance is installed and authenticated lazily; an initialized instance signs in and reuses authenticated state. Full runs prove reset and bootstrap during setup rather than through a Gherkin scenario. Cucumber's exit status is the behavior gate, and the runner also requires at least one `testCaseStarted` message so an empty tag selection cannot pass. Do not replace this gate with scenario-count baselines or skipped-scenario allowlists.

35+

36+## Tags And External Runtime

37+

38+- Default scenarios use shared authenticated storage state. `@unauthenticated` creates a clean context; `@authenticated` is an intent and selection tag only.

39+- `@prepared` requires the prepared fixtures; the post-merge seed profile includes them.

40+- `@external-model` and `@external-tool` identify scenarios that call real external runtimes. Deterministic commands exclude these tags; external commands are opt-in.

41+- `@microphone` uses the checked-in fake audio fixture and an isolated Chromium context.

42+- `@browser-smoke` runs focused keyboard and navigation coverage in Chromium and WebKit CI lanes.

43+- Feature-owned services use their own tags. Agent v2 runtime scenarios use `@agent-backend-runtime` and require the explicit runtime-availability step. Set `E2E_START_AGENT_BACKEND=1` to start it locally, or provide `E2E_AGENT_BACKEND_URL` / `AGENT_BACKEND_BASE_URL`.

44+

45+Seed and Cucumber must share one runtime lifecycle. Combined commands own reset, middleware, services, seed, Cucumber, and teardown; CI must not reproduce that lifecycle in workflow YAML. `E2E_START_AGENT_BACKEND=1` starts a managed local backend before the API; it is mutually exclusive with an explicit Agent backend URL.

46+

47+Do not overload runtime tags to imply unrelated services or silently skip behavior when a required fixture is missing.

48+

49+## Browser, API, And Contract Boundaries

50+

51+The action under test belongs to the browser. APIs may prepare fixtures, poll persistence, and clean up; they do not replace the user's `When` action. Prefer a user-observable browser result unless persisted backend state is the contract under test.

52+

53+For ordinary Console JSON and representable multipart operations, use the scenario- or process-owned generated oRPC client with request and response validation enabled. Call generated operations directly. Do not add handwritten endpoint URLs, duplicate DTOs or schemas, response casts, one-to-one forwarding wrappers, mutable cross-scenario clients, or TanStack Query caching.

54+

55+Keep helpers only when they own fixture construction, multi-operation orchestration, cleanup registries, invariants, eventual-consistency polling, narrowed test views, or a protocol adapter. SSE, binary downloads, redirect-only flows, external services, and infrastructure readiness may use centralized adapters under their real owner.

56+

57+Validation failures are contract failures. Trace them to the backend schema owner, update `api/controllers/API_SCHEMA_GUIDE.md` contracts when required, regenerate `@dify/contracts`, and keep the scenario aligned with the product's real state owner. Do not disable validation or add fallback schemas to make E2E pass.

58+

59+## Seeds, Cleanup, And Diagnostics

60+

61+- Generate disposable resource names through `support/naming.ts` with an `E2E` prefix.

62+- Keep deterministic upload material in `fixtures/test-materials/` and resolve it through `support/test-materials.ts`.

63+- Seed scripts own shared long-lived fixtures; scenarios own disposable resources they create and must register cleanup.

64+- Use typed `DifyWorld` cleanup fields for known resource types and `registerCleanup(...)` for additional lifecycle owners. Registered callbacks run LIFO after typed cleanup queues.

65+- Remove child and referencing resources before owners. Attach cleanup failures to the report instead of swallowing them.

66+

67+Failures produce screenshots and HTML captures under `cucumber-report/artifacts/`; the HTML and Cucumber Messages reports live under `cucumber-report/`. Backend and frontend startup logs live under `.logs/`. Additional CI lanes preserve their own report and log directories.

1568