assertions

package
v2.175.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 11, 2025 License: Apache-2.0 Imports: 6 Imported by: 2

README

Assertions

If you're migrating from the old @aws-cdk/assert library, first use this migration guide to migrate from @aws-cdk/assert to @aws-cdk/assertions found in our GitHub repository. Then, you can migrate your application to AWS CDK v2 in order to use this library using this guide.

Functions for writing test asserting against CDK applications, with focus on CloudFormation templates.

The Template class includes a set of methods for writing assertions against CloudFormation templates. Use one of the Template.fromXxx() static methods to create an instance of this class.

To create Template from CDK stack, start off with:

import "github.com/aws/aws-cdk-go/awscdk"
import "github.com/aws/aws-cdk-go/awscdk"

stack := awscdk.NewStack()
// ...
template := awscdk.Template_FromStack(stack)

Alternatively, assertions can be run on an existing CloudFormation template -

templateJson := "{ \"Resources\": ... }" /* The CloudFormation template as JSON serialized string. */
template := awscdk.Template_FromString(templateJson)

Cyclical Resources Note

If allowing cyclical references is desired, for example in the case of unprocessed Transform templates, supply TemplateParsingOptions and set skipCyclicalDependenciesCheck to true. In all other cases, will fail on detecting cyclical dependencies.

Full Template Match

The simplest assertion would be to assert that the template matches a given template.

template.TemplateMatches(map[string]map[string]map[string]interface{}{
	"Resources": map[string]map[string]interface{}{
		"BarLogicalId": map[string]interface{}{
			"Type": jsii.String("Foo::Bar"),
			"Properties": map[string]*string{
				"Baz": jsii.String("Qux"),
			},
		},
	},
})

By default, the templateMatches() API will use the an 'object-like' comparison, which means that it will allow for the actual template to be a superset of the given expectation. See Special Matchers for details on how to change this.

Snapshot testing is a common technique to store a snapshot of the output and compare it during future changes. Since CloudFormation templates are human readable, they are a good target for snapshot testing.

The toJSON() method on the Template can be used to produce a well formatted JSON of the CloudFormation template that can be used as a snapshot.

See Snapshot Testing in Jest and Snapshot Testing in Java.

Counting Resources

This module allows asserting the number of resources of a specific type found in a template.

template.ResourceCountIs(jsii.String("Foo::Bar"), jsii.Number(2))

You can also count the number of resources of a specific type whose Properties section contains the specified properties:

template.ResourcePropertiesCountIs(jsii.String("Foo::Bar"), map[string]interface{}{
	"Foo": jsii.String("Bar"),
	"Baz": jsii.Number(5),
	"Qux": []*string{
		jsii.String("Waldo"),
		jsii.String("Fred"),
	},
}, jsii.Number(1))

Resource Matching & Retrieval

Beyond resource counting, the module also allows asserting that a resource with specific properties are present.

The following code asserts that the Properties section of a resource of type Foo::Bar contains the specified properties -

template.HasResourceProperties(jsii.String("Foo::Bar"), map[string]interface{}{
	"Lorem": jsii.String("Ipsum"),
	"Baz": jsii.Number(5),
	"Qux": []*string{
		jsii.String("Waldo"),
		jsii.String("Fred"),
	},
})

You can also assert that the Properties section of all resources of type Foo::Bar contains the specified properties -

template.AllResourcesProperties(jsii.String("Foo::Bar"), map[string]interface{}{
	"Lorem": jsii.String("Ipsum"),
	"Baz": jsii.Number(5),
	"Qux": []*string{
		jsii.String("Waldo"),
		jsii.String("Fred"),
	},
})

Alternatively, if you would like to assert the entire resource definition, you can use the hasResource() API.

template.HasResource(jsii.String("Foo::Bar"), map[string]interface{}{
	"Properties": map[string]*string{
		"Lorem": jsii.String("Ipsum"),
	},
	"DependsOn": []*string{
		jsii.String("Waldo"),
		jsii.String("Fred"),
	},
})

You can also assert the definitions of all resources of a type using the allResources() API.

template.AllResources(jsii.String("Foo::Bar"), map[string]interface{}{
	"Properties": map[string]*string{
		"Lorem": jsii.String("Ipsum"),
	},
	"DependsOn": []*string{
		jsii.String("Waldo"),
		jsii.String("Fred"),
	},
})

Beyond assertions, the module provides APIs to retrieve matching resources. The findResources() API is complementary to the hasResource() API, except, instead of asserting its presence, it returns the set of matching resources.

By default, the hasResource() and hasResourceProperties() APIs perform deep partial object matching. This behavior can be configured using matchers. See subsequent section on special matchers.

