{"id":2872,"library":"aws-cdk-integ-tests-alpha","title":"CDK Integration Testing Constructs (Alpha)","description":"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.","status":"active","version":"2.248.0a0","language":"en","source_language":"en","source_url":"https://github.com/aws/aws-cdk.git","tags":["aws","cdk","testing","integration-testing","alpha","infrastructure-as-code"],"install":[{"cmd":"pip install aws-cdk-integ-tests-alpha","lang":"bash","label":"Python library"},{"cmd":"npm install -g @aws-cdk/integ-runner","lang":"bash","label":"Required CLI tool for execution"}],"dependencies":[{"reason":"Core AWS CDK constructs are required to define applications and stacks for testing.","package":"aws-cdk.lib","optional":false},{"reason":"Fundamental library for defining tree-structured runtime objects (constructs).","package":"constructs","optional":false},{"reason":"Runtime requirement for the library.","package":"python","optional":false,"version_spec":"~=3.9"}],"imports":[{"note":"The primary construct for defining an integration test case.","symbol":"IntegTest","correct":"from aws_cdk.integ_tests_alpha import IntegTest"},{"note":"Used to define the expected outcomes in assertions.","symbol":"ExpectedResult","correct":"from aws_cdk.integ_tests_alpha import ExpectedResult"},{"note":"Utility for constructing complex expected results, similar to @aws-cdk/assertions.","symbol":"Match","correct":"from aws_cdk.integ_tests_alpha import Match"}],"quickstart":{"code":"import os\nfrom aws_cdk import App, Stack\nfrom aws_cdk.aws_s3 import Bucket\nfrom aws_cdk.integ_tests_alpha import IntegTest, ExpectedResult\n\nclass MyTestStack(Stack):\n    def __init__(self, scope: App, id: str):\n        super().__init__(scope, id)\n        self.bucket = Bucket(self, \"MyTestBucket\")\n\napp = App()\nstack_under_test = MyTestStack(app, \"IntegTestStack\")\n\ninteg_test = IntegTest(app, \"Integ\",\n    test_cases=[stack_under_test],\n    # Optional: allow the test runner to destroy specific resource types\n    allow_destroy=['AWS::S3::Bucket']\n)\n\n# Assert that the S3 bucket exists by calling the S3 ListBuckets API\n# and matching the bucket name token. The `get_att` is crucial for\n# referencing runtime-generated resource attributes.\ninteg_test.assertions.aws_api_call(\n    service=\"S3\",\n    api=\"listBuckets\",\n    output_paths=[\"Buckets\"]\n).expect(\n    ExpectedResult.object_like({\n        \"Buckets\": ExpectedResult.array_with([\n            ExpectedResult.object_like({\"Name\": integ_test.get_att(stack_under_test.bucket.bucket_name).token})\n        ])\n    })\n)\n\n# To run this integration test, save the above as `my_integ_test.py`,\n# then synthesize with `cdk synth` and execute with the `integ-runner` CLI:\n# cdk synth\n# integ-runner --directory cdk.out --test-case IntegTestStack/Integ --force-update\n","lang":"python","description":"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."},"warnings":[{"fix":"Be prepared to update your source code when upgrading versions. Regularly review AWS CDK release notes for 'alpha' modules.","message":"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.","severity":"breaking","affected_versions":"All alpha versions"},{"fix":"Ensure `npm install -g @aws-cdk/integ-runner` is performed in your environment.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"The integration tests expect interactions with AWS SDK v3. Older implementations relying on AWS SDK v2 within constructs might behave unexpectedly or require migration.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Provision a separate AWS account solely for integration testing. Ensure appropriate IAM policies are in place to limit the scope of test deployments.","message":"Integration tests should always be run in a dedicated, isolated AWS account to prevent accidental modifications or resource conflicts with development or production environments.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}