Categorygithub.com/aws/aws-cdk-go/awscdkintegtests
package
1.204.0-devpreview
Repository: https://github.com/aws/aws-cdk-go.git
Documentation: pkg.go.dev
Overview
Dependencies
9
Dependents
0

# README

integ-tests

Overview

This library is meant to be used in combination with the integ-runner CLI to enable users to write and execute integration tests for AWS CDK Constructs.

An integration test should be defined as a CDK application, and there should be a 1:1 relationship between an integration test and a CDK application.

So for example, in order to create an integration test called my-function we would need to create a file to contain our integration test application.

test/integ.my-function.ts

app := awscdk.NewApp()
stack := awscdk.NewStack()
lambda.NewFunction(stack, jsii.String("MyFunction"), &FunctionProps{
	Runtime: lambda.Runtime_NODEJS_14_X(),
	Handler: jsii.String("index.handler"),
	Code: lambda.Code_FromAsset(path.join(__dirname, jsii.String("lambda-handler"))),
})

This is a self contained CDK application which we could deploy by running

cdk deploy --app 'node test/integ.my-function.js'

In order to turn this into an integration test, all that is needed is to use the IntegTest construct.

var app app
var stack stack

awscdk.NewIntegTest(app, jsii.String("Integ"), &IntegTestProps{
	TestCases: []*stack{
		stack,
	},
})

You will notice that the stack is registered to the IntegTest as a test case. Each integration test can contain multiple test cases, which are just instances of a stack. See the Usage section for more details.

Usage

IntegTest

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_14_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_14_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()