Output and Mapping sections

The module allows you to assert that the CloudFormation template contains an Output that matches specific properties. The following code asserts that a template contains an Output with a logicalId of Foo and the specified properties -

expected := map[string]interface{}{
	"Value": jsii.String("Bar"),
	"Export": map[string]*string{
		"Name": jsii.String("ExportBaz"),
	},
}
template.HasOutput(jsii.String("Foo"), expected)

If you want to match against all Outputs in the template, use * as the logicalId.

template.HasOutput(jsii.String("*"), map[string]interface{}{
	"Value": jsii.String("Bar"),
	"Export": map[string]*string{
		"Name": jsii.String("ExportBaz"),
	},
})

findOutputs() will return a set of outputs that match the logicalId and props, and you can use the '*' special case as well.

result := template.FindOutputs(jsii.String("*"), map[string]*string{
	"Value": jsii.String("Fred"),
})
expect(result.foo).toEqual(map[string]*string{
	"Value": jsii.String("Fred"),
	"Description": jsii.String("FooFred"),
})
expect(result.bar).toEqual(map[string]*string{
	"Value": jsii.String("Fred"),
	"Description": jsii.String("BarFred"),
})

The APIs hasMapping(), findMappings(), hasCondition(), and hasCondtions() provide similar functionalities.

Special Matchers

The expectation provided to the hasXxx(), findXxx() and templateMatches() APIs, besides carrying literal values, as seen in the above examples, also accept special matchers.

They are available as part of the Match class.

Object Matchers

The Match.objectLike() API can be used to assert that the target is a superset object of the provided pattern. This API will perform a deep partial match on the target. Deep partial matching is where objects are matched partially recursively. At each level, the list of keys in the target is a subset of the provided pattern.

// Given a template -
// {
//   "Resources": {
//     "MyBar": {
//       "Type": "Foo::Bar",
//       "Properties": {
//         "Fred": {
//           "Wobble": "Flob",
//           "Bob": "Cat"
//         }
//       }
//     }
//   }
// }

// The following will NOT throw an assertion error
template.HasResourceProperties(jsii.String("Foo::Bar"), map[string]matcher{
	"Fred": awscdk.Match_objectLike(map[string]interface{}{
		"Wobble": jsii.String("Flob"),
	}),
})

// The following will throw an assertion error
template.HasResourceProperties(jsii.String("Foo::Bar"), map[string]matcher{
	"Fred": awscdk.Match_objectLike(map[string]interface{}{
		"Brew": jsii.String("Coffee"),
	}),
})

The Match.objectEquals() API can be used to assert a target as a deep exact match.

Presence and Absence

The Match.absent() matcher can be used to specify that a specific value should not exist on the target. This can be used within Match.objectLike() or outside of any matchers.

// Given a template -
// {
//   "Resources": {
//     "MyBar": {
//       "Type": "Foo::Bar",
//       "Properties": {
//         "Fred": {
//           "Wobble": "Flob",
//         }
//       }
//     }
//   }
// }

// The following will NOT throw an assertion error
template.HasResourceProperties(jsii.String("Foo::Bar"), map[string]matcher{
	"Fred": awscdk.Match_objectLike(map[string]interface{}{
		"Bob": awscdk.Match_absent(),
	}),
})

// The following will throw an assertion error
template.HasResourceProperties(jsii.String("Foo::Bar"), map[string]matcher{
	"Fred": awscdk.Match_objectLike(map[string]interface{}{
		"Wobble": awscdk.Match_absent(),
	}),
})

The Match.anyValue() matcher can be used to specify that a specific value should be found at the location. This matcher will fail if when the target location has null-ish values (i.e., null or undefined).

This matcher can be combined with any of the other matchers.

// Given a template -
// {
//   "Resources": {
//     "MyBar": {
//       "Type": "Foo::Bar",
//       "Properties": {
//         "Fred": {
//           "Wobble": ["Flob", "Flib"],
//         }
//       }
//     }
//   }
// }

// The following will NOT throw an assertion error
template.HasResourceProperties(jsii.String("Foo::Bar"), map[string]map[string][]matcher{
	"Fred": map[string][]matcher{
		"Wobble": []matcher{
			awscdk.Match_anyValue(),
			awscdk.Match_anyValue(),
		},
	},
})

// The following will throw an assertion error
template.HasResourceProperties(jsii.String("Foo::Bar"), map[string]map[string]matcher{
	"Fred": map[string]matcher{
		"Wimble": awscdk.Match_anyValue(),
	},
})
Array Matchers

The Match.arrayWith() API can be used to assert that the target is equal to or a subset of the provided pattern array. This API will perform subset match on the target.

