Build Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.
Python agentagentic-aiagentic-frameworkagentic-workflowaiautomationclaudedeepseekgenaigptllmlow-codemcpnextjsno-codeopenaipythonskillsworkflow
docs(web): clarify browser mode focus test boundary (#41692)
yyh6536ffc422ce
diff --git a/web/docs/test.md b/web/docs/test.mdindex 7de60d55f15..d021dcb04ee 100644--- a/web/docs/test.md+++ b/web/docs/test.md@@ -36,22 +36,26 @@ Use the smallest boundary that includes the behavior owner and proves the produc- Test hooks directly only when the hook itself exposes a reusable public contract. Otherwise, exercise the hook through its owning component or feature.- Use React Testing Library for component and feature behavior visible through the DOM or external side effects.- Use integration tests for behavior that crosses meaningful module boundaries.-- Use a real browser for layout, responsive behavior, browser-specific APIs, animation, and focus behavior that `happy-dom` cannot represent faithfully.+- Use the `browser` project only for browser-owned behavior that `happy-dom` cannot represent faithfully.- Follow the [Dify UI testing contract] for the Storybook and Vitest boundary of Dify UI primitives.Test the behavior owner. Barrel exports, pass-through wrappers, and purely presentational children do not need separate tests when the owning feature already proves their contract. Do not repeat generic behavior already owned by Base UI, React Aria, or the browser; test Dify's integration, overrides, and known regressions.### Browser Mode Admission-`happy-dom` is the default choice for tests under `web/`. Use the `unit` project for pure logic, hooks, and DOM-observable component or feature behavior that does not depend on a browser's rendering engine. This split follows [Vitest test projects] and [Why Browser Mode].+`happy-dom` is the default choice for tests under `web/`. Use the `unit` project for pure logic, hooks, and DOM-observable component or feature behavior that does not depend on browser-owned behavior. This split follows [Vitest test projects] and [Why Browser Mode].-Use the `browser` project only when the asserted contract depends on browser-owned behavior that `happy-dom` cannot represent faithfully, such as:+First choose the test scope by the behavior owner, then choose the project by the environment needed to prove the asserted contract—not by an interaction label such as "focus," "keyboard," or "pointer." Use the `unit` project for Dify-owned markup, event handling, and DOM-observable state when `@testing-library/user-event`'s simulation is sufficient for the asserted result. For example, `user.tab()` can protect a focus sequence encoded by simple semantic markup when the assertion is determined by DOM order, disabled state, and `tabindex`; it does not validate the browser's native sequential focus navigation. See the [Testing Library user-event convenience APIs].-- Layout geometry, CSS hit testing, responsive behavior, or pointer targeting.-- Native focus, selection, scrolling, keyboard, or pointer behavior.-- Browser APIs, observers, or animation lifecycles whose real implementation affects the result.+Use the `browser` project only when you can name a browser-owned failure that `happy-dom` could miss, such as:-Rendering UI, reducing mocks, increasing confidence, or raising coverage is not enough reason to use Browser Mode. Each `*.browser.spec.{ts,tsx}` test under `web/app/` must name the browser-owned behavior and why `happy-dom` is insufficient, exercise the smallest owner through semantic locators, and justify its additional runtime. Do not use forced interaction, fixed sleeps, private DOM or CSS assertions, or real network requests.+- CSS layout or rendered visibility changing geometry, hit testing, responsive behavior, or pointer targeting.+- Native focus behavior or focus-event ordering changing because of browser-calculated focusability, `inert`, Shadow DOM traversal, or another browser default.+- Selection, scrolling, real keyboard or pointer input, browser APIs, observers, or animation lifecycles whose native implementation changes the result.++The presence of a portal, focus trap, shadow root, observer, focus assertion, or keyboard or pointer interaction does not justify Browser Mode by itself. Name the browser-owned result it can change; if you cannot name one, Browser Mode is not the right project.++Rendering UI, reducing mocks, increasing confidence, or raising coverage is not enough reason to use Browser Mode. Each `*.browser.spec.{ts,tsx}` test under `web/app/` must exercise the smallest owner through semantic locators and justify its additional runtime with the browser-owned contract. Do not use forced interaction, fixed sleeps, private DOM or CSS assertions, or real network requests.Browser Mode remains a focused component or feature test and currently proves Chromium only. Use the end-to-end suite for a running application, authentication, real routing, backend APIs, persistence, or complete journeys.@@ -179,12 +183,14 @@ Always pass `--project unit` or `--project browser`. Bare `vp test` runs both re- [React Testing Library documentation]- [Testing Library query guidance]- [Testing Library user-event guidance]+- [Testing Library user-event convenience APIs][Dify UI testing contract]: ../../packages/dify-ui/docs/testing.md[React Testing Library documentation]: https://testing-library.com/docs/react-testing-library/intro[Storybook Vitest addon]: https://storybook.js.org/docs/writing-tests/integrations/vitest-addon[Testing Library guiding principles]: https://testing-library.com/docs/guiding-principles[Testing Library query guidance]: https://testing-library.com/docs/queries/about+[Testing Library user-event convenience APIs]: https://testing-library.com/docs/user-event/convenience[Testing Library user-event guidance]: https://testing-library.com/docs/user-event/intro[Vite+ testing configuration]: https://viteplus.dev/guide/test[Vitest Browser Mode documentation]: https://v4.vitest.dev/guide/browser