AWS SDK v3 Client Mock Jest Matchers

Common errors

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

  cause The Jest matchers have not been imported and registered with Jest's `expect` API.
  fix Add `import 'aws-sdk-client-mock-jest';` to your test setup file (e.g., `setupFilesAfterEnv` in Jest configuration) or directly at the top of your test files.

• Matcher error: Received value must be an instance of AwsStub

  cause The `expect()` assertion is being called on an object that is not an `AwsStub` instance returned by `mockClient()`.
  fix Ensure that `expect()` is called with the result of `mockClient(YourClient)` (e.g., `expect(ddbMock)`) not the client instance itself (e.g., `expect(ddbClient)`).

• Command type mismatch. Expected to receive a Command of type 'PutItemCommand', but received 'GetItemCommand'.

  cause The test is asserting that a specific command type was received, but a different command type was actually invoked.
  fix Review your application code to confirm the correct AWS SDK command is being sent, or adjust your test assertion to match the actual command type invoked.

• Expected to receive 'DynamoDBClient.PutItemCommand' with input matching: { TableName: 'WrongTable' } but no matching command was received.

  cause The `toHaveReceivedCommandWith` matcher found the correct command type but no invocation matched the specified input parameters.
  fix Inspect the input arguments passed to your AWS SDK command in the application code and ensure they precisely match (or are a partial match of) the object provided to `toHaveReceivedCommandWith`.

Warnings

• breaking The behavior of `expect.assertions()` was corrected for commands used with `toHaveReceivedCommandWith` matchers. If your tests relied on an incorrect assertion count for these matchers, they might now fail.
  Fix: Review tests using `toHaveReceivedCommandWith` and adjust `expect.assertions()` counts if necessary to reflect the correct number of assertions made by the matcher.
• gotcha When using `toHaveReceivedCommandWith`, partial matching for `Command` inputs was inconsistent in older versions. If you attempted to match only a subset of the command's input fields, it might have failed or behaved unexpectedly.
  Fix: Upgrade to `aws-sdk-client-mock-jest@4.0.2` or higher to ensure robust partial matching of `Command` input objects, allowing you to specify only the relevant fields for assertion.
• gotcha Support for `@jest/globals` asymmetric matchers (e.g., `expect.any(String)`, `expect.objectContaining`) was improved in `v4.0.1`. Using them in `toHaveReceivedCommandWith` with older versions might have led to incorrect matching results.
  Fix: Update to `aws-sdk-client-mock-jest@4.0.1` or newer to correctly utilize `expect.any`, `expect.objectContaining`, and other asymmetric matchers within `toHaveReceivedCommandWith` assertions.
• gotcha The package added `vitest` as an optional peer dependency starting from version 4.1.0-beta.0. While this broadens compatibility, ensure your project's testing setup correctly distinguishes between Jest and Vitest environments if both are present, to avoid potential conflicts or unexpected behavior.
  Fix: Verify that your `package.json` correctly reflects `vitest` as an optional peer dependency if you intend to use it, and that your test runner configuration (`jest.config.js` or `vitest.config.ts`) is set up to handle the matchers appropriately for the chosen framework.

Install

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

Imports

• Matchers
  wrong:

  import { toHaveReceivedCommand } from 'aws-sdk-client-mock-jest';

  correct:

  import 'aws-sdk-client-mock-jest';

  The matchers are registered globally by a side-effect import. No direct symbols are exported for individual matcher functions; they extend Jest's `expect` API.
• Types

  /// <reference types="aws-sdk-client-mock-jest" />

  TypeScript types are included with the package and are usually automatically picked up by your `tsconfig.json`. Explicit reference might be needed in some older configurations or specific environments to ensure `expect` extensions are recognized.
• CommonJS Setup

  require('aws-sdk-client-mock-jest');

  For CommonJS environments, a simple `require` call is sufficient to register the matchers globally.

Quickstart

This example demonstrates how to set up `aws-sdk-client-mock` with Jest matchers to test DynamoDB `PutItemCommand` invocations, asserting on command types, call counts, and input parameters.

import { DynamoDBClient, PutItemCommand } from '@aws-sdk/client-dynamodb';
import { mockClient } from 'aws-sdk-client-mock';
import 'aws-sdk-client-mock-jest'; // Import to enable Jest matchers

describe('DynamoDB interactions', () => {
  let ddbMock: ReturnType<typeof mockClient>;
  const tableName = 'MyTestTable';

  beforeEach(() => {
    ddbMock = mockClient(DynamoDBClient);
  });

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

  it('should put an item into DynamoDB', async () => {
    ddbMock.on(PutItemCommand).resolves({ Attributes: { id: { S: '123' } } });

    const client = new DynamoDBClient({});
    const command = new PutItemCommand({
      TableName: tableName,
      Item: { id: { S: '123' }, name: { S: 'Test Item' } },
    });
    await client.send(command);

    expect(ddbMock).toHaveReceivedCommand(PutItemCommand);
    expect(ddbMock).toHaveReceivedCommandTimes(PutItemCommand, 1);
    expect(ddbMock).toHaveReceivedCommandWith(PutItemCommand, {
      TableName: tableName,
      Item: { id: { S: '123' } }, // Partial match works
    });
    expect(ddbMock).toHaveReceivedAnyCommand();
    expect(ddbMock).toHaveReceivedAnyCommandTimes(1);
  });
});