Registry /
aws / aws-cdk-integ-tests-alpha
The `aws-cdk-integ-tests-alpha` library provides constructs for defining and validating integration tests for AWS CDK applications. It allows developers to deploy real AWS resources, run assertions against them, and manage their lifecycle. As an 'alpha' module, its APIs are experimental and subject to non-backward compatible changes or removal in future versions, not adhering to semantic versioning. The current version is 2.248.0a0, following the rapid release cadence of the AWS CDK.
Install & Compatibility
Where this runs
tested against v2.258.1a0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
The primary construct for defining an integration test case.
from aws_cdk.integ_tests_alpha import IntegTest
Used to define the expected outcomes in assertions.
from aws_cdk.integ_tests_alpha import ExpectedResult
Utility for constructing complex expected results, similar to @aws-cdk/assertions.
from aws_cdk.integ_tests_alpha import Match
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
Upgrade
Version history
Breaking-change detection hasn't run for this library yet.
Audit
Security & dependencies
CVE tracking and dependency tree are planned for a later release.