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