README
¶
integ-tests
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.
Usage
Suppose you have a simple stack, that only encapsulates a Lambda function with a certain handler:
interface StackUnderTestProps extends StackProps {
functionProps?: lambda.FunctionProps;
}
class StackUnderTest extends Stack {
constructor(scope: Construct, id: string, props: StackUnderTestProps) {
super(scope, id, props);
new lambda.Function(this, 'Handler', {
runtime: lambda.Runtime.NODEJS_12_X,
handler: 'index.handler',
code: lambda.Code.fromAsset(path.join(__dirname, 'lambda-handler')),
...props.functionProps,
});
}
}
You may want to test this stack under different conditions. For example, we want
this stack to be deployed correctly, regardless of the architecture we choose
for the Lambda function. In particular, it should work for both ARM_64 and
X86_64. So you can create an IntegTestCase that exercises both scenarios:
interface StackUnderTestProps extends StackProps {
architecture?: lambda.Architecture;
}
class StackUnderTest extends Stack {
constructor(scope: Construct, id: string, props: StackUnderTestProps) {
super(scope, id, props);
new lambda.Function(this, 'Handler', {
runtime: lambda.Runtime.NODEJS_12_X,
handler: 'index.handler',
code: lambda.Code.fromAsset(path.join(__dirname, 'lambda-handler')),
architecture: props.architecture,
});
}
}
// Beginning of the test suite
const app = new App();
const stack = new Stack(app, 'stack');
new IntegTestCase(stack, 'DifferentArchitectures', {
stacks: [
new StackUnderTest(app, 'Stack1', {
architecture: lambda.Architecture.ARM_64,
}),
new StackUnderTest(app, 'Stack2', {
architecture: lambda.Architecture.X86_64,
}),
],
});
This is all the instruction you need for the integration test runner to know which stacks to synthesize, deploy and destroy. But you may also need to customize the behavior of the runner by changing its parameters. For example:
const app = new App();
const stackUnderTest = new Stack(app, 'StackUnderTest', /* ... */);
const stack = new Stack(app, 'stack');
new IntegTestCase(stack, 'CustomizedDeploymentWorkflow', {
stacks: [stackUnderTest],
diffAssets: true,
stackUpdateWorkflow: true,
cdkCommandOptions: {
deploy: {
args: {
requireApproval: RequireApproval.NEVER,
json: true,
},
},
destroy: {
args: {
force: true,
},
},
},
});
Documentation
¶
Overview ¶
CDK Integration Testing Constructs
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IntegTestCase_IsConstruct ¶
func IntegTestCase_IsConstruct(x interface{}) *bool
Checks if `x` is a construct.
Returns: true if `x` is an object created from a class which extends `Construct`. Deprecated: use `x instanceof Construct` instead.
func NewIntegTestCase_Override ¶
func NewIntegTestCase_Override(i IntegTestCase, scope constructs.Construct, id *string, props *IntegTestCaseProps)
Experimental.
Types ¶
type IntegTestCase ¶
type IntegTestCase interface {
constructs.Construct
// The tree node.
// Experimental.
Node() constructs.Node
// Returns a string representation of this construct.
// Experimental.
ToString() *string
}
An integration test case.
Allows the definition of test properties that apply to all stacks under this case.
Example:
type stackUnderTestProps struct {
stackProps
architecture architecture
}
type stackUnderTest struct {
stack
}
func newStackUnderTest(scope construct, id *string, props stackUnderTestProps) *stackUnderTest {
this := &stackUnderTest{}
newStack_Override(this, scope, id, props)
lambda.NewFunction(this, jsii.String("Handler"), &functionProps{
runtime: lambda.runtime_NODEJS_12_X(),
handler: jsii.String("index.handler"),
code: lambda.code.fromAsset(path.join(__dirname, jsii.String("lambda-handler"))),
architecture: props.architecture,
})
return this
}
// Beginning of the test suite
app := NewApp()
stack := NewStack(app, jsii.String("stack"))
NewIntegTestCase(stack, jsii.String("DifferentArchitectures"), &integTestCaseProps{
stacks: []*stack{
NewStackUnderTest(app, jsii.String("Stack1"), &stackUnderTestProps{
architecture: lambda.*architecture_ARM_64(),
}),
NewStackUnderTest(app, jsii.String("Stack2"), &stackUnderTestProps{
architecture: lambda.*architecture_X86_64(),
}),
},
})
Experimental.
func NewIntegTestCase ¶
func NewIntegTestCase(scope constructs.Construct, id *string, props *IntegTestCaseProps) IntegTestCase
Experimental.
type IntegTestCaseProps ¶
type IntegTestCaseProps struct {
// List of CloudFormation resource types in this stack that can be destroyed as part of an update without failing the test.
//
// This list should only include resources that for this specific
// integration test we are sure will not cause errors or an outage if
// destroyed. For example, maybe we know that a new resource will be created
// first before the old resource is destroyed which prevents any outage.
//
// e.g. ['AWS::IAM::Role']
// Experimental.
AllowDestroy *[]*string `json:"allowDestroy" yaml:"allowDestroy"`
// Additional options to use for each CDK command.
// Experimental.
CdkCommandOptions *cloudassemblyschema.CdkCommands `json:"cdkCommandOptions" yaml:"cdkCommandOptions"`
// Whether or not to include asset hashes in the diff Asset hashes can introduces a lot of unneccessary noise into tests, but there are some cases where asset hashes _should_ be included.
//
// For example
// any tests involving custom resources or bundling.
// Experimental.
DiffAssets *bool `json:"diffAssets" yaml:"diffAssets"`
// Additional commands to run at predefined points in the test workflow.
//
// e.g. { postDeploy: ['yarn', 'test'] }
// Experimental.
Hooks *cloudassemblyschema.Hooks `json:"hooks" yaml:"hooks"`
// Limit deployment to these regions.
// Experimental.
Regions *[]*string `json:"regions" yaml:"regions"`
// Run update workflow on this test case This should only be set to false to test scenarios that are not possible to test as part of the update workflow.
// Experimental.
StackUpdateWorkflow *bool `json:"stackUpdateWorkflow" yaml:"stackUpdateWorkflow"`
// Stacks to be deployed during the test.
// Experimental.
Stacks *[]awscdk.Stack `json:"stacks" yaml:"stacks"`
}
Properties of an integration test case.
Example:
type stackUnderTestProps struct {
stackProps
architecture architecture
}
type stackUnderTest struct {
stack
}
func newStackUnderTest(scope construct, id *string, props stackUnderTestProps) *stackUnderTest {
this := &stackUnderTest{}
newStack_Override(this, scope, id, props)
lambda.NewFunction(this, jsii.String("Handler"), &functionProps{
runtime: lambda.runtime_NODEJS_12_X(),
handler: jsii.String("index.handler"),
code: lambda.code.fromAsset(path.join(__dirname, jsii.String("lambda-handler"))),
architecture: props.architecture,
})
return this
}
// Beginning of the test suite
app := NewApp()
stack := NewStack(app, jsii.String("stack"))
NewIntegTestCase(stack, jsii.String("DifferentArchitectures"), &integTestCaseProps{
stacks: []*stack{
NewStackUnderTest(app, jsii.String("Stack1"), &stackUnderTestProps{
architecture: lambda.*architecture_ARM_64(),
}),
NewStackUnderTest(app, jsii.String("Stack2"), &stackUnderTestProps{
architecture: lambda.*architecture_X86_64(),
}),
},
})
Experimental.
Source Files
Directories