Package: aws-cdk.integ-tests
integ-tests---AWS CDK v1 has reached End-of-Support on 2023-06-01.
This package is no longer being updated, and users should migrate to AWS CDK v2.For more information on how to migrate, see theMigrating to AWS CDK v2guide.OverviewThis library is meant to be used in combination with theinteg-runnerCLI
to enable users to write and execute integration tests for AWS CDK Constructs.An integration test should be defined as a CDK application, and
there should be a 1:1 relationship between an integration test and a CDK application.So for example, in order to create an integration test calledmy-functionwe would need to create a file to contain our integration test application.test/integ.my-function.tsapp=App()stack=Stack()lambda_.Function(stack,"MyFunction",runtime=lambda_.Runtime.NODEJS_14_X,handler="index.handler",code=lambda_.Code.from_asset(path.join(__dirname,"lambda-handler")))This is a self contained CDK application which we could deploy by runningcdkdeploy--app'node test/integ.my-function.js'In order to turn this into an integration test, all that is needed is to
use theIntegTestconstruct.# app: App# stack: StackIntegTest(app,"Integ",test_cases=[stack])You will notice that thestackis registered to theIntegTestas a test case.
Each integration test can contain multiple test cases, which are just instances
of a stack. See theUsagesection for more details.UsageIntegTestSuppose you have a simple stack, that only encapsulates a Lambda function with a
certain handler:classStackUnderTest(Stack):def__init__(self,scope,id,*,architecture=None,description=None,env=None,stackName=None,tags=None,synthesizer=None,terminationProtection=None,analyticsReporting=None):super().__init__(scope,id,architecture=architecture,description=description,env=env,stackName=stackName,tags=tags,synthesizer=synthesizer,terminationProtection=terminationProtection,analyticsReporting=analyticsReporting)lambda_.Function(self,"Handler",runtime=lambda_.Runtime.NODEJS_14_X,handler="index.handler",code=lambda_.Code.from_asset(path.join(__dirname,"lambda-handler")),architecture=architecture)You may want to test this stack under different conditions. For example, we want
this stack to be deployed correctly, regardless of the architecture we choose
for the Lambda function. In particular, it should work for bothARM_64andX86_64. So you can create anIntegTestCasethat exercises both scenarios:classStackUnderTest(Stack):def__init__(self,scope,id,*,architecture=None,description=None,env=None,stackName=None,tags=None,synthesizer=None,terminationProtection=None,analyticsReporting=None):super().__init__(scope,id,architecture=architecture,description=description,env=env,stackName=stackName,tags=tags,synthesizer=synthesizer,terminationProtection=terminationProtection,analyticsReporting=analyticsReporting)lambda_.Function(self,"Handler",runtime=lambda_.Runtime.NODEJS_14_X,handler="index.handler",code=lambda_.Code.from_asset(path.join(__dirname,"lambda-handler")),architecture=architecture)# Beginning of the test suiteapp=App()IntegTest(app,"DifferentArchitectures",test_cases=[StackUnderTest(app,"Stack1",architecture=lambda_.Architecture.ARM_64),StackUnderTest(app,"Stack2",architecture=lambda_.Architecture.X86_64)])This is all the instruction you need for the integration test runner to know
which stacks to synthesize, deploy and destroy. But you may also need to
customize the behavior of the runner by changing its parameters. For example:app=App()stack_under_test=Stack(app,"StackUnderTest")stack=Stack(app,"stack")test_case=IntegTest(app,"CustomizedDeploymentWorkflow",test_cases=[stack_under_test],diff_assets=True,stack_update_workflow=True,cdk_command_options=CdkCommands(deploy=DeployCommand(args=DeployOptions(require_approval=RequireApproval.NEVER,json=True)),destroy=DestroyCommand(args=DestroyOptions(force=True))))IntegTestCaseStackIn the majority of cases an integration test will contain a singleIntegTestCase.
By default when you create anIntegTestanIntegTestCaseis created for you
and all of your test cases are registered to thisIntegTestCase. TheIntegTestCaseandIntegTestCaseStackconstructs are only needed when it is necessary to
defined different options for individual test cases.For example, you might want to have one test case wherediffAssetsis enabled.# app: App# stack_under_test: Stacktest_case_with_assets=IntegTestCaseStack(app,"TestCaseAssets",diff_assets=True)IntegTest(app,"Integ",test_cases=[stack_under_test,test_case_with_assets])AssertionsThis library also provides a utility to make assertions against the infrastructure that the integration test deploys.There are two main scenarios in which assertions are created.Part of an integration test usinginteg-runnerIn this case you would create an integration test using theIntegTestconstruct and then make assertions using theassertproperty.
You shouldnotutilize the assertion constructs directly, but should instead use themethodsonIntegTest.assert.# app: App# stack: Stackinteg=IntegTest(app,"Integ",test_cases=[stack])integ.assertions.aws_api_call("S3","getObject")Part of a  normal CDK deploymentIn this case you may be using assertions as part of a normal CDK deployment in order to make an assertion on the infrastructure
before the deployment is considered successful. In this case you can utilize the assertions constructs directly.# my_app_stack: StackAwsApiCall(my_app_stack,"GetObject",service="S3",api="getObject")DeployAssertAssertions are created by using theDeployAssertconstruct. This construct creates it's ownStackseparate from
any stacks that you create as part of your integration tests. ThisStackis treated differently from other stacks
by theinteg-runnertool. For example, this stack will not be diffed by theinteg-runner.DeployAssertalso provides utilities to register your own assertions.# my_custom_resource: CustomResource# stack: Stack# app: Appinteg=IntegTest(app,"Integ",test_cases=[stack])integ.assertions.expect("CustomAssertion",ExpectedResult.object_like({"foo":"bar"}),ActualResult.from_custom_resource(my_custom_resource,"data"))In the above example an assertion is created that will trigger a user definedCustomResourceand assert that thedataattribute is equal to{ foo: 'bar' }.AwsApiCallA common method to retrieve the "actual" results to compare with what is expected is to make an
AWS API call to receive some data. This library does this by utilizing CloudFormation custom resources
which means that CloudFormation will call out to a Lambda Function which will
use the AWS JavaScript SDK to make the API call.This can be done by using the class directory (in the case of a normal deployment):# stack: StackAwsApiCall(stack,"MyAssertion",service="SQS",api="receiveMessage",parameters={"QueueUrl":"url"})Or by using theawsApiCallmethod onDeployAssert(when writing integration tests):# app: App# stack: Stackinteg=IntegTest(app,"Integ",test_cases=[stack])integ.assertions.aws_api_call("SQS","receiveMessage",{"QueueUrl":"url"})EqualsAssertionThis library currently provides the ability to assert that two values are equal
to one another by utilizing theEqualsAssertionclass. This utilizes a Lambda
backedCustomResourcewhich in tern uses theMatchutility from the@aws-cdk/assertionslibrary.# app: App# stack: Stack# queue: sqs.Queue# fn: lambda.IFunctioninteg=IntegTest(app,"Integ",test_cases=[stack])integ.assertions.invoke_function(function_name=fn.function_name,invocation_type=InvocationType.EVENT,payload=JSON.stringify({"status":"OK"}))message=integ.assertions.aws_api_call("SQS","receiveMessage",{"QueueUrl":queue.queue_url,"WaitTimeSeconds":20})message.assert_at_path("Messages.0.Body",ExpectedResult.object_like({"request_context":{"condition":"Success"},"request_payload":{"status":"OK"},"response_context":{"status_code":200},"response_payload":"success"}))Matchinteg-testsalso provides aMatchutility similar to the@aws-cdk/assertionsmodule.Matchcan be used to construct theExpectedResult.# message: AwsApiCallmessage.expect(ExpectedResult.object_like({"Messages":Match.array_with([{"Body":{"Values":Match.array_with([{"Asdf":3}]),"Message":Match.string_like_regexp("message")}}])}))ExamplesInvoke a Lambda FunctionIn this example there is a Lambda Function that is invoked and
we assert that the payload that is returned is equal to '200'.# lambda_function: lambda.IFunction# app: Appstack=Stack(app,"cdk-integ-lambda-bundling")integ=IntegTest(app,"IntegTest",test_cases=[stack])invoke=integ.assertions.invoke_function(function_name=lambda_function.function_name)invoke.expect(ExpectedResult.object_like({"Payload":"200"}))Make an AWS API CallIn this example there is a StepFunctions state machine that is executed
and then we assert that the result of the execution is successful.# app: App# stack: Stack# sm: IStateMachinetest_case=IntegTest(app,"IntegTest",test_cases=[stack])# Start an executionstart=test_case.assertions.aws_api_call("StepFunctions","startExecution",{"state_machine_arn":sm.state_machine_arn})# describe the results of the executiondescribe=test_case.assertions.aws_api_call("StepFunctions","describeExecution",{"execution_arn":start.get_att_string("executionArn")})# assert the resultsdescribe.expect(ExpectedResult.object_like({"status":"SUCCEEDED"}))