vitest-localstack

🥾 A simple way to do testing AWS Services using Vitest

Install

Install via yarn or npm

$ yarn add -D @thadeu/vitest-localstack

or

$ npm i -D @thadeu/vitest-localstack

or directly via Github

$ npm i -D thadeu/vitest-localstack

Dependencies

• Docker
• LocalStack Image
• NodeJS >= 12.x

Configuration

In your vite.config.ts, adding into test object, a globalSetup using vite.setup.ts

import { defineConfig } from 'vitest/config'

export default ({ mode }) => {
  return defineConfig({
    test: {
      globalSetup: ['./vite.setup.ts'],
    },
  })
}

Create or update your vite.setup.ts

import localStackSetup from '@thadeu/vitest-localstack/setup'
import localStackTeardown from '@thadeu/vitest-localstack/teardown'

export async function setup() {
  await localStackSetup()
}

export async function teardown() {
  await localStackTeardown()
}

Create or update your localstack.config.js file with your required services, for example.

module.exports = {
  // https://docs.localstack.cloud/aws/feature-coverage/
  services: ['dynamodb', 'kinesis', 's3'],
  showLog: JSON.parse(process.env.LOCALSTACK_DEBUG || false),
  autoPullImage: true,
  DynamoDB: [
    {
      TableName: `users_test`,
      BillingMode: 'PAY_PER_REQUEST',
      KeySchema: [
        { AttributeName: 'pk', KeyType: 'HASH' },
        { AttributeName: 'sk', KeyType: 'RANGE' },
      ],
      AttributeDefinitions: [
        { AttributeName: 'pk', AttributeType: 'S' },
        { AttributeName: 'sk', AttributeType: 'S' },
      ],
    },
  ],
}

| Key | Value | Description | | ------------- | -------- | -------------------------------------------------- | | readyTimeout | boolean | Define timeout in milliseconds to create container | | autoPullImage | boolean | Define if we go to download image automatically | | showLog | boolean | Define show logs for localstack | | services | [string] | List of AWS Services | | image | string | LocalStack image/tag (default localstack/localstack) | | authToken | string | LocalStack Auth Token (see below) |

You can define environment VITEST_LOCALSTACK_AUTO_PULLING to precede autoPullImage configuration in your CI/CD

Auth Token (required since 2026-03-23)

Since March 23, 2026 LocalStack ships as a single image and localstack/localstack:latest requires an Auth Token at runtime — even for the Free plan and in CI. The image pull itself stays public; the token only activates the container.

Provide it via the LOCALSTACK_AUTH_TOKEN environment variable (recommended for CI — keep it in a secret), or via the authToken key in localstack.config.js. The env var takes precedence.

module.exports = {
  services: ['dynamodb', 's3'],
  authToken: process.env.LOCALSTACK_AUTH_TOKEN,
}

If you'd rather not use a token, pin the last community image (4.4.0, the final release before the auth requirement) instead — no token or account needed:

module.exports = {
  image: 'localstack/localstack:4.4.0',
  services: ['dynamodb', 's3'],
}

The image can also be set per-run with the LOCALSTACK_IMAGE environment variable, which takes precedence over the image config key (handy to override the pin in CI without editing config).

Usage

When you use configureMockSDK function, we configure many things to you transparently. This means that you going to use aws-sdk normally, without change.

We will apply yhis

{
  accessKeyId: 'access-key',
  secretAccessKey: 'secret-key',
  region: 'us-east-1',
  endpoint: 'http://localhost:4566',
  s3ForcePathStyle: true,
}

But, if you need configure in runtime, enjoy and to do that. Anywhere you can use the endpoint_url to access localstack services locally.

So, use custom endpoint process.env.AWS_ENDPOINT_URL for general or specific to DynamoDB process.env.AWS_DYNAMODB_ENDPOINT_URL in the AWS clients in your code.

For example to use DynamoDB or S3.

import AWS from 'aws-sdk'

const Table = new AWS.DynamoDB.DocumentClient({
  endpoint: process.env.AWS_DYNAMODB_ENDPOINT_URL,
})

