jest-e2e-serverless

jest-e2e-serverless

Note: This library is still at POC level, if you're missing any capability please open an issue :)

Prerequisites

You should have your aws credentials under ~/.aws/credentials (if you have aws cli installed and configured).

Note: aws credentials are loaded automatically as described here

If you plan to use the deploy utility function please install and configure serverless.

node >= 8 (for async/await support).

Installation

Install with yarn

yarn add jest-e2e-serverless --dev

or npm

npm install jest-e2e-serverless --save-dev

Setup

The simplest setup is to use jest's setupTestFrameworkScriptFile config.

Make sure your package.json includes the following:

// package.json
"jest": {
  "setupTestFrameworkScriptFile": "./node_modules/jest-e2e-serverless/lib/index.js",
},

Usage with TypeScript

When using jest-e2e-serverless with TypeScript and ts-jest, you'll need to add a setupFrameworks.ts file to your app that explicitly imports jest-e2e-serverless, and point the setupTestFrameworkScriptFile field in your package.json file towards it:

// src/setupFrameworks.ts
import 'jest-e2e-serverless';

// package.json
"jest": {
 "setupTestFrameworkScriptFile": "./src/setupFrameworks.ts",
},

Assertions

Notes

• The matchers use aws-sdk under the hood, thus they are all asynchronous and require using async/await

• toHaveItem()
• toHaveObject()
• toHaveLog()
• toBeAtState()
• toHaveState()
• toReturnResponse()
• toHaveRecord()
• toHaveMessage()

toHaveItem()

Asserts existence/equality of a DynamoDb item

expect.assertions(1); // makes sure the assertion was called
await expect({
  region: 'us-east-1',
  table: 'dynamo-db-table',
  timeout: 0 /* optional (defaults to 2500) */,
  pollEvery: 0 /* optional (defaults to 500) */,
}).toHaveItem(
  {
    id: 'itemId',
  } /* dynamoDb key object (https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/DynamoDB.html#getItem-property) */,
  {
    id: 'itemId',
    createdAt: new Date().getTime(),
    text: 'some content',
  } /* optional, if exists will check equality in addition to existence */,
  true /* optional, strict mode comparison, defaults to true */,
);

See complete example

toHaveObject()

Asserts existence/equality of a S3 object

expect.assertions(1); // makes sure the assertion was called
await expect({
  region: 'us-east-1',
  bucket: 's3-bucket',
  timeout: 0 /* optional (defaults to 2500) */,
  pollEvery: 0 /* optional (defaults to 500) */,
}).toHaveObject(
  'someFileInTheBucket' /* a string representing the object key in the bucket */,
  Buffer.from(
    'a buffer of the file content',
  ) /* optional, if exists will check equality in addition to existence */,
);

See complete example

toHaveLog()

Asserts log message of a lambda function

expect.assertions(1); // makes sure the assertion was called
await expect({
  region: 'us-east-1',
  function: 'functionName',
  timeout: 0 /* optional (defaults to 2500) */,
  pollEvery: 0 /* optional (defaults to 500) */,
}).toHaveLog(
  'some message written to log by the lambda' /* a pattern to match against log messages */,
);

See complete example

toBeAtState()

Asserts a state machine current state

expect.assertions(1); // makes sure the assertion was called
await expect({
  pollEvery: 5000 /* optional (defaults to 500) */,
  region: 'us-east-1',
  stateMachineArn: 'stateMachineArn',
  timeout: 30 * 1000 /* optional (defaults to 2500) */,
}).toBeAtState('ExpectedState');

See complete example

toHaveState()

Asserts that a state machine has been at a state

expect.assertions(1); // makes sure the assertion was called
await expect({
  pollEvery: 5000 /* optional (defaults to 500) */,
  region: 'us-east-1',
  stateMachineArn: 'stateMachineArn',
  timeout: 30 * 1000 /* optional (defaults to 2500) */,
}).toHaveState('ExpectedState');

See complete example

toReturnResponse()

Asserts that an api returns a specific response

