@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.18.0 (2018-11-19)

Bug Fixes

• aws-cdk: make bootstrapping not require --app (#1191) (c7b1004), closes #1188
• aws-ecs: don't emit DesiredCount in daemon mode (#1199) (7908de4), closes #1197
• aws-elasticloadbalancingv2: 'targetType' on groups (#1174) (b4293f2)
• aws-elasticloadbalancingv2: fix rule dependency (#1170) (aeb0f4f), closes #1160
• deps: upgrade jsii to 0.7.11 (#1202) (f3a5f12)
• docs: fix "getting started" documentation (#1045) (29b611f)
• toolkit: typo in cdk bootstrap output (#1176) (b83fe85)

Features

• aws-autoscaling: add instance AutoScaling (#1134) (d397dd7), closes #1042 #1113
• aws-codebuild: add support for additional sources and artifact in Projects. (#1110) (d911b08)
• aws-ec2: add VPC context provider (#1168) (e8380fa), closes #1095
• aws-ecs: expose service and target group on the LoadBalancedFargateService (#1175) (e799699)
• aws-ecs: instance autoscaling and drain hook (#1192) (811462e), closes #1162
• aws-ecs: Support HTTPS in load balanced Fargate service (#1115) (76a5cc7)
• aws-ecs: TLS support for Fargate service applet (#1184) (18166ce)
• update to CloudFormation spec v2.13.0 (#1203) (c531c84)
• aws-elasticloadbalancingv2: add metrics (#1173) (68d481d), closes #853
• docs: getting started instructions for csharp (#1185) (2915ac1), closes #696
• toolkit: add 'cdk context' command (#1169) (2db536e), closes #311
• toolkit: by default hide AWS::CDK::Metadata from "cdk diff" (#1186) (ef0017a), closes #465
• toolkit: improve diff user interface (#1187) (9c3c5c7), closes #1121 #1120
• aws-codepipeline: switch to webhooks instead of polling by default for the GitHub (#1074)

BREAKING CHANGES TO EXPERIMENTAL FEATURES

• aws-codebuild: this changes the way CodeBuild Sources are constructed (we moved away from multiple parameters in the constructor, in favor of the more idiomatic property interface).
• aws-elasticloadbalancingv2: targetGroup.listenerDependency() has been renamed to targetGroup.loadBalancerDependency().