jest-dynalite

Enchaned unit testing, with a mock DynamoDB instance

jest-dynalite is a fork of @shelf/jest-dynamodb that allows unit tests to execute real queries against a local DynamoDB instance. It was created in an attempt to address some of the most important missing features of @shelf/jest-dynamodb, such as the fact that it uses a single shared database, which makes it hard to keep tests independent while also potentially causing race conditions because of jest's parallel execution of tests (see this issue for more information).

Why should I use this?

Using this jest-dynalite makes writing queries with dynamodb very easy, your tests can really check if your data is manipulated in the way you expect it to be. This means that queries and mutations can be developed without ever having to deploy or run your application, and significantly speeds up writing code which interacts with dynamodb.

This in turn makes your tests much more robust, because a change to a data structure or db query in your application will be reflected by failing tests, instead of using mocks to check if calls were made correctly.

This library could almost be seen as an integration test, but the lines are very blurred these days and I'd definitely place this within the unit testing boundary because it can easily integrate with unit tests.

Features

• Optionally clear tables between tests
• Isolated tables between test runners
• Ability to specify config directory
• No java requirement

BREAKING CHANGES

From v2.0.0 jest-dynalite now uses a JavaScript file for table configuration. This change makes it possible to set the dynalite config programatically (enabling things such as reading the parameters from a cloudformation template) while also improving compatibility with jest-dynamodb. Thanks to @corollari for this change.

Installation

yarn add jest-dynalite -D

Timeouts

Because jest has a default timeout of 5000ms per test, jest-dynalite can sometimes cause failures due to the timeout being exceeded. This can happen when there are many tests or lots of tables to create between tests. If this happens, try increasing your test timeouts jest.setTimeout(10000). Another option is to selectively run the database only for suites which use it. Please see advanced config.

Config

In your package root, create a jest-dynalite-config.js with the tables schemas, and an optional basePort to run dynalite on:

module.exports = {
  tables: [
    {
      TableName: "table",
      KeySchema: [{ AttributeName: "id", KeyType: "HASH" }],
      AttributeDefinitions: [{ AttributeName: "id", AttributeType: "S" }],
      ProvisionedThroughput: {
        ReadCapacityUnits: 1,
        WriteCapacityUnits: 1
      }
    }
  ],
  basePort: 8000
};

Update your sourcecode

const client = new DocumentClient({
  ...yourConfig,
  ...(process.env.MOCK_DYNAMODB_ENDPOINT && {
    endpoint: process.env.MOCK_DYNAMODB_ENDPOINT,
    sslEnabled: false,
    region: "local"
  })
});

process.env.MOCK_DYNAMODB_ENDPOINT is unqiue to each test runner.

Jest config

Simple usage (preset)

jest.config.js

module.exports = {
  ...
  preset: "jest-dynalite"
}

The simple preset config will use the config and clear tables between tests by default.

This the recommended usage, unless you have custom setupFilesAfterEnv or testEnvironment set.

Monorepo/Advanced setup

When you use jest-dynalite in a monorepo, you must tell it where the config directory is, as that can't be detected.

setupBeforeEnv.js

import { setup } from "jest-dynalite";

// You must give it a config directory
setup(__dirname);

In every test suite where you are using dynamodb, apply import "jest-dynalite/withDb" to the top of the test suites to run the db for that suite.

If you want the tables to exist for all your tests, create a setupAfterEnv.js file with the content:

import "jest-dynalite/withDb";

You then must add the setup files to your jest config

jest.config.js

module.exports = {
  ...
  setupFiles: ["./setupBeforeEnv.js"],
  setupFilesAfterEnv: ["./setupAfterEnv.js"]
}

If you want to use a more advanced setup, you can start the db yourself at any point.

import { startDb, stopDb, createTables, deleteTables } from "jest-dynalite";

beforeAll(startDb);

// Create tables but don't delete them after tests
beforeAll(createTables);

// or
beforeEach(createTables);
afterEach(deleteTables);

afterAll(stopDb);

Other options

setup.js

import "jest-dynalite/dist/setupTables";

// Optional (but recommended)
import "jest-dynalite/dist/clearAfterEach";

jest.config.js

module.exports = {
  ...
  testEnvironment: "jest-dynalite/dist/environment",
  setupFilesAfterEnv: ["./setup.js"]
}

This setup should be used if you want to override the default config of clearAfterEach.

License

MIT