integ 运行者

本单元中更高层次的构件的API是实验性的并正在积极开发中. 在今后任何版本中,它们都须作非背向相容的修改或去除。 这些是 不适用 语义版本 模型和断开的更改 在发行笔记中宣布. 这意味着虽然你可能使用它们,但可能需要更新 当更新到此软件包的更新版本时,您的源代码.

概览

此工具已经创建, 最初由此 repo (aws/aws- cdk) 使用 。 长期目标是: 用于运行 CDK 集成测试。 我们是 发布这个工具,让社区能够使用,我们想得到反馈 工具应当支持的用例,或妨碍工具在 图书馆.

本工具意在与 综合测试 图书馆.

使用量

• 运行全部集成测试 test 目录

integ-runner [ARGS] [TEST...]

这将查找所有符合命名惯例的文件 /integ.*.(js|ts)$/ 或者说 /integ_*.py。 。 。 . 每个文件都代表一个自装的 AWS CDK 应用程序,使用 综合测试 图书馆.

默认执行 integ-runner 将针对每个文件( app) 执行以下任务 :

1. 合成每个集成测试以创建内存中的新快照
2. 将快照与上一个版本(即文件在 *.snapshot/**),并因任何分歧而失败.
   对于新的测试,它总是失败.

为了接受一个快照更新,必须部署优异测试,而且必须通过断言.
再次执行跑者,这次与 integ-runner --update-on-fail ,每个文件将发生下列情况:

1. 部署上一个快照
2. 将新版本作为 Stack 更新并运行断言
3. 如果成功, 更新快照

所有快照文件(即:. *.snapshot/**)必须进入版本控制. 如果不是,就不能在全系统和 更新工作流程 无法使用.

选项

• --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 接下来 更新工作流程 将被禁用

• --update-from-tags 在部署当前代码之前按顺序从给定的 git 标记部署快照 . 符号 --force。见 从标签更新 详细情况.

• --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\..*(?<!\.d)\.ts$
    • 应用运行命令 : node -r ts-node/register {filePath}
  • python数字 :
    • 文件正则Exp : ^integ_.*\.py$
    • 应用运行命令 : python {filePath}
  • go数字 :
    • 文件正则Exp : ^integ_.*\.go$
    • 应用运行命令 : go run {filePath}

• --list (默认=false(中文(简体) ) 列表测试而不是运行.

• --inspect-failures (默认=false(中文(简体) ) 当在快照比较中存在差异时保留生成快照 .

• --max-workers (默认=16(中文(简体) ) 在同时进行融合测试时,最多要使用多少工人.

• --proxy 对所有 AWS API 呼叫使用指定的代理 。 如果没有指定, 代理服务器设置是自动检测的 从 HTTPS_PROXY 编号 : HTTP_PROXY 环境变量.

• --ca-bundle-path 验证 HTTPS 请求时使用的 PEM 证书捆绑路径 。 如未指明, 从 AWS_CA_BUNDLE 环境变量.

示例

integ-runner --update-on-failed --parallel-regions us-east-1 --parallel-regions us-east-2 --parallel-regions us-west-2 --directory ./ --language python

这将从当前目录中循环搜索 Python 集成测试, 然后在全局平行执行 us-east-1, (中文(简体) ), us-east-2,并 us-west-2。 。 。 .

如果您正在提供要执行的测试列表, 作为 CLI 参数或文件, 测试名称需要相对 directory。 。 。 . 例如,如果有测试 aws-iam/test/integ.policy.js 而当前工作目录为 aws-iam 你会提供 integ.policy.js

integ-runner integ.policy.js

共同工作流程

运行集成测试时使用的一个常见的工作流程是首先运行集成测试,看看是否有任何快照差异.

integ-runner

如果有任何差异, 您可能会看到下面输出的输出 .

integ-runner

Verifying integration test snapshots...

  eks-cluster-private-endpoint No Change!
  eks-inference No Change!
  alb-controller No Change!
  eks-oidc-provider No Change!
  eks-bottlerocket-ng No Change!
  eks-cluster No Change!
  fargate-cluster No Change!
  eks-cluster-handlers-vpc No Change!
  eks-helm-asset - Snapshot changed!
Resources
[+] Custom::AWSCDK-EKS-HelmChart Clustercharttestocichart9C188967



Snapshot Results:

Tests:    1 failed, 9 total
Error: Some snapshot tests failed!
To re-run failed tests run: integ-runner --update-on-failed
    at main (packages/@aws-cdk/integ-runner/lib/cli.js:90:15)
error Command failed with exit code 1.

要重新运行失败测试的集成测试, 您将会运行 :

integ-runner --update-on-failed

这将运行快照测试并收集所有失败的测试. 然后会重新执行 失败测试的集成测试, 如果成功, 请保存新的快照 .

integ-runner --update-on-failed

Verifying integration test snapshots...

  eks-cluster-private-endpoint No Change!
  eks-inference No Change!
  alb-controller No Change!
  eks-oidc-provider No Change!
  eks-bottlerocket-ng No Change!
  eks-cluster No Change!
  fargate-cluster No Change!
  eks-cluster-handlers-vpc No Change!
  eks-helm-asset - Snapshot changed!
Resources
[+] Custom::AWSCDK-EKS-HelmChart Clustercharttestocichart9C188967



Snapshot Results:

Tests:    1 failed, 9 total

Running integration tests for failed tests...

Running in parallel across: us-east-1, us-east-2, us-west-2
Running test test/integ.eks-helm-asset.js in us-east-1
  eks-helm-asset Test Succeeded!

Test Results:

Tests:    1 passed, 1 total

巢穴堆栈模板也作为快照的一部分进行比较. 然而资产散列被默认忽略. 要启用 diff 资产散列, 设置 diffAssets: true 联 合 国 IntegTestProps。 。 。 .

更新工作流程

默认情况下,通过启用"更新工作流程"进行集成测试. 通过使用 --disable-update-workflow 命令行选项.

如果正在更新已有的快照, 集成测试跑取程序将首先部署已有快照, 然后进行堆栈更新 随着新的变化。 这是用来测试更新只会在堆栈更新中导致突破性变化的情况.

重要内容: 更新工作流程(均为 --update-workflow 财务报告和审定财务报表 --update-from-tags) 仅能工作 与 环境不可知性 示意图. 一个快照是环境不可知的,当它的模板做了 不嵌入特定账户ID或区域。 使用上下文查看的测试( 例如 VPC 或 AZ) 提供商)在快照中存储已解析的假值——这些可以进行分解,但可以 只有在快照没有硬码真实的环境特有值时才会部署. 如果你的测试 声明具体 env: { account, region },其快照不便,更新 工作流程将无法可靠地运作.

这个 integ-runner 并试图警告您,如果您正在做任何破坏性的改变,并发出如下信息:

!!! 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 然后你会跑:

integ-runner --update-on-failed --disable-update-workflow integ.new-test.js

这是因为对于一个新的测试,我们不需要测试更新工作流程(没有什么可以更新的).

从标签更新

使用 --update-from-tags 以验证一个堆栈可以通过特定版本的序列安全更新。 这主要有利于待命工程师验证一个固定装置对于目前处于破损版本的客户来说是安全的.

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 ,则跳过正常的合并基更新工作流程.

监视

移动时在监视模式下运行集成测试可能有用 在一个特定的测试.

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 如果一个文件没有 已存在.

{
  "watch": {}
}

您可以在创建后进一步编辑此文件并添加额外内容 watch 字段。 例如:

{
  "watch": {
    "include": ["**/*.js"]
  }
}

integ.json 计划

见 @aws-cdk/cloud-assembly-schema/lib/integ-tests/schema.ts

定义整合测试

见 @aws-cdk/integ-tests 关于如何定义的模块 跑者锻炼的融合测试.

配置文件

所有选项都可以通过 integ.config.json 当前工作目录中的配置文件 .

{
  "maxWorkers": 10,
  "parallelRegions": [
    "eu-west-1",
    "ap-southeast-2"
  ]
}

可用选项可通过运行以下命令列出:

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 的上下文和特征标记 .