{"id":15527,"library":"aws-sdk-client-mock-jest","title":"AWS SDK v3 Client Mock Jest Matchers","description":"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.","status":"active","version":"4.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/m-radzikowski/aws-sdk-client-mock","tags":["javascript","aws","aws-sdk","testing","mock","unit-testing","aws-lambda","jest","jest-matchers","typescript"],"install":[{"cmd":"npm install aws-sdk-client-mock-jest","lang":"bash","label":"npm"},{"cmd":"yarn add aws-sdk-client-mock-jest","lang":"bash","label":"yarn"},{"cmd":"pnpm add aws-sdk-client-mock-jest","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core mocking library that these Jest matchers extend and integrate with.","package":"aws-sdk-client-mock","optional":false},{"reason":"Optional peer dependency for Vitest support, added in v4.1.0-beta.0.","package":"vitest","optional":true}],"imports":[{"note":"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.","wrong":"import { toHaveReceivedCommand } from 'aws-sdk-client-mock-jest';","symbol":"Matchers","correct":"import 'aws-sdk-client-mock-jest';"},{"note":"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.","symbol":"Types","correct":"/// <reference types=\"aws-sdk-client-mock-jest\" />"},{"note":"For CommonJS environments, a simple `require` call is sufficient to register the matchers globally.","symbol":"CommonJS Setup","correct":"require('aws-sdk-client-mock-jest');"}],"quickstart":{"code":"import { DynamoDBClient, PutItemCommand } from '@aws-sdk/client-dynamodb';\nimport { mockClient } from 'aws-sdk-client-mock';\nimport 'aws-sdk-client-mock-jest'; // Import to enable Jest matchers\n\ndescribe('DynamoDB interactions', () => {\n  let ddbMock: ReturnType<typeof mockClient>;\n  const tableName = 'MyTestTable';\n\n  beforeEach(() => {\n    ddbMock = mockClient(DynamoDBClient);\n  });\n\n  afterEach(() => {\n    ddbMock.reset();\n  });\n\n  it('should put an item into DynamoDB', async () => {\n    ddbMock.on(PutItemCommand).resolves({ Attributes: { id: { S: '123' } } });\n\n    const client = new DynamoDBClient({});\n    const command = new PutItemCommand({\n      TableName: tableName,\n      Item: { id: { S: '123' }, name: { S: 'Test Item' } },\n    });\n    await client.send(command);\n\n    expect(ddbMock).toHaveReceivedCommand(PutItemCommand);\n    expect(ddbMock).toHaveReceivedCommandTimes(PutItemCommand, 1);\n    expect(ddbMock).toHaveReceivedCommandWith(PutItemCommand, {\n      TableName: tableName,\n      Item: { id: { S: '123' } }, // Partial match works\n    });\n    expect(ddbMock).toHaveReceivedAnyCommand();\n    expect(ddbMock).toHaveReceivedAnyCommandTimes(1);\n  });\n});","lang":"typescript","description":"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."},"warnings":[{"fix":"Review tests using `toHaveReceivedCommandWith` and adjust `expect.assertions()` counts if necessary to reflect the correct number of assertions made by the matcher.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<4.0.2"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<4.0.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=4.1.0-beta.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"The Jest matchers have not been imported and registered with Jest's `expect` API.","error":"TypeError: expect(...).toHaveReceivedCommand is not a function"},{"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)`).","cause":"The `expect()` assertion is being called on an object that is not an `AwsStub` instance returned by `mockClient()`.","error":"Matcher error: Received value must be an instance of AwsStub"},{"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.","cause":"The test is asserting that a specific command type was received, but a different command type was actually invoked.","error":"Command type mismatch. Expected to receive a Command of type 'PutItemCommand', but received 'GetItemCommand'."},{"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`.","cause":"The `toHaveReceivedCommandWith` matcher found the correct command type but no invocation matched the specified input parameters.","error":"Expected to receive 'DynamoDBClient.PutItemCommand' with input matching: { TableName: 'WrongTable' } but no matching command was received."}],"ecosystem":"npm"}