收測試：@umbraco/acceptance-test-helpers 端到端測試助手包使用指南)
CMS后端【免費(fèi)下載鏈接】Umbraco-CMSUmbraco is a free and open source .NET content management system helping you deliver delightful digital experiences.項(xiàng)目地址https://gitcode.com/gh_mirrors/um/Umbraco-CMS點(diǎn)擊查看免費(fèi)下載本篇技術(shù)指南介紹 Umbraco CMS 官方驗(yàn)收測試工程中發(fā)布的 npm 測試助手包umbraco/acceptance-test-helpers它基于 Playwright 提供 API 助手umbracoApi、UI 交互助手umbracoUi與 JSON 模型 Builder 三類能力用于簡化 Umbraco backoffice 功能的端到端測試。讀完本文你將掌握該包的安裝與認(rèn)證配置、自定義testfixture 的用法、API/UI 助手的完整清單、常量與 Builder 的調(diào)用方式并能結(jié)合倉庫源碼理解其底層認(rèn)證與默認(rèn)值機(jī)制直接上手編寫可復(fù)現(xiàn)的 Umbraco 驗(yàn)收測試。一、包概覽它解決什么問題umbraco/acceptance-test-helpers是為編寫 Umbraco CMS 解決方案的 Playwright 端到端測試而設(shè)計(jì)的輔助庫核心由三部分組成API helpersumbracoApi通過 Umbraco Management API 完成服務(wù)端的數(shù)據(jù)準(zhǔn)備setup、清理teardown與斷言比純 UI 操作更快、更穩(wěn)定UI helpersumbracoUi封裝 backoffice 各區(qū)塊的瀏覽器交互動作如導(dǎo)航、點(diǎn)擊、填寫表單、斷言保存狀態(tài)JSON model builders以流式fluentAPI 構(gòu)建復(fù)雜的 Umbraco JSON 數(shù)據(jù)模型文檔類型、數(shù)據(jù)類型、文檔、媒體、成員、用戶等配合合理的默認(rèn)值減少樣板代碼。該工程位于倉庫 tests/Umbraco.Tests.AcceptanceTest 目錄其倉庫級使用說明見 README.md。本文所述包內(nèi)容即由該目錄下lib/中的源碼編譯發(fā)布而來入口見 lib/index.ts。二、安裝在已初始化的 Node.js 項(xiàng)目中安裝為開發(fā)依賴npm install -D umbraco/acceptance-test-helpers倉庫內(nèi) package.json 展示了該包自身的工程化信息可作為集成時的參考包的peerDependencies要求playwright/test 1.56即宿主項(xiàng)目需要安裝兼容版本的 Playwright包的入口為dist/index.js與dist/index.d.ts通過exports字段暴露包自身以 TypeScript 編寫構(gòu)建命令為tsc -p tsconfig.build.json。注意文檔與 README 中使用的包名為umbraco/acceptance-test-helpers倉庫內(nèi)package.json的name字段寫作umbraco-cms/acceptance-test-helpers安裝時請以發(fā)布在 npm registry 上的實(shí)際名稱為準(zhǔn)README 中給出的安裝命令即umbraco/acceptance-test-helpers。三、運(yùn)行前配置連接與認(rèn)證環(huán)境變量測試助手需要知道如何連接并認(rèn)證你的 Umbraco 實(shí)例。運(yùn)行測試前需設(shè)置以下環(huán)境變量變量必填默認(rèn)值說明URL否https://localhost:44339Umbraco 實(shí)例的基礎(chǔ) URLUMBRACO_USER_LOGIN是—Backoffice 超級管理員superadmin郵箱UMBRACO_USER_PASSWORD是—Backoffice 超級管理員密碼STORAGE_STATE_PATH推薦—Playwright 認(rèn)證存儲狀態(tài) JSON 的路徑應(yīng)與playwright.config中的storageState一致。API 助手會從該文件讀取 token 用于 REST 調(diào)用未設(shè)置時 token 將從實(shí)時頁面上下文中提取速度更慢、可靠性更低。CONSOLE_ERRORS_PATH否—測試運(yùn)行期間收集瀏覽器 console 錯誤的 JSON 文件路徑3.1 通過 .env 文件配置可以在項(xiàng)目根目錄使用.env文件配合 dotenv 類工具加載集中管理這些變量URLhttps://localhost:44339 UMBRACO_USER_LOGINadminexample.com UMBRACO_USER_PASSWORDyour-password STORAGE_STATE_PATH./playwright/.auth/user.json CONSOLE_ERRORS_PATH./console-errors.json3.2 在 CI 中直接傳遞也可以直接在 CI 流水線中作為環(huán)境變量傳入env: URL: https://localhost:44339 UMBRACO_USER_LOGIN: $(TestUserEmail) UMBRACO_USER_PASSWORD: $(TestUserPassword)3.3 源碼視角環(huán)境變量如何被讀取在倉庫中環(huán)境變量的讀取集中在 lib/umbraco.config.tsURL、UMBRACO_USER_LOGIN、UMBRACO_USER_PASSWORD被映射為environment.baseUrl與user.login/password并提供了兜底默認(rèn)值本地開發(fā)默認(rèn)登錄ngeumbraco.dk。而STORAGE_STATE_PATH則在 lib/helpers/testExtension.ts 的 fixture 生命周期中消費(fèi)每次umbracoApi測試結(jié)束時會把瀏覽器上下文的storageState保存到該路徑從而為下一個測試持久化一個有效會話。值得留意的是認(rèn)證不是一次性登錄ApiHelpers在每次測試前會先調(diào)用isLoginStateValid()嘗試刷新 token僅在刷新失敗時才執(zhí)行完整重新登錄見 ApiHelpers.ts 中的refreshLoginState與updateTokenAndCookie這樣可顯著減少整批測試的認(rèn)證開銷。四、快速上手第一個端到端測試該包導(dǎo)出一個自定義的 Playwrighttestfixture在原生test基礎(chǔ)上注入了umbracoApi與umbracoUi兩個夾具。以下示例完整演示通過 API 準(zhǔn)備數(shù)據(jù) → 通過 UI 創(chuàng)建內(nèi)容 → 斷言結(jié)果的典型鏈路import { ConstantHelper, test } from umbraco/acceptance-test-helpers; import { expect } from playwright/test; test(can create content, async ({ umbracoApi, umbracoUi }) { // Setup via API await umbracoApi.documentType.createDefaultDocumentType(TestType); // UI interactions await umbracoUi.content.goToSection(ConstantHelper.sections.content); await umbracoUi.content.clickActionsMenuAtRoot(); await umbracoUi.content.clickCreateButton(); await umbracoUi.content.chooseDocumentType(TestType); await umbracoUi.content.enterContentName(TestContent); await umbracoUi.content.clickSaveButton(); // Assertions await umbracoUi.content.isSuccessStateVisibleForSaveButton(); expect(await umbracoApi.document.doesNameExist(TestContent)).toBeTruthy(); });4.1 fixture 的底層實(shí)現(xiàn)從 testExtension.ts 可以看到兩個 fixture 的具體職責(zé)umbracoApi每個測試開始前先調(diào)用isLoginStateValid()確保管理員會話有效測試結(jié)束后將storageState持久化到STORAGE_STATE_PATH供后續(xù)測試復(fù)用umbracoUi監(jiān)聽頁面所有console事件把error級消息收集到CONSOLE_ERRORS_PATH并在測試結(jié)束時以去重后的注解console-error附加到測試報告中。這是可見信號而非失敗門檻的設(shè)計(jì)——backoffice 本身會記錄一些良性錯誤故不直接導(dǎo)致用例失敗。4.2 倉庫內(nèi)真實(shí)用例參考倉庫自身的驗(yàn)收測試也遵循同樣的模式例如在 README.md 中展示了帶beforeEach/afterEach的 Arrange-Act-Assert 結(jié)構(gòu)并用ensureNameNotExists()做冪等清理清理不存在的數(shù)據(jù)不會報錯這是編寫可靠驗(yàn)收測試的推薦約定。五、三大 Fixture 詳解該包擴(kuò)展了 Playwright 的test提供兩個自定義 fixture 外加標(biāo)準(zhǔn)的page。5.1umbracoApi— REST API 助手用于服務(wù)端的數(shù)據(jù)準(zhǔn)備、清理與斷言// Create test data const docTypeId await umbracoApi.documentType.createDefaultDocumentType(TestType); const dataTypeId await umbracoApi.dataType.createTextstringDataType(TestDataType); // Query data const exists await umbracoApi.document.doesNameExist(MyContent); // Cleanup (idempotent — wont fail if not exists) await umbracoApi.documentType.ensureNameNotExists(TestType); // Publishing await umbracoApi.document.publish(documentId);可用 API helpers 完整清單dataType、dictionary、document、documentBlueprint、documentType、healthCheck、indexer、language、login、logViewer、media、mediaType、member、memberGroup、memberType、modelsBuilder、objectTypes、package、partialView、publishedCache、redirectManagement、relationType、report、script、smtp、stylesheet、telemetry、template、temporaryFile、user、userGroup、webhook、contentDeliveryApi、mediaDeliveryApi。源碼佐證ApiHelpers.ts 中所有請求都經(jīng)由page.request發(fā)出并自動攜帶瀏覽器上下文中的 cookie無需顯式設(shè)置 Cookie 頭post/put/delete會斷言響應(yīng)狀態(tài)碼 500把服務(wù)端錯誤顯式暴露為斷言失敗而非靜默的詭異異常getIdFromLocation()從創(chuàng)建類接口響應(yīng)的Location頭解析新實(shí)體 ID。創(chuàng)建文檔類型等高層方法如createDefaultDocumentType還會先調(diào)用ensureNameNotExists做冪等清理見 DocumentTypeApiHelper.ts。5.2umbracoUi— UI 交互助手封裝瀏覽器交互按 backoffice 區(qū)塊section組織// Navigation await umbracoUi.goToBackOffice(); await umbracoUi.content.goToSection(ConstantHelper.sections.content); // Interactions await umbracoUi.content.enterContentName(My Content); await umbracoUi.content.clickSaveButton(); // Assertions await umbracoUi.content.isSuccessStateVisibleForSaveButton(); await umbracoUi.content.doesSuccessNotificationHaveText(Content saved);可用 UI helpers 完整清單content、contentRender、currentUserProfile、dataType、dictionary、documentBlueprint、documentType、examineManagement、externalLogin、form、healthCheck、install、language、login、logViewer、media、mediaType、member、memberGroup、memberType、modelsBuilder、package、partialView、profiling、publishedStatus、redirectManagement、relationType、script、stylesheet、telemetryData、template、user、userGroup、webhook、welcomeDashboard。源碼佐證UiHelpers.ts 中g(shù)oToBackOffice()直接跳轉(zhuǎn)到${baseUrl}/umbraco所有 helper 以區(qū)塊導(dǎo)航定位器section-links為基準(zhǔn)reloadPage()會等待該元素重新可見以確保頁面真正加載完成。5.3page— 原始 Playwright Page對于標(biāo)準(zhǔn)助手未覆蓋的定制交互可直接使用 Playwright 原生page對象例如await page.pause(); // 打開 Playwright Inspector await page.screenshot({ path: debug.png }); // 調(diào)試截圖六、Helper 常量包導(dǎo)出三個常量/工具類ConstantHelper、NotificationConstantHelper與AliasHelper。import { ConstantHelper, NotificationConstantHelper, AliasHelper } from umbraco/acceptance-test-helpers; // Section names ConstantHelper.sections.content ConstantHelper.sections.media ConstantHelper.sections.settings // Notification messages NotificationConstantHelper.success.published NotificationConstantHelper.success.saved // String utilities AliasHelper.toAlias(Test Document Type) // - testDocumentType源碼佐證ConstantHelper.ts 中還提供了豐富的預(yù)置常量測試中可直接復(fù)用ConstantHelper.sectionsContent、Media、Settings、Library、Packages、Members、Translation、Users 等區(qū)塊名ConstantHelper.timeout/waitshort(1000ms)、medium(5000ms)、long(10000ms)、navigation(30000ms)、pageLoad(60000ms)等超時檔位以及animation/debounce等等待檔位ConstantHelper.apiEndpoints/umbraco/management/api/v1/document、/data-type、/user/current等 Management API 端點(diǎn)路徑ConstantHelper.validationMessages、loginErrorMessages、auditTrailMessages等斷言文案。AliasHelper.ts 的toAlias基于toCamelCase實(shí)現(xiàn)如Test Document Type→testDocumentType另有toSafeAlias以a開頭結(jié)尾并做駝峰化確保 alias 合法、capitalize、uuidToAlias等工具。七、Builders流式構(gòu)建 Umbraco JSON 模型Builder 用于以 fluent API 構(gòu)建復(fù)雜的 Umbraco JSON 測試數(shù)據(jù)模型并內(nèi)置合理的默認(rèn)值。7.1 Builder 方法約定方法用途with*()設(shè)置某個屬性值add*()創(chuàng)建并添加一個子 builderbuild()構(gòu)造最終的 JSON 對象done()返回父級 builder子 builder 使用7.2 快速上手import { DocumentTypeBuilder, AliasHelper } from umbraco/acceptance-test-helpers; // Minimal — uses defaults const simpleDocType new DocumentTypeBuilder().build(); // Custom configuration const documentType new DocumentTypeBuilder() .withName(Blog Post) .withAlias(AliasHelper.toAlias(Blog Post)) .withAllowedAsRoot(true) .withIcon(icon-newspaper) .addProperty() .withName(Title) .withDataTypeId(textStringDataTypeId) .done() .build();源碼佐證documentTypeBuilder.ts 展示了with*/add*/build的完整實(shí)現(xiàn)未顯式設(shè)置的字段會在build()時自動填充默認(rèn)值例如icon默認(rèn)icon-document、allowedAsRoot默認(rèn)false、variesByCulture默認(rèn)false、cleanup.preventCleanup默認(rèn)false而id通過 BuilderUtils.ts 中的ensureIdExists()在缺失時自動生成 UUID。也就是說極簡 builder 也能產(chǎn)出可提交給 Management API 的合法 JSON。7.3 可用 Builders 完整清單Document Types文檔類型DocumentTypeBuilder、DocumentTypePropertyBuilder、DocumentTypeContainerBuilder、DocumentTypeCompositionBuilder、DocumentTypeAllowedDocumentTypeBuilder、DocumentTypeAllowedTemplateBuilderData Types數(shù)據(jù)類型34 個文本類TextStringDataTypeBuilder、TextAreaDataTypeBuilder、MultipleTextStringDataTypeBuilder數(shù)值類NumericDataTypeBuilder、DecimalDataTypeBuilder、SliderDataTypeBuilder布爾類TrueFalseDataTypeBuilder日期/時間類DatePickerDataTypeBuilder、DateOnlyPickerDataTypeBuilder、TimeOnlyPickerDataTypeBuilder、DateTimePickerDataTypeBuilder、DateTimeWithTimeZonePickerDataTypeBuilder選擇類DropdownDataTypeBuilder、CheckboxListDataTypeBuilder、RadioboxDataTypeBuilder、TagsDataTypeBuilder選擇器類ContentPickerDataTypeBuilder、MultiNodeTreePickerDataTypeBuilder、MediaPickerDataTypeBuilder、MultiUrlPickerDataTypeBuilder、EntityDataPickerDataTypeBuilder富文本類TinyMCEDataTypeBuilder、TiptapDataTypeBuilder、MarkdownEditorDataTypeBuilder、CodeEditorDataTypeBuilder復(fù)雜類BlockListDataTypeBuilder、BlockGridDataTypeBuilder、ImageCropperDataTypeBuilder、ListViewDataTypeBuilder其他LabelDataTypeBuilder、EmailAddressDataTypeBuilder、ApprovedColorDataTypeBuilder、UploadFieldDataTypeBuilderDocuments文檔DocumentBuilder、DocumentValueBuilder、DocumentVariantBuilder、DocumentDomainBuilderDocument Blueprints文檔藍(lán)圖DocumentBlueprintsBuilder、DocumentBlueprintsValueBuilder、DocumentBlueprintsVariantBuilderMedia媒體MediaTypeBuilder、MediaTypePropertyBuilder、MediaTypeContainerBuilder、MediaTypeCompositionBuilder、MediaTypeAllowedMediaTypeBuilder、MediaBuilder、MediaValueBuilder、MediaVariantBuilder、MediaValueDataBuilderMembers成員MemberTypeBuilder、MemberTypePropertyBuilder、MemberTypeContainerBuilder、MemberTypeCompositionBuilder、MemberBuilder、MemberValueBuilder、MemberVariantBuilderUsers用戶UserBuilder、UserGroupBuilder、UserGroupPermissionBuilder、UserGroupDocumentPermissionBuilder、UserGroupPropertyValuePermissionBuilder其他WebhookBuilder、PackageBuilder這些 Builder 的目錄實(shí)現(xiàn)見 lib/builders按documentTypes、dataTypes、document、documentBlueprints、media、mediaTypes、member、memberTypes、users、userGroups、webhook、packages分類存放。八、配套運(yùn)行腳本與調(diào)試倉庫內(nèi)實(shí)踐盡管 README.npm.md 聚焦于包的使用倉庫 package.json 中的腳本與 playwright.config.ts 的配置可作為集成該包時的實(shí)戰(zhàn)參考npm run buildtsc -p tsconfig.build.json編譯包源碼npx playwright test運(yùn)行用例倉庫內(nèi)以多 project 組織setup認(rèn)證項(xiàng)目先跑defaultConfig等項(xiàng)目依賴其產(chǎn)出的storageStatenpm run config重新引導(dǎo)環(huán)境配置生成.env調(diào)試手段npx playwright test --headed可見瀏覽器運(yùn)行、PWDEBUG1進(jìn)入調(diào)試模式、npx playwright show-trace查看失敗用例自動保存的 trace詳見 README.md。九、總結(jié)與注意事項(xiàng)認(rèn)證先行運(yùn)行前務(wù)必配置UMBRACO_USER_LOGIN與UMBRACO_USER_PASSWORD推薦同時配置STORAGE_STATE_PATH以復(fù)用認(rèn)證狀態(tài)、加速 API 調(diào)用分層策略用umbracoApi做數(shù)據(jù)準(zhǔn)備與斷言、用umbracoUi驗(yàn)證真實(shí)用戶工作流二者結(jié)合能兼顧速度與覆蓋面冪等清理優(yōu)先使用ensureNameNotExists()這類冪等方法做測試數(shù)據(jù)清理避免測試之間相互污染默認(rèn)值機(jī)制Builder 的build()會補(bǔ)齊合法默認(rèn)值并自動生成 UUID極簡配置即可產(chǎn)出可提交的 API 請求體版本約束宿主項(xiàng)目需滿足 peer 依賴playwright/test 1.56倉庫當(dāng)前代碼基于 Playwright 1.56 開發(fā)見 package.json。在此基礎(chǔ)上你已具備使用umbraco/acceptance-test-helpers編寫、配置與調(diào)試 Umbraco CMS 驗(yàn)收測試的完整能力需要更細(xì)的用例組織、標(biāo)簽smoke/release與項(xiàng)目劃分實(shí)踐時可直接研讀倉庫內(nèi)的 README.md 與 playwright.config.ts。贊分享CMS后端【免費(fèi)下載鏈接】Umbraco-CMSUmbraco is a free and open source .NET content management system helping you deliver delightful digital experiences.項(xiàng)目地址https://gitcode.com/gh_mirrors/um/Umbraco-CMS點(diǎn)擊查看免費(fèi)下載相關(guān)推薦Umbraco CMS 端到端驗(yàn)收測試實(shí)戰(zhàn)指南Playwright Acceptance Tests 全解析Umbraco CMS 端到端驗(yàn)收測試實(shí)戰(zhàn)指南Playwright Acceptance Tests 全解析 本指南圍繞 Umbraco CMS 官方倉庫中的CMS后端Umbraco CMS 驗(yàn)收測試開發(fā)指南Playwright 端到端套件的架構(gòu)與防 Flaky 約定Umbraco CMS 驗(yàn)收測試開發(fā)指南Playwright 端到端套件的架構(gòu)與防 Flaky 約定 本篇指南以 Umbraco CMS 倉庫內(nèi) tests/CMS后端代碼深度解析NorthCinder排名權(quán)重表與硬性淘汰規(guī)則代碼深度解析NorthCinder排名權(quán)重表與硬性淘汰規(guī)則 NorthCinder 是一款買家自主、廣告中立的購物代理 MCP 軟件其核心賣點(diǎn)是 確定性且可上一篇90DaysOfDevOps 之 Git 安裝與配置實(shí)戰(zhàn)從 Windows/Linux 環(huán)境搭建到分布式版本控制原理下一篇用 AG-UI .NET SDK 分離展示推理模型的思考過程TextReasoningContent 事件流實(shí)戰(zhàn)指南創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 Umbraco CMS 驗(yàn)收測試：@umbraco/acceptance-test-helpers 端到端測試助手包使用指南
CMS后端【免費(fèi)下載鏈接】Umbraco-CMSUmbraco is a free and open source .NET content management system helping you deliver delightful digital experiences.項(xiàng)目地址https://gitcode.com/gh_mirrors/um/Umbraco-CMS點(diǎn)擊查看免費(fèi)下載本篇技術(shù)指南介紹 Umbraco CMS 官方驗(yàn)收測試工程中發(fā)布的 npm 測試助手包umbraco/acceptance-test-helpers它基于 Playwright 提供 API 助手umbracoApi、UI 交互助手umbracoUi與 JSON 模型 Builder 三類能力用于簡化 Umbraco backoffice 功能的端到端測試。讀完本文你將掌握該包的安裝與認(rèn)證配置、自定義testfixture 的用法、API/UI 助手的完整清單、常量與 Builder 的調(diào)用方式并能結(jié)合倉庫源碼理解其底層認(rèn)證與默認(rèn)值機(jī)制直接上手編寫可復(fù)現(xiàn)的 Umbraco 驗(yàn)收測試。一、包概覽它解決什么問題umbraco/acceptance-test-helpers是為編寫 Umbraco CMS 解決方案的 Playwright 端到端測試而設(shè)計(jì)的輔助庫核心由三部分組成API helpersumbracoApi通過 Umbraco Management API 完成服務(wù)端的數(shù)據(jù)準(zhǔn)備setup、清理teardown與斷言比純 UI 操作更快、更穩(wěn)定UI helpersumbracoUi封裝 backoffice 各區(qū)塊的瀏覽器交互動作如導(dǎo)航、點(diǎn)擊、填寫表單、斷言保存狀態(tài)JSON model builders以流式fluentAPI 構(gòu)建復(fù)雜的 Umbraco JSON 數(shù)據(jù)模型文檔類型、數(shù)據(jù)類型、文檔、媒體、成員、用戶等配合合理的默認(rèn)值減少樣板代碼。該工程位于倉庫 tests/Umbraco.Tests.AcceptanceTest 目錄其倉庫級使用說明見 README.md。本文所述包內(nèi)容即由該目錄下lib/中的源碼編譯發(fā)布而來入口見 lib/index.ts。二、安裝在已初始化的 Node.js 項(xiàng)目中安裝為開發(fā)依賴npm install -D umbraco/acceptance-test-helpers倉庫內(nèi) package.json 展示了該包自身的工程化信息可作為集成時的參考包的peerDependencies要求playwright/test 1.56即宿主項(xiàng)目需要安裝兼容版本的 Playwright包的入口為dist/index.js與dist/index.d.ts通過exports字段暴露包自身以 TypeScript 編寫構(gòu)建命令為tsc -p tsconfig.build.json。注意文檔與 README 中使用的包名為umbraco/acceptance-test-helpers倉庫內(nèi)package.json的name字段寫作umbraco-cms/acceptance-test-helpers安裝時請以發(fā)布在 npm registry 上的實(shí)際名稱為準(zhǔn)README 中給出的安裝命令即umbraco/acceptance-test-helpers。三、運(yùn)行前配置連接與認(rèn)證環(huán)境變量測試助手需要知道如何連接并認(rèn)證你的 Umbraco 實(shí)例。運(yùn)行測試前需設(shè)置以下環(huán)境變量變量必填默認(rèn)值說明URL否https://localhost:44339Umbraco 實(shí)例的基礎(chǔ) URLUMBRACO_USER_LOGIN是—Backoffice 超級管理員superadmin郵箱UMBRACO_USER_PASSWORD是—Backoffice 超級管理員密碼STORAGE_STATE_PATH推薦—Playwright 認(rèn)證存儲狀態(tài) JSON 的路徑應(yīng)與playwright.config中的storageState一致。API 助手會從該文件讀取 token 用于 REST 調(diào)用未設(shè)置時 token 將從實(shí)時頁面上下文中提取速度更慢、可靠性更低。CONSOLE_ERRORS_PATH否—測試運(yùn)行期間收集瀏覽器 console 錯誤的 JSON 文件路徑3.1 通過 .env 文件配置可以在項(xiàng)目根目錄使用.env文件配合 dotenv 類工具加載集中管理這些變量URLhttps://localhost:44339 UMBRACO_USER_LOGINadminexample.com UMBRACO_USER_PASSWORDyour-password STORAGE_STATE_PATH./playwright/.auth/user.json CONSOLE_ERRORS_PATH./console-errors.json3.2 在 CI 中直接傳遞也可以直接在 CI 流水線中作為環(huán)境變量傳入env: URL: https://localhost:44339 UMBRACO_USER_LOGIN: $(TestUserEmail) UMBRACO_USER_PASSWORD: $(TestUserPassword)3.3 源碼視角環(huán)境變量如何被讀取在倉庫中環(huán)境變量的讀取集中在 lib/umbraco.config.tsURL、UMBRACO_USER_LOGIN、UMBRACO_USER_PASSWORD被映射為environment.baseUrl與user.login/password并提供了兜底默認(rèn)值本地開發(fā)默認(rèn)登錄ngeumbraco.dk。而STORAGE_STATE_PATH則在 lib/helpers/testExtension.ts 的 fixture 生命周期中消費(fèi)每次umbracoApi測試結(jié)束時會把瀏覽器上下文的storageState保存到該路徑從而為下一個測試持久化一個有效會話。值得留意的是認(rèn)證不是一次性登錄ApiHelpers在每次測試前會先調(diào)用isLoginStateValid()嘗試刷新 token僅在刷新失敗時才執(zhí)行完整重新登錄見 ApiHelpers.ts 中的refreshLoginState與updateTokenAndCookie這樣可顯著減少整批測試的認(rèn)證開銷。四、快速上手第一個端到端測試該包導(dǎo)出一個自定義的 Playwrighttestfixture在原生test基礎(chǔ)上注入了umbracoApi與umbracoUi兩個夾具。以下示例完整演示通過 API 準(zhǔn)備數(shù)據(jù) → 通過 UI 創(chuàng)建內(nèi)容 → 斷言結(jié)果的典型鏈路import { ConstantHelper, test } from umbraco/acceptance-test-helpers; import { expect } from playwright/test; test(can create content, async ({ umbracoApi, umbracoUi }) { // Setup via API await umbracoApi.documentType.createDefaultDocumentType(TestType); // UI interactions await umbracoUi.content.goToSection(ConstantHelper.sections.content); await umbracoUi.content.clickActionsMenuAtRoot(); await umbracoUi.content.clickCreateButton(); await umbracoUi.content.chooseDocumentType(TestType); await umbracoUi.content.enterContentName(TestContent); await umbracoUi.content.clickSaveButton(); // Assertions await umbracoUi.content.isSuccessStateVisibleForSaveButton(); expect(await umbracoApi.document.doesNameExist(TestContent)).toBeTruthy(); });4.1 fixture 的底層實(shí)現(xiàn)從 testExtension.ts 可以看到兩個 fixture 的具體職責(zé)umbracoApi每個測試開始前先調(diào)用isLoginStateValid()確保管理員會話有效測試結(jié)束后將storageState持久化到STORAGE_STATE_PATH供后續(xù)測試復(fù)用umbracoUi監(jiān)聽頁面所有console事件把error級消息收集到CONSOLE_ERRORS_PATH并在測試結(jié)束時以去重后的注解console-error附加到測試報告中。這是可見信號而非失敗門檻的設(shè)計(jì)——backoffice 本身會記錄一些良性錯誤故不直接導(dǎo)致用例失敗。4.2 倉庫內(nèi)真實(shí)用例參考倉庫自身的驗(yàn)收測試也遵循同樣的模式例如在 README.md 中展示了帶beforeEach/afterEach的 Arrange-Act-Assert 結(jié)構(gòu)并用ensureNameNotExists()做冪等清理清理不存在的數(shù)據(jù)不會報錯這是編寫可靠驗(yàn)收測試的推薦約定。五、三大 Fixture 詳解該包擴(kuò)展了 Playwright 的test提供兩個自定義 fixture 外加標(biāo)準(zhǔn)的page。5.1umbracoApi— REST API 助手用于服務(wù)端的數(shù)據(jù)準(zhǔn)備、清理與斷言// Create test data const docTypeId await umbracoApi.documentType.createDefaultDocumentType(TestType); const dataTypeId await umbracoApi.dataType.createTextstringDataType(TestDataType); // Query data const exists await umbracoApi.document.doesNameExist(MyContent); // Cleanup (idempotent — wont fail if not exists) await umbracoApi.documentType.ensureNameNotExists(TestType); // Publishing await umbracoApi.document.publish(documentId);可用 API helpers 完整清單dataType、dictionary、document、documentBlueprint、documentType、healthCheck、indexer、language、login、logViewer、media、mediaType、member、memberGroup、memberType、modelsBuilder、objectTypes、package、partialView、publishedCache、redirectManagement、relationType、report、script、smtp、stylesheet、telemetry、template、temporaryFile、user、userGroup、webhook、contentDeliveryApi、mediaDeliveryApi。源碼佐證ApiHelpers.ts 中所有請求都經(jīng)由page.request發(fā)出并自動攜帶瀏覽器上下文中的 cookie無需顯式設(shè)置 Cookie 頭post/put/delete會斷言響應(yīng)狀態(tài)碼 500把服務(wù)端錯誤顯式暴露為斷言失敗而非靜默的詭異異常getIdFromLocation()從創(chuàng)建類接口響應(yīng)的Location頭解析新實(shí)體 ID。創(chuàng)建文檔類型等高層方法如createDefaultDocumentType還會先調(diào)用ensureNameNotExists做冪等清理見 DocumentTypeApiHelper.ts。5.2umbracoUi— UI 交互助手封裝瀏覽器交互按 backoffice 區(qū)塊section組織// Navigation await umbracoUi.goToBackOffice(); await umbracoUi.content.goToSection(ConstantHelper.sections.content); // Interactions await umbracoUi.content.enterContentName(My Content); await umbracoUi.content.clickSaveButton(); // Assertions await umbracoUi.content.isSuccessStateVisibleForSaveButton(); await umbracoUi.content.doesSuccessNotificationHaveText(Content saved);可用 UI helpers 完整清單content、contentRender、currentUserProfile、dataType、dictionary、documentBlueprint、documentType、examineManagement、externalLogin、form、healthCheck、install、language、login、logViewer、media、mediaType、member、memberGroup、memberType、modelsBuilder、package、partialView、profiling、publishedStatus、redirectManagement、relationType、script、stylesheet、telemetryData、template、user、userGroup、webhook、welcomeDashboard。源碼佐證UiHelpers.ts 中g(shù)oToBackOffice()直接跳轉(zhuǎn)到${baseUrl}/umbraco所有 helper 以區(qū)塊導(dǎo)航定位器section-links為基準(zhǔn)reloadPage()會等待該元素重新可見以確保頁面真正加載完成。5.3page— 原始 Playwright Page對于標(biāo)準(zhǔn)助手未覆蓋的定制交互可直接使用 Playwright 原生page對象例如await page.pause(); // 打開 Playwright Inspector await page.screenshot({ path: debug.png }); // 調(diào)試截圖六、Helper 常量包導(dǎo)出三個常量/工具類ConstantHelper、NotificationConstantHelper與AliasHelper。import { ConstantHelper, NotificationConstantHelper, AliasHelper } from umbraco/acceptance-test-helpers; // Section names ConstantHelper.sections.content ConstantHelper.sections.media ConstantHelper.sections.settings // Notification messages NotificationConstantHelper.success.published NotificationConstantHelper.success.saved // String utilities AliasHelper.toAlias(Test Document Type) // - testDocumentType源碼佐證ConstantHelper.ts 中還提供了豐富的預(yù)置常量測試中可直接復(fù)用ConstantHelper.sectionsContent、Media、Settings、Library、Packages、Members、Translation、Users 等區(qū)塊名ConstantHelper.timeout/waitshort(1000ms)、medium(5000ms)、long(10000ms)、navigation(30000ms)、pageLoad(60000ms)等超時檔位以及animation/debounce等等待檔位ConstantHelper.apiEndpoints/umbraco/management/api/v1/document、/data-type、/user/current等 Management API 端點(diǎn)路徑ConstantHelper.validationMessages、loginErrorMessages、auditTrailMessages等斷言文案。AliasHelper.ts 的toAlias基于toCamelCase實(shí)現(xiàn)如Test Document Type→testDocumentType另有toSafeAlias以a開頭結(jié)尾并做駝峰化確保 alias 合法、capitalize、uuidToAlias等工具。七、Builders流式構(gòu)建 Umbraco JSON 模型Builder 用于以 fluent API 構(gòu)建復(fù)雜的 Umbraco JSON 測試數(shù)據(jù)模型并內(nèi)置合理的默認(rèn)值。7.1 Builder 方法約定方法用途with*()設(shè)置某個屬性值add*()創(chuàng)建并添加一個子 builderbuild()構(gòu)造最終的 JSON 對象done()返回父級 builder子 builder 使用7.2 快速上手import { DocumentTypeBuilder, AliasHelper } from umbraco/acceptance-test-helpers; // Minimal — uses defaults const simpleDocType new DocumentTypeBuilder().build(); // Custom configuration const documentType new DocumentTypeBuilder() .withName(Blog Post) .withAlias(AliasHelper.toAlias(Blog Post)) .withAllowedAsRoot(true) .withIcon(icon-newspaper) .addProperty() .withName(Title) .withDataTypeId(textStringDataTypeId) .done() .build();源碼佐證documentTypeBuilder.ts 展示了with*/add*/build的完整實(shí)現(xiàn)未顯式設(shè)置的字段會在build()時自動填充默認(rèn)值例如icon默認(rèn)icon-document、allowedAsRoot默認(rèn)false、variesByCulture默認(rèn)false、cleanup.preventCleanup默認(rèn)false而id通過 BuilderUtils.ts 中的ensureIdExists()在缺失時自動生成 UUID。也就是說極簡 builder 也能產(chǎn)出可提交給 Management API 的合法 JSON。7.3 可用 Builders 完整清單Document Types文檔類型DocumentTypeBuilder、DocumentTypePropertyBuilder、DocumentTypeContainerBuilder、DocumentTypeCompositionBuilder、DocumentTypeAllowedDocumentTypeBuilder、DocumentTypeAllowedTemplateBuilderData Types數(shù)據(jù)類型34 個文本類TextStringDataTypeBuilder、TextAreaDataTypeBuilder、MultipleTextStringDataTypeBuilder數(shù)值類NumericDataTypeBuilder、DecimalDataTypeBuilder、SliderDataTypeBuilder布爾類TrueFalseDataTypeBuilder日期/時間類DatePickerDataTypeBuilder、DateOnlyPickerDataTypeBuilder、TimeOnlyPickerDataTypeBuilder、DateTimePickerDataTypeBuilder、DateTimeWithTimeZonePickerDataTypeBuilder選擇類DropdownDataTypeBuilder、CheckboxListDataTypeBuilder、RadioboxDataTypeBuilder、TagsDataTypeBuilder選擇器類ContentPickerDataTypeBuilder、MultiNodeTreePickerDataTypeBuilder、MediaPickerDataTypeBuilder、MultiUrlPickerDataTypeBuilder、EntityDataPickerDataTypeBuilder富文本類TinyMCEDataTypeBuilder、TiptapDataTypeBuilder、MarkdownEditorDataTypeBuilder、CodeEditorDataTypeBuilder復(fù)雜類BlockListDataTypeBuilder、BlockGridDataTypeBuilder、ImageCropperDataTypeBuilder、ListViewDataTypeBuilder其他LabelDataTypeBuilder、EmailAddressDataTypeBuilder、ApprovedColorDataTypeBuilder、UploadFieldDataTypeBuilderDocuments文檔DocumentBuilder、DocumentValueBuilder、DocumentVariantBuilder、DocumentDomainBuilderDocument Blueprints文檔藍(lán)圖DocumentBlueprintsBuilder、DocumentBlueprintsValueBuilder、DocumentBlueprintsVariantBuilderMedia媒體MediaTypeBuilder、MediaTypePropertyBuilder、MediaTypeContainerBuilder、MediaTypeCompositionBuilder、MediaTypeAllowedMediaTypeBuilder、MediaBuilder、MediaValueBuilder、MediaVariantBuilder、MediaValueDataBuilderMembers成員MemberTypeBuilder、MemberTypePropertyBuilder、MemberTypeContainerBuilder、MemberTypeCompositionBuilder、MemberBuilder、MemberValueBuilder、MemberVariantBuilderUsers用戶UserBuilder、UserGroupBuilder、UserGroupPermissionBuilder、UserGroupDocumentPermissionBuilder、UserGroupPropertyValuePermissionBuilder其他WebhookBuilder、PackageBuilder這些 Builder 的目錄實(shí)現(xiàn)見 lib/builders按documentTypes、dataTypes、document、documentBlueprints、media、mediaTypes、member、memberTypes、users、userGroups、webhook、packages分類存放。八、配套運(yùn)行腳本與調(diào)試倉庫內(nèi)實(shí)踐盡管 README.npm.md 聚焦于包的使用倉庫 package.json 中的腳本與 playwright.config.ts 的配置可作為集成該包時的實(shí)戰(zhàn)參考npm run buildtsc -p tsconfig.build.json編譯包源碼npx playwright test運(yùn)行用例倉庫內(nèi)以多 project 組織setup認(rèn)證項(xiàng)目先跑defaultConfig等項(xiàng)目依賴其產(chǎn)出的storageStatenpm run config重新引導(dǎo)環(huán)境配置生成.env調(diào)試手段npx playwright test --headed可見瀏覽器運(yùn)行、PWDEBUG1進(jìn)入調(diào)試模式、npx playwright show-trace查看失敗用例自動保存的 trace詳見 README.md。九、總結(jié)與注意事項(xiàng)認(rèn)證先行運(yùn)行前務(wù)必配置UMBRACO_USER_LOGIN與UMBRACO_USER_PASSWORD推薦同時配置STORAGE_STATE_PATH以復(fù)用認(rèn)證狀態(tài)、加速 API 調(diào)用分層策略用umbracoApi做數(shù)據(jù)準(zhǔn)備與斷言、用umbracoUi驗(yàn)證真實(shí)用戶工作流二者結(jié)合能兼顧速度與覆蓋面冪等清理優(yōu)先使用ensureNameNotExists()這類冪等方法做測試數(shù)據(jù)清理避免測試之間相互污染默認(rèn)值機(jī)制Builder 的build()會補(bǔ)齊合法默認(rèn)值并自動生成 UUID極簡配置即可產(chǎn)出可提交的 API 請求體版本約束宿主項(xiàng)目需滿足 peer 依賴playwright/test 1.56倉庫當(dāng)前代碼基于 Playwright 1.56 開發(fā)見 package.json。在此基礎(chǔ)上你已具備使用umbraco/acceptance-test-helpers編寫、配置與調(diào)試 Umbraco CMS 驗(yàn)收測試的完整能力需要更細(xì)的用例組織、標(biāo)簽smoke/release與項(xiàng)目劃分實(shí)踐時可直接研讀倉庫內(nèi)的 README.md 與 playwright.config.ts。贊分享CMS后端【免費(fèi)下載鏈接】Umbraco-CMSUmbraco is a free and open source .NET content management system helping you deliver delightful digital experiences.項(xiàng)目地址https://gitcode.com/gh_mirrors/um/Umbraco-CMS點(diǎn)擊查看免費(fèi)下載相關(guān)推薦Umbraco CMS 端到端驗(yàn)收測試實(shí)戰(zhàn)指南Playwright Acceptance Tests 全解析Umbraco CMS 端到端驗(yàn)收測試實(shí)戰(zhàn)指南Playwright Acceptance Tests 全解析 本指南圍繞 Umbraco CMS 官方倉庫中的CMS后端Umbraco CMS 驗(yàn)收測試開發(fā)指南Playwright 端到端套件的架構(gòu)與防 Flaky 約定Umbraco CMS 驗(yàn)收測試開發(fā)指南Playwright 端到端套件的架構(gòu)與防 Flaky 約定 本篇指南以 Umbraco CMS 倉庫內(nèi) tests/CMS后端代碼深度解析NorthCinder排名權(quán)重表與硬性淘汰規(guī)則代碼深度解析NorthCinder排名權(quán)重表與硬性淘汰規(guī)則 NorthCinder 是一款買家自主、廣告中立的購物代理 MCP 軟件其核心賣點(diǎn)是 確定性且可上一篇90DaysOfDevOps 之 Git 安裝與配置實(shí)戰(zhàn)從 Windows/Linux 環(huán)境搭建到分布式版本控制原理下一篇用 AG-UI .NET SDK 分離展示推理模型的思考過程TextReasoningContent 事件流實(shí)戰(zhàn)指南創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考