CDK Integration Testing Constructs (Alpha)

Warnings

• breaking This library is an 'alpha' module, meaning its APIs are experimental and under active development. It is subject to non-backward compatible changes or removal in any future version and does not adhere to the Semantic Versioning model. Breaking changes will be announced in release notes.
  Fix: Be prepared to update your source code when upgrading versions. Regularly review AWS CDK release notes for 'alpha' modules.
• gotcha Executing integration tests requires the `@aws-cdk/integ-runner` CLI, which is a separate Node.js package installed via `npm`. Python users might incorrectly assume a pure Python execution environment.
  Fix: Ensure `npm install -g @aws-cdk/integ-runner` is performed in your environment.
• gotcha Integration tests deploy actual AWS resources to your account, incurring potential costs and requiring proper cleanup. While `integ-runner` handles cleanup by default, options like `--no-clean` can leave resources behind.
  Fix: Always use a dedicated, non-production AWS account for integration testing. Monitor resource usage and ensure `integ-runner` completes successfully, or manually clean up if necessary.
• gotcha The integration tests expect interactions with AWS SDK v3. Older implementations relying on AWS SDK v2 within constructs might behave unexpectedly or require migration.
  Fix: Ensure that any custom resources or Lambda functions invoked by integration tests are compatible with AWS SDK v3. Verify if your specific CDK constructs have been updated to use SDK v3.
• gotcha Initial runs of integration tests will often fail snapshot verification because no previous snapshot exists. This is expected behavior as the runner creates the first snapshot.
  Fix: If this is the first run, the failure is benign. The snapshot will be created, and subsequent runs will compare against it. Use `--force-update` to automatically update the snapshot on intended changes.
• gotcha Integration tests should always be run in a dedicated, isolated AWS account to prevent accidental modifications or resource conflicts with development or production environments.
  Fix: Provision a separate AWS account solely for integration testing. Ensure appropriate IAM policies are in place to limit the scope of test deployments.

Install

• pip install aws-cdk-integ-tests-alpha Python library
• npm install -g @aws-cdk/integ-runner Required CLI tool for execution

Imports

• IntegTest

  from aws_cdk.integ_tests_alpha import IntegTest

  The primary construct for defining an integration test case.
• ExpectedResult

  from aws_cdk.integ_tests_alpha import ExpectedResult

  Used to define the expected outcomes in assertions.
• Match

  from aws_cdk.integ_tests_alpha import Match

  Utility for constructing complex expected results, similar to @aws-cdk/assertions.

Quickstart

This quickstart defines a simple CDK stack with an S3 bucket and then uses `aws-cdk-integ-tests-alpha` to assert that the created bucket can be listed via an AWS API call. It demonstrates the use of `IntegTest` with `aws_api_call` and `ExpectedResult` for making assertions against deployed resources. Note that executing this test requires the `@aws-cdk/integ-runner` CLI (installed via npm) to handle the deployment, assertion, and cleanup lifecycle.

import os
from aws_cdk import App, Stack
from aws_cdk.aws_s3 import Bucket
from aws_cdk.integ_tests_alpha import IntegTest, ExpectedResult

class MyTestStack(Stack):
    def __init__(self, scope: App, id: str):
        super().__init__(scope, id)
        self.bucket = Bucket(self, "MyTestBucket")

app = App()
stack_under_test = MyTestStack(app, "IntegTestStack")

integ_test = IntegTest(app, "Integ",
    test_cases=[stack_under_test],
    # Optional: allow the test runner to destroy specific resource types
    allow_destroy=['AWS::S3::Bucket']
)

# Assert that the S3 bucket exists by calling the S3 ListBuckets API
# and matching the bucket name token. The `get_att` is crucial for
# referencing runtime-generated resource attributes.
integ_test.assertions.aws_api_call(
    service="S3",
    api="listBuckets",
    output_paths=["Buckets"]
).expect(
    ExpectedResult.object_like({
        "Buckets": ExpectedResult.array_with([
            ExpectedResult.object_like({"Name": integ_test.get_att(stack_under_test.bucket.bucket_name).token})
        ])
    })
)

# To run this integration test, save the above as `my_integ_test.py`,
# then synthesize with `cdk synth` and execute with the `integ-runner` CLI:
# cdk synth
# integ-runner --directory cdk.out --test-case IntegTestStack/Integ --force-update