CMS后端【免费下载链接】Umbraco-CMSUmbraco is a free and open source .NET content management system helping you deliver delightful digital experiences.项目地址https://gitcode.com/gh_mirrors/um/Umbraco-CMS点击查看免费下载本篇技术指南介绍 Umbraco CMS 官方验收测试工程中发布的 npm 测试助手包umbraco/acceptance-test-helpers它基于 Playwright 提供 API 助手umbracoApi、UI 交互助手umbracoUi与 JSON 模型 Builder 三类能力用于简化 Umbraco backoffice 功能的端到端测试。读完本文你将掌握该包的安装与认证配置、自定义testfixture 的用法、API/UI 助手的完整清单、常量与 Builder 的调用方式并能结合仓库源码理解其底层认证与默认值机制直接上手编写可复现的 Umbraco 验收测试。一、包概览它解决什么问题umbraco/acceptance-test-helpers是为编写 Umbraco CMS 解决方案的 Playwright 端到端测试而设计的辅助库核心由三部分组成API helpersumbracoApi通过 Umbraco Management API 完成服务端的数据准备setup、清理teardown与断言比纯 UI 操作更快、更稳定UI helpersumbracoUi封装 backoffice 各区块的浏览器交互动作如导航、点击、填写表单、断言保存状态JSON model builders以流式fluentAPI 构建复杂的 Umbraco JSON 数据模型文档类型、数据类型、文档、媒体、成员、用户等配合合理的默认值减少样板代码。该工程位于仓库 tests/Umbraco.Tests.AcceptanceTest 目录其仓库级使用说明见 README.md。本文所述包内容即由该目录下lib/中的源码编译发布而来入口见 lib/index.ts。二、安装在已初始化的 Node.js 项目中安装为开发依赖npm install -D umbraco/acceptance-test-helpers仓库内 package.json 展示了该包自身的工程化信息可作为集成时的参考包的peerDependencies要求playwright/test 1.56即宿主项目需要安装兼容版本的 Playwright包的入口为dist/index.js与dist/index.d.ts通过exports字段暴露包自身以 TypeScript 编写构建命令为tsc -p tsconfig.build.json。注意文档与 README 中使用的包名为umbraco/acceptance-test-helpers仓库内package.json的name字段写作umbraco-cms/acceptance-test-helpers安装时请以发布在 npm registry 上的实际名称为准README 中给出的安装命令即umbraco/acceptance-test-helpers。三、运行前配置连接与认证环境变量测试助手需要知道如何连接并认证你的 Umbraco 实例。运行测试前需设置以下环境变量变量必填默认值说明URL否https://localhost:44339Umbraco 实例的基础 URLUMBRACO_USER_LOGIN是—Backoffice 超级管理员superadmin邮箱UMBRACO_USER_PASSWORD是—Backoffice 超级管理员密码STORAGE_STATE_PATH推荐—Playwright 认证存储状态 JSON 的路径应与playwright.config中的storageState一致。API 助手会从该文件读取 token 用于 REST 调用未设置时 token 将从实时页面上下文中提取速度更慢、可靠性更低。CONSOLE_ERRORS_PATH否—测试运行期间收集浏览器 console 错误的 JSON 文件路径3.1 通过 .env 文件配置可以在项目根目录使用.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 流水线中作为环境变量传入env: URL: https://localhost:44339 UMBRACO_USER_LOGIN: $(TestUserEmail) UMBRACO_USER_PASSWORD: $(TestUserPassword)3.3 源码视角环境变量如何被读取在仓库中环境变量的读取集中在 lib/umbraco.config.tsURL、UMBRACO_USER_LOGIN、UMBRACO_USER_PASSWORD被映射为environment.baseUrl与user.login/password并提供了兜底默认值本地开发默认登录ngeumbraco.dk。而STORAGE_STATE_PATH则在 lib/helpers/testExtension.ts 的 fixture 生命周期中消费每次umbracoApi测试结束时会把浏览器上下文的storageState保存到该路径从而为下一个测试持久化一个有效会话。值得留意的是认证不是一次性登录ApiHelpers在每次测试前会先调用isLoginStateValid()尝试刷新 token仅在刷新失败时才执行完整重新登录见 ApiHelpers.ts 中的refreshLoginState与updateTokenAndCookie这样可显著减少整批测试的认证开销。四、快速上手第一个端到端测试该包导出一个自定义的 Playwrighttestfixture在原生test基础上注入了umbracoApi与umbracoUi两个夹具。以下示例完整演示通过 API 准备数据 → 通过 UI 创建内容 → 断言结果的典型链路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 的底层实现从 testExtension.ts 可以看到两个 fixture 的具体职责umbracoApi每个测试开始前先调用isLoginStateValid()确保管理员会话有效测试结束后将storageState持久化到STORAGE_STATE_PATH供后续测试复用umbracoUi监听页面所有console事件把error级消息收集到CONSOLE_ERRORS_PATH并在测试结束时以去重后的注解console-error附加到测试报告中。这是可见信号而非失败门槛的设计——backoffice 本身会记录一些良性错误故不直接导致用例失败。4.2 仓库内真实用例参考仓库自身的验收测试也遵循同样的模式例如在 README.md 中展示了带beforeEach/afterEach的 Arrange-Act-Assert 结构并用ensureNameNotExists()做幂等清理清理不存在的数据不会报错这是编写可靠验收测试的推荐约定。五、三大 Fixture 详解该包扩展了 Playwright 的test提供两个自定义 fixture 外加标准的page。5.1umbracoApi— REST API 助手用于服务端的数据准备、清理与断言// 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 中所有请求都经由page.request发出并自动携带浏览器上下文中的 cookie无需显式设置 Cookie 头post/put/delete会断言响应状态码 500把服务端错误显式暴露为断言失败而非静默的诡异异常getIdFromLocation()从创建类接口响应的Location头解析新实体 ID。创建文档类型等高层方法如createDefaultDocumentType还会先调用ensureNameNotExists做幂等清理见 DocumentTypeApiHelper.ts。5.2umbracoUi— UI 交互助手封装浏览器交互按 backoffice 区块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 中goToBackOffice()直接跳转到${baseUrl}/umbraco所有 helper 以区块导航定位器section-links为基准reloadPage()会等待该元素重新可见以确保页面真正加载完成。5.3page— 原始 Playwright Page对于标准助手未覆盖的定制交互可直接使用 Playwright 原生page对象例如await page.pause(); // 打开 Playwright Inspector await page.screenshot({ path: debug.png }); // 调试截图六、Helper 常量包导出三个常量/工具类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 中还提供了丰富的预置常量测试中可直接复用ConstantHelper.sectionsContent、Media、Settings、Library、Packages、Members、Translation、Users 等区块名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 端点路径ConstantHelper.validationMessages、loginErrorMessages、auditTrailMessages等断言文案。AliasHelper.ts 的toAlias基于toCamelCase实现如Test Document Type→testDocumentType另有toSafeAlias以a开头结尾并做驼峰化确保 alias 合法、capitalize、uuidToAlias等工具。七、Builders流式构建 Umbraco JSON 模型Builder 用于以 fluent API 构建复杂的 Umbraco JSON 测试数据模型并内置合理的默认值。7.1 Builder 方法约定方法用途with*()设置某个属性值add*()创建并添加一个子 builderbuild()构造最终的 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的完整实现未显式设置的字段会在build()时自动填充默认值例如icon默认icon-document、allowedAsRoot默认false、variesByCulture默认false、cleanup.preventCleanup默认false而id通过 BuilderUtils.ts 中的ensureIdExists()在缺失时自动生成 UUID。也就是说极简 builder 也能产出可提交给 Management API 的合法 JSON。7.3 可用 Builders 完整清单Document Types文档类型DocumentTypeBuilder、DocumentTypePropertyBuilder、DocumentTypeContainerBuilder、DocumentTypeCompositionBuilder、DocumentTypeAllowedDocumentTypeBuilder、DocumentTypeAllowedTemplateBuilderData Types数据类型34 个文本类TextStringDataTypeBuilder、TextAreaDataTypeBuilder、MultipleTextStringDataTypeBuilder数值类NumericDataTypeBuilder、DecimalDataTypeBuilder、SliderDataTypeBuilder布尔类TrueFalseDataTypeBuilder日期/时间类DatePickerDataTypeBuilder、DateOnlyPickerDataTypeBuilder、TimeOnlyPickerDataTypeBuilder、DateTimePickerDataTypeBuilder、DateTimeWithTimeZonePickerDataTypeBuilder选择类DropdownDataTypeBuilder、CheckboxListDataTypeBuilder、RadioboxDataTypeBuilder、TagsDataTypeBuilder选择器类ContentPickerDataTypeBuilder、MultiNodeTreePickerDataTypeBuilder、MediaPickerDataTypeBuilder、MultiUrlPickerDataTypeBuilder、EntityDataPickerDataTypeBuilder富文本类TinyMCEDataTypeBuilder、TiptapDataTypeBuilder、MarkdownEditorDataTypeBuilder、CodeEditorDataTypeBuilder复杂类BlockListDataTypeBuilder、BlockGridDataTypeBuilder、ImageCropperDataTypeBuilder、ListViewDataTypeBuilder其他LabelDataTypeBuilder、EmailAddressDataTypeBuilder、ApprovedColorDataTypeBuilder、UploadFieldDataTypeBuilderDocuments文档DocumentBuilder、DocumentValueBuilder、DocumentVariantBuilder、DocumentDomainBuilderDocument Blueprints文档蓝图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 的目录实现见 lib/builders按documentTypes、dataTypes、document、documentBlueprints、media、mediaTypes、member、memberTypes、users、userGroups、webhook、packages分类存放。八、配套运行脚本与调试仓库内实践尽管 README.npm.md 聚焦于包的使用仓库 package.json 中的脚本与 playwright.config.ts 的配置可作为集成该包时的实战参考npm run buildtsc -p tsconfig.build.json编译包源码npx playwright test运行用例仓库内以多 project 组织setup认证项目先跑defaultConfig等项目依赖其产出的storageStatenpm run config重新引导环境配置生成.env调试手段npx playwright test --headed可见浏览器运行、PWDEBUG1进入调试模式、npx playwright show-trace查看失败用例自动保存的 trace详见 README.md。九、总结与注意事项认证先行运行前务必配置UMBRACO_USER_LOGIN与UMBRACO_USER_PASSWORD推荐同时配置STORAGE_STATE_PATH以复用认证状态、加速 API 调用分层策略用umbracoApi做数据准备与断言、用umbracoUi验证真实用户工作流二者结合能兼顾速度与覆盖面幂等清理优先使用ensureNameNotExists()这类幂等方法做测试数据清理避免测试之间相互污染默认值机制Builder 的build()会补齐合法默认值并自动生成 UUID极简配置即可产出可提交的 API 请求体版本约束宿主项目需满足 peer 依赖playwright/test 1.56仓库当前代码基于 Playwright 1.56 开发见 package.json。在此基础上你已具备使用umbraco/acceptance-test-helpers编写、配置与调试 Umbraco CMS 验收测试的完整能力需要更细的用例组织、标签smoke/release与项目划分实践时可直接研读仓库内的 README.md 与 playwright.config.ts。赞分享CMS后端【免费下载链接】Umbraco-CMSUmbraco is a free and open source .NET content management system helping you deliver delightful digital experiences.项目地址https://gitcode.com/gh_mirrors/um/Umbraco-CMS点击查看免费下载相关推荐Umbraco CMS 端到端验收测试实战指南Playwright Acceptance Tests 全解析Umbraco CMS 端到端验收测试实战指南Playwright Acceptance Tests 全解析 本指南围绕 Umbraco CMS 官方仓库中的CMS后端Umbraco CMS 验收测试开发指南Playwright 端到端套件的架构与防 Flaky 约定Umbraco CMS 验收测试开发指南Playwright 端到端套件的架构与防 Flaky 约定 本篇指南以 Umbraco CMS 仓库内 tests/CMS后端代码深度解析NorthCinder排名权重表与硬性淘汰规则代码深度解析NorthCinder排名权重表与硬性淘汰规则 NorthCinder 是一款买家自主、广告中立的购物代理 MCP 软件其核心卖点是 确定性且可上一篇90DaysOfDevOps 之 Git 安装与配置实战从 Windows/Linux 环境搭建到分布式版本控制原理下一篇用 AG-UI .NET SDK 分离展示推理模型的思考过程TextReasoningContent 事件流实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考