@aws-cdk/integ-tests-alpha

integ-tests

Version 2.274.0-alpha.0

Separate package

@aws-cdk/integ-tests-alpha is not part of aws-cdk-lib — install it separately:

npm install @aws-cdk/integ-tests-alpha
pip install aws-cdk.integ-tests-alpha

This module is experimental (alpha): its API may change in any release, without a major version bump.

---

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.

---

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

const app = new App();
const stack = new Stack();
new lambda.Function(stack, 'MyFunction', {
  runtime: lambda.Runtime.NODEJS_LATEST,
  handler: 'index.handler',
  code: lambda.Code.fromAsset(path.join(__dirname, 'lambda-handler')),
});

app = App()
stack = Stack()
lambda_.Function(stack, "MyFunction",
    runtime=lambda_.Runtime.NODEJS_LATEST,
    handler="index.handler",
    code=lambda_.Code.from_asset(path.join(__dirname, "lambda-handler"))
)

App app = new App();
Stack stack = new Stack();
Function.Builder.create(stack, "MyFunction")
        .runtime(Runtime.NODEJS_LATEST)
        .handler("index.handler")
        .code(Code.fromAsset(join(__dirname, "lambda-handler")))
        .build();

var app = new App();
var stack = new Stack();
new Function(stack, "MyFunction", new FunctionProps {
    Runtime = Runtime.NODEJS_LATEST,
    Handler = "index.handler",
    Code = Code.FromAsset(Join(__dirname, "lambda-handler"))
});

app := awscdk.NewApp()
stack := awscdk.NewStack()
lambda.NewFunction(stack, jsii.String("MyFunction"), &FunctionProps{
	Runtime: lambda.Runtime_NODEJS_LATEST(),
	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.

declare const app: App;
declare const stack: Stack;
new IntegTest(app, 'Integ', { testCases: [stack] });

# app: App
# stack: Stack

IntegTest(app, "Integ", test_cases=[stack])

App app;
Stack stack;

IntegTest.Builder.create(app, "Integ").testCases(List.of(stack)).build();

App app;
Stack stack;

new IntegTest(app, "Integ", new IntegTestProps { TestCases = new [] { stack } });

var app App
var stack Stack

awscdkintegtestsalpha.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:

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_LATEST,
      handler: 'index.handler',
      code: lambda.Code.fromAsset(path.join(__dirname, 'lambda-handler')),
      architecture: props.architecture,
    });
  }
}

class StackUnderTest(Stack):
    def __init__(self, scope, id, *, architecture=None, description=None, env=None, stackName=None, tags=None, notificationArns=None, synthesizer=None, terminationProtection=None, analyticsReporting=None, crossRegionReferences=None, permissionsBoundary=None, suppressTemplateIndentation=None, propertyInjectors=None):
        super().__init__(scope, id, architecture=architecture, description=description, env=env, stackName=stackName, tags=tags, notificationArns=notificationArns, synthesizer=synthesizer, terminationProtection=terminationProtection, analyticsReporting=analyticsReporting, crossRegionReferences=crossRegionReferences, permissionsBoundary=permissionsBoundary, suppressTemplateIndentation=suppressTemplateIndentation, propertyInjectors=propertyInjectors)

        lambda_.Function(self, "Handler",
            runtime=lambda_.Runtime.NODEJS_LATEST,
            handler="index.handler",
            code=lambda_.Code.from_asset(path.join(__dirname, "lambda-handler")),
            architecture=architecture
        )

public class StackUnderTestProps extends StackProps {
    private Architecture architecture;
    public Architecture getArchitecture() {
        return this.architecture;
    }
    public StackUnderTestProps architecture(Architecture architecture) {
        this.architecture = architecture;
        return this;
    }
}

public class StackUnderTest extends Stack {
    public StackUnderTest(Construct scope, String id, StackUnderTestProps props) {
        super(scope, id, props);

        Function.Builder.create(this, "Handler")
                .runtime(Runtime.NODEJS_LATEST)
                .handler("index.handler")
                .code(Code.fromAsset(join(__dirname, "lambda-handler")))
                .architecture(props.getArchitecture())
                .build();
    }
}

class StackUnderTestProps : StackProps
{
    public Architecture? Architecture { get; set; }
}

class StackUnderTest : Stack
{
    public StackUnderTest(Construct scope, string id, StackUnderTestProps props) : base(scope, id, props)
    {

        new Function(this, "Handler", new FunctionProps {
            Runtime = Runtime.NODEJS_LATEST,
            Handler = "index.handler",
            Code = Code.FromAsset(Join(__dirname, "lambda-handler")),
            Architecture = props.Architecture
        });
    }
}

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_LATEST(),
		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:

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_LATEST,
      handler: 'index.handler',
      code: lambda.Code.fromAsset(path.join(__dirname, 'lambda-handler')),
      architecture: props.architecture,
    });
  }
}

// Beginning of the test suite
const app = new App();

new IntegTest(app, 'DifferentArchitectures', {
  testCases: [
    new StackUnderTest(app, 'Stack1', {
      architecture: lambda.Architecture.ARM_64,
    }),
    new StackUnderTest(app, 'Stack2', {
      architecture: lambda.Architecture.X86_64,
    }),
  ],
});

class StackUnderTest(Stack):
    def __init__(self, scope, id, *, architecture=None, description=None, env=None, stackName=None, tags=None, notificationArns=None, synthesizer=None, terminationProtection=None, analyticsReporting=None, crossRegionReferences=None, permissionsBoundary=None, suppressTemplateIndentation=None, propertyInjectors=None):
        super().__init__(scope, id, architecture=architecture, description=description, env=env, stackName=stackName, tags=tags, notificationArns=notificationArns, synthesizer=synthesizer, terminationProtection=terminationProtection, analyticsReporting=analyticsReporting, crossRegionReferences=crossRegionReferences, permissionsBoundary=permissionsBoundary, suppressTemplateIndentation=suppressTemplateIndentation, propertyInjectors=propertyInjectors)

        lambda_.Function(self, "Handler",
            runtime=lambda_.Runtime.NODEJS_LATEST,
            handler="index.handler",
            code=lambda_.Code.from_asset(path.join(__dirname, "lambda-handler")),
            architecture=architecture
        )

# Beginning of the test suite
app = App()

IntegTest(app, "DifferentArchitectures",
    test_cases=[
        StackUnderTest(app, "Stack1",
            architecture=lambda_.Architecture.ARM_64
        ),
        StackUnderTest(app, "Stack2",
            architecture=lambda_.Architecture.X86_64
        )
    ]
)

public class StackUnderTestProps extends StackProps {
    private Architecture architecture;
    public Architecture getArchitecture() {
        return this.architecture;
    }
    public StackUnderTestProps architecture(Architecture architecture) {
        this.architecture = architecture;
        return this;
    }
}

