Dify E2E 測試實踐Cucumber Gherkin 場景、步驟定義與參數(shù)表達式的最佳實踐【免費下載鏈接】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 倉庫內(nèi)置的 E2E 測試技能文檔 cucumber-best-practices.md 展開講解在 Dify 的e2e/目錄Cucumber Playwright 組合中編寫與評審 Gherkin 場景、步驟定義Step Definitions、參數(shù)表達式Cucumber Expressions以及步驟復(fù)用時應(yīng)遵循的方法論。讀完后你將掌握如何把場景寫成“可執(zhí)行的產(chǎn)品行為規(guī)格”、如何在 Dify 的全局步驟命名空間中做真實而非生硬的復(fù)用、如何用{string}等表達式保持 Gherkin 可讀性以及標(biāo)簽Tag體系與 World 狀態(tài)管理的源碼級實現(xiàn)依據(jù)。背景這份規(guī)范在 Dify 測試體系中的位置Dify 的倉庫級 E2E 套件位于 e2e/其架構(gòu)由 e2e/AGENTS.md 定義Cucumber 負責(zé)場景與鉤子Hook的調(diào)度和報告Playwright 提供瀏覽器自動化、上下文、定位器、斷言、請求與追蹤 API。配套的倉庫級技能文檔 SKILL.md 明確了主題路由場景措辭、步驟粒度、表達式、World 狀態(tài)、鉤子可見性或標(biāo)簽設(shè)計問題歸屬本文所講的 Cucumber 最佳實踐參考文檔而定位器、斷言、隔離與等待決策則歸屬 playwright-best-practices.md。也就是說本文的規(guī)范不是泛泛而談的 BDD 口號而是直接服務(wù)于 Dify 這套真實運行的回歸套件默認場景復(fù)用共享的已認證存儲狀態(tài)標(biāo)簽驅(qū)動選擇范圍Cucumber 退出碼是行為門禁且 runner 要求至少有一條testCaseStarted消息以防止空的標(biāo)簽選擇“假通過”。原則一把場景當(dāng)作可執(zhí)行規(guī)格來寫原文檔的第一條核心建議是Cucumber 場景應(yīng)當(dāng)以聲明式方式描述行為而不是復(fù)現(xiàn)一段交互腳本。具體做法寫“用戶做了什么、應(yīng)當(dāng)發(fā)生什么”避免 UI 內(nèi)部措辭如選擇器細節(jié)、DOM 結(jié)構(gòu)或組件名語言要足夠具體使場景讀起來像“活文檔”living documentation。唯一的例外當(dāng)交互機制本身就是被測行為時過程性措辭是合理的例如鍵盤導(dǎo)航、焦點移動或必須按順序執(zhí)行的多角色multi-actor序列。Dify 套件中確實存在這類場景——browser-smoke標(biāo)簽下的鍵盤與導(dǎo)航覆蓋正是“過程即行為”的典型案例。對照倉庫中的真實場景 authenticated-entry.feature可以看到標(biāo)準(zhǔn)寫法smoke authenticated Feature: Authenticated console home Scenario: Open the default console entry with the shared authenticated state Given I am signed in as the default E2E admin When I open the default console entry Then I should be on the console home And I should not see the Sign in button整個場景沒有任何選擇器或 DOM 詞匯Given建立初始上下文When是用戶動作Then/And描述用戶可觀察的結(jié)果。對應(yīng)的步驟定義 navigation.steps.ts 內(nèi)部雖然使用了getByRole等 Playwright 定位手段但這些實現(xiàn)細節(jié)全部封裝在 glue 層不會泄漏到 Gherkin 文本中——這正是“規(guī)格層與自動化層分離”的示范。原則二保持場景聚焦原文檔要求一個場景證明一個業(yè)務(wù)規(guī)則或一個連貫的結(jié)果。Cucumber 社區(qū)“三到五個步驟”的建議只是評審啟發(fā)式而非硬性上限當(dāng)場景變長時應(yīng)檢查是否存在多個結(jié)果、順帶的 setup、或可以下沉到領(lǐng)域步驟背后的 UI 流程。Gherkin 關(guān)鍵字的分工約定Given初始上下文When觸發(fā)事件Then期望結(jié)果。需要強調(diào)的是兩個易被誤讀的點Given/When/Then 階段的重復(fù)不是自動失敗而是一個“重新審視敘事”的信號避免隱藏依賴場景之間不得依賴彼此的副作用。此外原文檔對Rule和Background給出了明確取舍用Rule包裝“多個示例說明同一條具名業(yè)務(wù)規(guī)則”的情形Background只用于讀者理解場景所必需的共享上下文不要在里面隱藏 fixture 準(zhǔn)備、運行時就緒檢查或冗長 setup。Dify 套件對此有配套約束種子腳本seed擁有共享的長生命周期 fixture場景擁有自己創(chuàng)建的臨時資源并必須注冊清理見 e2e/AGENTS.md 的 “Seeds, Cleanup, And Diagnostics” 一節(jié)。這保證了Background里不會出現(xiàn)“偷偷初始化環(huán)境”的黑盒fixture 的歸屬始終可追溯。原則三復(fù)用步驟但只在行為真正一致時復(fù)用原文檔將“壞的復(fù)用”概括為一句話好的復(fù)用減少重復(fù)壞的復(fù)用隱藏語義。應(yīng)當(dāng)優(yōu)先復(fù)用的情形用戶動作確實是同一個動作期望結(jié)果確實是同一個結(jié)果措辭在不同 feature 中仍然自然參數(shù)是真實的產(chǎn)品領(lǐng)域值如具名的界面、模式、資源或狀態(tài)。應(yīng)當(dāng)另寫新步驟的情形行為存在實質(zhì)性差異強行復(fù)用舊措辭會讓場景產(chǎn)生誤導(dǎo)所謂“通用步驟”實際上變成實現(xiàn)細節(jié)的包裝器。總結(jié)論是不要為了壓低步驟數(shù)量而制造模糊步驟而是優(yōu)化出一組“真實、由領(lǐng)域擁有”的步驟。Dify 的步驟定義目錄結(jié)構(gòu)直接體現(xiàn)了這一條。e2e/features/step-definitions/ 按能力域capability組織apps/、auth/、accessibility/、agent-v2/等common/只留給真正跨能力的步驟。同時有一個關(guān)鍵的運行時事實——所有步驟定義共享同一個全局匹配命名空間與它們所在的目錄無關(guān)。目錄只是代碼組織方式不是命名空間隔離。因此步驟定義的組織要按領(lǐng)域能力劃分避免與單個 feature 耦合的 glue表達式不能寬到與不相關(guān)行為重疊否則全局匹配會發(fā)生歧義或沖突。以 create-app.steps.ts 為例I select the {string} app type步驟的參數(shù)是“Chatbot / Workflow”這類真實的產(chǎn)品領(lǐng)域值動作和結(jié)果在多個 feature 中語義一致屬于教科書式的正當(dāng)復(fù)用而I confirm app creation內(nèi)部包含了等待POST /console/api/apps響應(yīng)、用zPostAppsResponse做契約校驗、并把新建應(yīng)用 ID 記入 World 狀態(tài)等實現(xiàn)細節(jié)——這些細節(jié)被封裝在步驟內(nèi)部Gherkin 層只保留一個連貫的領(lǐng)域動作。原則四優(yōu)先使用 Cucumber Expressions原文檔要求除非正則確有必要否則一律使用 Cucumber Expressions。常用形式表達式適用場景{string}標(biāo)簽、名稱、可見文本{int}計數(shù){float}十進制數(shù)值{word}僅當(dāng)值確實是一個不可分割的單詞token時兩條配套紀(jì)律保持表達式可讀。如果一個步驟需要復(fù)雜的解析邏輯先反問是不是場景措辭本身應(yīng)該更簡單只在它能讓 Gherkin 保持可讀時才用有界的自然語言正則替代例如原文檔給出的例子/(Web app|Backend service API)/要避免接受“無主語言”unowned language的寬正則。Dify 的現(xiàn)有步驟定義大量使用{string}且用法克制。例如 navigation.steps.ts 中的I should see the {string} buttonThen(I should see the {string} button, async function (this: DifyWorld, label: string) { await expect(this.getPage().getByRole(button, { name: label })).toBeVisible() })參數(shù)label是按鈕的可見文本——一個真實的產(chǎn)品領(lǐng)域值而不是顏色、索引或內(nèi)部 ID。這類步驟在 smoke、認證、應(yīng)用管理等多個 feature 中被自然復(fù)用措辭在每處都保持誠實恰好落在“原則三”的正當(dāng)復(fù)用區(qū)間內(nèi)。原則五保持步驟定義薄而有意義原文檔對步驟定義給出了三層約束步驟定義是 Gherkin 與自動化之間的膠水不是第二套抽象語言。一個步驟應(yīng)表達一個連貫的領(lǐng)域動作或結(jié)果為了讓 UI 機制不進入規(guī)格層它可以內(nèi)部調(diào)用多個實現(xiàn)輔助函數(shù)。狀態(tài)放在 World 里而不是模塊全局變量。Cucumber 會為每個場景創(chuàng)建新的 World 實例因此場景狀態(tài)必須掛在 World 上以保證場景間隔離。鉤子對 feature 讀者是不可見的。把鉤子留給低層的瀏覽器生命周期、清理與診斷凡與業(yè)務(wù)相關(guān)的上下文一律表達在 Gherkin 中。DifyWorld每條原則的源碼級落地Dify 的 World 實現(xiàn) 是這一原則最完整的證據(jù)。DifyWorld繼承自cucumber/cucumber的World并通過文件末尾的setWorldConstructor(DifyWorld)注冊為全局構(gòu)造器export class DifyWorld extends World { context: BrowserContext | undefined consoleClient: ConsoleClient | undefined page: Page | undefined consoleErrors: string[] [] pageErrors: string[] [] createdAppIds: string[] [] createdAgentIds: string[] [] scenarioCleanups: ScenarioCleanup[] [] // ... } setWorldConstructor(DifyWorld)幾個值得注意的設(shè)計點與原文檔規(guī)范逐條對應(yīng)每場景新 World 顯式狀態(tài)重置構(gòu)造函數(shù)與startSession都會調(diào)用resetScenarioState()把createdAppIds、lastCreatedAppName、agentBuilder等字段歸零。這直接落實了“場景狀態(tài)放 World、不放模塊全局”的隔離要求也讓“場景之間無隱藏副作用依賴”在代碼層面可驗證。瀏覽器與 API 身份分離startSession中瀏覽器上下文僅在authenticated時注入storageState而consoleRequestContext始終持有獨立的 API 請求上下文。e2e/AGENTS.md 對此的解釋是讓瀏覽器身份與 API 身份保持分離未認證unauthenticated和登出logout旅程才不會把 fixture 的 ownership 搞亂。清理是 World 的一等公民registerCleanup(...)收集場景內(nèi)注冊的清理回調(diào)runRegisteredCleanups以 LIFO 順序執(zhí)行并與類型化清理隊列配合。這支撐了“場景擁有自己創(chuàng)建的臨時資源并必須注冊清理”的契約。類型化的this: DifyWorld寫法Cucumber.js 支持通過world代理在箭頭函數(shù)中訪問 World但 Dify 套件一致性地使用類型化的async function (this: DifyWorld, ...)函數(shù)式寫法SKILL.md 與 e2e/AGENTS.md 均將其列為硬性約定。原因是箭頭函數(shù)無法接收 Cucumber 綁定的 World 實例而顯式的this注解讓 World 的所有權(quán)和 TypeScript 類型發(fā)現(xiàn)都保持明確。倉庫中所有步驟定義如 create-app.steps.ts都嚴(yán)格遵循這一模式。一個“薄步驟”的完整示例create-app.steps.ts 中的I confirm app creationWhen(I confirm app creation, async function (this: DifyWorld) { const page this.getPage() const createButton page.getByRole(dialog).getByRole(button, { name: /^Create(?:\s|$)/ }) const responsePromise page.waitForResponse(/* 匹配 POST /console/api/apps */) await expect(createButton).toBeEnabled() await createButton.click() const response await responsePromise expect(response.ok()).toBe(true) const createdApp zPostAppsResponse.parse(await response.json()) this.createdAppIds.push(createdApp.id) })Gherkin 里只有一個連貫動作“我確認創(chuàng)建應(yīng)用”而按鈕定位、響應(yīng)等待、契約校驗zPostAppsResponse是生成的 oRPC 客戶端的 zod schema、狀態(tài)記錄這些實現(xiàn)細節(jié)全部被封裝在步驟內(nèi)部——規(guī)格保持聲明式自動化保持完整。原則六有意地使用標(biāo)簽原文檔對標(biāo)簽的界定是標(biāo)簽可以傳達穩(wěn)定的能力分組、選擇范圍、fixture 依賴或條件鉤子意圖只有當(dāng) runner、seed profile 或鉤子真正“擁有”這個含義時標(biāo)簽才會改變運行時行為。換句話說一個不被任何運行邏輯解釋的標(biāo)簽就是純粹的自欺。Dify 的標(biāo)簽體系定義于 e2e/AGENTS.md 的 “Tags And External Runtime” 一節(jié)是這條原則的完整實例標(biāo)簽運行時歸屬unauthenticated創(chuàng)建干凈無存儲狀態(tài)的瀏覽器上下文authenticated僅是意圖與選擇標(biāo)簽不改變運行行為smoke用于選擇冒煙子集如pnpm -C e2e e2e -- --tags smokeaxe/wcag-a/wcag-aa/wcag-page-slugWCAG 獨立掃描體系被默認功能套件排除選級別時必須同時選axeprepared依賴 seed 的 prepared fixturepost-merge seed profile 會提供external-model/external-tool依賴真實外部運行時確定性命令默認排除外部命令才可選microphone使用檢入的假音頻 fixture 與隔離的 Chromium 上下文browser-smoke在 Chromium 與 WebKit CI 通道運行聚焦的鍵盤與導(dǎo)航覆蓋skip從所有 runner profile 中臨時排除產(chǎn)品行為恢復(fù)后必須移除禁止用于永久或環(huán)境相關(guān)的抑制agent-backend-runtimeAgent v2 運行時場景需要顯式的運行時可用性步驟與E2E_START_AGENT_BACKEND1或后端 URL標(biāo)簽在 runner 層如何“被擁有”可以在 cucumber.config.ts 中直接看到const defaultNonExternalTags not axe and not prepared and not external-model and not external-tool const selectedTags process.env.E2E_CUCUMBER_TAGS || (hasCliTags ? undefined : defaultNonExternalTags) const tags selectedTags ? (${selectedTags}) and not skip : not skip const config { format: [progress-bar, summary, html:./cucumber-report/report.html, message:./cucumber-report/report.ndjson], import: [./tsx-register.js, features/**/*.ts], paths: [features/**/*.feature], tags, timeout: 60_000, }這段配置說明了兩件事默認命令會自動排除 WCAG 掃描、prepared fixture 場景與外部運行時場景且無條件排除skip而smoke、authenticated這類標(biāo)簽只有在選擇器層面生效。原文檔最后一問——“新標(biāo)簽是在記錄真實行為還是在發(fā)明套件并未實現(xiàn)的語義”——在這套配置下有非常具體的檢驗標(biāo)準(zhǔn)如果 runner、seed 或鉤子都不解釋它就不要加它。評審清單合并前的九個問題原文檔給出的 Review Questions 是評審 Gherkin 與步驟定義時的完整檢查表建議逐條過這個場景讀起來像產(chǎn)品行為的真實示例嗎它證明的是一個結(jié)果還是把幾個獨立階段揉在了一起步驟是面向行為的還是面向?qū)崿F(xiàn)的過程性措辭對“被測行為”是否必要一個被復(fù)用的步驟在這個 feature 里仍然保持誠實嗎新表達式是否會在全局命名空間中與已有步驟重疊用Rule能澄清業(yè)務(wù)規(guī)則還是Background會隱藏重要的 setup新標(biāo)簽是在記錄真實行為還是在發(fā)明套件并未實現(xiàn)的語義一個新讀者在不打開步驟定義文件的情況下能理解這個場景的結(jié)果嗎落地如何在 Dify 倉庫中運行與驗證規(guī)范最終要落到可執(zhí)行的命令上。根據(jù) e2e/AGENTS.md從倉庫根目錄執(zhí)行依賴與瀏覽器只需安裝一次pnpm install與pnpm -C e2e e2e:install同一時間只運行一個本地e2e*進程因為 runner 共享端口、認證狀態(tài)與日志路徑# 對已有初始化好的實例直接運行 pnpm -C e2e e2e # 重置、初始化并運行確定性場景 pnpm -C e2e e2e:full # 只跑冒煙子集標(biāo)簽選擇 pnpm -C e2e e2e -- --tags smoke # 有頭模式調(diào)試可配合 E2E_SLOW_MO500 放慢操作 pnpm -C e2e e2e:headed -- --tags smoke # 依賴 prepared fixture 的場景 E2E_START_AGENT_BACKEND1 pnpm -C e2e e2e:prepared結(jié)果產(chǎn)物失敗會在cucumber-report/artifacts/生成截圖與 HTML 捕獲HTML 報告與 Cucumber Messages 報告位于cucumber-report/下前后端啟動日志在.logs/。靜態(tài)檢查可用vp check e2e。寫改動時的紀(jì)律與 SKILL.md 的工作流一致先復(fù)用措辭與行為都匹配的既有步驟都不匹配時再加一個連貫的場景或步驟改動后跑最窄的標(biāo)簽化場景只有當(dāng)改動觸及共享鉤子、標(biāo)簽或 support 代碼時才擴大運行范圍。小結(jié)這份規(guī)范的核心思想可以濃縮為一句話讓 Gherkin 停留在產(chǎn)品行為層把機制、狀態(tài)與清理壓進它們各自的 owner。在 Dify 的 e2e 套件中這體現(xiàn)為按能力域組織的步驟定義與全局唯一命名空間、類型化this: DifyWorld的薄步驟、每場景重建的 World 狀態(tài)與 LIFO 清理注冊表、以及每個標(biāo)簽都有 runner/seed/鉤子解釋的標(biāo)簽體系。對維護 E2E 套件的工程師來說這套實踐的價值不在于讓測試跑起來而在于讓測試在半年后依然讀得懂、找得到、信得過?！久赓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），僅供參考