Aws-cdk-lambda-test-runner NPM

aws-cdk-lambda-test-runner

Install

From TypeScript CDK project run:

npm install aws-cdk-lambda-test-runner

This will install the CDK construct required to deploy TestRunner into your AWS account.

Developing Tests Locally

It is not strictly required to install Jasmine in your CDK project to run integration tests because TestRunner will automatically package and execute tests in the Lambda environment. However, to speed up test development time, you can install Jasmine in your dev dependencies and execute the tests locally.

First install Jasmine and ts-node. ts-node will transpile your test code at runtime, allowing you to write tests in TypeScript without rebuilding before running tests.

npm install --save-dev jasmine @types/jasmine ts-node

Then create a script in your package.json

"scripts": {
    "test:integ": "ts-node node_modules/jasmine/bin/jasmine.js --config=/your-test-folder/support/jasmine.json"
}

For more information on writing tests see: Jasmine: Getting Started

Constructs

TestRunner

Create a suite of unit tests using the Jasmine unit testing framework. Then use the TestRunner construct to deploy them into an AWS Lambda function.

Upon execution the TestRunner Lambda can be configured to publish metrics, write test results into a DynamoDB table, or you can parse the response to determine if the tests passed.

Test execution logs are written into CloudWatch Logs as JSON data using a customized test reporter.

Because tests are executed inside an AWS Lambda function, permissions can be managed through the IAM role assigned to the Function. TestRunner implements IGrantable. This allows it to be use grant functions inside the CDK to grant permission to it directly.

TestRunnerAction

Extends LambdaInvokeAction and integrates the TestRunner with an AWS CodePipeline

Getting Started

To create a TestRunner, initialize the construct. This example creates a Lambda which will be triggered every 30 minutes.

First create a set unit tests. Refer to Jasmine Documentation for a full list of features.

Create a test file like spec-directory/sample.spec.js

describe("A sample test file", () => {
    it("should be able to do addition", () => {
        expect(2 + 2).toBe(4);
    });
})

Then in your CDK stack initialize the TestRunner construct by pointing it to the new directory with test file.

new TestRunner(this, "test-runner", {
    functionName: "MyTestRunner",
    specDir: "spec-directory",
    metricNamespace: "MyCustomMetricNamespace",
    environment: {
        E1: "V1",
        E2: "V2",
    },
    resultsTable: {
        tableName: "MyTestResults",
        dataRetentionDays: 14,
    },
    schedule: events.Schedule.rate(core.Duration.minutes(30)),
    lambdaOptions: {
        logRetention: logs.RetentionDays.TWO_WEEKS,
    },
});

Grant Permissions

TestRunner implements IGrantable. This allows you to grant the TestRunner access to resources in your AWS account by passing it to any resource which accepts an IGrantable

import { Bucket } from "aws-cdk-lib/aws-s3";

var testRunner = new TestRunner(this, ...);

var myBucket = new Bucket(this, "my-resource-bucket")

myBucket.grantReadWrite(testRunner);

Integrating with AWS CodePipeline

TestRunner can be used inside of an AWS CodePipeline to run integration tests during pipeline execution by using the TestRunnerAction construct. The construct can be added to CodePipeline Stage and can detect when it is being run inside CodePipeline

To add TestRunner to an AWS CodePipeline, first create an instance of TestRunner

const integrationTestRunner = new TestRunner(this, "integ-test-runner", { ...props });

Then you can insert it as an action to a CodePipeline stage

const pipeline = new codepipeline.Pipeline(this, "sample-pipeline", { ...pipelineProps });
const integrationTestStage = pipeline.addStage({ ...stageProps });

integrationTestStage.addAction(new TestRunnerAction({
    testRunner: integrationTestRunner,
    lambdaInvokeActionProps: {
        actionName: "RunIntegrationTests"
    }
});

TestRunner Properties

TestRunner Constructor Props

specDir: Path to the directory where tests are stored (e.g. "spec" or "test")
functionName: Custom name to give to the AWS Lambda function created
environment (Optional): Record<string, string> of extra environment properties to pass to the Lambda function environment
resultsTable: TestResultsTableProps object. Allows you to configure the DynamoDB table name and dataRetentionDays for TTL on test results.
lambdaOptions: TestRunnerLambdaOptions object of extra configuration options for your Lambda for settings like Timeout or Memory Size
schedule (Optional): events.Schedule

TestRunner properties

testRunnerTable: TestRunner exposes the DynamoDB created where it stores metrics
testRunnerLambda: TestRunner Lambda CDK construct
functionUrl: TestRunner creates a Lambda function URL to make requests to it directly

TestRunnerAction Constructor Props

testRunner: Instance of TestRunner used to execute tests
lambdaInvokeActionProps: Configure other LambdaInvokeActionProps from underlying LambdaInvoke action