// Given a template -
// {
//   "Resources": {
//     "MyBar": {
//       "Type": "Foo::Bar",
//       "Properties": {
//         "Fred": ["Flob", "Cat"]
//       }
//     }
//   }
// }

// The following will NOT throw an assertion error
template.HasResourceProperties(jsii.String("Foo::Bar"), map[string]matcher{
	"Fred": awscdk.Match_arrayWith([]interface{}{
		jsii.String("Flob"),
	}),
})

// The following will throw an assertion error
template.HasResourceProperties(jsii.String("Foo::Bar"), awscdk.Match_ObjectLike(map[string]interface{}{
	"Fred": awscdk.Match_arrayWith([]interface{}{
		jsii.String("Wobble"),
	}),
}))

Note: The list of items in the pattern array should be in order as they appear in the target array. Out of order will be recorded as a match failure.

Alternatively, the Match.arrayEquals() API can be used to assert that the target is exactly equal to the pattern array.

String Matchers

The Match.stringLikeRegexp() API can be used to assert that the target matches the provided regular expression.

// Given a template -
// {
//   "Resources": {
//     "MyBar": {
//       "Type": "Foo::Bar",
//       "Properties": {
//         "Template": "const includeHeaders = true;"
//       }
//     }
//   }
// }

// The following will NOT throw an assertion error
template.HasResourceProperties(jsii.String("Foo::Bar"), map[string]matcher{
	"Template": awscdk.Match_stringLikeRegexp(jsii.String("includeHeaders = (true|false)")),
})

// The following will throw an assertion error
template.HasResourceProperties(jsii.String("Foo::Bar"), map[string]matcher{
	"Template": awscdk.Match_stringLikeRegexp(jsii.String("includeHeaders = null")),
})
Not Matcher

The not matcher inverts the search pattern and matches all patterns in the path that does not match the pattern specified.

// Given a template -
// {
//   "Resources": {
//     "MyBar": {
//       "Type": "Foo::Bar",
//       "Properties": {
//         "Fred": ["Flob", "Cat"]
//       }
//     }
//   }
// }

// The following will NOT throw an assertion error
template.HasResourceProperties(jsii.String("Foo::Bar"), map[string]matcher{
	"Fred": awscdk.Match_not([]interface{}{
		jsii.String("Flob"),
	}),
})

// The following will throw an assertion error
template.HasResourceProperties(jsii.String("Foo::Bar"), awscdk.Match_ObjectLike(map[string]interface{}{
	"Fred": awscdk.Match_not([]interface{}{
		jsii.String("Flob"),
		jsii.String("Cat"),
	}),
}))
Serialized JSON

Often, we find that some CloudFormation Resource types declare properties as a string, but actually expect JSON serialized as a string. For example, the BuildSpec property of AWS::CodeBuild::Project, the Definition property of AWS::StepFunctions::StateMachine, to name a couple.

The Match.serializedJson() matcher allows deep matching within a stringified JSON.

// Given a template -
// {
//   "Resources": {
//     "MyBar": {
//       "Type": "Foo::Bar",
//       "Properties": {
//         "Baz": "{ \"Fred\": [\"Waldo\", \"Willow\"] }"
//       }
//     }
//   }
// }

// The following will NOT throw an assertion error
template.HasResourceProperties(jsii.String("Foo::Bar"), map[string]matcher{
	"Baz": awscdk.Match_serializedJson(map[string]matcher{
		"Fred": awscdk.Match_arrayWith([]interface{}{
			jsii.String("Waldo"),
		}),
	}),
})

// The following will throw an assertion error
template.HasResourceProperties(jsii.String("Foo::Bar"), map[string]matcher{
	"Baz": awscdk.Match_serializedJson(map[string][]*string{
		"Fred": []*string{
			jsii.String("Waldo"),
			jsii.String("Johnny"),
		},
	}),
})

Capturing Values

The matcher APIs documented above allow capturing values in the matching entry (Resource, Output, Mapping, etc.). The following code captures a string from a matching resource.

// Given a template -
// {
//   "Resources": {
//     "MyBar": {
//       "Type": "Foo::Bar",
//       "Properties": {
//         "Fred": ["Flob", "Cat"],
//         "Waldo": ["Qix", "Qux"],
//       }
//     }
//   }
// }

fredCapture := awscdk.NewCapture()
waldoCapture := awscdk.NewCapture()
template.HasResourceProperties(jsii.String("Foo::Bar"), map[string]interface{}{
	"Fred": fredCapture,
	"Waldo": []interface{}{
		jsii.String("Qix"),
		waldoCapture,
	}.([]interface{}),
})

