integtests

README

integ-tests

Usage

Suppose you have a simple stack, that only encapsulates a Lambda function with a certain handler:

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
}

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:

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 := awscdk.NewApp()

stack := awscdk.Newstack(app, jsii.String("stack"))

differentArchsCase := awscdk.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(),
		}),
	},
})

// There must be exactly one instance of TestCase per file
// There must be exactly one instance of TestCase per file
awscdk.NewIntegTest(app, jsii.String("integ-test"), &integTestProps{

	// Register as many test cases as you want here
	testCases: []integTestCase{
		differentArchsCase,
	},
})

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:

app := awscdk.NewApp()

stackUnderTest := awscdk.NewStack(app, jsii.String("StackUnderTest"))

stack := awscdk.NewStack(app, jsii.String("stack"))

testCase := awscdk.NewIntegTestCase(stack, jsii.String("CustomizedDeploymentWorkflow"), &integTestCaseProps{
	stacks: []stack{
		stackUnderTest,
	},
	diffAssets: jsii.Boolean(true),
	stackUpdateWorkflow: jsii.Boolean(true),
	cdkCommandOptions: &cdkCommands{
		deploy: &deployCommand{
			args: &deployOptions{
				requireApproval: awscdk.RequireApproval_NEVER,
				json: jsii.Boolean(true),
			},
		},
		destroy: &destroyCommand{
			args: &destroyOptions{
				force: jsii.Boolean(true),
			},
		},
	},
})

awscdk.NewIntegTest(app, jsii.String("integ-test"), &integTestProps{
	testCases: []integTestCase{
		testCase,
	},
})

Documentation

Index

• func IntegTestCase_IsConstruct(x interface{}) *bool
• func IntegTest_IsConstruct(x interface{}) *bool
• func NewIntegTestCase_Override(i IntegTestCase, scope awscdk.Construct, id *string, props *IntegTestCaseProps)
• func NewIntegTest_Override(i IntegTest, scope awscdk.Construct, id *string, props *IntegTestProps)
• type IntegTest
  • func NewIntegTest(scope awscdk.Construct, id *string, props *IntegTestProps) IntegTest
• type IntegTestCase
  • func NewIntegTestCase(scope awscdk.Construct, id *string, props *IntegTestCaseProps) IntegTestCase
• type IntegTestCaseProps
• type IntegTestProps

Functions

func IntegTestCase_IsConstruct

func IntegTestCase_IsConstruct(x interface{}) *bool

Return whether the given object is a Construct. Experimental.

func IntegTest_IsConstruct

func IntegTest_IsConstruct(x interface{}) *bool

Return whether the given object is a Construct. Experimental.

func NewIntegTestCase_Override

func NewIntegTestCase_Override(i IntegTestCase, scope awscdk.Construct, id *string, props *IntegTestCaseProps)

Experimental.

func NewIntegTest_Override

func NewIntegTest_Override(i IntegTest, scope awscdk.Construct, id *string, props *IntegTestProps)

Experimental.

Types

type IntegTest

type IntegTest interface {
	awscdk.Construct
	// The construct tree node associated with this construct.
	// Experimental.
	Node() awscdk.ConstructNode
	// Perform final modifications before synthesis.
	//
	// This method can be implemented by derived constructs in order to perform
	// final changes before synthesis. prepare() will be called after child
	// constructs have been prepared.
	//
	// This is an advanced framework feature. Only use this if you
	// understand the implications.
	// Experimental.
	OnPrepare()
	// Allows this construct to emit artifacts into the cloud assembly during synthesis.
	//
	// This method is usually implemented by framework-level constructs such as `Stack` and `Asset`
	// as they participate in synthesizing the cloud assembly.
	// Experimental.
	OnSynthesize(session constructs.ISynthesisSession)
	// Validate the current construct.
	//
	// This method can be implemented by derived constructs in order to perform
	// validation logic. It is called on all constructs before synthesis.
	//
	// Returns: An array of validation error messages, or an empty array if the construct is valid.
	// Experimental.
	OnValidate() *[]*string
	// Perform final modifications before synthesis.
	//
	// This method can be implemented by derived constructs in order to perform
	// final changes before synthesis. prepare() will be called after child
	// constructs have been prepared.
	//
	// This is an advanced framework feature. Only use this if you
	// understand the implications.
	// Experimental.
	Prepare()
	// Allows this construct to emit artifacts into the cloud assembly during synthesis.
	//
	// This method is usually implemented by framework-level constructs such as `Stack` and `Asset`
	// as they participate in synthesizing the cloud assembly.
	// Experimental.
	Synthesize(session awscdk.ISynthesisSession)
	// Returns a string representation of this construct.
	// Experimental.
	ToString() *string
	// Validate the current construct.
	//
	// This method can be implemented by derived constructs in order to perform
	// validation logic. It is called on all constructs before synthesis.
	//
	// Returns: An array of validation error messages, or an empty array if the construct is valid.
	// Experimental.
	Validate() *[]*string
}

A collection of test cases.

Each test case file should contain exactly one instance of this class.

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 := awscdk.NewApp()

stack := awscdk.Newstack(app, jsii.String("stack"))

differentArchsCase := awscdk.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(),
		}),
	},
})

