@aws-cdk/assert

Testing utilities and assertions for CDK libraries

This library contains helpers for writing unit tests and integration tests for CDK libraries

Unit tests

Write your unit tests like this:

const stack = new Stack();

new MyConstruct(stack, 'MyConstruct', {
    ...
});

expect(stack).to(someExpectation(...));

Here are the expectations you can use:

Verify (parts of) a template

Check that the synthesized stack template looks like the given template, or is a superset of it. These functions match logical IDs and all properties of a resource.

matchTemplate(template, matchStyle)
exactlyMatchTemplate(template)
beASupersetOfTemplate(template)

Example:

expect(stack).to(beASupersetOfTemplate({
    Resources: {
        HostedZone674DD2B7: {
            Type: "AWS::Route53::HostedZone",
            Properties: {
                Name: "test.private.",
                VPCs: [{
                    VPCId: { Ref: 'VPC06C5F037' },
                    VPCRegion: { Ref: 'AWS::Region' }
                }]
            }
        }
    }
}));

Check existence of a resource

If you only care that a resource of a particular type exists (regardless of its logical identifier), and that some of its properties are set to specific values:

haveResource(type, subsetOfProperties)

Example:

expect(stack).to(haveResource('AWS::CertificateManager::Certificate', {
    DomainName: 'test.example.com'
    // Note: some properties omitted here
}));

Integration tests

Integration tests are modeled as CDK apps that are deployed by the developers. If deployment succeeds, the synthesized template is saved in a local file and "locked". During build, the test app is only synthesized and compared against the checked-in file to protect against regressions.

Setup

Create any number of files called integ.*.ts in your test directory. These should be CDK apps containing a single stack.

Add the following to your package.json':

{
    scripts: {
        "test": ".... && cdk-integ-assert",
        "integ": "cdk-integ"
    },
    ...
    devDependencies: {
        "@aws-cdk/assert": "*",
        "aws-cdk": "*"
    }
}

This installs two tools into your scripts:

• When npm test is executed (during build), the cdk-integ-assert tool is invoked. This tool will only synthesize the integration test stacks and compare them to the .expected files. If the files differ (or do not exist), the test will fail.
• When npm run integ is executed (manually by the developer), the cdk-integ tool is invoked. This tool will actually attempt to deploy the integration test stacks into the default environment. If it succeeds, the .expected file will be updated to include the latest synthesized stack.

The usage of cdk-integ is:

cdk-integ [--no-clean] [filters...]

# or

npm run integ -- [--no-clean] [filters...]

• If --no-clean is specified, the integration test stacks will not be cleaned up. This can be used to perform manual validation on the stacks.
• If filters are specified, each test name is evaluated against each filter. If the name matches any of the filters, the test is included. Otherwise it is skipped.

Changelog

0.25.0 (2019-02-28)

Bug Fixes