fredCapture.AsArray() // returns ["Flob", "Cat"]
waldoCapture.AsString()

With captures, a nested pattern can also be specified, so that only targets that match the nested pattern will be captured. This pattern can be literals or further Matchers.

// Given a template -
// {
//   "Resources": {
//     "MyBar1": {
//       "Type": "Foo::Bar",
//       "Properties": {
//         "Fred": ["Flob", "Cat"],
//       }
//     }
//     "MyBar2": {
//       "Type": "Foo::Bar",
//       "Properties": {
//         "Fred": ["Qix", "Qux"],
//       }
//     }
//   }
// }

capture := awscdk.NewCapture(awscdk.Match_ArrayWith([]interface{}{
	jsii.String("Cat"),
}))
template.HasResourceProperties(jsii.String("Foo::Bar"), map[string]capture{
	"Fred": capture,
})

capture.AsArray()

When multiple resources match the given condition, each Capture defined in the condition will capture all matching values. They can be paged through using the next() API. The following example illustrates this -

// Given a template -
// {
//   "Resources": {
//     "MyBar": {
//       "Type": "Foo::Bar",
//       "Properties": {
//         "Fred": "Flob",
//       }
//     },
//     "MyBaz": {
//       "Type": "Foo::Bar",
//       "Properties": {
//         "Fred": "Quib",
//       }
//     }
//   }
// }

fredCapture := awscdk.NewCapture()
template.HasResourceProperties(jsii.String("Foo::Bar"), map[string]capture{
	"Fred": fredCapture,
})

fredCapture.AsString() // returns "Flob"
fredCapture.Next() // returns true
fredCapture.AsString()

Asserting Annotations

In addition to template matching, we provide an API for annotation matching. Annotations can be added via the Aspects API. You can learn more about Aspects here.

Say you have a MyAspect and a MyStack that uses MyAspect:

import "github.com/aws/aws-cdk-go/awscdk"
import "github.com/aws/constructs-go/constructs"

type myAspect struct {
}

func (this *myAspect) visit(node iConstruct) {
	if *node instanceof cdk.CfnResource && *node.CfnResourceType == "Foo::Bar" {
		this.error(*node, jsii.String("we do not want a Foo::Bar resource"))
	}
}

func (this *myAspect) error(node iConstruct, message *string) {
	cdk.Annotations_Of(*node).AddError(*message)
}

type myStack struct {
	stack
}

func newMyStack(scope construct, id *string) *myStack {
	this := &myStack{}
	cdk.NewStack_Override(this, scope, id)

	stack := cdk.NewStack()
	cdk.NewCfnResource(stack, jsii.String("Foo"), &CfnResourceProps{
		Type: jsii.String("Foo::Bar"),
		Properties: map[string]interface{}{
			"Fred": jsii.String("Thud"),
		},
	})
	cdk.Aspects_Of(stack).Add(NewMyAspect())
	return this
}

We can then assert that the stack contains the expected Error:

// import { Annotations } from '@aws-cdk/assertions';

awscdk.Annotations_FromStack(stack).HasError(jsii.String("/Default/Foo"), jsii.String("we do not want a Foo::Bar resource"))

Here are the available APIs for Annotations:

  • hasError(), hasNoError(), and findError()
  • hasWarning(), hasNoWarning(), and findWarning()
  • hasInfo(), hasNoInfo(), and findInfo()

The corresponding findXxx() API is complementary to the hasXxx() API, except instead of asserting its presence, it returns the set of matching messages.

In addition, this suite of APIs is compatible with Matchers for more fine-grained control. For example, the following assertion works as well:

awscdk.Annotations_FromStack(stack).HasError(jsii.String("/Default/Foo"), awscdk.Match_StringLikeRegexp(jsii.String(".*Foo::Bar.*")))

Asserting Stack tags

Tags applied to a Stack are not part of the rendered template: instead, they are included as properties in the Cloud Assembly Manifest. To test that stacks are tagged as expected, simple assertions can be written.

Given the following setup:

import "github.com/aws/aws-cdk-go/awscdk"
import "github.com/aws/aws-cdk-go/awscdk"

app := awscdk.NewApp()
stack := awscdk.NewStack(app, jsii.String("MyStack"), &StackProps{
	Tags: map[string]*string{
		"tag-name": jsii.String("tag-value"),
	},
})

It is possible to test against these values:

tags := awscdk.Tags_FromStack(stack)

// using a default 'objectLike' Matcher
tags.HasValues(map[string]*string{
	"tag-name": jsii.String("tag-value"),
})

// ... with Matchers embedded
tags.HasValues(map[string]matcher{
	"tag-name": awscdk.Match_stringLikeRegexp(jsii.String("value")),
})

