Dify 的 langgenius/dify-ui 組件包測試體系Vitest 雙項目、Storybook 渲染契約與 a11y 門禁【免費下載鏈接】difyBuild 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.項目地址: https://gitcode.com/GitHub_Trending/di/dify本文以 Dify 倉庫中packages/dify-ui/docs/testing.md這份《Testing and Development》文檔為核心系統(tǒng)講解langgenius/dify-ui組件包的完整測試與開發(fā)工作流如何運行格式化/lint/類型檢查與雙 Vitest 項目、Storybook 故事即渲染契約的測試邊界設(shè)計、Storybook a11y 門禁的配置細節(jié)以及 Base UI 動畫在測試中的處理策略。讀完本文你將能夠在該包中正確選擇測試歸屬unit 還是 storybook、運行全部測試命令、并為組件編寫符合包規(guī)范的單元測試與 Storybookplay測試。一、包的定位與命令入口packages/dify-ui是 Dify 工作區(qū)內(nèi)的私有 UI 原語包langgenius/dify-ui提供獨立 UI 原語、設(shè)計 token、CSS 優(yōu)先的 Tailwind 樣式和cn()工具函數(shù)大部分交互原語是對 Base UI headless 組件的薄而有主見的封裝見 README。測試體系正是圍繞Base UI 上游行為歸上游、Dify 自有契約歸本包這一邊界來組織的。文檔給出的命令分為兩層倉庫根目錄執(zhí)行格式、lint 與 TypeScript 診斷vp check packages/dify-ui在packages/dify-ui/目錄下執(zhí)行測試與 Storybook 命令命令作用vp test --project unit運行原語primitive單元測試vp run storybook啟動 Storybookvp test --project storybook --run以瀏覽器模式運行 Storybook 組件測試vp test同時運行兩個測試項目這些命令與包內(nèi) package.json 中的scripts一一對應(yīng)test: vp test --project unit、test:storybook: vp test --project storybook --run、test:watch: vp test --project unit --watch、storybook: storybook dev -p 6006、type-check: tsc。也就是說vp test這類 vite-plus 命令既可以通過根目錄直接執(zhí)行也可以落到 npm script 上日常調(diào)用二者等價。二、測試邊界兩個 Vitest 項目一個 Chromium 運行時文檔明確了兩點架構(gòu)性事實包內(nèi)配置了兩個 Vitest 項目Vitest projects二者都運行在Playwright Chromium Browser Mode中——項目名標識的是行為歸屬方而不是不同的運行時。Storybook 用于承載有文檔的組件示例每一個 story 都是一份渲染契約render contract并通過 Storybook Vitest addon 運行配置的無障礙檢查。當示例還承擔可見狀態(tài)變化、用戶交互、鍵盤路徑、overlay 流程、表單行為、加載行為、受控狀態(tài)協(xié)同中的任一項時應(yīng)為其添加play測試。普通 Vitest 測試用于更底層的 wrapper 契約如 class 變體cva variants、Base UI 透傳 props、hidden-input 序列化、data-attribute 鉤子、stores以及不需要有文檔示例覆蓋的邊界情況。源碼層面的項目配置印證vite.config.ts 完整實現(xiàn)了這一邊界頂層test.browser開啟enabled: trueprovider 為playwright()實例為chromiumheadless: true失敗時自動截圖screenshotFailures: true截圖落在./.vitest-browser/screenshotsprojects[0]命名unit掛載 Tailwind 插件、開啟globals、加載setupFiles: [./vitest.setup.ts]、include: [src/**/__tests__/**/*.spec.{ts,tsx}]并配置瀏覽器 trace 在失敗時保留trace.mode: retain-on-failureprojects[1]命名storybook通過storybook/addon-vitest/vitest-plugin的storybookTest({ configDir })加載.storybook目錄下的故事并生成測試覆蓋率由 v8 提供include: [src/**/*.{ts,tsx}]排除 stories、__tests__、themes、stylesCI 環(huán)境process.env.CI輸出json json-summary本地額外輸出text報告。這條路徑解釋了為什么unit 項目也要跑在瀏覽器里因為組件依賴真實 DOM、CSS 布局與 Base UI 的 presence 生命周期瀏覽器模式才是與生產(chǎn)一致的驗證環(huán)境。unit 測試實例Button 契約以 Button 單元測試 為例可以看到wrapper 契約測試的典型形態(tài)使用vitest-browser-react的render與vite-plus/test/browser的userEvent斷言默認typebutton、可覆蓋為submit、nativeButton{false}時經(jīng) render prop 渲染為非原生元素斷言disabled使用原生語義toBeDisabled()且不帶aria-disabledloading狀態(tài)可通過focusableWhenDisabled{false}選擇退出焦點斷言 loading 中的 submit 按鈕不會隱式觸發(fā)表單提交——這正是文檔所說不需要有文檔示例的底層契約的典型用例。三、無障礙a11y門禁test error與唯一的 color-contrast 例外文檔對 a11y 的約定非常嚴格Storybook 無障礙測試使用a11y.test error任何被啟用的違例會直接讓測試失敗顏色對比度color-contrast是唯一被全局禁用的規(guī)則原因是它是已知的設(shè)計 token 缺口known design-token gap明確規(guī)定不要新增任何全局例外臨時例外必須局部化到受影響的 story不要用play測試來替代一個無障礙修復(fù)。這一約定在 .storybook/preview.tsx 中逐行落實a11y: { test: error, config: { rules: [ { id: color-contrast, enabled: false, }, ], }, },同時該 preview 文件通過withThemeByDataAttribute裝飾器以data-theme屬性切換light/dark主題默認 light并以tags: [autodocs]為每個 story 自動生成文檔頁。而 .storybook/main.ts 聲明了故事發(fā)現(xiàn) glob../src/**/*.stories.(js|jsx|mjs|ts|tsx)、react-vite框架以及addon-a11y、addon-vitest、addon-docs、addon-themes等插件鏈——a11y與vitest兩個 addon 正是story 即契約 違規(guī)即失敗機制的執(zhí)行者。實踐含義如果你在某個 story 中確實需要臨時豁免某條 a11y 規(guī)則應(yīng)把該豁免寫在對應(yīng) story 的局部配置里而不是回到 preview 里再加一條enabled: false。四、動畫測試策略BASE_UI_ANIMATIONS_DISABLED標志Base UI 在卸載由 transition 驅(qū)動的原語前會等待element.getAnimations()。當測試斷言的是最終 DOM 狀態(tài)而非動畫行為本身時文檔要求在 Vitest setup 文件中關(guān)閉動畫;( globalThis as typeof globalThis { BASE_UI_ANIMATIONS_DISABLED: boolean } ).BASE_UI_ANIMATIONS_DISABLED true包內(nèi)三處相關(guān)配置分別對應(yīng)文檔中的三條規(guī)則unit 項目默認關(guān)閉動畫vitest.setup.ts 正是文檔中代碼片段的落地此外它還引入./vitest.css并將document.documentElement.dataset.theme固定為light保證主題變量與故事一致Storybook 項目保留真實動畫生命周期文檔明確指出 Storybook 使用其 preview setupmust retain real animation lifecycles因此vitest.setup.ts只對 unit 項目生效見 vite.config.ts 中僅 unit 項目配置setupFiles有意斷言動畫行為的單測可局部恢復(fù)為false但必須在 cleanup 中還原舊值。倉庫中已有兩處示范這一模式popover 測試約 L41-L69在測試前讀取并保存animationSettings.BASE_UI_ANIMATIONS_DISABLED置為false在 teardown 中還原為animationsDisabledtoast 測試L93-L162 附近同樣先保存animationState測試中關(guān)閉禁用標志結(jié)束后還原。這種保存—改寫—還原的寫法避免了測試間的全局狀態(tài)污染是遵循文檔要求的具體實現(xiàn)范式。五、端到端自查流程綜合文檔與倉庫配置修改packages/dify-ui中的一個組件后的完整驗證流程為在packages/dify-ui/下運行vp test --project unit確認新增/修改的 wrapper 契約class 變體、透傳 props、data-attribute 鉤子等通過在packages/dify-ui/下運行vp test --project storybook --run確認所有 story 的渲染契約與 a11y 檢查通過違規(guī)會因test error而失敗需要交互式核對組件行為時運行vp run storybook打開 6006 端口的 Storybook注意 Storybook 保留真實動畫驗證 presence/transition 相關(guān)行為時不要依賴 unit 項目的動畫禁用標志回到倉庫根目錄運行vp check packages/dify-ui完成格式化、lint 與 TypeScript 診斷若涉及動畫相關(guān)的 DOM 狀態(tài)斷言確認你的測試落在 unit 項目setup 已自動關(guān)閉動畫若要斷言動畫本身參考 popover/toast 的測試寫法在局部臨時恢復(fù)BASE_UI_ANIMATIONS_DISABLED false并保證 cleanup 還原。關(guān)鍵文件索引關(guān)注點文件本文核心文檔testing.md命令腳本package.json雙項目與瀏覽器模式配置vite.config.tsunit 項目 setup 與動畫禁用vitest.setup.tsa11y 門禁與主題裝飾器preview.tsxStory 發(fā)現(xiàn)與 addon 鏈main.tsunit 測試示例button/index.spec.tsx動畫標志的局部恢復(fù)范式popover/index.spec.tsx、toast/index.spec.tsx這套體系的核心思想可以概括為用瀏覽器模式統(tǒng)一運行時用項目名劃分行為歸屬用 Storybook 把文檔示例升級為可執(zhí)行的渲染契約用error級別的 a11y 檢查把可訪問性變成 CI 硬門禁并用一個全局動畫標志在斷言狀態(tài)與斷言動畫兩類測試之間做出清晰取舍?！久赓M下載鏈接】difyBuild 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.項目地址: https://gitcode.com/GitHub_Trending/di/dify創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考