public class StackUnderTest extends Stack {
    public StackUnderTest(Construct scope, String id, StackUnderTestProps props) {
        super(scope, id, props);

        Function.Builder.create(this, "Handler")
                .runtime(Runtime.NODEJS_LATEST)
                .handler("index.handler")
                .code(Code.fromAsset(join(__dirname, "lambda-handler")))
                .architecture(props.getArchitecture())
                .build();
    }
}

// Beginning of the test suite
App app = new App();

IntegTest.Builder.create(app, "DifferentArchitectures")
        .testCases(List.of(
            new StackUnderTest(app, "Stack1", new StackUnderTestProps()
                    .architecture(Architecture.ARM_64)
                    ),
            new StackUnderTest(app, "Stack2", new StackUnderTestProps()
                    .architecture(Architecture.X86_64)
                    )))
        .build();

class StackUnderTestProps : StackProps
{
    public Architecture? Architecture { get; set; }
}

class StackUnderTest : Stack
{
    public StackUnderTest(Construct scope, string id, StackUnderTestProps props) : base(scope, id, props)
    {

        new Function(this, "Handler", new FunctionProps {
            Runtime = Runtime.NODEJS_LATEST,
            Handler = "index.handler",
            Code = Code.FromAsset(Join(__dirname, "lambda-handler")),
            Architecture = props.Architecture
        });
    }
}

// Beginning of the test suite
var app = new App();

new IntegTest(app, "DifferentArchitectures", new IntegTestProps {
    TestCases = new [] {
        new StackUnderTest(app, "Stack1", new StackUnderTestProps {
            Architecture = Architecture.ARM_64
        }),
        new StackUnderTest(app, "Stack2", new StackUnderTestProps {
            Architecture = Architecture.X86_64
        }) }
});

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_LATEST(),
		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()

awscdkintegtestsalpha.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:

const app = new App();

const stackUnderTest = new Stack(app, 'StackUnderTest', /* ... */);

const stack = new Stack(app, 'stack');

const testCase = new IntegTest(app, 'CustomizedDeploymentWorkflow', {
  testCases: [stackUnderTest],
  diffAssets: true,
  stackUpdateWorkflow: true,
  cdkCommandOptions: {
    deploy: {
      args: {
        requireApproval: RequireApproval.NEVER,
        json: true,
      },
    },
    destroy: {
      args: {
        force: true,
      },
    },
  },
});

from aws_cdk.cloud_assembly_schema import CdkCommands, DeployCommand, DeployOptions, DestroyCommand, DestroyOptions
app = App()

stack_under_test = Stack(app, "StackUnderTest")

stack = Stack(app, "stack")

test_case = IntegTest(app, "CustomizedDeploymentWorkflow",
    test_cases=[stack_under_test],
    diff_assets=True,
    stack_update_workflow=True,
    cdk_command_options=CdkCommands(
        deploy=DeployCommand(
            args=DeployOptions(
                require_approval=RequireApproval.NEVER,
                json=True
            )
        ),
        destroy=DestroyCommand(
            args=DestroyOptions(
                force=True
            )
        )
    )
)

App app = new App();

Stack stackUnderTest = new Stack(app, "StackUnderTest");

Stack stack = new Stack(app, "stack");

IntegTest testCase = IntegTest.Builder.create(app, "CustomizedDeploymentWorkflow")
        .testCases(List.of(stackUnderTest))
        .diffAssets(true)
        .stackUpdateWorkflow(true)
        .cdkCommandOptions(CdkCommands.builder()
                .deploy(DeployCommand.builder()
                        .args(DeployOptions.builder()
                                .requireApproval(RequireApproval.NEVER)
                                .json(true)
                                .build())
                        .build())
                .destroy(DestroyCommand.builder()
                        .args(DestroyOptions.builder()
                                .force(true)
                                .build())
                        .build())
                .build())
        .build();

var app = new App();

var stackUnderTest = new Stack(app, "StackUnderTest");

var stack = new Stack(app, "stack");

var testCase = new IntegTest(app, "CustomizedDeploymentWorkflow", new IntegTestProps {
    TestCases = new [] { stackUnderTest },
    DiffAssets = true,
    StackUpdateWorkflow = true,
    CdkCommandOptions = new CdkCommands {
        Deploy = new DeployCommand {
            Args = new DeployOptions {
                RequireApproval = RequireApproval.NEVER,
                Json = true
            }
        },
        Destroy = new DestroyCommand {
            Args = new DestroyOptions {
                Force = true
            }
        }
    }
});

app := awscdk.NewApp()

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

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

