@aws-cdk/assert

Testing utilities and assertions for CDK libraries

---

The APIs of higher level constructs in this module are experimental and under active development. They are subject to non-backward compatible changes or removal in any future version. These are not subject to the Semantic Versioning model and breaking changes will be announced in the release notes. This means that while you may use them, you may need to update your source code when upgrading to a newer version of this package.

---

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

    ShouldNotExist: ABSENT
}));

ABSENT is a magic value to assert that a particular key in an object is not set (or set to undefined).

Check number of resources

If you want to assert that n number of resources of a particular type exist, with or without specific properties:

countResources(type, count)
countResourcesLike(type, count, props)

Example:

expect(stack).to(countResources('AWS::ApiGateway::Method', 3));
expect(stack).to(countResourcesLike('AWS::ApiGateway::Method', 1, {
  HttpMethod: 'GET',
  ResourceId: {
    "Ref": "MyResource01234"
  }
}));

Check existence of an output

haveOutput assertion can be used to check that a stack contains specific output. Parameters to check against can be:

• outputName
• outputValue
• exportName

If outputValue is provided, at least one of outputName, exportName should be provided as well

Example

expect(synthStack).to(haveOutput({
  outputName: 'TestOutputName',
  exportName: 'TestOutputExportName',
  outputValue: {
    'Fn::GetAtt': [
      'TestResource',
      'Arn'
    ]
  }
}));

Changelog

1.33.0 (2020-04-17)

⚠ BREAKING CHANGES TO EXPERIMENTAL FEATURES

• kinesis: grantRead() API no longer provides permissions to kinesis:DescribeStream as it provides permissions to kinesis:DescribeStreamSummary and kinesis:SubscribeToShard in it's place. If it's still desired, it can be added through the grant() API on the stream.
• kinesis: grantWrite() API no longer has DescribeStream permissions as it has been replaced by ListShards for shard discovery

Features

• cfnspec: cloudformation spec v12.2.0 (#7248) (1475d5a)
• Support AppSync DataSource type: NONE (f35a4db)
• cfnspec: cloudformation spec v12.3.0 (#7359) (a80918f)
• ec2: expose blockDevices in CommonAutoScalingGroupProps (#7291) (5fe4480)
• ec2: filtering selected subnets by availability zone (2d3e612)
• eks: support a new option to create bottlerocket capacity. (e9f691f), closes #7268
• kinesis: grantRead now allows the ListShards action and grant is now public (#6141) (563fba4), closes #3357
• kinesis: add grant API to IStream to add permissions to a Stream (#7354) (c223406)
• kinesis: the aws-kinesis module is now stable (#7349) (4ab3ffa), closes #5874
• update "constructs" to 3.x (#7408) (8f8d20f), closes #6978

Bug Fixes

• appsync: Don't create serviceRole for datasource type NONE (6d1cb11), closes #7360
• cli: --app command does not work when executing a command without arguments (#7249) (994414c), closes #6930
• cli: parameter values with multiple = symbols get truncated (#7226) (b7ddf5b), closes #7246
• cloudwatch: Alarm annotation ignores datapointsToAlarm (#7202) (92fb853), closes #7152
• cloudwatch: Dashboard Spacer doesn't require empty props object (ca2f923)
• new IAM Condition type is unusable in Java (#7270) (ffb2e1e)
• core: unable to reference resources across multiple nested stacks (#7187) (000f0c2), closes #6473 #7059 #7059 #5888
• ec2: can reference VpcEndpointService id and service name (1007a22)
• efs: support tagging + filesystem naming (3dd8058)
• eks: missing permissions to add and remove tags when creating EKS cluster resource (#7302) (b14172d), closes #7163
• eks: unable to create KubernetesResources in another stack (#7322) (54129c8), closes #7231
• elbv2: imported LoadBalancer ignores pathPatterns prop (8ed2e0c), closes #7303
• route53-patterns: HttpsRedirect redirects to index.html (278fe29), closes /github.com/aws/aws-cdk/issues/5700#issuecomment-614112813 /github.com/aws/aws-cdk/issues/5700#issuecomment-614816819
• s3: allow accessLogsPrefix without accessLogsBucket (#6709) (4c199f6), closes #6599