// or another object Matcher at the top level
tags.HasValues(awscdk.Match_ObjectEquals(map[string]interface{}{
	"tag-name": awscdk.Match_anyValue(),
}))

When tags are not defined on the stack, it is represented as an empty object rather than undefined. To make this more obvious, there is a hasNone() method that can be used in place of Match.exactly({}). If Match.absent() is passed, an error will result.

// no tags present
awscdk.Tags_FromStack(stack).HasNone()

// don't use absent() at the top level, it won't work
expect(() => { Tags.fromStack(stack).hasValues(Match.absent()); }).toThrow(/will never match/i)

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Capture_IsMatcher 

func Capture_IsMatcher(x interface{}) *bool

Check whether the provided object is a subtype of the `IMatcher`.

func Matcher_IsMatcher 

func Matcher_IsMatcher(x interface{}) *bool

Check whether the provided object is a subtype of the `IMatcher`.

func NewCapture_Override 

func NewCapture_Override(c Capture, pattern interface{})

Initialize a new capture.

func NewMatchResult_Override 

func NewMatchResult_Override(m MatchResult, target interface{})

func NewMatch_Override 

func NewMatch_Override(m Match)

func NewMatcher_Override 

func NewMatcher_Override(m Matcher)

Types

type Annotations added in v2.10.0 

type Annotations interface {
	// Get the set of matching errors of a given construct path and message.
	FindError(constructPath *string, message interface{}) *[]*cxapi.SynthesisMessage
	// Get the set of matching infos of a given construct path and message.
	FindInfo(constructPath *string, message interface{}) *[]*cxapi.SynthesisMessage
	// Get the set of matching warning of a given construct path and message.
	FindWarning(constructPath *string, message interface{}) *[]*cxapi.SynthesisMessage
	// Assert that an error with the given message exists in the synthesized CDK `Stack`.
	HasError(constructPath *string, message interface{})
	// Assert that an info with the given message exists in the synthesized CDK `Stack`.
	HasInfo(constructPath *string, message interface{})
	// Assert that an error with the given message does not exist in the synthesized CDK `Stack`.
	HasNoError(constructPath *string, message interface{})
	// Assert that an info with the given message does not exist in the synthesized CDK `Stack`.
	HasNoInfo(constructPath *string, message interface{})
	// Assert that an warning with the given message does not exist in the synthesized CDK `Stack`.
	HasNoWarning(constructPath *string, message interface{})
	// Assert that an warning with the given message exists in the synthesized CDK `Stack`.
	HasWarning(constructPath *string, message interface{})
}

Suite of assertions that can be run on a CDK Stack.

Focused on asserting annotations.

Example: 

// The code below shows an example of how to instantiate this type.
// The values are placeholders you should change.
import cdk "github.com/aws/aws-cdk-go/awscdk"
import "github.com/aws/aws-cdk-go/awscdk"

var stack stack

annotations := awscdk.Assertions.Annotations_FromStack(stack)

func Annotations_FromStack added in v2.10.0 

func Annotations_FromStack(stack awscdk.Stack) Annotations

Base your assertions on the messages returned by a synthesized CDK `Stack`.

type Capture 

type Capture interface {
	Matcher
	// A name for the matcher.
	//
	// This is collected as part of the result and may be presented to the user.
	Name() *string
	// Retrieve the captured value as an array.
	//
	// An error is generated if no value is captured or if the value is not an array.
	AsArray() *[]interface{}
	// Retrieve the captured value as a boolean.
	//
	// An error is generated if no value is captured or if the value is not a boolean.
	AsBoolean() *bool
	// Retrieve the captured value as a number.
	//
	// An error is generated if no value is captured or if the value is not a number.
	AsNumber() *float64
	// Retrieve the captured value as a JSON object.
	//
	// An error is generated if no value is captured or if the value is not an object.
	AsObject() *map[string]interface{}
	// Retrieve the captured value as a string.
	//
	// An error is generated if no value is captured or if the value is not a string.
	AsString() *string
	// When multiple results are captured, move the iterator to the next result.
	//
	// Returns: true if another capture is present, false otherwise.
	Next() *bool
	// Test whether a target matches the provided pattern.
	//
	// Every Matcher must implement this method.
	// This method will be invoked by the assertions framework. Do not call this method directly.
	Test(actual interface{}) MatchResult
}

Capture values while matching templates.

Using an instance of this class within a Matcher will capture the matching value. The `as*()` APIs on the instance can be used to get the captured value.

Example: 