So, create your tests and then.

An example for DynamoDB.

import AWS from 'aws-sdk'
import { describe, it, expect } from 'vitest'

import { configureMockSDK } from '@thadeu/vitest-localstack'
configureMockSDK(AWS)

const Table = new AWS.DynamoDB.DocumentClient()

it('should insert item into table', async () => {
  await Table.put({
    TableName: 'users_test',
    Item: { pk: '1', sk: 'vitest-localstack' },
  }).promise()

  const { Count } = await Table.scan({ TableName: 'users_test' }).promise()
  expect(Count).toBe(1)
})

An example for S3

import AWS from 'aws-sdk'
import { describe, it, expect } from 'vitest'

import { configureMockSDK } from '@thadeu/vitest-localstack'
configureMockSDK(AWS)

const s3 = new AWS.S3()

it('must be create a bucket', async () => {
  await s3.createBucket({ Bucket: 'examplebucket' }).promise()

  const { Buckets } = await s3.listBuckets().promise()

  expect(Buckets.length).toBe(1)
  expect(Buckets[0].Name).toBe('examplebucket')
})

Usually you go to use other files, class and functions.

// UserReposity.js
import AWS from 'aws-sdk'
const Table = new AWS.DynamoDB.DocumentClient()

export default class UserReposity {
  static async all(props = {}) {
    return Table.scan({ TableName: 'users', ...props }).promise()
  }

  static async save(props) {
    return Table.put({
      TableName: 'users',
      ...props,
    }).promise()
  }
}

// UserReposity.test.ts
import AWS from 'aws-sdk'
import { describe, it, expect } from 'vitest'

import { configureMockSDK } from '@thadeu/vitest-localstack'
configureMockSDK(AWS)

import UserReposity from './UserReposity'

describe('UserReposity', function () {
  it('should insert item into repository', async () => {
    await UserReposity.save({
      Item: { pk: '1', sk: 'vitest-localstack' },
    })

    const { Count } = await UserReposity.all()
    expect(Count).toBe(1)
  })
})

In this moment, all process will be make using LocalStack.

How Its Works?

Programmatically, we start a docker container with localstack, we run all tests and then, when tests finished, we destroy all containers related

What services work?

Basically, whatever!

For more AWS Service available visit, https://docs.localstack.cloud/aws/feature-coverage/

Debugging

You can enabled debug flag using your custom environment.

| Envs | Type | | ---------------------------- | ------- | | LOCALSTACK_DEBUG | boolean | | VITEST_LOCALSTACK_AUTO_PULLING | boolean | | LOCALSTACK_AUTH_TOKEN | string | | LOCALSTACK_IMAGE | string |

CI (Continuous Integration)

• Github Actions, see .github/workflows/ci

Simple example

name: ci

on: push

jobs:
  test:
    name: test
    runs-on: ubuntu-latest

    services:
      localstack:
        image: localstack/localstack

    defaults:
      run:
        working-directory: ./

    steps:
      - uses: actions/checkout@v2

      - uses: actions/cache@v2
        with:
          path: '**/node_modules'
          key: ${{ runner.os }}-modules-${{ hashFiles('**/yarn.lock') }}
          restore-keys: |
            ${{ runner.os }}-modules-

      - name: Setup NodeJS
        uses: actions/setup-node@v2
        with:
          node-version: 18.17

      - name: Install Yarn Dependencies
        run: yarn install --frozen-lockfile

      - name: Yarn tests
        run: yarn test
        env:
          LOCALSTACK_DEBUG: true
          VITEST_LOCALSTACK_AUTO_PULLING: true

Contributing

Once you've made your great commits (include tests, please):

1. Fork this repository
2. Create a topic branch - git checkout -b my_branch
3. Push to your branch - git push origin my_branch
4. Create a pull request
5. That's it!

Please respect the indentation rules and code style. And use 2 spaces, not tabs. And don't touch the version thing or distribution files; this will be made when a new version is going to be release

License

The Dockerfile and associated scripts and documentation in this project are released under the MIT License.