// There must be exactly one instance of TestCase per file
// There must be exactly one instance of TestCase per file
awscdk.NewIntegTest(app, jsii.String("integ-test"), &integTestProps{

	// Register as many test cases as you want here
	testCases: []integTestCase{
		differentArchsCase,
	},
})

Experimental.

func NewIntegTest

func NewIntegTest(scope awscdk.Construct, id *string, props *IntegTestProps) IntegTest

Experimental.

type IntegTestCase

type IntegTestCase interface {
	awscdk.Construct
	// The integration test manifest for this test case.
	//
	// Manifests are used
	// by the integration test runner.
	// Experimental.
	Manifest() *cloudassemblyschema.IntegManifest
	// The construct tree node associated with this construct.
	// Experimental.
	Node() awscdk.ConstructNode
	// Perform final modifications before synthesis.
	//
	// This method can be implemented by derived constructs in order to perform
	// final changes before synthesis. prepare() will be called after child
	// constructs have been prepared.
	//
	// This is an advanced framework feature. Only use this if you
	// understand the implications.
	// Experimental.
	OnPrepare()
	// Allows this construct to emit artifacts into the cloud assembly during synthesis.
	//
	// This method is usually implemented by framework-level constructs such as `Stack` and `Asset`
	// as they participate in synthesizing the cloud assembly.
	// Experimental.
	OnSynthesize(session constructs.ISynthesisSession)
	// Validate the current construct.
	//
	// This method can be implemented by derived constructs in order to perform
	// validation logic. It is called on all constructs before synthesis.
	//
	// Returns: An array of validation error messages, or an empty array if the construct is valid.
	// Experimental.
	OnValidate() *[]*string
	// Perform final modifications before synthesis.
	//
	// This method can be implemented by derived constructs in order to perform
	// final changes before synthesis. prepare() will be called after child
	// constructs have been prepared.
	//
	// This is an advanced framework feature. Only use this if you
	// understand the implications.
	// Experimental.
	Prepare()
	// Allows this construct to emit artifacts into the cloud assembly during synthesis.
	//
	// This method is usually implemented by framework-level constructs such as `Stack` and `Asset`
	// as they participate in synthesizing the cloud assembly.
	// Experimental.
	Synthesize(session awscdk.ISynthesisSession)
	// Returns a string representation of this construct.
	// Experimental.
	ToString() *string
	// Validate the current construct.
	//
	// This method can be implemented by derived constructs in order to perform
	// validation logic. It is called on all constructs before synthesis.
	//
	// Returns: An array of validation error messages, or an empty array if the construct is valid.
	// Experimental.
	Validate() *[]*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 := awscdk.NewApp()

stack := awscdk.Newstack(app, jsii.String("stack"))

differentArchsCase := awscdk.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(),
		}),
	},
})

// There must be exactly one instance of TestCase per file
// There must be exactly one instance of TestCase per file
awscdk.NewIntegTest(app, jsii.String("integ-test"), &integTestProps{

	// Register as many test cases as you want here
	testCases: []integTestCase{
		differentArchsCase,
	},
})

Experimental.

func NewIntegTestCase

func NewIntegTestCase(scope awscdk.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 `field:"optional" json:"allowDestroy" yaml:"allowDestroy"`
	// Additional options to use for each CDK command.
	// Experimental.
	CdkCommandOptions *cloudassemblyschema.CdkCommands `field:"optional" 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 `field:"optional" json:"diffAssets" yaml:"diffAssets"`
	// Additional commands to run at predefined points in the test workflow.
	//
	// e.g. { postDeploy: ['yarn', 'test'] }
	// Experimental.
	Hooks *cloudassemblyschema.Hooks `field:"optional" json:"hooks" yaml:"hooks"`
	// Limit deployment to these regions.
	// Experimental.
	Regions *[]*string `field:"optional" 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 `field:"optional" json:"stackUpdateWorkflow" yaml:"stackUpdateWorkflow"`
	// Stacks to be deployed during the test.
	// Experimental.
	Stacks *[]awscdk.Stack `field:"required" 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 := awscdk.NewApp()

stack := awscdk.Newstack(app, jsii.String("stack"))

differentArchsCase := awscdk.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(),
		}),
	},
})

// There must be exactly one instance of TestCase per file
// There must be exactly one instance of TestCase per file
awscdk.NewIntegTest(app, jsii.String("integ-test"), &integTestProps{

	// Register as many test cases as you want here
	testCases: []integTestCase{
		differentArchsCase,
	},
})

Experimental.

type IntegTestProps

type IntegTestProps struct {
	// List of test cases that make up this test.
	// Experimental.
	TestCases *[]IntegTestCase `field:"required" json:"testCases" yaml:"testCases"`
}

Integration test properties.

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 := awscdk.NewApp()

stack := awscdk.Newstack(app, jsii.String("stack"))

differentArchsCase := awscdk.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(),
		}),
	},
})

// There must be exactly one instance of TestCase per file
// There must be exactly one instance of TestCase per file
awscdk.NewIntegTest(app, jsii.String("integ-test"), &integTestProps{

	// Register as many test cases as you want here
	testCases: []integTestCase{
		differentArchsCase,
	},
})

Experimental.