awscdk.NewIntegTest(app, jsii.String("DifferentArchitectures"), &IntegTestProps{
	TestCases: []*stack{
		NewStackUnderTest(app, jsii.String("Stack1"), &stackUnderTestProps{
			architecture: lambda.*architecture_ARM_64(),
		}),
		NewStackUnderTest(app, jsii.String("Stack2"), &stackUnderTestProps{
			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:

app := awscdk.NewApp()

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

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

testCase := awscdk.NewIntegTest(app, jsii.String("CustomizedDeploymentWorkflow"), &IntegTestProps{
	TestCases: []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),
			},
		},
	},
})

IntegTestCaseStack

In the majority of cases an integration test will contain a single IntegTestCase. By default when you create an IntegTest an IntegTestCase is created for you and all of your test cases are registered to this IntegTestCase. The IntegTestCase and IntegTestCaseStack constructs are only needed when it is necessary to defined different options for individual test cases.

For example, you might want to have one test case where diffAssets is enabled.

var app app
var stackUnderTest stack

testCaseWithAssets := awscdk.NewIntegTestCaseStack(app, jsii.String("TestCaseAssets"), &IntegTestCaseStackProps{
	DiffAssets: jsii.Boolean(true),
})

awscdk.NewIntegTest(app, jsii.String("Integ"), &IntegTestProps{
	TestCases: []*stack{
		stackUnderTest,
		testCaseWithAssets,
	},
})

Assertions

This library also provides a utility to make assertions against the infrastructure that the integration test deploys.

There are two main scenarios in which assertions are created.

  • Part of an integration test using integ-runner

In this case you would create an integration test using the IntegTest construct and then make assertions using the assert property. You should not utilize the assertion constructs directly, but should instead use the methods on IntegTest.assert.

var app app
var stack stack


integ := awscdk.NewIntegTest(app, jsii.String("Integ"), &IntegTestProps{
	TestCases: []*stack{
		stack,
	},
})
integ.Assertions.AwsApiCall(jsii.String("S3"), jsii.String("getObject"))
  • Part of a normal CDK deployment

In this case you may be using assertions as part of a normal CDK deployment in order to make an assertion on the infrastructure before the deployment is considered successful. In this case you can utilize the assertions constructs directly.

var myAppStack stack


awscdk.NewAwsApiCall(myAppStack, jsii.String("GetObject"), &AwsApiCallProps{
	Service: jsii.String("S3"),
	Api: jsii.String("getObject"),
})

DeployAssert

Assertions are created by using the DeployAssert construct. This construct creates it's own Stack separate from any stacks that you create as part of your integration tests. This Stack is treated differently from other stacks by the integ-runner tool. For example, this stack will not be diffed by the integ-runner.

DeployAssert also provides utilities to register your own assertions.

var myCustomResource customResource
var stack stack
var app app


integ := awscdk.NewIntegTest(app, jsii.String("Integ"), &IntegTestProps{
	TestCases: []*stack{
		stack,
	},
})
integ.Assertions.Expect(jsii.String("CustomAssertion"), awscdk.ExpectedResult_ObjectLike(map[string]interface{}{
	"foo": jsii.String("bar"),
}), awscdk.ActualResult_FromCustomResource(myCustomResource, jsii.String("data")))

In the above example an assertion is created that will trigger a user defined CustomResource and assert that the data attribute is equal to { foo: 'bar' }.

AwsApiCall

A common method to retrieve the "actual" results to compare with what is expected is to make an AWS API call to receive some data. This library does this by utilizing CloudFormation custom resources which means that CloudFormation will call out to a Lambda Function which will use the AWS JavaScript SDK to make the API call.

This can be done by using the class directory (in the case of a normal deployment):

var stack stack


awscdk.NewAwsApiCall(stack, jsii.String("MyAssertion"), &AwsApiCallProps{
	Service: jsii.String("SQS"),
	Api: jsii.String("receiveMessage"),
	Parameters: map[string]*string{
		"QueueUrl": jsii.String("url"),
	},
})

Or by using the awsApiCall method on DeployAssert (when writing integration tests):

var app app
var stack stack

integ := awscdk.NewIntegTest(app, jsii.String("Integ"), &IntegTestProps{
	TestCases: []*stack{
		stack,
	},
})
integ.Assertions.AwsApiCall(jsii.String("SQS"), jsii.String("receiveMessage"), map[string]*string{
	"QueueUrl": jsii.String("url"),
})

EqualsAssertion

This library currently provides the ability to assert that two values are equal to one another by utilizing the EqualsAssertion class. This utilizes a Lambda backed CustomResource which in tern uses the Match utility from the @aws-cdk/assertions library.

var app app
var stack stack
var queue queue
var fn iFunction


integ := awscdk.NewIntegTest(app, jsii.String("Integ"), &IntegTestProps{
	TestCases: []*stack{
		stack,
	},
})

integ.Assertions.InvokeFunction(&LambdaInvokeFunctionProps{
	FunctionName: fn.FunctionName,
	InvocationType: awscdk.InvocationType_EVENT,
	Payload: jSON.stringify(map[string]*string{
		"status": jsii.String("OK"),
	}),
})

message := integ.Assertions.AwsApiCall(jsii.String("SQS"), jsii.String("receiveMessage"), map[string]interface{}{
	"QueueUrl": queue.queueUrl,
	"WaitTimeSeconds": jsii.Number(20),
})

message.AssertAtPath(jsii.String("Messages.0.Body"), awscdk.ExpectedResult_ObjectLike(map[string]interface{}{
	"requestContext": map[string]*string{
		"condition": jsii.String("Success"),
	},
	"requestPayload": map[string]*string{
		"status": jsii.String("OK"),
	},
	"responseContext": map[string]*f64{
		"statusCode": jsii.Number(200),
	},
	"responsePayload": jsii.String("success"),
}))

Match

integ-tests also provides a Match utility similar to the @aws-cdk/assertions module. Match can be used to construct the ExpectedResult.

var message awsApiCall


message.Expect(awscdk.ExpectedResult_ObjectLike(map[string]interface{}{
	"Messages": awscdk.Match_arrayWith([]interface{}{
		map[string]map[string]map[string][]interface{}{
			"Body": map[string]map[string][]interface{}{
				"Values": awscdk.Match_arrayWith([]interface{}{
					map[string]*f64{
						"Asdf": jsii.Number(3),
					},
				}),
				"Message": awscdk.Match_stringLikeRegexp(jsii.String("message")),
			},
		},
	}),
}))

Examples

Invoke a Lambda Function

In this example there is a Lambda Function that is invoked and we assert that the payload that is returned is equal to '200'.

var lambdaFunction iFunction
var app app


stack := awscdk.NewStack(app, jsii.String("cdk-integ-lambda-bundling"))

integ := awscdk.NewIntegTest(app, jsii.String("IntegTest"), &IntegTestProps{
	TestCases: []stack{
		stack,
	},
})

invoke := integ.Assertions.InvokeFunction(&LambdaInvokeFunctionProps{
	FunctionName: lambdaFunction.FunctionName,
})
invoke.Expect(awscdk.ExpectedResult_ObjectLike(map[string]interface{}{
	"Payload": jsii.String("200"),
}))

Make an AWS API Call

In this example there is a StepFunctions state machine that is executed and then we assert that the result of the execution is successful.

var app app
var stack stack
var sm iStateMachine


testCase := awscdk.NewIntegTest(app, jsii.String("IntegTest"), &IntegTestProps{
	TestCases: []*stack{
		stack,
	},
})

// Start an execution
start := testCase.Assertions.AwsApiCall(jsii.String("StepFunctions"), jsii.String("startExecution"), map[string]*string{
	"stateMachineArn": sm.stateMachineArn,
})

// describe the results of the execution
describe := testCase.Assertions.AwsApiCall(jsii.String("StepFunctions"), jsii.String("describeExecution"), map[string]*string{
	"executionArn": start.getAttString(jsii.String("executionArn")),
})

// assert the results
describe.Expect(awscdk.ExpectedResult_ObjectLike(map[string]interface{}{
	"status": jsii.String("SUCCEEDED"),
}))