AWS SDK Client Mock Vitest

This module adds custom matchers to verfiy calls to your AWS Client Mock. It was heavily inspired by aws-sdk-client-mock-jest.

Why do you want to use the module

You develop code that makes use of the AWS SDK for JavaScript v3. You are already writing tests for it through the great aws-sdk-client-mock package. You also want to ensure that your actual code performs certain calls against your AWS Client Mocks. While there is aws-sdk-client-mock-jest you prefer vitest.

You can use this module to use expect extensions for vitest to ensure certain commands have been called on your AWS clients.

Install

npm install --save-dev aws-sdk-client-mock-vitest

You must register the new matchers explicity (think about putting this to a setup file). You can either just register the matchers you are interested in, or register all available matchers (the easiest solution).

To register all matchers use the following:

/*
  you may want to put the following into a file tests/setup.ts
  and then specify your vite.config.ts as such

      import { defineConfig } from "vitest/config";

      export default defineConfig({
        test: {
          setupFiles: ["tests/setup.ts"],
        },
      });

  to add the custom matchers before each test run
*/
import { expect } from "vitest";
import { allCustomMatcher } from "aws-sdk-client-mock-vitest";

expect.extend(allCustomMatcher)

You can also register just the matchers you care about:

/*
  you may want to put the following into a file tests/setup.ts
  and then specify your vite.config.ts as such

      import { defineConfig } from "vitest/config";

      export default defineConfig({
        test: {
          setupFiles: ["tests/setup.ts"],
        },
      });

  to add the custom matchers before each test run
*/
import { expect } from "vitest";
import {
  toReceiveCommandTimes,
  toHaveReceivedCommandTimes,
  toReceiveCommandOnce,
  toHaveReceivedCommandOnce,
  toReceiveCommand,
  toHaveReceivedCommand,
  toReceiveCommandWith,
  toHaveReceivedCommandWith,
  toReceiveNthCommandWith,
  toHaveReceivedNthCommandWith,
  toReceiveLastCommandWith,
  toHaveReceivedLastCommandWith,
  toReceiveAnyCommand,
  toHaveReceivedAnyCommand,
  toReceiveCommandExactlyOnceWith,
  toHaveReceivedCommandExactlyOnceWith,
} from "aws-sdk-client-mock-vitest";

expect.extend({
  toReceiveCommandTimes,
  toHaveReceivedCommandTimes,
  toReceiveCommandOnce,
  toHaveReceivedCommandOnce,
  toReceiveCommand,
  toHaveReceivedCommand,
  toReceiveCommandWith,
  toHaveReceivedCommandWith,
  toReceiveNthCommandWith,
  toHaveReceivedNthCommandWith,
  toReceiveLastCommandWith,
  toHaveReceivedLastCommandWith,
  toReceiveAnyCommand,
  toHaveReceivedAnyCommand,
  toReceiveCommandExactlyOnceWith,
  toHaveReceivedCommandExactlyOnceWith,
});

Typescript support

In case you are using typescript, create a vitest.d.ts file with the following content

// tests/vitest.d.ts
import "vitest";
import { CustomMatcher } from "aws-sdk-client-mock-vitest";

declare module "vitest" {
  interface Assertion<T = any> extends CustomMatcher<T> {}
  interface AsymmetricMatchersContaining extends CustomMatcher {}
}

Tip

If you are using eslint in your project you may want to add the following lines at the beginning of your vitest.d.ts file:

/* eslint-disable @typescript-eslint/no-empty-object-type */
/* eslint-disable @typescript-eslint/no-explicit-any */

If you get the following error in your tests

Error: Invalid Chai property: toHaveReceivedCommandWith

Then you probably forgot to run expect.extend with the matcher you are using in your test (see above)

Sample usage

Lets assume you have written a function to read a secret from the AWS Secrets Manager. It may look like this:

// src/main.ts
import {
  SecretsManagerClient,
  GetSecretValueCommand,
} from "@aws-sdk/client-secrets-manager";

export async function readSecret(secretId: string): Promise<string> {
  const client = new SecretsManagerClient({});
  const command = new GetSecretValueCommand({ SecretId: secretId });
  const response = await client.send(command);
  if (response.SecretString) {
    return response.SecretString;
  }
  throw new Error("Unable to read the secret");
}

Naturally we want to test this function to verify it either returns the secret when found or raises an exception otherwise. But we do not want to do actual AWS API calls. We can write a test with vite without doing any network requests thanks to aws-sdk-client-mock. This test may look like this:

// tests/main.test.ts
import { describe, it, expect } from "vitest";
import { mockClient } from "aws-sdk-client-mock";
import {
  GetSecretValueCommand,
  SecretsManagerClient,
} from "@aws-sdk/client-secrets-manager";

import { readSecret } from "../src/main";

const smMock = mockClient(SecretsManagerClient);

describe("readSecret", () => {
  it("should return the secret value", async () => {
    /* Setup our mock. In this test the secret will always be secr3t */
    smMock.on(GetSecretValueCommand).resolves({ SecretString: "secr3t" });

    const result = await readSecret("foo");
    expect(result).toBe("secr3t");

    // We have not verified that we actually interacted with our
    // Secret Manager correcty
  });
});

The test above verifies our readSecret function does indeed return the value of the secret when the API response includes a SecretString. However we have not validated we are actually retrieving the correct secret.

We may want to actually inspect our mock client to verify we sent a specific command. We can do this with our custom expect matcher expect(mockClient).toHaveReceivedCommandWith(...).

To make use of it we are changing our testfile and registering custom matchers

// tests/main.test.ts
import { describe, it, expect } from "vitest";
import { mockClient } from "aws-sdk-client-mock";
import {
  GetSecretValueCommand,
  SecretsManagerClient,
} from "@aws-sdk/client-secrets-manager";

import {
  CustomMatcher,
  toHaveReceivedCommandWith,
} from "aws-sdk-client-mock-vitest";

/* you can also run this in setupTests, see above */
expect.extend({ toHaveReceivedCommandWith });

/* You may want to put this in some vitest.d.ts, see above */
declare module "vitest" {
  interface Assertion<T = any> extends CustomMatcher<T> {}
  interface AsymmetricMatchersContaining extends CustomMatcher {}
}

import { readSecret } from "../src/main";

const smMock = mockClient(SecretsManagerClient);

describe("readSecret", () => {
  it("should read it", async () => {
    smMock.on(GetSecretValueCommand).resolves({ SecretString: "secr3t" });

    const result = await readSecret("foo");
    expect(result).toBe("secr3t");

    /* Ensure we use the inut of the function to fetch the correct secret */
    expect(smMock).toHaveReceivedCommandWith(GetSecretValueCommand, {
      SecretId: "foo",
    });
  });
});

Running test

In order to run tests locally, execute the following

npm ci
npm run test:coverage

If you get an ERR_INSPECTOR_NOT_AVAILABLE error, make sure your nodejs is compiled with inspector support. Otherwise run npm run test to skip code coverage

Thank you

I would like to thank Maciej Radzikowski for the awesome aws-sdk-client-mock and aws-sdk-client-mock-jest packages. These helped a lot testing AWS code and also helped building this library