Angular 仓库 AI Agent 开发规范pnpm Bazel 环境、Zoneless 测试范式与贡献工作流【免费下载链接】angularDeliver web apps with confidence 项目地址: https://gitcode.com/GitHub_Trending/an/angularAngular 官方仓库内置了一份专门面向 AI Agent 的开发规范AGENTS.md/.agent/rules/agents.md它浓缩了在此仓库中工作所需的三类关键能力用 pnpm 与 Bazel 搭建构建测试环境、遵循 Zoneless无 Zone.js环境下的“Act, Wait, Assert”异步测试范式以及通过 gh CLI 和规范化的 commit 消息提交 Pull Request。读完本文你将能准确复现仓库中的测试运行方式理解框架自身测试为何不再依赖detectChanges()并能按仓库标准完成一次合格的代码提交。规范文件的定位AI Agent 的“always_on”工作手册仓库根目录下的 AGENTS.md 与.agent/rules/agents.md内容一致文件以如下 frontmatter 开头--- trigger: always_on ---这表示该规范对任何进入本仓库工作的 AI Agent始终生效而非按需触发。全文仅 35 行但覆盖四个维度环境Environment、关键文档索引Key Documentation、测试约定Testing与 Pull Request 流程。它的核心断言是This is the source code for the Angular framework. This guide outlines standard practices for AI agents working in this repository.换言之该文件不是通用贡献指南而是把 Angular 框架源码仓库中“与框架自身开发强绑定的约定”提炼为 Agent 可直接执行的规则。环境与构建命令pnpm 管理依赖Bazel 驱动测试规范文件 Environment 一节给出两条硬性约定使用pnpm进行包管理版本由根目录 package.json 的engines字段指定使用pnpm bazel test //target运行测试其中//target是 Bazel 目标路径。这两条约定与 构建与测试指南 完全一致该指南是仓库中运行 Bazel 目标的“权威手册”。结合指南内容完整的工作流命令如下# 1. 安装依赖对应 package.json 中的依赖声明 pnpm install # 2. 构建 Angular 框架产物输出到 dist/packages-dist pnpm build # 3. 运行指定 Bazel 目标的测试 pnpm bazel test //target # 4. 提交 PR 前建议跑完整测试套件 pnpm test //packages/... # 5. 代码格式检查 / 校验prettier 格式由 CI 强制 pnpm lint # 6. 自动格式化 pnpm ng-dev format changed [shaOrRef] # 只格式化相对某 ref 的变更文件默认 main pnpm ng-dev format all # 格式化全部源码几个值得注意的前提与限制Bazel 是构建测试的第一工具指南明确 “Bazel is used as the primary tool for building and testing Angular”调试细节见 Bazel 构建指南 的 “Testing Angular” 章节提交 PR 前应执行受影响的全部测试pnpm test //packages/...CI 也会在提交后再次运行受影响测试失败会在 GitHub 上以错误状态呈现代码必须通过格式检查才能合并仓库使用 prettier 自动格式化CI 会强制校验。关键文档索引三份“必读”规范规范文件 Key Documentation 一节列出了三份配套文档均位于 contributing-docs/ 目录文档作用Building and Testing运行各类目标build/test/snapshot的权威指南Coding StandardsTypeScript 及其他文件的代码风格规范Commit Guidelinescommit 消息与 PR 标题的格式规范其中 编码规范 明确其适用范围“仅针对 Angular 框架本身的开发而非用 Angular 构建的应用”并以 Google JavaScript Style Guide 为基础、prettier 自动格式化由 CI 强制执行它还包含若干具体的 API 设计要求例如“避免用布尔参数表达‘做额外的事’应拆分为不同函数”。这些是 Agent 在修改框架源码时必须对照的风格基准。测试约定核心Zoneless 与 Async-First这是规范文件技术含量最高的部分也是 Agent 在 Angular 仓库写测试时最容易出错的地方。前提假定运行在无 Zone 的环境中规范第一条即声明Zoneless Async-First:Assume a zoneless environment where state changes schedule updates asynchronously.这意味着框架自身测试默认运行在zoneless不依赖 Zone.js 的NgZone/ProxyZone模式下状态变化会异步地调度变更检测与视图更新。直接推论是禁止使用fixture.detectChanges()手动触发更新——它属于 Zone.js 时代的同步刷新手法与异步调度模型相冲突必须采用 “Act, Wait, Assert” 三步模式Act操作更新状态或执行一个动作Wait等待await fixture.whenStable()让框架处理完已调度的更新Assert断言验证输出。这一模式在框架各包的测试中大量出现。例如 Router 包的 router_link_spec.ts 中每个用例都遵循“操作后await fixture.whenStable()再断言”的写法导航集成测试 navigation.spec.ts 亦同。用 useAutoTick() 通过“快进”假时钟减少等待为了让测试保持快速规范要求在可能的情况下最小化等待推荐方式是引入useAutoTick()来自 packages/private/testing/src/utils.ts通过 mock clock 快进时间。查看该文件源码可以看到其实现非常直白——它在beforeEach中安装 Jasmine 的 fake clock 并开启autoTick在afterEach中卸载// packages/private/testing/src/utils.ts (约 L204-L212) export function useAutoTick() { beforeEach(() { jasmine.clock().install(); jasmine.clock().autoTick(); }); afterEach(() { jasmine.clock().uninstall(); }); }由于定时器在假时钟下“即时推进”依赖setTimeout/setInterval的异步逻辑无需真实等待。实际用例可见 form_builder_spec.ts它在describe顶层调用useAutoTick()因此块内大量用例包括涉及异步校验器的用例都能以同步断言完成。确需等待时真实异步测试 timeout() / whenStable()规范同时给出“必须等待”场景的标准做法使用真实异步测试it(..., async () { ... })并搭配两个工具await timeout(ms)等待指定毫秒数await fixture.whenStable()等待框架进入稳定状态。timeout的实现位于同一文件utils.ts 约 L183-L187本质是一个基于setTimeout的 Promise 包装// packages/private/testing/src/utils.ts (约 L183-L187) export async function timeout(ms?: number): Promisevoid { return new Promise((resolve) { setTimeout(resolve, ms); }); }一个典型组合出现在 form_builder_spec.ts 中import {useAutoTick, timeout} from angular/private/testing; describe(Form Builder, () { useAutoTick(); // 顶层开启假时钟自动推进 it(... 需要等待的用例 ..., async () { // Act: 更新状态 // Wait: await timeout(); // 让出宏任务约 L250 处用法 await fixture.whenStable(); // 等待框架稳定约 L279/L305 处用法 // Assert: expect(...).toEqual(...); }); });从源码结构看utils.ts 还配套了几个值得了解的测试辅助函数Agent 在编写框架测试时同样可以复用waitFor(callback, options)约 L264-L299以真实时钟为基准的轮询等待器默认超时 100ms、默认间隔 0超时后抛出携带“尝试次数 最后一次错误 原始调用栈”的增强错误信息expectText(text, options)约 L245-L258基于waitFor断言容器默认为最近 fixture 的nativeElement文本内容匹配字符串或正则withBody/withHead约 L38-L75为测试自动注入/清理document.body/head中的 HTMLensureDocument/cleanupDocument约 L120-L166在 Node 环境下用 domino 建立document并在beforeEach/afterEach中自动注册/还原。Pull Request 与提交规范规范文件 Pull Requests 一节要求创建和管理 PR 使用ghCLIGitHub CLI。与之配套的提交格式约束来自 Commit Message 规范其核心结构为header body footer三段header BLANK LINE body BLANK LINE footerHeader 采用type(scope): short summary格式其中 type 必须为build/ci/docs/feat/fix/perf/refactor/test之一scope 为受影响的 npm 包名如animations、common、compiler-cli、core、forms、router等summary 使用现在时、首字母小写、结尾无句号。Body 除docs类型外为必填且至少 20 个字符Footer 可选。该格式同时用于 PR 标题。规范要点速查清单场景约定依据包管理一律使用 pnpmAGENTS.md Environment 节运行测试pnpm bazel test //targetAGENTS.md / 构建指南触发更新禁止fixture.detectChanges()改用await fixture.whenStable()AGENTS.md Testing 节减少等待describe 顶层useAutoTick()utils.ts必须等待真实 async 用例 await timeout(ms)/await fixture.whenStable()utils.ts代码格式prettierpnpm lint校验pnpm ng-dev format修复构建指南PR / 提交gh CLI type(scope): summary格式AGENTS.md / 提交规范需要强调的是上述约定均以当前仓库实际内容为准测试工具函数位于私有包angular/private/testing源码路径 packages/private/testing/src/utils.ts框架包内测试如 packages/forms/test/、packages/router/test/即是这些约定的参考实现Agent 在扩展测试时优先对齐同包内既有用例的写法比遵循任何外部惯例都更可靠。【免费下载链接】angularDeliver web apps with confidence 项目地址: https://gitcode.com/GitHub_Trending/an/angular创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考