sls-test-tools provides a range of utilities, setup, teardown and assertions to make it easier to write effective and high quality integration tests for Serverless Architectures on AWS.
🚧 This is in an alpha state while we trial a few initial assertions and get feedback on the approach and structure. 🚧
With npm:
npm install --save-dev sls-test-toolsWith yarn:
yarn add -D sls-test-toolssls-test-tools is currently being actively maintained, yet is in alpha. Your feedback is very welcome.
expect(eventBridgeEvents).toHaveEvent();
expect(eventBridgeEvents).toHaveEventWithSource("order.created");
Note: these async assertions require "await"
await expect("BUCKET NAME").toHaveS3ObjectWithNameEqualTo("FILE NAME");
await expect("BUCKET NAME").toExistAsS3Bucket();
await expect({
bucketName: "BUCKET_NAME",
objectName: "FILE NAME",
}).toHaveContentTypeEqualTo("CONTENT_TYPE");;
where CONTENT_TYPE are standards MIME types
await expect({
bucketName: "BUCKET_NAME",
objectName: "FILE NAME",
}).toHaveContentEqualTo("CONTENT");
Note: these assertions also require "await"
await expect("STATE_MACHINE_NAME").toHaveCompletedExecutionWithStatus("STATUS");
await expect("STATE_MACHINE_NAME").toMatchStateMachineOutput({EXPECTED_OUTPUT}));
Note: these assertions also require "await"
await expect("TABLENAME").toContainItemWithValues({[field]: value});
await expect({PK: pk,
SK: sk,
}).toExistInDynamoTable('TABLENAME');
Note: this assertion also requires "await"
await expect('USER_POOL_ID').toContainUser('USERNAME');
AWSClient - An AWS client with credentials set up
getStackResources(stackName) - get information about a stack
getOptions() - get options for making requests to AWS
An interface to the deployed EventBridge, allowing events to be injected and intercepted via an SQS queue and EventBridge rule.
EventBridge.build(busName) - create a EventBridge instance to allow events to be injected and intercepted
eventBridge.publishEvent(source, detailType, detail, clear?) - publish an event to the bus
eventBridge.getEvents(clear?) - get the events that have been sent to the bus
eventBridge.clear() - clear old messages
eventBridge.destroy() - remove infastructure used to track events
An interface to a deployed Step Function, with a function to execute a Step Function until its completion.
StepFunctions.build() // create a Step Functions Client for executing existing state machines
stepFunctions.runExecution(stateMachineName, input) // executes state machine until completion
await createAuthenticatedUser({
clientId: "CLIENT_ID",
userPoolId: "USER_POOL_ID",
standardAttributes: ["email", "middle_name"], // works for all cognito standard user attributes
customAttributes: [{hello: "string"}], // only works for customAttributes which have been explicitly defined in the user pool schema
});
await createUnauthenticatedUser({
clientId: "CLIENT_ID",
userPoolId: "USER_POOL_ID",
confirmed: true,
standardAttributes: ["email", "middle_name", "address", "birthdate"], // works for all cognito standard user attributes
customAttributes: [{hello: "string"}], // only works for customAttributes which have been explicitly defined in the user pool schema
});
- When running tests with
jestusingsls-test-toolsmatchers there are certain parameters needed forsls-test-toolsto make assertions. - These are passed either as command line arguments, using quotation to match
jestsconvention on test arguments, or by using environment variables. CLI arguments override environment variables.
Required
'--stack=my-service-dev'orprocess.env.CFN_STACK_NAME- the CloudFormation stack name of the stack under test.
Optional
-
'--profile=[PROFILE NAME]'orprocess.env.AWS_PROFILE(will default todefault) -
'--region=[AWS Region]'orprocess.env.AWS_REGION(will default toeu-west-2) -
'--keep=true'orprocess.env.SLS_TEST_TOOLS_KEEP(will default tofalse) - keeps testing resources up to avoid creation throttles (e.g. SQS Queue created for EventBridge assertions) -
'--event-rule-name=[Event Bus Rule Name]'- Custom Event bridge Rule name (will deafult totest-${eventBridgeName}-rule) -
'--queue-name=[SQS Queue Name]'- Custom SQS Queue name (will deafult to${eventBridgeName}-testing-queue) -
To avoid issues we recommend
--runInBand
import { AWSClient, EventBridge } from "sls-test-tools";
const lambda = new AWSClient.Lambda()
let eventBridge;
const s3 = new AWSClient.S3()
describe("Integration Testing Event Bridge", () => {
beforeAll(async () => {
eventBridge = await EventBridge.build("event-bridge")
});
afterAll(async () => {
await eventBridge.destroy()
});
it("correctly publishes an event to the event bus when the lambda is invoked", async () => {
const event = {
body: JSON.stringify({
filename: filename,
}),
};
// Invoke Lambda Function
const params = {
FunctionName: "event-bridge-example-dev-service1",
Payload: JSON.stringify(event),
};
await lambda.invoke(params).promise();
const eventBridgeEvents = await eventBridge.getEvents()
expect(eventBridgeEvents).toHaveEvent();
expect(eventBridgeEvents).toHaveEventWithSource("order.created");
});
it("correctly generates a PDF when an order is created", async () => {
const bucketName = example-bucket
await eventBridge
.publishEvent("order.created", "example", JSON.stringify({ filename: filename }));
await sleep(5000); // wait 5 seconds to allow event to pass
const params = {
Bucket: bucketName,
Key: filename,
};
// Assert that file was added to the S3 bucket
await expect("example-dev-thumbnails-bucket").toHaveS3ObjectWithNameEqualTo(
filename
);
});
Thanks goes to these wonderful people (emoji key):
Ben Ellerby 💻 📖 🤔 🎨 👀 |
Sarah Hamilton 💻 📖 |
Alexander White 💻 |
Joel Hamilton 💻 |
This project follows the all-contributors specification. Contributions of any kind welcome!
sls-test-tools provides a range of utilities, setup, teardown and assertions to make it easier to write effective and high quality integration tests for Serverless Architectures on AWS.
🚧 This is in an alpha state while we trial a few initial assertions and get feedback on the approach and structure. 🚧
With npm:
npm install --save-dev sls-test-toolsWith yarn:
yarn add -D sls-test-toolssls-test-tools is currently being actively maintained, yet is in alpha. Your feedback is very welcome.
expect(eventBridgeEvents).toHaveEvent();
expect(eventBridgeEvents).toHaveEventWithSource("order.created");
Note: these async assertions require "await"
await expect("BUCKET NAME").toHaveS3ObjectWithNameEqualTo("FILE NAME");
await expect("BUCKET NAME").toExistAsS3Bucket();
await expect({
bucketName: "BUCKET_NAME",
objectName: "FILE NAME",
}).toHaveContentTypeEqualTo("CONTENT_TYPE");;
where CONTENT_TYPE are standards MIME types
await expect({
bucketName: "BUCKET_NAME",
objectName: "FILE NAME",
}).toHaveContentEqualTo("CONTENT");
Note: these assertions also require "await"
await expect("STATE_MACHINE_NAME").toHaveCompletedExecutionWithStatus("STATUS");
await expect("STATE_MACHINE_NAME").toMatchStateMachineOutput({EXPECTED_OUTPUT}));
Note: these assertions also require "await"
await expect("TABLENAME").toContainItemWithValues({[field]: value});
await expect({PK: pk,
SK: sk,
}).toExistInDynamoTable('TABLENAME');
Note: this assertion also requires "await"
await expect('USER_POOL_ID').toContainUser('USERNAME');
AWSClient - An AWS client with credentials set up
getStackResources(stackName) - get information about a stack
getOptions() - get options for making requests to AWS
An interface to the deployed EventBridge, allowing events to be injected and intercepted via an SQS queue and EventBridge rule.
EventBridge.build(busName) - create a EventBridge instance to allow events to be injected and intercepted
eventBridge.publishEvent(source, detailType, detail) - publish an event to the bus
eventBridge.getEvents() - get the events that have been sent to the bus
eventBridge.clear() - clear old messages
eventBridge.destroy() - remove infastructure used to track events
An interface to a deployed Step Function, with a function to execute a Step Function until its completion.
StepFunctions.build() // create a Step Functions Client for executing existing state machines
stepFunctions.runExecution(stateMachineName, input) // executes state machine until completion
await createAuthenticatedUser({
clientId: "CLIENT_ID",
userPoolId: "USER_POOL_ID",
standardAttributes: ["email", "middle_name"], // works for all cognito standard user attributes
customAttributes: ["hello"], // only works for customAttributes which have been explicitly defined in the user pool schema
});
await createUnauthenticatedUser({
clientId: "CLIENT_ID",
userPoolId: "USER_POOL_ID",
confirmed: true,
standardAttributes: ["email", "middle_name", "address", "birthdate"], // works for all cognito standard user attributes
});
- When running tests with
jestusingsls-test-toolsmatchers there are certain parameters needed forsls-test-toolsto make assertions. - These are passed either as command line arguments, using quotation to match
jestsconvention on test arguments, or by using environment variables. CLI arguments override environment variables.
Required
'--stack=my-service-dev'orprocess.env.CFN_STACK_NAME- the CloudFormation stack name of the stack under test.
Optional
-
'--profile=[PROFILE NAME]'orprocess.env.AWS_PROFILE(will default todefault) -
'--region=[AWS Region]'orprocess.env.AWS_REGION(will default toeu-west-2) -
'--keep=true'- keeps testing resources up to avoid creation throttles (e.g. SQS Queue created for EventBridge assertions) -
To avoid issues we recommend
--runInBand
import { AWSClient, EventBridge } from "sls-test-tools";
const lambda = new AWSClient.Lambda()
let eventBridge;
const s3 = new AWSClient.S3()
describe("Integration Testing Event Bridge", () => {
beforeAll(async () => {
eventBridge = await EventBridge.build("event-bridge")
});
afterAll(async () => {
await eventBridge.destroy()
});
it("correctly publishes an event to the event bus when the lambda is invoked", async () => {
const event = {
body: JSON.stringify({
filename: filename,
}),
};
// Invoke Lambda Function
const params = {
FunctionName: "event-bridge-example-dev-service1",
Payload: JSON.stringify(event),
};
await lambda.invoke(params).promise();
const eventBridgeEvents = await eventBridge.getEvents()
expect(eventBridgeEvents).toHaveEvent();
expect(eventBridgeEvents).toHaveEventWithSource("order.created");
});
it("correctly generates a PDF when an order is created", async () => {
const bucketName = example-bucket
await eventBridge
.publishEvent("order.created", "example", JSON.stringify({ filename: filename }));
await sleep(5000); // wait 5 seconds to allow event to pass
const params = {
Bucket: bucketName,
Key: filename,
};
// Assert that file was added to the S3 bucket
await expect("example-dev-thumbnails-bucket").toHaveS3ObjectWithNameEqualTo(
filename
);
});
Thanks goes to these wonderful people (emoji key):
Ben Ellerby 💻 🖋 📖 🤔 🎨 📢 👀 |
Sarah Hamilton 💻 🖋 📖 🤔 |
Alex White 💻📖 |
This project follows the all-contributors specification. Contributions of any kind welcome!