// Given a template -
// {
//   "Resources": {
//     "MyBar": {
//       "Type": "Foo::Bar",
//       "Properties": {
//         "Fred": "Flob",
//       }
//     },
//     "MyBaz": {
//       "Type": "Foo::Bar",
//       "Properties": {
//         "Fred": "Quib",
//       }
//     }
//   }
// }

fredCapture := awscdk.NewCapture()
template.HasResourceProperties(jsii.String("Foo::Bar"), map[string]capture{
	"Fred": fredCapture,
})

fredCapture.AsString() // returns "Flob"
fredCapture.Next() // returns true
fredCapture.AsString()

func NewCapture 

func NewCapture(pattern interface{}) Capture

Initialize a new capture.

type Match 

type Match interface {
}

Partial and special matching during template assertions.

type MatchCapture added in v2.1.0 

type MatchCapture struct {
	// The instance of Capture class to which this capture is associated with.
	Capture Capture `field:"required" json:"capture" yaml:"capture"`
	// The value that was captured.
	Value interface{} `field:"required" json:"value" yaml:"value"`
}

Information about a value captured during match.

Example: 

// The code below shows an example of how to instantiate this type.
// The values are placeholders you should change.
import "github.com/aws/aws-cdk-go/awscdk"

var capture capture
var value interface{}

matchCapture := &MatchCapture{
	Capture: capture,
	Value: value,
}

type MatchFailure added in v2.1.0 

type MatchFailure struct {
	// The matcher that had the failure.
	Matcher Matcher `field:"required" json:"matcher" yaml:"matcher"`
	// Failure message.
	Message *string `field:"required" json:"message" yaml:"message"`
	// The relative path in the target where the failure occurred.
	//
	// If the failure occurred at root of the match tree, set the path to an empty list.
	// If it occurs in the 5th index of an array nested within the 'foo' key of an object,
	// set the path as `['/foo', '[5]']`.
	Path *[]*string `field:"required" json:"path" yaml:"path"`
	// The cost of this particular mismatch.
	// Default: 1.
	//
	Cost *float64 `field:"optional" json:"cost" yaml:"cost"`
}

Match failure details.

Example: 

// The code below shows an example of how to instantiate this type.
// The values are placeholders you should change.
import "github.com/aws/aws-cdk-go/awscdk"

var matcher matcher

matchFailure := &MatchFailure{
	Matcher: matcher,
	Message: jsii.String("message"),
	Path: []*string{
		jsii.String("path"),
	},

	// the properties below are optional
	Cost: jsii.Number(123),
}

type MatchResult 

type MatchResult interface {
	// The cost of the failures so far.
	FailCost() *float64
	// The number of failures.
	FailCount() *float64
	// Whether the match is a success.
	IsSuccess() *bool
	// The target for which this result was generated.
	Target() interface{}
	// Compose the results of a previous match as a subtree.
	Compose(id *string, inner MatchResult) MatchResult
	// Prepare the result to be analyzed.
	//
	// This API *must* be called prior to analyzing these results.
	Finished() MatchResult
	// Does the result contain any failures.
	//
	// If not, the result is a success.
	HasFailed() *bool
	// DEPRECATED.
	// Deprecated: use recordFailure().
	Push(matcher Matcher, path *[]*string, message *string) MatchResult
	// Record a capture against in this match result.
	RecordCapture(options *MatchCapture)
	// Record a new failure into this result at a specific path.
	RecordFailure(failure *MatchFailure) MatchResult
	// Do a deep render of the match result, showing the structure mismatches in context.
	RenderMismatch() *string
	// Render the failed match in a presentable way.
	//
	// Prefer using `renderMismatch` over this method. It is left for backwards
	// compatibility for test suites that expect it, but `renderMismatch()` will
	// produce better output.
	ToHumanStrings() *[]*string
}

The result of `Match.test()`.

Example: 

// The code below shows an example of how to instantiate this type.
// The values are placeholders you should change.
import "github.com/aws/aws-cdk-go/awscdk"

var target interface{}

matchResult := awscdk.Assertions.NewMatchResult(target)

func NewMatchResult 

func NewMatchResult(target interface{}) MatchResult

type Matcher 

type Matcher interface {
	// A name for the matcher.
	//
	// This is collected as part of the result and may be presented to the user.
	Name() *string
	// Test whether a target matches the provided pattern.
	//
	// Every Matcher must implement this method.
	// This method will be invoked by the assertions framework. Do not call this method directly.
	//
	// Returns: the list of match failures. An empty array denotes a successful match.
	Test(actual interface{}) MatchResult
}

Represents a matcher that can perform special data matching capabilities between a given pattern and a target.

Example: 