• toolkit: Don't collect runtime information when versionReporting is disabled (#1890) (f827a88)
• aws-codepipeline: update CFN example. (#1653) (5dec01a)
• aws-s3-deployment: add setup.cfg to fix pip install bug on mac (#1826) (759c708)
• cdk: move apply() from Construct to ConstructNode (#1738) (642c8a6), closes #1732
• cloudtrail: addS3EventSelector does not expose all options (#1854) (5c3431b), closes #1841
• cloudtrail: Invalid resource for policy when using sendToCloudWatchLogs (#1851) (816cfc0), closes #1848
• cloudwatch: fix name of 'MetricAlarmProps' (#1765) (c87f09a), closes #1760
• codebuild: accept IRole instead of Role (#1781) (f08ca15), closes #1778
• codedeploy: LambdaDeploymentGroup now takes IRole (#1840) (f6adb7c), closes #1833
• codepipeline: allow providing Tokens as the physical name of the Pipeline. (#1800) (f6aea1b), closes #1788
• core: improve error message if construct names conflict (#1706) (0ea4a78)
• core: performance improvements (#1750) (77b516f)
• ecs: rename capacity adding methods (#1715) (e3738ac)
• elbv2: explicitly implement IApplicationTargetGroup (#1806) (828a2d7), closes #1799
• init: add new parameter to C# example (#1831) (c7b99d8)
• kms: have EncryptionKeyBase implement IEncryptionKey (#1728) (49080c6)
• lambda: Add 'provided' runtime (#1764) (73d5bef), closes #1761
• lambda: add region check for environment variables (#1690) (846ed9f)
• ssm: Generate correct SSM Parameter ARN (#1726) (39df456)
• toolkit: correctly reset context from the shell command (#1903) (58025c0)
• toolkit: correcty load cdk.json file without context (#1900) (7731565)
• toolkit: ignore hidden files for 'cdk init' (#1766) (afdd173), closes #1758
• toolkit: only fail if errors are on selected stacks (#1807) (9c0cf8d), closes #1784 #1783
• toolkit: support diff on multiple stacks (#1855) (72d2535)
• build: Npm ignores files and folders named "core" by default (#1767) (42876e7), closes npm/npm-packlist#24
• core: stack.partition is never scoped (#1763) (c968588)

Features

• apigateway: add support for MethodResponse to aws-apigateway. (#1572) (46236d9)
• autoscaling: bring your own IAM role (#1727) (2016b8d), closes #1701
• aws-eks: add construct library for EKS (#1655) (22fc8b9), closes #991
• cfnspec: manually add VPCEndpointService (#1734) (f782958), closes #1659
• codebuild: add support for setting the gitCloneDepth property on Project sources. (#1798) (5408a53), closes #1789
• core: Add construct.node.stack attribute (#1753) (a46cfd8), closes #798
• dynamodb: partitionKey and sortKey are now immutable (#1744) (63ae0b4)
• ecs: allow ECS to be used declaratively (#1745) (2480f0f), closes #1618
• kms: Allow opting out of "Retain" deletion policy (#1685) (7706302)
• lambda: allow specify event sources in props (#1746) (a84157d)
• lambda-event-sources: "api" event source (#1742) (5c11680)
• route53: Convenience API for creating zone delegations (#1853) (f974531), closes #1847
• sns: Support raw message delivery (#1827) (cc0a28c)
• ssm: allow referencing "latest" version of SSM parameter (#1768) (9af36af), closes #1587
• toolkit: improve docker build time in CI (#1776) (1060b95), closes #1748
• codepipelines: re-structure the CodePipeline Construct library API. (#1590) (3c3db07)
• decdk: Prototype for declarative CDK (decdk) (#1618) (8713ac6)

BREAKING CHANGES TO EXPERIMENTAL FEATURES

• cloudtrail: The CloudTrail.addS3EventSelector accepts an options object instead of only a ReadWriteType value.
• codedeploy: If an existing role is provided to a LambdaDeploymentGroup, you will need to provide the assuming service principal (codedeploy.amazonaws.com) yourself.
• core:$$** 'Aws' class returns unscoped Tokens, introduce a new class 'ScopedAws' which returns scoped Tokens.
• ssm: Rename parameter.valueAsString => parameter.stringValue, rename parameter.valueAsList => parameter.stringListValue, rename ssmParameter.parameterValue => ssmParameter.stringValue or ssmParameter.stringListValue depending on type, rename secretString.value => secretString.stringValue, rename secret.toSecretString() =>secret.secretString
• cloudwatch: Rename 'MetricAarmProps' => 'MetricAlarmProps'.
• core: Stack.find(c) and Stack.tryFind(c) were replaced by c.node.stack.
• dynamodb: partitionKey is now a required property when defining a dynamodb.Table. The addPartitionKey and addSortKey methods have been removed.
• cdk: Tag aspects use this feature and any consumers of this implementation must change from myConstruct.apply( ... ) to myConstruct.node.apply( ... ).
• ecs: Rename 'addDefaultAutoScalingGroupCapacity' => 'addCapacity', 'addAutoScalingGroupCapacity' => 'addAutoScalingGroup'.
• codepipelines: the CodePipeline Stage class is no longer a Construct, and cannot be instantiated directly, only through calling Pipeline#addStage; which now takes an Object argument instead of a String.
• codepipelines: the CodePipeline Actions are no longer Constructs.
• codepipelines: the CodePipeline Action name is now part of the Action props, instead of being a separate parameter.
• codepipelines: the Pipeline#addToPipeline methods in Resources like S3, CodeBuild, CodeCommit etc. have been renamed to toCodePipelineAction.
• aws-eks: For AutoScalingGroup, renamed minSize => minCapacity, maxSize => maxCapacity, for consistency with desiredCapacity and also Application AutoScaling. For ECS's addDefaultAutoScalingGroupCapacity(), instanceCount => desiredCapacity and the function now takes an ID (pass "DefaultAutoScalingGroup" to avoid interruption to your deployments).