testCase := awscdkintegtestsalpha.NewIntegTest(app, jsii.String("CustomizedDeploymentWorkflow"), &IntegTestProps{
	TestCases: []Stack{
		stackUnderTest,
	},
	DiffAssets: jsii.Boolean(true),
	StackUpdateWorkflow: jsii.Boolean(true),
	CdkCommandOptions: &CdkCommands{
		Deploy: &DeployCommand{
			Args: &DeployOptions{
				RequireApproval: awscdklibcloudassemblyschema.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.

declare const app: App;
declare const stackUnderTest: Stack;
const testCaseWithAssets = new IntegTestCaseStack(app, 'TestCaseAssets', {
  diffAssets: true,
});

new IntegTest(app, 'Integ', { testCases: [stackUnderTest, testCaseWithAssets] });

# app: App
# stack_under_test: Stack

test_case_with_assets = IntegTestCaseStack(app, "TestCaseAssets",
    diff_assets=True
)

IntegTest(app, "Integ", test_cases=[stack_under_test, test_case_with_assets])

App app;
Stack stackUnderTest;

IntegTestCaseStack testCaseWithAssets = IntegTestCaseStack.Builder.create(app, "TestCaseAssets")
        .diffAssets(true)
        .build();

IntegTest.Builder.create(app, "Integ").testCases(List.of(stackUnderTest, testCaseWithAssets)).build();

App app;
Stack stackUnderTest;

var testCaseWithAssets = new IntegTestCaseStack(app, "TestCaseAssets", new IntegTestCaseStackProps {
    DiffAssets = true
});

new IntegTest(app, "Integ", new IntegTestProps { TestCases = new [] { stackUnderTest, testCaseWithAssets } });

var app App
var stackUnderTest Stack

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

awscdkintegtestsalpha.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.assertions.

declare const app: App;
declare const stack: Stack;

const integ = new IntegTest(app, 'Integ', { testCases: [stack] });
integ.assertions.awsApiCall('S3', 'getObject');

# app: App
# stack: Stack


integ = IntegTest(app, "Integ", test_cases=[stack])
integ.assertions.aws_api_call("S3", "getObject")

App app;
Stack stack;


IntegTest integ = IntegTest.Builder.create(app, "Integ").testCases(List.of(stack)).build();
integ.assertions.awsApiCall("S3", "getObject");

App app;
Stack stack;


var integ = new IntegTest(app, "Integ", new IntegTestProps { TestCases = new [] { stack } });
integ.Assertions.AwsApiCall("S3", "getObject");

var app App
var stack Stack


integ := awscdkintegtestsalpha.NewIntegTest(app, jsii.String("Integ"), &IntegTestProps{
	TestCases: []Stack{
		stack,
	},
})
integ.Assertions.AwsApiCall(jsii.String("S3"), jsii.String("getObject"))

By default an assertions stack is automatically generated for you. You may however provide your own stack to use.

declare const app: App;
declare const stack: Stack;
declare const assertionStack: Stack;

const integ = new IntegTest(app, 'Integ', { testCases: [stack], assertionStack: assertionStack });
integ.assertions.awsApiCall('S3', 'getObject');

# app: App
# stack: Stack
# assertion_stack: Stack


integ = IntegTest(app, "Integ", test_cases=[stack], assertion_stack=assertion_stack)
integ.assertions.aws_api_call("S3", "getObject")

App app;
Stack stack;
Stack assertionStack;


IntegTest integ = IntegTest.Builder.create(app, "Integ").testCases(List.of(stack)).assertionStack(assertionStack).build();
integ.assertions.awsApiCall("S3", "getObject");

App app;
Stack stack;
Stack assertionStack;


var integ = new IntegTest(app, "Integ", new IntegTestProps { TestCases = new [] { stack }, AssertionStack = assertionStack });
integ.Assertions.AwsApiCall("S3", "getObject");

var app App
var stack Stack
var assertionStack Stack


integ := awscdkintegtestsalpha.NewIntegTest(app, jsii.String("Integ"), &IntegTestProps{
	TestCases: []Stack{
		stack,
	},
	AssertionStack: assertionStack,
})
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.

declare const myAppStack: Stack;

new AwsApiCall(myAppStack, 'GetObject', {
  service: 'S3',
  api: 'getObject',
});

# my_app_stack: Stack


AwsApiCall(my_app_stack, "GetObject",
    service="S3",
    api="getObject"
)

Stack myAppStack;


AwsApiCall.Builder.create(myAppStack, "GetObject")
        .service("S3")
        .api("getObject")
        .build();

Stack myAppStack;


new AwsApiCall(myAppStack, "GetObject", new AwsApiCallProps {
    Service = "S3",
    Api = "getObject"
});

var myAppStack Stack


awscdkintegtestsalpha.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.

declare const myCustomResource: CustomResource;
declare const stack: Stack;
declare const app: App;

const integ = new IntegTest(app, 'Integ', { testCases: [stack] });
integ.assertions.expect(
  'CustomAssertion',
  ExpectedResult.objectLike({ foo: 'bar' }),
  ActualResult.fromCustomResource(myCustomResource, 'data'),
);

# my_custom_resource: CustomResource
# stack: Stack
# app: App


integ = IntegTest(app, "Integ", test_cases=[stack])
integ.assertions.expect("CustomAssertion",
    ExpectedResult.object_like({"foo": "bar"}),
    ActualResult.from_custom_resource(my_custom_resource, "data"))

CustomResource myCustomResource;
Stack stack;
App app;


IntegTest integ = IntegTest.Builder.create(app, "Integ").testCases(List.of(stack)).build();
integ.assertions.expect("CustomAssertion", ExpectedResult.objectLike(Map.of("foo", "bar")), ActualResult.fromCustomResource(myCustomResource, "data"));

CustomResource myCustomResource;
Stack stack;
App app;


var integ = new IntegTest(app, "Integ", new IntegTestProps { TestCases = new [] { stack } });
integ.Assertions.Expect("CustomAssertion", ExpectedResult.ObjectLike(new Dictionary<string, object> { { "foo", "bar" } }), ActualResult.FromCustomResource(myCustomResource, "data"));

var myCustomResource CustomResource
var stack Stack
var app App


integ := awscdkintegtestsalpha.NewIntegTest(app, jsii.String("Integ"), &IntegTestProps{
	TestCases: []Stack{
		stack,
	},
})
integ.Assertions.Expect(jsii.String("CustomAssertion"), awscdkintegtestsalpha.ExpectedResult_ObjectLike(map[string]interface{}{
	"foo": jsii.String("bar"),
}), awscdkintegtestsalpha.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' }.

API Calls

A common method to retrieve the "actual" results to compare with what is expected is to make an 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 make the API call.

HttpApiCall

Using the HttpApiCall will use the node-fetch JavaScript library to make the HTTP call.

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

declare const stack: Stack;

new HttpApiCall(stack, 'MyAsssertion', {
  url: 'https://example-api.com/abc',
});

# stack: Stack


HttpApiCall(stack, "MyAsssertion",
    url="https://example-api.com/abc"
)

Stack stack;


HttpApiCall.Builder.create(stack, "MyAsssertion")
        .url("https://example-api.com/abc")
        .build();

Stack stack;


new HttpApiCall(stack, "MyAsssertion", new HttpCallProps {
    Url = "https://example-api.com/abc"
});

var stack Stack


awscdkintegtestsalpha.NewHttpApiCall(stack, jsii.String("MyAsssertion"), &HttpCallProps{
	Url: jsii.String("https://example-api.com/abc"),
})

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

declare const app: App;
declare const stack: Stack;
const integ = new IntegTest(app, 'Integ', {
  testCases: [stack],
});
integ.assertions.httpApiCall('https://example-api.com/abc');

# app: App
# stack: Stack

integ = IntegTest(app, "Integ",
    test_cases=[stack]
)
integ.assertions.http_api_call("https://example-api.com/abc")

App app;
Stack stack;

IntegTest integ = IntegTest.Builder.create(app, "Integ")
        .testCases(List.of(stack))
        .build();
integ.assertions.httpApiCall("https://example-api.com/abc");

App app;
Stack stack;

var integ = new IntegTest(app, "Integ", new IntegTestProps {
    TestCases = new [] { stack }
});
integ.Assertions.HttpApiCall("https://example-api.com/abc");

var app App
var stack Stack

integ := awscdkintegtestsalpha.NewIntegTest(app, jsii.String("Integ"), &IntegTestProps{
	TestCases: []Stack{
		stack,
	},
})
integ.Assertions.HttpApiCall(jsii.String("https://example-api.com/abc"))

AwsApiCall

Using the AwsApiCall construct 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):

declare const stack: Stack;

new AwsApiCall(stack, 'MyAssertion', {
  service: 'SQS',
  api: 'receiveMessage',
  parameters: {
    QueueUrl: 'url',
  },
});

# stack: Stack


AwsApiCall(stack, "MyAssertion",
    service="SQS",
    api="receiveMessage",
    parameters={
        "QueueUrl": "url"
    }
)

Stack stack;


AwsApiCall.Builder.create(stack, "MyAssertion")
        .service("SQS")
        .api("receiveMessage")
        .parameters(Map.of(
                "QueueUrl", "url"))
        .build();

Stack stack;


new AwsApiCall(stack, "MyAssertion", new AwsApiCallProps {
    Service = "SQS",
    Api = "receiveMessage",
    Parameters = new Dictionary<string, string> {
        { "QueueUrl", "url" }
    }
});

var stack Stack


awscdkintegtestsalpha.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):

declare const app: App;
declare const stack: Stack;
const integ = new IntegTest(app, 'Integ', {
  testCases: [stack],
});
integ.assertions.awsApiCall('SQS', 'receiveMessage', {
  QueueUrl: 'url',
});

# app: App
# stack: Stack

integ = IntegTest(app, "Integ",
    test_cases=[stack]
)
integ.assertions.aws_api_call("SQS", "receiveMessage", {
    "QueueUrl": "url"
})

App app;
Stack stack;

IntegTest integ = IntegTest.Builder.create(app, "Integ")
        .testCases(List.of(stack))
        .build();
integ.assertions.awsApiCall("SQS", "receiveMessage", Map.of(
        "QueueUrl", "url"));

App app;
Stack stack;

var integ = new IntegTest(app, "Integ", new IntegTestProps {
    TestCases = new [] { stack }
});
integ.Assertions.AwsApiCall("SQS", "receiveMessage", new Dictionary<string, string> {
    { "QueueUrl", "url" }
});

var app App
var stack Stack

integ := awscdkintegtestsalpha.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"),
})

You must specify the service and the api when using The AwsApiCall construct. The service is the name of an AWS service, in one of the following forms:

• An AWS SDK for JavaScript v3 package name (@aws-sdk/client-api-gateway)
• An AWS SDK for JavaScript v3 client name (api-gateway)
• An AWS SDK for JavaScript v2 constructor name (APIGateway)
• A lowercase AWS SDK for JavaScript v2 constructor name (apigateway)

The api is the name of an AWS API call, in one of the following forms:

• An API call name as found in the API Reference documentation (GetObject)
• The API call name starting with a lowercase letter (getObject)
• The AWS SDK for JavaScript v3 command class name (GetObjectCommand)

By default, the AwsApiCall construct will automatically add the correct IAM policies to allow the Lambda function to make the API call. It does this based on the service and api that is provided. In the above example the service is SQS and the api is receiveMessage so it will create a policy with Action: 'sqs:ReceiveMessage.

There are some cases where the permissions do not exactly match the service/api call, for example the S3 listObjectsV2 api. In these cases it is possible to add the correct policy by accessing the provider object.

declare const app: App;
declare const stack: Stack;
declare const integ: IntegTest;

const apiCall = integ.assertions.awsApiCall('S3', 'listObjectsV2', {
  Bucket: 'mybucket',
});

apiCall.provider.addToRolePolicy({
  Effect: 'Allow',
  Action: ['s3:GetObject', 's3:ListBucket'],
  Resource: ['*'],
});

# app: App
# stack: Stack
# integ: IntegTest


api_call = integ.assertions.aws_api_call("S3", "listObjectsV2", {
    "Bucket": "mybucket"
})

api_call.provider.add_to_role_policy({
    "Effect": "Allow",
    "Action": ["s3:GetObject", "s3:ListBucket"],
    "Resource": ["*"]
})

App app;
Stack stack;
IntegTest integ;


IApiCall apiCall = integ.assertions.awsApiCall("S3", "listObjectsV2", Map.of(
        "Bucket", "mybucket"));

apiCall.provider.addToRolePolicy(Map.of(
        "Effect", "Allow",
        "Action", List.of("s3:GetObject", "s3:ListBucket"),
        "Resource", List.of("*")));

App app;
Stack stack;
IntegTest integ;


var apiCall = integ.Assertions.AwsApiCall("S3", "listObjectsV2", new Dictionary<string, string> {
    { "Bucket", "mybucket" }
});

apiCall.Provider.AddToRolePolicy(new Dictionary<string, object> {
    { "Effect", "Allow" },
    { "Action", new [] { "s3:GetObject", "s3:ListBucket" } },
    { "Resource", new [] { "*" } }
});

var app App
var stack Stack
var integ IntegTest


apiCall := integ.Assertions.AwsApiCall(jsii.String("S3"), jsii.String("listObjectsV2"), map[string]*string{
	"Bucket": jsii.String("mybucket"),
})

apiCall.Provider.AddToRolePolicy(map[string]interface{}{
	"Effect": jsii.String("Allow"),
	"Action": []*string{
		jsii.String("s3:GetObject"),
		jsii.String("s3:ListBucket"),
	},
	"Resource": []*string{
		jsii.String("*"),
	},
})

When executing waitForAssertion(), it is necessary to add an IAM policy using waiterProvider.addToRolePolicy(). Because IApiCall does not have a waiterProvider property, you need to cast it to AwsApiCall.

declare const integ: IntegTest;

const apiCall = integ.assertions.awsApiCall('S3', 'listObjectsV2', {
  Bucket: 'mybucket',
}).waitForAssertions() as AwsApiCall;

apiCall.waiterProvider?.addToRolePolicy({
  Effect: 'Allow',
  Action: ['s3:GetObject', 's3:ListBucket'],
  Resource: ['*'],
});

# integ: IntegTest


api_call = integ.assertions.aws_api_call("S3", "listObjectsV2", {
    "Bucket": "mybucket"
}).wait_for_assertions()

api_call.waiter_provider.add_to_role_policy({
    "Effect": "Allow",
    "Action": ["s3:GetObject", "s3:ListBucket"],
    "Resource": ["*"]
})

IntegTest integ;


AwsApiCall apiCall = (AwsApiCall)integ.assertions.awsApiCall("S3", "listObjectsV2", Map.of(
        "Bucket", "mybucket")).waitForAssertions();

apiCall.waiterProvider.addToRolePolicy(Map.of(
        "Effect", "Allow",
        "Action", List.of("s3:GetObject", "s3:ListBucket"),
        "Resource", List.of("*")));

IntegTest integ;


var apiCall = (AwsApiCall)integ.Assertions.AwsApiCall("S3", "listObjectsV2", new Dictionary<string, string> {
    { "Bucket", "mybucket" }
}).WaitForAssertions();

apiCall.WaiterProvider.AddToRolePolicy(new Dictionary<string, object> {
    { "Effect", "Allow" },
    { "Action", new [] { "s3:GetObject", "s3:ListBucket" } },
    { "Resource", new [] { "*" } }
});

var integ IntegTest


apiCall := integ.Assertions.AwsApiCall(jsii.String("S3"), jsii.String("listObjectsV2"), map[string]*string{
	"Bucket": jsii.String("mybucket"),
}).WaitForAssertions().(AwsApiCall)

apiCall.WaiterProvider.AddToRolePolicy(map[string]interface{}{
	"Effect": jsii.String("Allow"),
	"Action": []*string{
		jsii.String("s3:GetObject"),
		jsii.String("s3:ListBucket"),
	},
	"Resource": []*string{
		jsii.String("*"),
	},
})

Note that addToRolePolicy() uses direct IAM JSON policy blobs, not a iam.PolicyStatement object like you will see in the rest of the CDK.

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.

declare const app: App;
declare const stack: Stack;
declare const queue: sqs.Queue;
declare const fn: lambda.IFunction;

const integ = new IntegTest(app, 'Integ', {
  testCases: [stack],
});

integ.assertions.invokeFunction({
  functionName: fn.functionName,
  invocationType: InvocationType.EVENT,
  payload: JSON.stringify({ status: 'OK' }),
});

const message = integ.assertions.awsApiCall('SQS', 'receiveMessage', {
  QueueUrl: queue.queueUrl,
  WaitTimeSeconds: 20,
});

message.assertAtPath('Messages.0.Body', ExpectedResult.objectLike({
  requestContext: {
    condition: 'Success',
  },
  requestPayload: {
    status: 'OK',
  },
  responseContext: {
    statusCode: 200,
  },
  responsePayload: 'success',
}));

# app: App
# stack: Stack
# queue: sqs.Queue
# fn: lambda.IFunction


integ = IntegTest(app, "Integ",
    test_cases=[stack]
)

integ.assertions.invoke_function(
    function_name=fn.function_name,
    invocation_type=InvocationType.EVENT,
    payload=JSON.stringify({"status": "OK"})
)

message = integ.assertions.aws_api_call("SQS", "receiveMessage", {
    "QueueUrl": queue.queue_url,
    "WaitTimeSeconds": 20
})

message.assert_at_path("Messages.0.Body", ExpectedResult.object_like({
    "request_context": {
        "condition": "Success"
    },
    "request_payload": {
        "status": "OK"
    },
    "response_context": {
        "status_code": 200
    },
    "response_payload": "success"
}))

App app;
Stack stack;
Queue queue;
IFunction fn;


IntegTest integ = IntegTest.Builder.create(app, "Integ")
        .testCases(List.of(stack))
        .build();

integ.assertions.invokeFunction(LambdaInvokeFunctionProps.builder()
        .functionName(fn.getFunctionName())
        .invocationType(InvocationType.EVENT)
        .payload(JSON.stringify(Map.of("status", "OK")))
        .build());

IApiCall message = integ.assertions.awsApiCall("SQS", "receiveMessage", Map.of(
        "QueueUrl", queue.getQueueUrl(),
        "WaitTimeSeconds", 20));

message.assertAtPath("Messages.0.Body", ExpectedResult.objectLike(Map.of(
        "requestContext", Map.of(
                "condition", "Success"),
        "requestPayload", Map.of(
                "status", "OK"),
        "responseContext", Map.of(
                "statusCode", 200),
        "responsePayload", "success")));

App app;
Stack stack;
Queue queue;
IFunction fn;


var integ = new IntegTest(app, "Integ", new IntegTestProps {
    TestCases = new [] { stack }
});

integ.Assertions.InvokeFunction(new LambdaInvokeFunctionProps {
    FunctionName = fn.FunctionName,
    InvocationType = InvocationType.EVENT,
    Payload = JSON.Stringify(new Dictionary<string, string> { { "status", "OK" } })
});

var message = integ.Assertions.AwsApiCall("SQS", "receiveMessage", new Dictionary<string, object> {
    { "QueueUrl", queue.QueueUrl },
    { "WaitTimeSeconds", 20 }
});

message.AssertAtPath("Messages.0.Body", ExpectedResult.ObjectLike(new Dictionary<string, object> {
    { "requestContext", new Dictionary<string, string> {
        { "condition", "Success" }
    } },
    { "requestPayload", new Dictionary<string, string> {
        { "status", "OK" }
    } },
    { "responseContext", new Dictionary<string, int> {
        { "statusCode", 200 }
    } },
    { "responsePayload", "success" }
}));

var app App
var stack Stack
var queue Queue
var fn IFunction


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

integ.Assertions.InvokeFunction(&LambdaInvokeFunctionProps{
	FunctionName: fn.FunctionName,
	InvocationType: awscdkintegtestsalpha.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"), awscdkintegtestsalpha.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. While the utility is similar, only a subset of methods are currently available on the Match utility of this module: arrayWith, objectLike, stringLikeRegexp and serializedJson.

declare const message: AwsApiCall;

message.expect(ExpectedResult.objectLike({
  Messages: Match.arrayWith([
    {
      Payload: Match.serializedJson({ key: 'value' }),
    },
    {
	  Body: {
	    Values: Match.arrayWith([{ Asdf: 3 }]),
		Message: Match.stringLikeRegexp('message'),
	  },
    },
  ]),
}));

# message: AwsApiCall


message.expect(ExpectedResult.object_like({
    "Messages": Match.array_with([{
        "Payload": Match.serialized_json({"key": "value"})
    }, {
        "Body": {
            "Values": Match.array_with([{"Asdf": 3}]),
            "Message": Match.string_like_regexp("message")
        }
    }
    ])
}))

AwsApiCall message;


message.expect(ExpectedResult.objectLike(Map.of(
        "Messages", Match.arrayWith(List.of(Map.of(
                "Payload", Match.serializedJson(Map.of("key", "value"))), Map.of(
                "Body", Map.of(
                        "Values", Match.arrayWith(List.of(Map.of("Asdf", 3))),
                        "Message", Match.stringLikeRegexp("message"))))))));

AwsApiCall message;


message.Expect(ExpectedResult.ObjectLike(new Dictionary<string, object> {
    { "Messages", Match.ArrayWith(new [] { new Dictionary<string, IDictionary<string, IDictionary<string, object>>> {
        { "Payload", Match.SerializedJson(new Dictionary<string, object> { { "key", "value" } }) }
    }, new Dictionary<string, IDictionary<string, IDictionary<string, object[]>>> {
        { "Body", new Struct {
            Values = Match.ArrayWith(new [] { new Dictionary<string, int> { { "Asdf", 3 } } }),
            Message = Match.StringLikeRegexp("message")
        } }
    } }) }
}));

var message AwsApiCall


message.Expect(awscdkintegtestsalpha.ExpectedResult_ObjectLike(map[string]interface{}{
	"Messages": awscdkintegtestsalpha.Match_arrayWith([]interface{}{
		map[string]map[string]map[string]interface{}{
			"Payload": awscdkintegtestsalpha.Match_serializedJson(map[string]interface{}{
				"key": jsii.String("value"),
			}),
		},
		map[string]map[string]map[string][]interface{}{
			"Body": map[string]map[string][]interface{}{
				"Values": awscdkintegtestsalpha.Match_arrayWith([]interface{}{
					map[string]*f64{
						"Asdf": jsii.Number(3),
					},
				}),
				"Message": awscdkintegtestsalpha.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'.

declare const lambdaFunction: lambda.IFunction;
declare const app: App;

const stack = new Stack(app, 'cdk-integ-lambda-bundling');

const integ = new IntegTest(app, 'IntegTest', {
  testCases: [stack],
});

const invoke = integ.assertions.invokeFunction({
  functionName: lambdaFunction.functionName,
});
invoke.expect(ExpectedResult.objectLike({
  Payload: '200',
}));

# lambda_function: lambda.IFunction
# app: App


stack = Stack(app, "cdk-integ-lambda-bundling")

integ = IntegTest(app, "IntegTest",
    test_cases=[stack]
)

invoke = integ.assertions.invoke_function(
    function_name=lambda_function.function_name
)
invoke.expect(ExpectedResult.object_like({
    "Payload": "200"
}))

IFunction lambdaFunction;
App app;


Stack stack = new Stack(app, "cdk-integ-lambda-bundling");

IntegTest integ = IntegTest.Builder.create(app, "IntegTest")
        .testCases(List.of(stack))
        .build();

IApiCall invoke = integ.assertions.invokeFunction(LambdaInvokeFunctionProps.builder()
        .functionName(lambdaFunction.getFunctionName())
        .build());
invoke.expect(ExpectedResult.objectLike(Map.of(
        "Payload", "200")));

IFunction lambdaFunction;
App app;


var stack = new Stack(app, "cdk-integ-lambda-bundling");

var integ = new IntegTest(app, "IntegTest", new IntegTestProps {
    TestCases = new [] { stack }
});

var invoke = integ.Assertions.InvokeFunction(new LambdaInvokeFunctionProps {
    FunctionName = lambdaFunction.FunctionName
});
invoke.Expect(ExpectedResult.ObjectLike(new Dictionary<string, object> {
    { "Payload", "200" }
}));

var lambdaFunction IFunction
var app App


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

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

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

The above example will by default create a CloudWatch log group that's never expired. If you want to configure it with custom log retention days, you need to specify the logRetention property.

import * as logs from 'aws-cdk-lib/aws-logs';

declare const lambdaFunction: lambda.IFunction;
declare const app: App;

const stack = new Stack(app, 'cdk-integ-lambda-bundling');

const integ = new IntegTest(app, 'IntegTest', {
  testCases: [stack],
});

const invoke = integ.assertions.invokeFunction({
  functionName: lambdaFunction.functionName,
  logRetention: logs.RetentionDays.ONE_WEEK,
});

import aws_cdk.aws_logs as logs

# lambda_function: lambda.IFunction
# app: App


stack = Stack(app, "cdk-integ-lambda-bundling")

integ = IntegTest(app, "IntegTest",
    test_cases=[stack]
)

invoke = integ.assertions.invoke_function(
    function_name=lambda_function.function_name,
    log_retention=logs.RetentionDays.ONE_WEEK
)

import software.amazon.awscdk.services.logs.*;

IFunction lambdaFunction;
App app;


Stack stack = new Stack(app, "cdk-integ-lambda-bundling");

IntegTest integ = IntegTest.Builder.create(app, "IntegTest")
        .testCases(List.of(stack))
        .build();

IApiCall invoke = integ.assertions.invokeFunction(LambdaInvokeFunctionProps.builder()
        .functionName(lambdaFunction.getFunctionName())
        .logRetention(RetentionDays.ONE_WEEK)
        .build());

using Amazon.CDK.AWS.Logs;

IFunction lambdaFunction;
App app;


var stack = new Stack(app, "cdk-integ-lambda-bundling");

var integ = new IntegTest(app, "IntegTest", new IntegTestProps {
    TestCases = new [] { stack }
});

var invoke = integ.Assertions.InvokeFunction(new LambdaInvokeFunctionProps {
    FunctionName = lambdaFunction.FunctionName,
    LogRetention = RetentionDays.ONE_WEEK
});

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

var lambdaFunction IFunction
var app App


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

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

invoke := integ.Assertions.InvokeFunction(&LambdaInvokeFunctionProps{
	FunctionName: lambdaFunction.FunctionName,
	LogRetention: logs.RetentionDays_ONE_WEEK,
})

Provider Log Level

By default, the assertion provider lambda function has its log level set to FATAL. If you need to debug assertion failures, you can increase the log level by setting providerLogLevel on the IntegTest construct:

declare const app: App;
declare const stack: Stack;

const integ = new IntegTest(app, 'IntegTest', {
  testCases: [stack],
  providerLogLevel: lambda.ApplicationLogLevel.INFO,
});

# app: App
# stack: Stack


integ = IntegTest(app, "IntegTest",
    test_cases=[stack],
    provider_log_level=lambda_.ApplicationLogLevel.INFO
)

App app;
Stack stack;


IntegTest integ = IntegTest.Builder.create(app, "IntegTest")
        .testCases(List.of(stack))
        .providerLogLevel(ApplicationLogLevel.INFO)
        .build();

App app;
Stack stack;


var integ = new IntegTest(app, "IntegTest", new IntegTestProps {
    TestCases = new [] { stack },
    ProviderLogLevel = ApplicationLogLevel.INFO
});

var app App
var stack Stack


integ := awscdkintegtestsalpha.NewIntegTest(app, jsii.String("IntegTest"), &IntegTestProps{
	TestCases: []Stack{
		stack,
	},
	ProviderLogLevel: lambda.ApplicationLogLevel_INFO,
})

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.

declare const app: App;
declare const stack: Stack;
declare const sm: IStateMachine;

const testCase = new IntegTest(app, 'IntegTest', {
  testCases: [stack],
});

// Start an execution
const start = testCase.assertions.awsApiCall('StepFunctions', 'startExecution', {
  stateMachineArn: sm.stateMachineArn,
});

// describe the results of the execution
const describe = testCase.assertions.awsApiCall('StepFunctions', 'describeExecution', {
  executionArn: start.getAttString('executionArn'),
});

// assert the results
describe.expect(ExpectedResult.objectLike({
  status: 'SUCCEEDED',
}));

# app: App
# stack: Stack
# sm: IStateMachine


test_case = IntegTest(app, "IntegTest",
    test_cases=[stack]
)

# Start an execution
start = test_case.assertions.aws_api_call("StepFunctions", "startExecution", {
    "state_machine_arn": sm.state_machine_arn
})

# describe the results of the execution
describe = test_case.assertions.aws_api_call("StepFunctions", "describeExecution", {
    "execution_arn": start.get_att_string("executionArn")
})

# assert the results
describe.expect(ExpectedResult.object_like({
    "status": "SUCCEEDED"
}))

App app;
Stack stack;
IStateMachine sm;


IntegTest testCase = IntegTest.Builder.create(app, "IntegTest")
        .testCases(List.of(stack))
        .build();

// Start an execution
IApiCall start = testCase.assertions.awsApiCall("StepFunctions", "startExecution", Map.of(
        "stateMachineArn", sm.getStateMachineArn()));

// describe the results of the execution
IApiCall describe = testCase.assertions.awsApiCall("StepFunctions", "describeExecution", Map.of(
        "executionArn", start.getAttString("executionArn")));

// assert the results
describe.expect(ExpectedResult.objectLike(Map.of(
        "status", "SUCCEEDED")));

App app;
Stack stack;
IStateMachine sm;


var testCase = new IntegTest(app, "IntegTest", new IntegTestProps {
    TestCases = new [] { stack }
});

// Start an execution
var start = testCase.Assertions.AwsApiCall("StepFunctions", "startExecution", new Dictionary<string, string> {
    { "stateMachineArn", sm.StateMachineArn }
});

// describe the results of the execution
var describe = testCase.Assertions.AwsApiCall("StepFunctions", "describeExecution", new Dictionary<string, string> {
    { "executionArn", start.GetAttString("executionArn") }
});

// assert the results
describe.Expect(ExpectedResult.ObjectLike(new Dictionary<string, object> {
    { "status", "SUCCEEDED" }
}));

var app App
var stack Stack
var sm IStateMachine


testCase := awscdkintegtestsalpha.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(awscdkintegtestsalpha.ExpectedResult_ObjectLike(map[string]interface{}{
	"status": jsii.String("SUCCEEDED"),
}))

Chain ApiCalls

Sometimes it may be necessary to chain API Calls. Since each API call is its own resource, all you need to do is add a dependency between the calls. There is an helper method next that can be used.

declare const integ: IntegTest;

integ.assertions.awsApiCall('S3', 'putObject', {
  Bucket: 'amzn-s3-demo-bucket',
  Key: 'my-key',
  Body: 'helloWorld',
}).next(integ.assertions.awsApiCall('S3', 'getObject', {
  Bucket: 'amzn-s3-demo-bucket',
  Key: 'my-key',
}));

# integ: IntegTest


integ.assertions.aws_api_call("S3", "putObject", {
    "Bucket": "amzn-s3-demo-bucket",
    "Key": "my-key",
    "Body": "helloWorld"
}).next(integ.assertions.aws_api_call("S3", "getObject", {
    "Bucket": "amzn-s3-demo-bucket",
    "Key": "my-key"
}))

IntegTest integ;


integ.assertions.awsApiCall("S3", "putObject", Map.of(
        "Bucket", "amzn-s3-demo-bucket",
        "Key", "my-key",
        "Body", "helloWorld")).next(integ.assertions.awsApiCall("S3", "getObject", Map.of(
        "Bucket", "amzn-s3-demo-bucket",
        "Key", "my-key")));

IntegTest integ;


integ.Assertions.AwsApiCall("S3", "putObject", new Dictionary<string, string> {
    { "Bucket", "amzn-s3-demo-bucket" },
    { "Key", "my-key" },
    { "Body", "helloWorld" }
}).Next(integ.Assertions.AwsApiCall("S3", "getObject", new Dictionary<string, string> {
    { "Bucket", "amzn-s3-demo-bucket" },
    { "Key", "my-key" }
}));

var integ IntegTest


integ.Assertions.AwsApiCall(jsii.String("S3"), jsii.String("putObject"), map[string]*string{
	"Bucket": jsii.String("amzn-s3-demo-bucket"),
	"Key": jsii.String("my-key"),
	"Body": jsii.String("helloWorld"),
}).Next(integ.Assertions.AwsApiCall(jsii.String("S3"), jsii.String("getObject"), map[string]*string{
	"Bucket": jsii.String("amzn-s3-demo-bucket"),
	"Key": jsii.String("my-key"),
}))

Wait for results

A common use case when performing assertions is to wait for a condition to pass. Sometimes the thing that you are asserting against is not done provisioning by the time the assertion runs. In these cases it is possible to run the assertion asynchronously by calling the waitForAssertions() method.

Taking the example above of executing a StepFunctions state machine, depending on the complexity of the state machine, it might take a while for it to complete.

declare const app: App;
declare const stack: Stack;
declare const sm: IStateMachine;

const testCase = new IntegTest(app, 'IntegTest', {
  testCases: [stack],
});

// Start an execution
const start = testCase.assertions.awsApiCall('StepFunctions', 'startExecution', {
  stateMachineArn: sm.stateMachineArn,
});

// describe the results of the execution
const describe = testCase.assertions.awsApiCall('StepFunctions', 'describeExecution', {
  executionArn: start.getAttString('executionArn'),
}).expect(ExpectedResult.objectLike({
  status: 'SUCCEEDED',
})).waitForAssertions();

# app: App
# stack: Stack
# sm: IStateMachine


test_case = IntegTest(app, "IntegTest",
    test_cases=[stack]
)

# Start an execution
start = test_case.assertions.aws_api_call("StepFunctions", "startExecution", {
    "state_machine_arn": sm.state_machine_arn
})

# describe the results of the execution
describe = test_case.assertions.aws_api_call("StepFunctions", "describeExecution", {
    "execution_arn": start.get_att_string("executionArn")
}).expect(ExpectedResult.object_like({
    "status": "SUCCEEDED"
})).wait_for_assertions()

App app;
Stack stack;
IStateMachine sm;


IntegTest testCase = IntegTest.Builder.create(app, "IntegTest")
        .testCases(List.of(stack))
        .build();

// Start an execution
IApiCall start = testCase.assertions.awsApiCall("StepFunctions", "startExecution", Map.of(
        "stateMachineArn", sm.getStateMachineArn()));

// describe the results of the execution
IApiCall describe = testCase.assertions.awsApiCall("StepFunctions", "describeExecution", Map.of(
        "executionArn", start.getAttString("executionArn"))).expect(ExpectedResult.objectLike(Map.of(
        "status", "SUCCEEDED"))).waitForAssertions();

App app;
Stack stack;
IStateMachine sm;


var testCase = new IntegTest(app, "IntegTest", new IntegTestProps {
    TestCases = new [] { stack }
});

// Start an execution
var start = testCase.Assertions.AwsApiCall("StepFunctions", "startExecution", new Dictionary<string, string> {
    { "stateMachineArn", sm.StateMachineArn }
});

// describe the results of the execution
var describe = testCase.Assertions.AwsApiCall("StepFunctions", "describeExecution", new Dictionary<string, string> {
    { "executionArn", start.GetAttString("executionArn") }
}).Expect(ExpectedResult.ObjectLike(new Dictionary<string, object> {
    { "status", "SUCCEEDED" }
})).WaitForAssertions();

var app App
var stack Stack
var sm IStateMachine


testCase := awscdkintegtestsalpha.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")),
}).Expect(awscdkintegtestsalpha.ExpectedResult_ObjectLike(map[string]interface{}{
	"status": jsii.String("SUCCEEDED"),
})).WaitForAssertions()

When you call waitForAssertions() the assertion provider will continuously make the awsApiCall until the ExpectedResult is met. You can also control the parameters for waiting, for example:

declare const testCase: IntegTest;
declare const start: IApiCall;

const describe = testCase.assertions.awsApiCall('StepFunctions', 'describeExecution', {
  executionArn: start.getAttString('executionArn'),
}).expect(ExpectedResult.objectLike({
  status: 'SUCCEEDED',
})).waitForAssertions({
  totalTimeout: Duration.minutes(5),
  interval: Duration.seconds(15),
  backoffRate: 3,
});

# test_case: IntegTest
# start: IApiCall


describe = test_case.assertions.aws_api_call("StepFunctions", "describeExecution", {
    "execution_arn": start.get_att_string("executionArn")
}).expect(ExpectedResult.object_like({
    "status": "SUCCEEDED"
})).wait_for_assertions(
    total_timeout=Duration.minutes(5),
    interval=Duration.seconds(15),
    backoff_rate=3
)

IntegTest testCase;
IApiCall start;


IApiCall describe = testCase.assertions.awsApiCall("StepFunctions", "describeExecution", Map.of(
        "executionArn", start.getAttString("executionArn"))).expect(ExpectedResult.objectLike(Map.of(
        "status", "SUCCEEDED"))).waitForAssertions(WaiterStateMachineOptions.builder()
        .totalTimeout(Duration.minutes(5))
        .interval(Duration.seconds(15))
        .backoffRate(3)
        .build());

IntegTest testCase;
IApiCall start;


var describe = testCase.Assertions.AwsApiCall("StepFunctions", "describeExecution", new Dictionary<string, string> {
    { "executionArn", start.GetAttString("executionArn") }
}).Expect(ExpectedResult.ObjectLike(new Dictionary<string, object> {
    { "status", "SUCCEEDED" }
})).WaitForAssertions(new WaiterStateMachineOptions {
    TotalTimeout = Duration.Minutes(5),
    Interval = Duration.Seconds(15),
    BackoffRate = 3
});

var testCase IntegTest
var start IApiCall


describe := testCase.Assertions.AwsApiCall(jsii.String("StepFunctions"), jsii.String("describeExecution"), map[string]*string{
	"executionArn": start.getAttString(jsii.String("executionArn")),
}).Expect(awscdkintegtestsalpha.ExpectedResult_ObjectLike(map[string]interface{}{
	"status": jsii.String("SUCCEEDED"),
})).WaitForAssertions(&WaiterStateMachineOptions{
	TotalTimeout: awscdk.Duration_Minutes(jsii.Number(5)),
	Interval: awscdk.Duration_Seconds(jsii.Number(15)),
	BackoffRate: jsii.Number(3),
})

Types

Name	Kind	Summary
ActualResult	Class	Represents the "actual" results to compare.
ApiCallBase	Construct	Base class for an ApiCall.
AssertionRequest	Struct	A request to make an assertion that the actual value matches the expected.
AssertionResult	Struct	The result of an Assertion wrapping the actual result data in another struct.
AssertionResultData	Struct	The result of an assertion.
AssertionsProvider	Construct	Represents an assertions provider.
AssertionsProviderProps	Struct	Properties for defining an AssertionsProvider.
AssertionType	Enum	The type of assertion to perform.
AwsApiCall	Construct	Construct that creates a custom resource that will perform a query using the AWS SDK.
AwsApiCallOptions	Struct	Options to perform an AWS JavaScript V2 API call.
AwsApiCallProps	Struct	Construct that creates a custom resource that will perform a query using the AWS SDK.
AwsApiCallRequest	Struct	A AWS JavaScript SDK V2 request.
AwsApiCallResult	Struct	The result from a SdkQuery.
EqualsAssertion	Construct	Construct that creates a CustomResource to assert that two values are equal.
EqualsAssertionProps	Struct	Options for an EqualsAssertion.
ExpectedResult	Class	Represents the "expected" results to compare.
FetchOptions	Struct	Options to pass to the JavaScript fetch api.
HttpApiCall	Construct	Construct that creates a custom resource that will perform an HTTP API Call.
HttpCallProps	Struct	Options for creating an HttpApiCall provider.
HttpRequest	Struct	Request to the HttpCall resource.
HttpRequestParameters	Struct
HttpResponse	Struct	Response from fetch.
HttpResponseWrapper	Struct	Response from the HttpCall resource.
IApiCall	Interface	Represents an ApiCall.
IDeployAssert	Interface	Interface that allows for registering a list of assertions that should be performed on a construct.
IntegTest	Construct	A collection of test cases.
IntegTestCase	Construct	An integration test case. Allows the definition of test properties that apply to all stacks under this case.
IntegTestCaseProps	Struct	Properties of an integration test case.
IntegTestCaseStack	Construct	An integration test case stack. Allows the definition of test properties that should apply to this stack.
IntegTestCaseStackProps	Struct	Properties of an integration test case stack.
IntegTestProps	Struct	Integration test properties.
InvocationType	Enum	The type of invocation.
LambdaFunctionProviderProps	Struct	Properties for a lambda function provider.
LambdaInvokeFunction	Construct	An AWS Lambda Invoke function API call.
LambdaInvokeFunctionProps	Struct	Options to pass to the Lambda invokeFunction API call.
LogType	Enum	Set to Tail to include the execution log in the response.
Match	Class	Partial and special matching during assertions.
ProviderOptions	Struct	Shared options for configuring the assertion provider lambda function.
Status	Enum	The status of the assertion.
WaiterStateMachine	Construct	A very simple StateMachine construct highly customized to the provider framework.
WaiterStateMachineOptions	Struct	Options for creating a WaiterStateMachine.
WaiterStateMachineProps	Struct	Props for creating a WaiterStateMachine.