expect.assertions(1); // makes sure the assertion was called
await expect({
  url: 'https://api-id.execute-api.us-east-1.amazonaws.com/dev/api/private',
  method: 'POST',
  params: { urlParam: 'value' } /* optional URL parameters */,
  data: { bodyParam: 'value' } /* optional body parameters */,
  headers: { Authorization: 'Bearer token_value' } /* optional headers */,
}).toReturnResponse({
  data: {
    message: 'Unauthorized',
  },
  statusCode: 401,
});

See complete example

toHaveRecord()

Asserts existence/equality of a Kinesis record

expect.assertions(1); // makes sure the assertion was called
await expect({
  region: 'us-east-1',
  stream: 'kinesis-stream',
  timeout: 0 /* optional (defaults to 10000) */,
  pollEvery: 0 /* optional (defaults to 500) */,
}).toHaveRecord(
  item => item.id === 'someId' /* predicate to match with the stream data */,
);

See complete example

toHaveMessage()

Asserts existence/equality of a message in an SQS queue

const {
  subscribeToTopic,
  unsubscribeFromTopic,
} = require('jest-e2e-serverless/lib/utils/sqs');

let [subscriptionArn, queueUrl] = ['', ''];
try {
  // create an SQS queue and subscribe to SNS topic
  ({ subscriptionArn, queueUrl } = await subscribeToTopic(region, topicArn));

  // run some code that will publish a message to the SNS topic
  someCodeThatResultsInPublishingAMessage();

  expect.assertions(1); // makes sure the assertion was called
  await expect({
    region,
    queueUrl,
    timeout: 10000 /* optional (defaults to 2500) */,
    pollEvery: 2500 /* optional (defaults to 500) */,
  }).toHaveMessage(
    /* predicate to match with the messages in the queue */
    message =>
      message.Subject === 'Some Subject' && message.Message === 'Some Message',
  );
} finally {
  // unsubscribe from SNS topic and delete SQS queue
  await unsubscribeFromTopic(region, subscriptionArn, queueUrl);
}

See complete example

Utils

• invoke()
• clearAllItems()
• writeItems()
• clearAllObjects()
• deleteAllLogs()
• stopRunningExecutions()
• getResponse()
• deploy()

invoke()

Invokes a lambda function

const { invoke } = require('jest-e2e-serverless/lib/utils/lambda');

const result = await invoke(
  'us-east-1',
  'functionName',
  {
    body: JSON.stringify({ text: 'from e2e test' }),
  } /* optional: payload for the lambda */,
);

clearAllItems()

Clear all items in a DynamoDb table

const { clearAllItems } = require('jest-e2e-serverless/lib/utils/dynamoDb');

await clearAllItems('us-east-1', 'dynamo-db-table');

writeItems()

Write items to a DynamoDb table

const { writeItems } = require('jest-e2e-serverless/lib/utils/dynamoDb');

const items = require('./seed.json');

await writeItems('us-east-1', 'dynamo-db-table', items);

clearAllObjects()

Clear all objects in a s3 bucket

const { clearAllObjects } = require('jest-e2e-serverless/lib/utils/s3');

await clearAllObjects(
  'us-east-1',
  's3-bucket',
  'key-prefix' /* optional, only delete objects with keys that begin with the specified prefix*/,
);

deleteAllLogs()

Clear all log streams for a lambda function

const { deleteAllLogs } = require('jest-e2e-serverless/lib/utils/cloudwatch');

await deleteAllLogs('us-east-1', 'lambda-function-name');

stopRunningExecutions()

Stop all running executions for a state machine

const {
  stopRunningExecutions,
} = require('jest-e2e-serverless/lib/utils/stepFunctions');

await stopRunningExecutions('us-east-1', 'state-machine-arn');

getResponse()

Send a request to an api and get a response

const { getResponse } = require('jest-e2e-serverless/lib/utils/api');

const result = await getResponse(
  url: 'https://api-id.execute-api.us-east-1.amazonaws.com/dev/api/private',
  method: 'POST',
  params: { urlParam: 'value' } /* optional URL parameters */,
  data: { bodyParam: 'value' } /* optional body parameters */,
  headers: { Authorization: 'Bearer token_value' } /* optional headers */,
);

deploy()

Deploys the current service using Serverless framework

const { deploy } = require('jest-e2e-serverless/lib/utils/serverless');

await deploy('dev' /* optional - deployment stage */);