# @aws-cdk-testing/cli-integ 中文文档 规范地址：https://npmcn.com/package/%40aws-cdk-testing/cli-integ/ 版本：3\.45\.0 npm 元数据更新时间：2026-11-05T16:47:19.069Z 中文译文更新时间：2026-11-07T14:55:10.217Z 软件包许可：Apache-2\.0 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40aws-cdk-testing/cli-integ 原文对照：https://npmcn.com/package/%40aws-cdk-testing/cli-integ/?lang=original 项目主页：https://github.com/aws/aws-cdk 源码仓库：https://github.com/aws/aws-cdk-cli ## 关键信息（来自 npm 元数据） - 包体积（解压后）：3.2 MB，798 个文件 - 模块格式：CommonJS - TypeScript 类型：包内自带 - Node.js 要求：\>= 18\.0\.0 - 运行依赖：38 个 - 首次发布：2023-01-19T06:01:44.177Z - 最新版本发布：2026-11-05T16:47:18.708Z - 近 30 天下载量：13023（2026-10-07 至 2026-11-05，npm 官方下载统计） - 已发布版本数：277（近 12 个月 62 个） ## 中文简介 AWS CDK CLI 集成测试 ## 安装 ```sh npm install @aws-cdk-testing/cli-integ ``` 也可以使用：`pnpm add @aws-cdk-testing/cli-integ`、`yarn add @aws-cdk-testing/cli-integ`、`bun add @aws-cdk-testing/cli-integ` ## README # CDK CLI 整合测试 * * * ![cdk-constructs: Stable](https://img.shields.io/badge/cdk--constructs-stable-success.svg?style=for-the-badge) * * * 此套件包含CDK CLI集成测试套件,以及对照CDK的不同分布运行这些套件所需的辅助工具(在源寄存器中,针对构建目录,或针对已发布发行). 包裹船装有 `npm-shrinkwrap.json` 由 `yarn-cling` 以确保通过 npm 安装时具有决定性的依赖性. > 工具和测试本身应该放在不同的包中,但我想防止包的扩散。 现在,我们将保持他们在一起. ## 测试 测试本身在 `tests/` 目录 : ```text tests/ ├── cli-integ-tests ├── init-csharp ├── init-fsharp ├── init-java ├── init-javascript ├── init-python ├── init-typescript-app ├── init-typescript-lib ├── init-go └── uberpackage ``` 每个子目录包含一个测试 **套间**,在开发的管道中,每套套房都以代码构建工作单独运行,都是平行的. 这需要在管道中进行人工配置:增加一个新的套房,首先在这里增加一个套房,再将套房也添加到管道中. 最安全的策略是首先增加一个微不足道的后继套房(例如,一个单一的测试与 `expect(true).toBeTruthy()`,然后写下实际测试. 测试套房是作为Jest测试的集合而写成的,它们使用Jest运行,使用其中的代码 `lib/` 作为助手的目录. ### 正在测试的部件 测试有自己的版本,可以在多个版本测试其他组件. 以下组件可以被注入, ,如果不提供,则默认为最近发布的版本. 由于许多测试都非常不同,因此没有通用机制可以用于: 将这些依赖性注入测试。 用户可以指定组件版本,但 测试作者负责取取这些参数并使用它来设置 合适的测试环境. | 构成部分 | 命令行参数 | 默认 | 跑者治疗 | 检测治疗 | | --- | --- | --- | --- | --- | | CDK 构造库 | `--framework-version=VERSION` | 最新 | 没什么 | `npm install` 输入临时项目目录. | | | `--framework-path=DIR` | | 没什么 | 使用安装在 `DIR`。 。 。 . | | 光盘CLI | `--cli-version=VERSION` | 自动源码 | `npm install` 进入临时目录 | 添加为 `$PATH`。 。 。 . | | | `--cli-source=ROOT` 或者说 `auto` | 自动源码 | | 添加 `/packages/aws-cdk/bin` 改为 `$PATH`。 。 。 . | | | `--cli-path=DIR` | | 没什么 | 添加为 `$PATH`。 。 。 . | | 工具包库 | `--toolkit-lib-version=VERSION` | 德维德 | 安装到自己的道具中 | 没什么 | | | `--toolkit-lib-path=DIR` | | 连接到自己的道具 | 没什么 | | cdk -资产 | `--cdk-assets-version=VERSION` | 最新 | `npm install` 进入临时目录 | 添加为 `$PATH`。 。 。 . | | | `--cdk-assets-path=DIR` | | 没什么 | 添加为 `$PATH`。 。 。 . | ### 运行测试套房 你开一间套房 `bin/run-suite` 工具。 您必须选择 CLI 和框架的版本 `npm install`ed,或指向源树的根: ```shell # Automatically determine the source tree root $ bin/run-suite # Use the CLI from the given repo $ bin/run-suite --cli-source=/path/to/repo-root # Run against a released version $ bin/run-suite --cli-version=2.34.5 # Run against a specific framework version $ bin/run-suite --framework-version=2.34.5 ``` 要使用已经安装的组件,而不是从登记册上安装,请通过 `--*-path` 选项。 包装进的目录是包含其 `node_modules`数字 : ```shell $ bin/run-suite \ --cli-path=/path/to/install-dir \ --cdk-assets-path=/path/to/install-dir \ --framework-path=/path/to/install-dir \ --toolkit-lib-path=/path/to/install-dir ``` 通过一个版本选项或一个组件的路径选项,而不是两者. 如果全部安装在同一个目录中,请通过一次 `--packages-path` 相反: ```shell $ bin/run-suite --packages-path=/path/to/install-dir ``` `--packages-path` 用于每个未配置自己选项的组件。 譬如说, `--packages-path=/path/a --framework-path=/path/b` 从 `/path/b` 其他一切从 `/path/a`。目录中缺失的组件会失败运行;它不会从登记册中安装. 与 `--framework-path`,设置 CDK 应用程序的测试则使用该目录中安装的软件包而不是安装. 如果测试需要一个没有安装在那里的软件包,则失败并列出缺失的软件包. #### 用已安装的软件包进行靴子套装测试 鞋带测试需要这些包: | 软件包 | 用于 | 选项 | | --- | --- | --- | | `aws-cdk` | 测试中的CLI | `--cli-path` | | `cdk-assets` | 资产公布 | `--cdk-assets-path` | | `@aws-cdk/toolkit-lib` | 工具包库 | `--toolkit-lib-path` | | `aws-cdk-lib` | 测试应用 | `--framework-path` | 最简单的设置是将它们全部提前安装到一个目录中,然后用 `--packages-path`数字 : ```shell $ mkdir -p /tmp/cdk-integ-packages $ (cd /tmp/cdk-integ-packages && npm install aws-cdk cdk-assets @aws-cdk/toolkit-lib aws-cdk-lib) $ bin/run-suite cli-integ-tests --packages-path=/tmp/cdk-integ-packages -F bootstrap ``` 使用已安装的软件包可以消除到达npm注册的需要. 由于其他原因,例如登录到公共ECR画廊,测试仍需要网络访问. 要进行特定测试,请添加 `-F`编号 :`-t` 以及测试名称的下弦. 例如: ```shell bin/run-suite -a cli-integ-tests -F some-test.integ -t 'load old assemblies' ``` ### 运行针对二进制的测试套件 运行"init test"的测试套件需要实际在CodeArtifact寄存器中上演的套件才能运行. 这需要您做一个完整的构建,然后在您自己的账户中创建一个代码Artifact寄存器,将软件包上传到那里,然后在外壳中运行测试,让NPU,Pip,Maven等在代码Artifact中查找这些软件包. ```shell # Build and pack all of CDK (in the `aws-cdk` repo, will take ~an hour) $ ./build.sh $ ./pack.sh # Use publib to upload to CodeArtifact $ npm install -g publib # publib-ca is a CLI tool that comes with publib $ publib-ca create $ publib-ca publish /path/to/dist # Run the tests against those repositories (may need to substitute 0.0.0 w/ local number) $ source ~/.publib-ca/usage/activate.bash $ bin/run-suite --use-cli-release=0.0.0 # Clean up $ publib-ca delete ``` ### 用调试器运行测试 ```json { "version": "0.2.0", "configurations": [ { "type": "node", "request": "launch", "args": ["-a", "cli-integ-tests", "-t", "context in stage propagates to top"], "name": "debug integ tests", "program": "~/aws-cdk/packages/@aws-cdk-testing/cli-integ/bin/run-suite", "console": "integratedTerminal", "sourceMaps": true, "skipFiles": [ "/**/*" ], "stopOnEntry": false } ] } ``` 1. 如果你查过了 `aws-cdk` 在您的仓库中 `~` 目录, 使用以上 `launch.json`。 。 。 . 2. 在那个 `"args"` 值在 `"-t"`输入您想要运行的测试名称 . 3. 按下 VS 代码绿色箭头启动调试器. ### 在公关期间运行 整合测试在公关期间自动执行. 每次工作流程运行都会生成下调摘要 详细列出哪些测试通过/失败,以及一些额外统计数据. > 例如: [https://github.com/aws/aws-cdk-cli/actions/runs/15305859516 (英语)](https://github.com/aws/aws-cdk-cli/actions/runs/15305859516) 要调试一个失败的测试, 请导航到执行日志并搜索测试的名称 . 你会找到一个动词日志,显示测试期间进行的所有操作. 与本地运行不同,公关使用 _大气层_ 服务,一种设计为 CDK 的内部服务 提供与清洁AWS环境的集成测试。 它让我们可以同时进行许多测试, 并大大缩短套房时间。 大多数时候, _大气层_ 应该对你透明, 但有时,通过本地的测试可能因额外的限制而在公关期间失败 它规定: - **服务控制政策:** AWS 环境(即账户)受拒绝访问的 SCP 约束 具体服务。 例如,你可能看到一个失败,类似于: ``` User: arn:aws:sts::111111111111:assumed-role/cdk-hnb659fds-cfn-exec-role-111111111111-eu-central-1/AWSCloudFormation is not authorized to perform: logs:CreateLogGroup on resource: arn:aws:logs:eu-central-1:111111111111:log-group:/aws/lambda/cdktest-00cyqupxno939-imp-cdkimportnodejslambdates-6X36hssZOiZk:log-stream: with an explicit deny in a service control policy ``` 这意味着你的公关引入了一种需要 援引新的服务, 或者部署一种新的资源, 这是以前不需要的。 当这种情况发生时——通过公关联系维护者. 他们将评估新要求是否合理,并给予必要的许可. ## 工具 里面有很多工具 里面有很多工具 `bin/` 目录。 它们是: ```text bin/ ├── apply-patches ├── query-github ├── run-suite ├── stage-distribution └── test-root ``` - `apply-patches`:用于回归测试。 将补丁应用于测试的历史版本来修复假正测试失败. - `query-github`:用于回归测试。 查询GitHub之前发布的版本. - `run-suite`:运行一个测试套房 `tests/` 目录. - `stage-distribution`:用于管道中的测试。 上传候选人释放二进制到 CodeArtifact 以便使用它们安装 `npm install`, (中文(简体) ), `pip install`等 (中文(简体) ). - `test-root`:返回包含所有测试的目录(用于应用补丁). ## 回归测试 回归测试机制也有所参与,因此值得自己的部分。 不过,这项原则并不难解释: _我们运行之前版本的CLI Integ测试 针对新的候选者发布CLI, 确保我们没有意外引入任何突破行为_。 。 。 . 有两个事实使这一点略为复杂: - (1) CLI和框架都可能已经改变,框架和CLI之间可能出现不相容. 更新的CLI必须始终支持更古老的框架版本. 因此,我们进行两种融合测试的口味: - 旧的测试,新的CLI,新的框架 - 旧测试、新CLI、旧框架 测试矩阵是这样的: ```text OLD TESTS NEW TESTS CLI CLI Old New Old New ┌────────┬────────┐ ┌────────┬────────┐ F'WORK │ prev │ │ F'WORK │ │ │ Old │ rls │ regr │ Old │ (N/A) │ ? │ │ integ │ │ │ │ │ ├────────┼────────┤ ├────────┼────────┤ │ │ │ │ │ cur │ New │ (N/A) │ regr │ New │ (N/A) │ rls │ │ │ │ │ │ integ │ └────────┴────────┘ └────────┴────────┘ ``` 除了"新测试,新CLI,旧框架"之外,我们覆盖了一切,这还不清楚测试甚至是否合理,因为有些新功能可能依赖于框架支持,而旧版本中还没有这种支持. - (2)有时,当我们出于一些严重(如安全原因)而引入对框架或CLI的突破性修改时,旧的测试会在较新的释放上失败,或者可能是因为我们有一个偶然通过的旧版本中的bug,但现在需要更新测试才能通过bugfix. 对于这个案例,我们有一个补丁机制, 这样在新发布的工具, 我们包含的文件 复制 通过一个OLED发布的测试, 允许它们通过。 对于最简单的案例,有一个抑制单一测试运行的机制,这样我们就可以跳过一个测试运行一个发布. 对于更复杂的案件,我们复制了补丁 `.js` 将替换旧源文件的源文件 。 (Patches 被认为是其中的一部分) _工具_中,不包含 _测试_) (中文(简体) ). ### 机制 为了以倒退的方式进行测试,应进行下列工作: - 下载当前 `@aws-cdk-testing/cli-integ` 文物在 `V1`。 。 。 . - 确定上一个版本 `V0` (使用时 `query-github` 为这个). - 下载上一个 `@aws-cdk-testing/cli-integ` 文物在 `V0`。 。 。 . - 从 `V1` 文物,应用 `V0` 补丁设置 . - 运行 `V0` 试验 `--framework-version` 选项 : ```shell # Old tests, new CLI, new framework V0/bin/run-suite --use-cli-release=V1 --framework-version=V1 [...] # Old tests, new CLI, old framework V0/bin/run-suite --use-cli-release=V1 --framework-version=V0 [...] ``` ### 补丁 要补齐之前的一组测试, 以新发布方式使其通过, 请添加一个目录到 `resources/cli-regression-patches`。最简单的方法是添加一个 `skip-tests.txt` 文件 : ```shell # The version of the tests that are currently failing (V0 in the paragraph above) export VERSION=X.Y.Z mkdir -p resources/cli-regression-patches/v${VERSION} cp skip-tests.txt resources/cli-regression-patches/v${VERSION}/ ``` 现在编辑 `resources/cli-regression-patches/vX.Y.Z/skip-tests.txt` 并且将您想要跳过的测试名称单独放在一条线上. 如果您需要替换源文件, 最好粘接编译 `.js` 这里的文件. `.ts` 源文件不会编译,因为它们不见了 `imports`。 。 。 . ## 常见问题 ### @aws-cdk-testing/cli-integ 是什么？ AWS CDK CLI 集成测试 ### 如何安装 @aws-cdk-testing/cli-integ？ 在项目目录运行 npm install @aws-cdk-testing/cli-integ，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 run-suite、test-root、query-github、apply-patches、stage-distribution、download-and-run-old-tests，可以用 npx run-suite 直接运行。 ### @aws-cdk-testing/cli-integ 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @aws-cdk-testing/cli-integ 支持 ESM 还是 CommonJS？ 以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。 ### @aws-cdk-testing/cli-integ 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>= 18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @aws-cdk-testing/cli-integ 可以商用吗？ @aws-cdk-testing/cli-integ 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。 ### @aws-cdk-testing/cli-integ 的下载量有多少？ 根据 npm 官方下载统计，@aws-cdk-testing/cli-integ 在 2026/10/07 – 2026/11/05 这 30 天内被下载 13,023 次，日均约 434 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @aws-cdk-testing/cli-integ 还在维护吗？ 最新版本 3\.45\.0 发布于 2026/11/06（2 天前）；至今共发布 277 个版本，其中过去 12 个月发布了 62 个；首次发布于 2023/01/19。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。