// Given a template -
// {
//   "Resources": {
//     "MyBar": {
//       "Type": "Foo::Bar",
//       "Properties": {
//         "Fred": {
//           "Wobble": ["Flob", "Flib"],
//         }
//       }
//     }
//   }
// }

// The following will NOT throw an assertion error
template.HasResourceProperties(jsii.String("Foo::Bar"), map[string]map[string][]matcher{
	"Fred": map[string][]matcher{
		"Wobble": []matcher{
			awscdk.Match_anyValue(),
			awscdk.Match_anyValue(),
		},
	},
})

// The following will throw an assertion error
template.HasResourceProperties(jsii.String("Foo::Bar"), map[string]map[string]matcher{
	"Fred": map[string]matcher{
		"Wimble": awscdk.Match_anyValue(),
	},
})

func Match_Absent 

func Match_Absent() Matcher

Use this matcher in the place of a field's value, if the field must not be present.

func Match_AnyValue 

func Match_AnyValue() Matcher

Matches any non-null value at the target.

func Match_ArrayEquals 

func Match_ArrayEquals(pattern *[]interface{}) Matcher

Matches the specified pattern with the array found in the same relative path of the target.

The set of elements (or matchers) must match exactly and in order.

func Match_ArrayWith 

func Match_ArrayWith(pattern *[]interface{}) Matcher

Matches the specified pattern with the array found in the same relative path of the target.

The set of elements (or matchers) must be in the same order as would be found.

func Match_Exact 

func Match_Exact(pattern interface{}) Matcher

Deep exact matching of the specified pattern to the target.

func Match_Not 

func Match_Not(pattern interface{}) Matcher

Matches any target which does NOT follow the specified pattern.

func Match_ObjectEquals 

func Match_ObjectEquals(pattern *map[string]interface{}) Matcher

Matches the specified pattern to an object found in the same relative path of the target.

The keys and their values (or matchers) must match exactly with the target.

func Match_ObjectLike 

func Match_ObjectLike(pattern *map[string]interface{}) Matcher

Matches the specified pattern to an object found in the same relative path of the target.

The keys and their values (or matchers) must be present in the target but the target can be a superset.

func Match_SerializedJson 

func Match_SerializedJson(pattern interface{}) Matcher

Matches any string-encoded JSON and applies the specified pattern after parsing it.

func Match_StringLikeRegexp added in v2.9.0 

func Match_StringLikeRegexp(pattern *string) Matcher

Matches targets according to a regular expression.

type Tags added in v2.137.0 

type Tags interface {
	// Get the tags associated with the manifest.
	//
	// This will be an empty object if
	// no tags were supplied.
	//
	// Returns: The tags associated with the stack's synthesized manifest.
	All() *map[string]*string
	// Assert that the there are no tags associated with the synthesized CDK Stack's manifest.
	//
	// This is a convenience method over `hasValues(Match.exact({}))`, and is
	// present because the more obvious method of detecting no tags
	// (`Match.absent()`) will not work. Manifests default the tag set to an empty
	// object.
	HasNone()
	// Assert that the given Matcher or object matches the tags associated with the synthesized CDK Stack's manifest.
	HasValues(tags interface{})
}

Allows assertions on the tags associated with a synthesized CDK stack's manifest.

Stack tags are not part of the synthesized template, so can only be checked from the manifest in this manner.

Example: 

tags := awscdk.Tags_FromStack(stack)

// using a default 'objectLike' Matcher
tags.HasValues(map[string]*string{
	"tag-name": jsii.String("tag-value"),
})

// ... with Matchers embedded
tags.HasValues(map[string]matcher{
	"tag-name": awscdk.Match_stringLikeRegexp(jsii.String("value")),
})

// or another object Matcher at the top level
tags.HasValues(awscdk.Match_ObjectEquals(map[string]interface{}{
	"tag-name": awscdk.Match_anyValue(),
}))

func Tags_FromStack added in v2.137.0 

func Tags_FromStack(stack awscdk.Stack) Tags

Find tags associated with a synthesized CDK `Stack`.

type Template 

