AWS SDK Client Mock Vitest Matchers

Common errors

• TypeError: expect(...).toHaveReceivedCommand is not a function

  cause The Vitest `expect` object has not been extended with the custom matchers, usually because the `setupFiles` configuration is missing or incorrect.
  fix Verify that your `vite.config.ts` includes `setupFiles: ['path/to/your/setup.ts']` under the `test` configuration, and that the specified `setup.ts` file correctly imports `aws-sdk-client-mock-vitest/extend` or calls `expect.extend(allCustomMatcher)`.

• Error: Vitest encountered an unexpected error... (related to Node.js version or unsupported environment)

  cause Using an `aws-sdk-client-mock-vitest` version (especially `v7.0.0` or higher) with an incompatible Node.js version, such as Node.js 18, which is no longer supported by Vitest v4.
  fix Upgrade your Node.js runtime to version 20 or newer. Check the `engines` field in the package.json for compatible Node.js versions and ensure your `vitest` version is also compatible with your Node.js environment.

• Error: Cannot find module 'aws-sdk-client-mock' or '@smithy/types'

  cause One of the package's peer dependencies (`aws-sdk-client-mock` or `@smithy/types`) is not installed or its version is incompatible.
  fix Ensure you have explicitly installed `aws-sdk-client-mock` and `@smithy/types` in your project, e.g., `npm install aws-sdk-client-mock @smithy/types --save-dev`, and that their versions are compatible with your installed `aws-sdk-client-mock-vitest`.

Warnings

• breaking Version `7.0.0` dropped support for Node.js 18. Users upgrading to `aws-sdk-client-mock-vitest@7` must use Node.js 20 or higher, as this aligns with Vitest v4's Node.js support policy.
  Fix: Upgrade your Node.js environment to version 20 or higher. Alternatively, if Node.js 18 is required, stick to `aws-sdk-client-mock-vitest@^6.2.1` and Vitest v3.
• breaking Compatibility with `vitest` is tightly coupled to `aws-sdk-client-mock-vitest` versions. `v7.0.0` supports `vitest@4`, while `v6.2.1` supports `vitest@3`, and `v5.1.0` supports `vitest@2`. Installing an incompatible version combination will lead to runtime errors or incorrect behavior.
  Fix: Ensure your `aws-sdk-client-mock-vitest` version matches your `vitest` version. Refer to the package README or release notes for specific version mapping guidance.
• gotcha Prior to `v5.0.0`, `aws-sdk-client-mock` was a direct dependency, but it became a peer dependency in `v5.0.0`. Similarly, `@smithy/types` became a peer dependency in `v5.1.0`. This means users must explicitly install compatible versions of these peer dependencies.
  Fix: Always install `aws-sdk-client-mock` and `@smithy/types` alongside `aws-sdk-client-mock-vitest`, ensuring their versions are compatible with each other and the AWS SDK v3 client libraries being mocked.
• gotcha The package depends on `@vitest/expect`, and an update in `v6.1.1` specifically addressed an issue to prevent users against `CVE-2025-24964`. Using older versions of `@vitest/expect` or `aws-sdk-client-mock-vitest` that rely on vulnerable `@vitest/expect` versions could expose projects to security risks.
  Fix: Ensure you are using `aws-sdk-client-mock-vitest` version `6.1.1` or newer, or update `@vitest/expect` to `^3.0.5` or later directly if managing dependencies manually.
• gotcha Forgetting to configure Vitest's `setupFiles` option to load the `aws-sdk-client-mock-vitest/extend` module or manually call `expect.extend()` will result in custom matchers not being available.
  Fix: Add `setupFiles: ['./tests/setup.ts']` (or your chosen path) to your `vite.config.ts`'s `test` block, and ensure `tests/setup.ts` contains `import 'aws-sdk-client-mock-vitest/extend';` or `expect.extend(allCustomMatcher);`.

Install

• npm install aws-sdk-client-mock-vitest npm
• yarn add aws-sdk-client-mock-vitest yarn
• pnpm add aws-sdk-client-mock-vitest pnpm

Imports

• Automatic Vitest extension
  wrong:

  import { extend } from 'aws-sdk-client-mock-vitest/extend';

  correct:

  import "aws-sdk-client-mock-vitest/extend";

  This is a side-effect import designed to automatically augment Vitest's `expect` object with all custom matchers. It should typically be placed in a Vitest `setupFile`.
• allCustomMatcher
  wrong:

  import allCustomMatcher from 'aws-sdk-client-mock-vitest';

  correct:

  import { allCustomMatcher } from "aws-sdk-client-mock-vitest";

  Used for manual `expect.extend` calls, allowing explicit registration of all custom matchers, typically within a Vitest `setupFile`.
• toHaveReceivedCommand
  wrong:

  import toHaveReceivedCommand from 'aws-sdk-client-mock-vitest';

  correct:

  import { toHaveReceivedCommand } from "aws-sdk-client-mock-vitest";

  To extend `expect` with specific matchers only, import them individually. This pattern is useful for fine-grained control over the testing environment.

Quickstart

This quickstart demonstrates how to configure Vitest to automatically load the custom matchers and then write a test verifying an S3 `GetObjectCommand` call using `toHaveReceivedCommandExactlyOnceWith`.

import { defineConfig } from "vitest/config";
import { S3Client, GetObjectCommand } from "@aws-sdk/client-s3";
import { mockClient } from "aws-sdk-client-mock";

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

// tests/setup.ts
import "aws-sdk-client-mock-vitest/extend";

// tests/s3.test.ts
describe("S3 Service", () => {
  let s3Mock;

  beforeEach(() => {
    s3Mock = mockClient(S3Client);
  });

  afterEach(() => {
    s3Mock.reset();
  });

  it("should call GetObjectCommand exactly once with correct parameters", async () => {
    s3Mock.on(GetObjectCommand).resolves({ Body: "mocked-content" });

    const client = new S3Client({});
    await client.send(new GetObjectCommand({
      Bucket: "my-bucket",
      Key: "test-key.txt",
    }));

    expect(s3Mock).toHaveReceivedCommandExactlyOnceWith(GetObjectCommand, {
      Bucket: "my-bucket",
      Key: "test-key.txt",
    });
  });
});