Registry / testing / aws-sdk-client-mock-jest

aws-sdk-client-mock-jest

library4.1.0jsnpmunverified

aws-sdk-client-mock-jest provides custom Jest matchers that extend Jest's `expect` API, specifically designed to simplify testing AWS SDK v3 clients when used in conjunction with `aws-sdk-client-mock`. It enables developers to assert on AWS SDK command invocations with readable and intuitive syntax like `toHaveReceivedCommand` or `toHaveReceivedCommandWith`. The package is currently at version 4.1.0 and maintains an active release cadence, with several minor and patch releases in recent months, often including beta cycles. Its key differentiator is the seamless integration into Jest's testing framework, allowing for robust unit and integration tests of AWS Lambda functions, frontend applications, and Node.js services interacting with AWS, without needing to manually inspect mock call arguments. Version 4.1.0 notably introduced support for Vitest, broadening its compatibility within the JavaScript testing ecosystem.

testing aws type-stubs

npm install aws-sdk-client-mock-jest

github ↗package ↗

INSTALL

IMPORT

SIG · AWS-SDK-CLIENT-MOC

aws-sdk-client-mock-jest

testingjavascriptv4.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Matchers

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

✗ import { toHaveReceivedCommand } from '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.

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); }); });

Debug

Known issues

breakingThe 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.

affects: >=4.0.0

gotchaWhen 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.

affects: <4.0.2

gotchaSupport 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.

affects: <4.0.1

gotchaThe 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.

affects: >=4.1.0-beta.0

Errors

Common errors & fixes

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

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

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'.

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.

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`.

Upgrade

Version history

4.1.0latest on npm

Audit

Dependencies

aws-sdk-client-mockrequiredCore mocking library that these Jest matchers extend and integrate with.

vitestoptionalOptional peer dependency for Vitest support, added in v4.1.0-beta.0.

Agent activity

48 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/m-radzikowski/aws-sdk-client-mock ↗

packagehttps://www.npmjs.com/package/aws-sdk-client-mock-jest ↗