• Version 2.68.0
  • Published
  • 186 kB
  • 1 dependency
  • Apache-2.0 license


npm i @aws-cdk/assert
yarn add @aws-cdk/assert
pnpm add @aws-cdk/assert


An assertion library for use with CDK Apps



variable ABSENT

const ABSENT: string;
  • Magic value to signify that a certain key should be absent from the property bag.

    The property is either not present or set to `undefined.

    NOTE: ABSENT only works with the haveResource() and haveResourceLike() assertions.


function annotateMatcher

annotateMatcher: <A extends object>(
how: A,
matcher: PropertyMatcher
) => PropertyMatcher;
  • Annotate a matcher with toJSON

    We will JSON.stringify() values if we have a match failure, but for matchers this would show (in traditional JS fashion) something like '[function Function]', or more accurately nothing at all since functions cannot be JSONified.

    We override to JSON() in order to produce a readable version of the matcher.

function anything

anything: () => PropertyMatcher;
  • Matches any value

function arrayWith

arrayWith: (...elements: any[]) => PropertyMatcher;
  • A matcher for a list that contains all of the given elements in any order

function beASupersetOfTemplate

beASupersetOfTemplate: (template: {
[key: string]: any;
}) => Assertion<StackInspector>;

    function canonicalizeTemplate

    canonicalizeTemplate: (template: any) => any;
    • Reduce template to a normal form where asset references have been normalized

      This makes it possible to compare templates if all that's different between them is the hashes of the asset values.

      Currently only handles parameterized assets, but can (and should) be adapted to handle convention-mode assets as well when we start using more of those.

    function countResources

    countResources: (
    resourceType: string,
    count?: number
    ) => JestFriendlyAssertion<StackInspector>;
    • An assertion to check whether a resource of a given type and with the given properties exists, disregarding properties

    function countResourcesLike

    countResourcesLike: (
    resourceType: string,
    count: number | undefined,
    props: any
    ) => Assertion<StackInspector>;
    • An assertion to check whether a resource of a given type and with the given properties exists, considering properties

    function deepObjectLike

    deepObjectLike: <A extends object>(pattern: A) => PropertyMatcher;
    • A matcher for an object that contains at least the given fields with the given matchers (or literals)

      Switches to "deep" lenient matching. Nested objects also only need to contain declared keys.

    function encodedJson

    encodedJson: (matcher: any) => PropertyMatcher;
    • Match on the innards of a JSON string, instead of the complete string

    function exactlyMatchTemplate

    exactlyMatchTemplate: (template: {
    [key: string]: any;
    }) => Assertion<StackInspector>;

      function exactValue

      exactValue: (expected: any) => PropertyMatcher;
      • Match exactly the given value

        This is the default, you only need this to escape from the deep lenient matching of deepObjectLike.

      function exist

      exist: () => Assertion<StackPathInspector>;

        function expect

        expect: (
        stack: api.CloudFormationStackArtifact | cdk.Stack | Record<string, any>,
        skipValidation?: boolean
        ) => StackInspector;

          function failMatcher

          failMatcher: (inspection: InspectionFailure, error: string) => boolean;
          • Helper function to make matcher failure reporting a little easier

            Our protocol is weird (change a string on a passed-in object and return 'false'), but I don't want to change that right now.

          function haveOutput

          haveOutput: (
          props: HaveOutputProperties
          ) => JestFriendlyAssertion<StackInspector>;
          • An assertion to check whether Output with particular properties is present in a stack

            Parameter props

            properties of the Output that is being asserted against. Check ``HaveOutputProperties`` interface to get full list of available parameters

          function haveResource

          haveResource: (
          resourceType: string,
          properties?: any,
          comparison?: ResourcePart,
          allowValueExtension?: boolean
          ) => Assertion<StackInspector>;
          • An assertion to check whether a resource of a given type and with the given properties exists, disregarding properties

            Parameter resourceType

            the type of the resource that is expected to be present.

            Parameter properties

            the properties that the resource is expected to have. A function may be provided, in which case it will be called with the properties of candidate resources and an ``InspectionFailure`` instance on which errors should be appended, and should return a truthy value to denote a match.

            Parameter comparison

            the entity that is being asserted against.

            Parameter allowValueExtension

            if properties is an object, tells whether values must match exactly, or if they are allowed to be supersets of the reference values. Meaningless if properties is a function.

          function haveResourceLike

          haveResourceLike: (
          resourceType: string,
          properties?: any,
          comparison?: ResourcePart
          ) => Assertion<StackInspector>;
          • Sugar for calling ``haveResource`` with ``allowValueExtension`` set to ``true``.

          function haveType

          haveType: (type: string) => Assertion<StackPathInspector>;

            function isSuperObject

            isSuperObject: (
            superObj: any,
            pattern: any,
            errors?: string[],
            allowValueExtension?: boolean
            ) => boolean;
            • Return whether superObj is a super-object of obj.

              A super-object has the same or more property values, recursing into sub properties if ``allowValueExtension`` is true.

              At any point in the object, a value may be replaced with a function which will be used to check that particular field. The type of a matcher function is expected to be of type PropertyMatcher.


              - Use objectLike or a literal object instead.

            function match

            match: (value: any, matcher: any, inspection: InspectionFailure) => boolean;
            • Match a given literal value against a matcher

              If the matcher is a callable, use that to evaluate the value. Otherwise, the values must be literally the same.

            function matcherFrom

            matcherFrom: (matcher: any) => PropertyMatcher;
            • Make a matcher out of the given argument if it's not a matcher already

              If it's not a matcher, it will be treated as a literal.

            function matchTemplate

            matchTemplate: (
            template: { [key: string]: any },
            matchStyle?: MatchStyle
            ) => Assertion<StackInspector>;

              function not

              not: <T extends Inspector>(assertion: Assertion<T>) => Assertion<T>;

                function notMatching

                notMatching: (matcher: any) => PropertyMatcher;
                • Negate an inner matcher

                function objectLike

                objectLike: <A extends object>(pattern: A) => PropertyMatcher;
                • A matcher for an object that contains at least the given fields with the given matchers (or literals)

                  Only does lenient matching one level deep, at the next level all objects must declare the exact expected keys again.

                function stringLike

                stringLike: (pattern: string) => PropertyMatcher;
                • Do a glob-like pattern match (which only supports *s). Supports multiline strings.


                class AndAssertion

                class AndAssertion<
                InspectorClass extends Inspector
                > extends Assertion<InspectorClass> {}


                  constructor(first: Assertion<InspectorClass>, second: Assertion<InspectorClass>);

                    property description

                    description: string;

                      method assertOrThrow

                      assertOrThrow: (inspector: InspectorClass) => void;

                        method assertUsing

                        assertUsing: (_inspector: InspectorClass) => boolean;

                          class Assertion

                          abstract class Assertion<InspectorClass extends Inspector> {}

                            property description

                            abstract readonly description: string;

                              method and

                              and: (assertion: Assertion<InspectorClass>) => Assertion<InspectorClass>;
                              • Assert this thing and another thing

                              method assertOrThrow

                              assertOrThrow: (inspector: InspectorClass) => void;

                                method assertUsing

                                abstract assertUsing: (inspector: InspectorClass) => boolean;

                                  class Capture

                                  class Capture<T = any> {}
                                  • Captures a value onto an object if it matches a given inner matcher

                                    Example 1

                                    const someValue = Capture.aString(); expect(stack).toHaveResource({ // ... Value: someValue.capture(stringMatching('*a*')), }); console.log(someValue.capturedValue);


                                  protected constructor(typeValidator?: TypeValidator<T>);

                                    property capturedValue

                                    readonly capturedValue: {};
                                    • Return the value that was captured

                                      Throws an exception if now value was captured

                                    property didCapture

                                    readonly didCapture: boolean;
                                    • Whether a value was successfully captured

                                    method a

                                    static a: <T>(validator: TypeValidator<T>) => Capture<T>;
                                    • A Capture object that captures a custom type

                                    method anyType

                                    static anyType: () => Capture<any>;
                                    • A Capture object that captures any type

                                    method aString

                                    static aString: () => Capture<string>;
                                    • A Capture object that captures a string type

                                    method capture

                                    capture: (matcher?: any) => PropertyMatcher;
                                    • Capture the value if the inner matcher successfully matches it

                                      If no matcher is given, anything() is assumed.

                                      And exception will be thrown if the inner matcher returns true and the value turns out to be of a different type than the Capture object is expecting.

                                    class HaveResourceAssertion

                                    class HaveResourceAssertion extends JestFriendlyAssertion<StackInspector> {}


                                      resourceType: string,
                                      properties?: any,
                                      part?: ResourcePart,
                                      allowValueExtension?: boolean

                                        property description

                                        readonly description: string;

                                          method assertOrThrow

                                          assertOrThrow: (inspector: StackInspector) => void;

                                            method assertUsing

                                            assertUsing: (inspector: StackInspector) => boolean;

                                              method generateErrorMessage

                                              generateErrorMessage: () => string;

                                                class Inspector

                                                abstract class Inspector {}



                                                    property aroundAssert

                                                    aroundAssert?: (cb: () => void) => any;

                                                      property value

                                                      readonly value: any;

                                                        method notTo

                                                        notTo: (assertion: Assertion<this>) => any;

                                                          method to

                                                          to: (assertion: Assertion<this>) => any;

                                                            class JestFriendlyAssertion

                                                            abstract class JestFriendlyAssertion<
                                                            InspectorClass extends Inspector
                                                            > extends Assertion<InspectorClass> {}

                                                              method generateErrorMessage

                                                              abstract generateErrorMessage: () => string;
                                                              • Generates an error message that can be used by Jest.

                                                              class NegatedAssertion

                                                              class NegatedAssertion<I extends Inspector> extends Assertion<I> {}


                                                                constructor(negated: Assertion<I>);

                                                                  property description

                                                                  readonly description: string;

                                                                    method assertUsing

                                                                    assertUsing: (inspector: I) => boolean;

                                                                      class StackInspector

                                                                      class StackInspector extends Inspector {}


                                                                        constructor(stack: any);

                                                                          property stack

                                                                          readonly stack: any;

                                                                            property value

                                                                            readonly value: { [key: string]: any };

                                                                              method at

                                                                              at: (path: string | string[]) => StackPathInspector;

                                                                                method toMatch

                                                                                toMatch: (template: { [key: string]: any }, matchStyle?: MatchStyle) => any;

                                                                                  class StackPathInspector

                                                                                  class StackPathInspector extends Inspector {}


                                                                                    constructor(stack: api.CloudFormationStackArtifact, path: string);

                                                                                      property path

                                                                                      readonly path: string;

                                                                                        property stack

                                                                                        readonly stack: api.CloudFormationStackArtifact;

                                                                                          property value

                                                                                          readonly value: { [key: string]: any };

                                                                                            class SynthUtils

                                                                                            class SynthUtils {}

                                                                                              method subset

                                                                                              static subset: (stack: core.Stack, options: SubsetOptions) => any;
                                                                                              • Returns

                                                                                                Returns a subset of the synthesized CloudFormation template (only specific resource types).

                                                                                              method synthesize

                                                                                              static synthesize: (
                                                                                              stack: core.Stack,
                                                                                              options?: core.StageSynthesisOptions
                                                                                              ) => cxapi.CloudFormationStackArtifact;
                                                                                              • Returns the cloud assembly template artifact for a stack.

                                                                                              method toCloudFormation

                                                                                              static toCloudFormation: (
                                                                                              stack: core.Stack,
                                                                                              options?: core.StageSynthesisOptions
                                                                                              ) => any;
                                                                                              • Synthesizes the stack and returns the resulting CloudFormation template.


                                                                                              interface HaveOutputProperties

                                                                                              interface HaveOutputProperties {}
                                                                                              • Interface for haveOutput function properties NOTE that at least one of [outputName, exportName] should be provided

                                                                                              property exportName

                                                                                              exportName?: any;
                                                                                              • Export name of the output, when it's exported for cross-stack referencing - the export name is not required and will not be checked

                                                                                              property outputName

                                                                                              outputName?: string;
                                                                                              • Logical ID of the output - the logical ID of the output will not be checked

                                                                                              property outputValue

                                                                                              outputValue?: any;
                                                                                              • Value of the output; - the value will not be checked

                                                                                              interface InspectionFailure

                                                                                              interface InspectionFailure {}

                                                                                                property failureReason

                                                                                                failureReason: string;

                                                                                                  property resource

                                                                                                  resource: any;

                                                                                                    interface SubsetOptions

                                                                                                    interface SubsetOptions {}

                                                                                                      property resourceTypes

                                                                                                      resourceTypes?: string[];
                                                                                                      • Match all resources of the given type


                                                                                                      enum MatchStyle

                                                                                                      enum MatchStyle {
                                                                                                      EXACT = 'exactly',
                                                                                                      NO_REPLACES = 'no replaces',
                                                                                                      SUPERSET = 'superset',

                                                                                                        member EXACT

                                                                                                        EXACT = 'exactly'
                                                                                                        • Requires an exact match

                                                                                                        member NO_REPLACES

                                                                                                        NO_REPLACES = 'no replaces'
                                                                                                        • Allows any change that does not cause a resource replacement

                                                                                                        member SUPERSET

                                                                                                        SUPERSET = 'superset'
                                                                                                        • Allows additions, but no updates

                                                                                                        enum ResourcePart

                                                                                                        enum ResourcePart {
                                                                                                        Properties = 0,
                                                                                                        CompleteDefinition = 1,
                                                                                                        • What part of the resource to compare

                                                                                                        member CompleteDefinition

                                                                                                        CompleteDefinition = 1
                                                                                                        • Check the entire CloudFormation config

                                                                                                          (including UpdateConfig, DependsOn, etc.)

                                                                                                        member Properties

                                                                                                        Properties = 0
                                                                                                        • Only compare the resource's properties

                                                                                                        Type Aliases

                                                                                                        type PropertyMatcher

                                                                                                        type PropertyMatcher = (props: any, inspection: InspectionFailure) => boolean;

                                                                                                          type TypeValidator

                                                                                                          type TypeValidator<T> = (x: any) => x is T;

                                                                                                            Package Files (15)

                                                                                                            Dependencies (1)

                                                                                                            Dev Dependencies (9)

                                                                                                            Peer Dependencies (3)


                                                                                                            To add a badge like this onejsDocs.io badgeto your package's README, use the codes available below.

                                                                                                            You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/@aws-cdk/assert.

                                                                                                            • Markdown
                                                                                                            • HTML
                                                                                                              <a href="https://www.jsdocs.io/package/@aws-cdk/assert"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>