# @aws-cdk/integ-runner 中文文档 规范地址：https://npmcn.com/package/%40aws-cdk/integ-runner/ 版本：2\.206\.1 npm 元数据更新时间：2026-11-05T16:29:14.044Z 中文译文更新时间：2026-11-07T11:45:59.253Z 软件包许可：Apache-2\.0 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40aws-cdk/integ-runner 原文对照：https://npmcn.com/package/%40aws-cdk/integ-runner/?lang=original 项目主页：https://github.com/aws/aws-cdk 源码仓库：https://github.com/aws/aws-cdk-cli ## 关键信息（来自 npm 元数据） - 包体积（解压后）：14.7 MB，89 个文件 - 模块格式：CommonJS - TypeScript 类型：包内自带 - Node.js 要求：\>= 18\.0\.0 - 运行依赖：1 个 - 首次发布：2022-06-03T02:40:25.236Z - 最新版本发布：2026-11-05T16:29:13.653Z - 近 30 天下载量：118262（2026-10-08 至 2026-11-06，npm 官方下载统计） - 已发布版本数：370（近 12 个月 69 个） ## 中文简介 CDK 集成测试工具 ## 安装 ```sh npm install @aws-cdk/integ-runner ``` 也可以使用：`pnpm add @aws-cdk/integ-runner`、`yarn add @aws-cdk/integ-runner`、`bun add @aws-cdk/integ-runner` ## README # integ 运行者 * * * ![cdk-constructs: Experimental](https://img.shields.io/badge/cdk--constructs-experimental-important.svg?style=for-the-badge) > 本单元中更高层次的构件的API是实验性的并正在积极开发中. 在今后任何版本中,它们都须作非背向相容的修改或去除。 这些是 不适用 [语义版本](https://semver.org/) 模型和断开的更改 在发行笔记中宣布. 这意味着虽然你可能使用它们,但可能需要更新 当更新到此软件包的更新版本时,您的源代码. * * * ## 概览 此工具已经创建, 最初由此 repo (aws/aws- cdk) 使用 。 长期目标是: 用于运行 CDK 集成测试。 我们是 发布这个工具,让社区能够使用,我们想得到反馈 工具应当支持的用例,或妨碍工具在 图书馆. 本工具意在与 [综合测试](https://docs.aws.amazon.com/cdk/api/v2/docs/integ-tests-alpha-readme.html) 图书馆. ## 使用量 - 运行全部集成测试 `test` 目录 ```bash integ-runner [ARGS] [TEST...] ``` 这将查找所有符合命名惯例的文件 `/integ.*.(js|ts)$/` 或者说 `/integ_*.py`。 。 。 . 每个文件都代表一个自装的 AWS CDK 应用程序,使用 [综合测试](https://docs.aws.amazon.com/cdk/api/v2/docs/integ-tests-alpha-readme.html) 图书馆. 默认执行 `integ-runner` 将针对每个文件( app) 执行以下任务 : 1. 合成每个集成测试以创建内存中的新快照 2. 将快照与上一个版本(即文件在 `*.snapshot/**`),并因任何分歧而失败. 对于新的测试,它总是失败. 为了接受一个快照更新,必须部署优异测试,而且必须通过断言. 再次执行跑者,这次与 `integ-runner --update-on-fail` ,每个文件将发生下列情况: 1. 部署上一个快照 2. 将新版本作为 Stack 更新并运行断言 3. 如果成功, 更新快照 所有快照文件(即:. `*.snapshot/**`)必须进入版本控制. 如果不是,就不能在全系统和 [更新工作流程](https://npmcn.com/package/%40aws-cdk/integ-runner/#readme-update-workflow) 无法使用. ### 选项 - `--update-on-failed` (默认=`false`(中文(简体) ) 如果快照失败, 重新运行集成测试 - `--clean` (默认=`true`(中文(简体) ) 部署后销毁堆栈( 使用) `--no-clean` 用于调试) - `--verbose` (默认=`false`(中文(简体) ) 动词记录,包括综合测试指标 (请注明多次以增加动词) - `--parallel-regions` (默认=`us-east-1`, (中文(简体) ),`us-east-2`, (中文(简体) ), `us-west-2`(中文(简体) ) 要进行测试的区域列表 。 如果提供这个,所有测试都会 将在这些区域平行运作 - `--directory` (默认=`test`(中文(简体) ) 从此初始目录中循环搜索集成测试 - `--force` (默认=`false`(中文(简体) ) 即使测试通过, 也要重新运行整合测试 - `--profiles` 并行运行测试时使用的 AWS 配置文件列表 - `--exclude` (默认=`false`(中文(简体) ) 如果设定为 `true` 然后,所提供的测试清单将被排除在外 - `--strict` (默认=`false`(中文(简体) ) 如果找不到任何指定的测试, 则失败 。 无法使用 `--exclude` - `--from-file` 从此文件中读取测试列表 - `--disable-update-workflow` (默认=`false`(中文(简体) ) 如果设定为 `true` 接下来 [更新工作流程](https://npmcn.com/package/%40aws-cdk/integ-runner/#readme-update-workflow) 将被禁用 - `--update-from-tags` 在部署当前代码之前按顺序从给定的 git 标记部署快照 . 符号 `--force`。见 [从标签更新](https://npmcn.com/package/%40aws-cdk/integ-runner/#readme-update-from-tags) 详细情况. - `--app` 用于运行测试文件的自定义 CLI 命令 。 您可以包括 {filePath} 以指定在命令中插入测试文件路径的位置 。 示例: --app="python3.8 {filePath}". 与 `--test-regex` 完全定制测试运行方式,或使用单个测试方式 `--language` 预设以更改用于此语言的命令. - `--test-regex` 检测匹配此 JavaScript regex 模式的集成测试文件 。 如果使用多次,则检测出所有匹配任何一种模式的文件. - `--watch` 在监视模式下进行单一整合测试. 在监视模式下 integ 运行器 将不会保存任何快照. 与 `--app` 完全定制测试运行方式,或使用单个测试方式 `--language` 预设以更改此语言检测到的文件. - `--language` 语言预设要使用. 您可以通过多次通过此旗帜来发现并运行多种语言的测试(`--language typescript --language python`) (中文(简体) ). 所有支持语言的默认值 。 目前支持的语言预设有: - `javascript`数字 : - 文件正则Exp : `^integ\..*\.js$` - 应用运行命令 : `node {filePath}` - `typescript`数字 : 请注意,对于编译为JavaScript的TypeScript文件,JS测试会优先进行,TS测试不会被评价. - 文件正则Exp : `^integ\..*(? **重要内容:** 更新工作流程(均为 `--update-workflow` 财务报告和审定财务报表 `--update-from-tags`) 仅能工作 与 **环境不可知性** 示意图. 一个快照是环境不可知的,当它的模板做了 不嵌入特定账户ID或区域。 使用上下文查看的测试( 例如 VPC 或 AZ) 提供商)在快照中存储已解析的假值——这些可以进行分解,但可以 只有在快照没有硬码真实的环境特有值时才会部署. 如果你的测试 声明具体 `env: { account, region }`,其快照不便,更新 工作流程将无法可靠地运作. 这个 `integ-runner` 并试图警告您,如果您正在做任何破坏性的改变,并发出如下信息: ```bash !!! This test contains destructive changes !!! Stack: aws-cdk-lambda-1 - Resource: MyLambdaServiceRole4539ECB6 - Impact: WILL_DESTROY Stack: aws-cdk-lambda-1 - Resource: AliasAliasPermissionAF30F9E8 - Impact: WILL_REPLACE Stack: aws-cdk-lambda-1 - Resource: AliasFunctionUrlDC6EC566 - Impact: WILL_REPLACE Stack: aws-cdk-lambda-1 - Resource: Aliasinvokefunctionurl4CA9917B - Impact: WILL_REPLACE !!! If these destructive changes are necessary, please indicate this on the PR !!! ``` 如果预期(和需要)有破坏性的变化,请在公关上注明. ##### 新测试 如果您正在添加一个新的测试, 创建一个新的快照, 那么您应该使用 `--disable-update-workflow`。 。 。 . 例如,如果您正在尝试新测试 `integ.new-test.js` 然后你会跑: ```bash integ-runner --update-on-failed --disable-update-workflow integ.new-test.js ``` 这是因为对于一个新的测试,我们不需要测试更新工作流程(没有什么可以更新的). ##### 从标签更新 使用 `--update-from-tags` 以验证一个堆栈可以通过特定版本的序列安全更新。 这主要有利于待命工程师验证一个固定装置对于目前处于破损版本的客户来说是安全的. ```bash integ-runner --update-from-tags v2.150.0,v2.151.0 --update-on-failed integ.my-stack.js ``` 这将: 1. 检查标签上的快照 `v2.150.0` 并部署它( 新建堆栈) 2. 检查标签上的快照 `v2.151.0` 并部署(更新) 3. 部署当前代码( 最后堆栈更新) 4. 如果成功, 请更新快照 典型的用法是回归验证:版本N是好的,N+1引入了回归,而您对当前分支有固定. 运行中 `--update-from-tags vN,vN+1` 证明N+1上的客户可以安全地移动到固定点. 注释: - `--update-from-tags` 隐含 `--force` ——所有相匹配的测试均部署,而不论速成对比结果如何. - 如果任何指定标记上都不存在快照, 跑者会快速失败 . - `allowDestroy` 检查适用于每一个过渡,而不仅仅是最后的过渡. - 无法一起使用 `--no-update-workflow`。 。 。 . - 何时 `--update-from-tags` ,则跳过正常的合并基更新工作流程. ### 监视 移动时在监视模式下运行集成测试可能有用 在一个特定的测试. ```console integ-runner integ.new-test.js --watch ``` 在监视模式下, Integ 测试将运行类似 `cdk deploy --watch` 与 此外,还显示断言结果。 默认输出会 只显示断言结果. - 显示监视器运行中的控制台输出 `-v` - 同时流出"云表"日志(即:. `cdk deploy --watch --logs`运行与 `-vv` 当在监视模式下运行时, 大部分的 integ 运行器功能将会被转换 关闭. - 不创建快照 - 更新工作流程将不会运行 - 堆栈不会被清理( 你必须手动清理堆栈) - 只有一个测试可以运行 一旦你用手表走动 想要创造你所能看到的快照 以创建快照并清理测试. #### cdk.context.json (英语) cdk 手表取决于一个 `cdk.context.json` 已存在的文件有: `watch` 键。 这个 integ 运行者将创建默认值 `cdk.context.json` 如果一个文件没有 已存在. ```json { "watch": {} } ``` 您可以在创建后进一步编辑此文件并添加额外内容 `watch` 字段。 例如: ```json { "watch": { "include": ["**/*.js"] } } ``` ### integ.json 计划 见 [@aws-cdk/cloud-assembly-schema/lib/integ-tests/schema.ts](https://npmcn.com/package/%40aws-cdk/cloud-assembly-schema/lib/integ-tests/schema.ts) ### 定义整合测试 见 `@aws-cdk/integ-tests` 关于如何定义的模块 跑者锻炼的融合测试. ### 配置文件 所有选项都可以通过 `integ.config.json` 当前工作目录中的配置文件 . ```json { "maxWorkers": 10, "parallelRegions": [ "eu-west-1", "ap-southeast-2" ] } ``` 可用选项可通过运行以下命令列出: ```sh integ-runner --help ``` 要使用不同的配置文件,请提供 `--config` 命令行选项. ## 处理上下文和地物旗 默认, `integ-runner` 将使用最近推荐的一组功能 旗帜。 结果是 当你升级 `integ-runner`,则 特性标记设定可能改变并影响您生成的快照, 需要 即时更新. 如果您的测试目录有 `integ.context.json` 文档或 `cdk.json` 文件 从测试的上游,将使用这些文件的上下文值 完全取代内置旗帜。 这可以保证你的背景 同样,即使你升级 `integ-runner`也给你能力 以立即改变所有测试的上下文值。 如果有多个文件 它们不会合并:将使用最接近测试的文件,与 `integ.context.json` 优先于 `cdk.json`。 。 。 . 若为 `integ.context.json` 的单级词典 值的上下文键。 若为 `cdk.json` 发现,它的 `"context"` 将使用密钥 作为上下文键和值的词典(与通常的文件相同) 控制一个 CDK app 的上下文和特征标记 . ## 常见问题 ### @aws-cdk/integ-runner 是什么？ CDK 集成测试工具 ### 如何安装 @aws-cdk/integ-runner？ 在项目目录运行 npm install @aws-cdk/integ-runner，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 integ-runner，可以用 npx integ-runner 直接运行。 ### @aws-cdk/integ-runner 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @aws-cdk/integ-runner 支持 ESM 还是 CommonJS？ 以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。 ### @aws-cdk/integ-runner 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>= 18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @aws-cdk/integ-runner 可以商用吗？ @aws-cdk/integ-runner 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。 ### @aws-cdk/integ-runner 的下载量有多少？ 根据 npm 官方下载统计，@aws-cdk/integ-runner 在 2026/10/08 – 2026/11/06 这 30 天内被下载 118,262 次，日均约 3,942 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @aws-cdk/integ-runner 还在维护吗？ 最新版本 2\.206\.1 发布于 2026/11/06（2 天前）；至今共发布 370 个版本，其中过去 12 个月发布了 69 个；首次发布于 2022/06/03。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。