如何把 RealWorld 规范仓库作为 submodule 引入实现项目并正确对待测试失败【免费下载链接】realworldThe mother of all demo apps — Exemplary fullstack Medium.com clone powered by React, Angular, Node, Django, and many more项目地址: https://gitcode.com/GitHub_Trending/re/realworld在开发自己的 RealWorldConduit一个 Medium 克隆前端或后端实现时你最终要回答一个问题我的实现是否满足官方规范RealWorld 规范仓库spec docs hub正是为此而存在的——CLAUDE.md 开宗明义这个仓库不是一个可运行的应用它只提供契约specs/api/下的 OpenAPI 规范与测试套件和验证前端的共享 E2E 套件specs/e2e/。该文件还专门有一节「If you are here as a submodule / vendored dependency」说明实现项目官方认可的嵌入方式就是把规范仓库以submodule 或 vendored dependency的形式引入自己的仓库其中 E2E 套件在实现项目中以./e2e路径被消费。本文给出完整路径引入 submodule、分别跑通 API 测试与 E2E 测试、以及遇到测试失败时的正确处理方式。规范仓库里有什么先分清两类测试引入之前先确认两类测试套件的位置和地位specs/api/后端契约。包含 openapi.yml、Hurl 测试套件hurl/*.hurl、由 Hurl 生成的 Bruno 集合以及两个运行脚本 run-api-tests-hurl.sh 和 run-api-tests-bruno.sh。specs/e2e/前端契约。包含 Playwright 测试*.spec.ts、选择器契约 SELECTORS.md 和基础配置 playwright.base.ts。后端规范文档反复强调一点backend/introduction.md 中写道这些页面只是用文字总结契约真正定义契约的是 OpenAPI 规范和 Hurl 套件——文字与测试不一致时以测试为准the tests win发现不一致应向规范仓库提 issue。这条原则是后文正确对待失败的总依据。把规范仓库作为 submodule 引入在实现项目的仓库根目录执行git submodule add https://gitcode.com/GitHub_Trending/re/realworld 挂载路径挂载路径是你自己提供的目录名。CLAUDE.md 同时认可 vendored dependency直接拷贝一份进仓库这种方式二者在仓库眼中没有差别。这里有一个路径约束需要注意E2E 基础配置的官方示例注释假设套件位于实现项目的./e2e导入路径写作./e2e/playwright.base。如果你把整个规范仓库挂载到某个路径比如specs/套件的实际位置就是挂载路径/specs/e2e/那么导入路径和 Playwright 的testDir都要相应改指到挂载路径/specs/e2e。也就是说不管 submodule 挂在哪里导入语句和testDir必须指向套件文件的真实位置二者是普通配置项按实际布局调整即可。对你的后端跑 API 测试套件前提条件后端服务已在本地运行且hurl命令可用。进入 submodule 内的specs/api/目录CLAUDE.md 明确要求从该目录运行执行 specs/api/README.md 给出的命令HOSThttp://localhost:3000/api ./run-api-tests-hurl.shHOST必须指向正在运行的后端。脚本在未设置时默认http://localhost:8000上面的http://localhost:3000/api是文档示例按你的实际地址调整。脚本默认运行时会把hurl/*.hurl下所有文件传给hurl --test脚本把全部位置参数原样传给 hurl因此你也可以只传单个.hurl文件先跑某一组用例。脚本在未显式指定时自动生成uid变量时间戳 进程号传给测试用例无需手工提供。如何判断结果脚本头部是set -euo pipefail且使用hurl --test模式运行——任何一条用例失败都会使脚本以非零状态码退出全部通过则正常结束。这就是 API 侧的验证方式。可选分支如果你偏好 GUI可以跑 Bruno 生成的镜像集合HOSThttp://localhost:3000/api ./run-api-tests-bruno.sh或者直接用 Bruno 应用打开bruno/目录交互式查看。但要注意specs/api/README.md 明确标注Hurl 文件是 source of truthBruno 集合由make bruno-generate从 Hurl 生成、由make bruno-check在 CI 中保持同步——不要手改嵌入的 Bruno 集合改测试只能改 Hurl 文件而这对实现项目来说是规范维护者的事不是你该做的。把你的前端接入 E2E 套件前提条件前端实现遵循 SELECTORS.md 定义的选择器契约且项目已安装 Playwright。frontend/tests.md 说明接入方式实现项目在自己的根playwright.config.ts中扩展specs/e2e/playwright.base.ts覆写baseURL和webServer指向自己的 dev server。官方注释给出的示例配置import { defineConfig } from playwright/test; import { baseConfig } from ./e2e/playwright.base; export default defineConfig({ ...baseConfig, use: { ...baseConfig.use, baseURL: http://localhost:3000 }, webServer: { command: npm run start, url: http://localhost:3000, reuseExistingServer: !process.env.CI, timeout: 120_000, }, });示例中的command: npm run start和端口3000是文档示例值替换为你实际的 dev server 启动命令与端口如果 submodule 挂载路径不是./e2e把导入路径改到挂载路径/specs/e2e/playwright.base。baseConfig自带几项与失败排查直接相关的设置见 playwright.base.tsworkers: 1串行执行、本地retries: 1CI 为 2、trace: on-first-retry、screenshot: only-on-failure。也就是说用例失败并重试时会自动留下 trace失败时会留下截图——这是你排查 E2E 失败的第一手材料。测试失败时如何正确对待这是引入 submodule 后最重要的一条纪律CLAUDE.md 的原话Fix the implementation, never edit the spec or tests to make them pass.即修你的实现永远不要为了让测试通过而编辑 submodule 里的规范和测试。specs/下的文件是失败实现必须去符合的 source of truth只有当你的任务本身就是修改 RealWorld 规范本身时你是规范维护者才允许编辑这些文件。对 submodule 的实际含义不要在里面提交任何让测试变绿的改动。按失败来源分别处理API 用例失败说明你的后端行为与 Hurl 套件断言不符。回到 endpoints、API response format、error-handling 等规范页比对你的接口行为修接口。若你认为规范本身有问题比如文字文档与测试不一致记住官方立场是以测试为准正确动作是向规范仓库提 issue而不是改本地测试。E2E 用例失败先看重试产生的 trace 和失败截图再逐项核对 SELECTORS.md 的契约表单输入的name属性、必需的 CSS 类layout、feed、tags、comments、profile、pagination、buttons、errors、按钮和链接的必需文本、路由、调试接口window.__conduit_debug__、JWT 的 LocalStorage key、默认头像行为。E2E 套件覆盖 authentication、articles、comments、navigation、settings、social、error handling 和基础 XSS 场景失败大多能对应到上面某一项契约。规范仓库更新后原本通过的用例开始失败规范与测试套件由维护者持续更新README.md 的 Active Maintainers 一节submodule 拉取新版后出现新失败时依然走修实现的路径不要回退测试。限制与后续要求规范仓库不是应用别期待在里面make出一个可跑的服务Makefile的入口make help可看主要服务于规范与文档本身的维护实现项目用它只需跑测试脚本。规范仓库内部约定用bun而非npm/node这适用于在规范仓库内工作文档构建、Bruno 再生成的场景实现项目侧跑 Hurl 和 Playwright 不受此约定影响。如果你的实现计划提交到 RealWorld 社区CodebaseShowexpectations.md 还要求实现项目至少包含一个单元测试不要求全覆盖、提供能说明本地运行方式的 README并保持实现与框架的更新同步。官方文档frontend/tests.md指出 Angular 实现angular-realworld-example-app是一个接入了该 E2E 套件的可用参考可作为别人是怎么挂载和配置的对照。完成标志HOST你的后端地址 ./run-api-tests-hurl.sh以退出码 0 结束且 Playwright E2E 运行无失败用例失败时按上文流程处理并留下 trace/截图证据。之后每次规范仓库更新重复这两个步骤即可。【免费下载链接】realworldThe mother of all demo apps — Exemplary fullstack Medium.com clone powered by React, Angular, Node, Django, and many more项目地址: https://gitcode.com/GitHub_Trending/re/realworld创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考