type Template interface {
	// Assert that all resources of the given type contain the given definition in the CloudFormation template.
	//
	// By default, performs partial matching on the resource, via the `Match.objectLike()`.
	// To configure different behavior, use other matchers in the `Match` class.
	AllResources(type_ *string, props interface{})
	// Assert that all resources of the given type contain the given properties CloudFormation template.
	//
	// By default, performs partial matching on the `Properties` key of the resource, via the
	// `Match.objectLike()`. To configure different behavior, use other matchers in the `Match` class.
	AllResourcesProperties(type_ *string, props interface{})
	// Get the set of matching Conditions that match the given properties in the CloudFormation template.
	FindConditions(logicalId *string, props interface{}) *map[string]*map[string]interface{}
	// Get the set of matching Mappings that match the given properties in the CloudFormation template.
	FindMappings(logicalId *string, props interface{}) *map[string]*map[string]interface{}
	// Get the set of matching Outputs that match the given properties in the CloudFormation template.
	FindOutputs(logicalId *string, props interface{}) *map[string]*map[string]interface{}
	// Get the set of matching Parameters that match the given properties in the CloudFormation template.
	FindParameters(logicalId *string, props interface{}) *map[string]*map[string]interface{}
	// Get the set of matching resources of a given type and properties in the CloudFormation template.
	FindResources(type_ *string, props interface{}) *map[string]*map[string]interface{}
	// Assert that a Condition with the given properties exists in the CloudFormation template.
	//
	// By default, performs partial matching on the resource, via the `Match.objectLike()`.
	// To configure different behavior, use other matchers in the `Match` class.
	HasCondition(logicalId *string, props interface{})
	// Assert that a Mapping with the given properties exists in the CloudFormation template.
	//
	// By default, performs partial matching on the resource, via the `Match.objectLike()`.
	// To configure different behavior, use other matchers in the `Match` class.
	HasMapping(logicalId *string, props interface{})
	// Assert that an Output with the given properties exists in the CloudFormation template.
	//
	// By default, performs partial matching on the resource, via the `Match.objectLike()`.
	// To configure different behavior, use other matchers in the `Match` class.
	HasOutput(logicalId *string, props interface{})
	// Assert that a Parameter with the given properties exists in the CloudFormation template.
	//
	// By default, performs partial matching on the parameter, via the `Match.objectLike()`.
	// To configure different behavior, use other matchers in the `Match` class.
	HasParameter(logicalId *string, props interface{})
	// Assert that a resource of the given type and given definition exists in the CloudFormation template.
	//
	// By default, performs partial matching on the resource, via the `Match.objectLike()`.
	// To configure different behavior, use other matchers in the `Match` class.
	HasResource(type_ *string, props interface{})
	// Assert that a resource of the given type and properties exists in the CloudFormation template.
	//
	// By default, performs partial matching on the `Properties` key of the resource, via the
	// `Match.objectLike()`. To configure different behavior, use other matchers in the `Match` class.
	HasResourceProperties(type_ *string, props interface{})
	// Assert that the given number of resources of the given type exist in the template.
	ResourceCountIs(type_ *string, count *float64)
	// Assert that the given number of resources of the given type and properties exists in the CloudFormation template.
	ResourcePropertiesCountIs(type_ *string, props interface{}, count *float64)
	// Assert that the CloudFormation template matches the given value.
	TemplateMatches(expected interface{})
	// The CloudFormation template deserialized into an object.
	ToJSON() *map[string]interface{}
}

Suite of assertions that can be run on a CDK stack.

Typically used, as part of unit tests, to validate that the rendered CloudFormation template has expected resources and properties.

Example: 

import "github.com/aws/aws-cdk-go/awscdk"
import "github.com/aws/aws-cdk-go/awscdk"

stack := awscdk.NewStack()
// ...
template := awscdk.Template_FromStack(stack)

func Template_FromJSON 

func Template_FromJSON(template *map[string]interface{}, templateParsingOptions *TemplateParsingOptions) Template

Base your assertions from an existing CloudFormation template formatted as an in-memory JSON object.

func Template_FromStack 

func Template_FromStack(stack awscdk.Stack, templateParsingOptions *TemplateParsingOptions) Template

Base your assertions on the CloudFormation template synthesized by a CDK `Stack`.

func Template_FromString 

func Template_FromString(template *string, templateParsingOptions *TemplateParsingOptions) Template

Base your assertions from an existing CloudFormation template formatted as a JSON string.

type TemplateParsingOptions added in v2.45.0 

type TemplateParsingOptions struct {
	// If set to true, will skip checking for cyclical / circular dependencies.
	//
	// Should be set to false other than for
	// templates that are valid despite containing cycles, such as unprocessed transform stacks.
	// Default: false.
	//
	SkipCyclicalDependenciesCheck *bool `field:"optional" json:"skipCyclicalDependenciesCheck" yaml:"skipCyclicalDependenciesCheck"`
}

Options to configure template parsing behavior, such as disregarding circular dependencies.

Example: 

// The code below shows an example of how to instantiate this type.
// The values are placeholders you should change.
import "github.com/aws/aws-cdk-go/awscdk"

templateParsingOptions := &TemplateParsingOptions{
	SkipCyclicalDependenciesCheck: jsii.Boolean(false),
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.