Registry /
aws / aws-cdk-integ-tests-alpha
Install & Compatibility
Where this runs
tested against v2.267.0a0 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 378.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 18.4s · import 0.000s · 379MB
400MB installed
● package 400MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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.
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
Debug
Known issues
breakingThis 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.fixBe prepared to update your source code when upgrading versions. Regularly review AWS CDK release notes for 'alpha' modules.
affects: All alpha versions
gotchaExecuting 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.fixEnsure `npm install -g @aws-cdk/integ-runner` is performed in your environment.
affects: All versions
gotchaIntegration 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.fixAlways 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.
affects: All versions
gotchaThe integration tests expect interactions with AWS SDK v3. Older implementations relying on AWS SDK v2 within constructs might behave unexpectedly or require migration.fixEnsure 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.
affects: All versions
gotchaInitial 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.fixIf 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.
affects: All versions
gotchaIntegration tests should always be run in a dedicated, isolated AWS account to prevent accidental modifications or resource conflicts with development or production environments.fixProvision a separate AWS account solely for integration testing. Ensure appropriate IAM policies are in place to limit the scope of test deployments.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'aws_cdk.integ_tests_alpha'
The 'aws_cdk.integ_tests_alpha' module is not installed or not found in the Python environment.
fixInstall the module using pip: 'pip install aws-cdk.integ-tests-alpha'.
ImportError: cannot import name 'IntegTest' from 'aws_cdk.integ_tests_alpha'
The 'IntegTest' class is not available in the 'aws_cdk.integ_tests_alpha' module, possibly due to an incorrect import statement or module version.
fixEnsure the correct import statement: 'from aws_cdk.integ_tests_alpha import IntegTest'.
TypeError: IntegTest() missing 2 required positional arguments: 'scope' and 'id'
The 'IntegTest' constructor requires 'scope' and 'id' arguments, which were not provided.
fixInstantiate 'IntegTest' with the required arguments: 'test = IntegTest(scope, id, props)'.
AttributeError: module 'aws_cdk.integ_tests_alpha' has no attribute 'IntegTest'
The 'IntegTest' class is not found in the 'aws_cdk.integ_tests_alpha' module, possibly due to an outdated module version.
fixUpdate the module to the latest version: 'pip install --upgrade aws-cdk.integ-tests-alpha'.
NameError: name 'IntegTest' is not defined
The 'IntegTest' class was not imported or is misspelled.
fixEnsure the correct import statement: 'from aws_cdk.integ_tests_alpha import IntegTest'.
Upgrade
Version history
2.267.0a0latest on PyPI · released Aug 27, 2026
Audit
Dependencies
aws-cdk.librequiredCore AWS CDK constructs are required to define applications and stacks for testing.
constructsrequiredFundamental library for defining tree-structured runtime objects (constructs).
pythonrequiredRuntime requirement for the library.