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

aws-sdk-client-mock-vitest

library7.0.1jsnpmunverified

This package provides custom Vitest matchers for `aws-sdk-client-mock`, a library used to mock the AWS SDK for JavaScript v3 clients in tests. It enables developers to write expressive assertions about how AWS service commands are called on their mocked clients within a Vitest testing environment. The current stable version is `7.0.1`, with releases often aligned with major Vitest versions. Key differentiators include its tight integration with Vitest's `expect` API, offering a wide range of matchers such as `toHaveReceivedCommand`, `toHaveReceivedCommandWith`, and `toHaveReceivedCommandTimes`. This package fills a crucial gap for Vitest users, providing functionality analogous to `aws-sdk-client-mock-jest` for Jest, allowing for robust verification of AWS SDK interactions in unit and integration tests.

testing aws

npm install aws-sdk-client-mock-vitest

github ↗package ↗

INSTALL

IMPORT

SIG · AWS-SDK-CLIENT-MOC

aws-sdk-client-mock-vitest

testingjavascriptv7.0.1

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.

Automatic Vitest extension

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

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

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

✗ 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

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

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

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

Debug

Known issues

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

affects: >=7.0.0

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

affects: >=3.0.0

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

affects: >=5.0.0

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

affects: <6.1.1

gotchaForgetting 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);`.

affects: >=1.0.0

Errors

Common errors & fixes

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

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)

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'

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

Upgrade

Version history

7.0.1latest on npm

Audit

Dependencies

@smithy/typesrequiredProvides shared type definitions for AWS SDK v3, crucial for type-safe mocking and assertions.

aws-sdk-client-mockrequiredThe core library for creating mock AWS SDK v3 clients, which this package extends with custom matchers.

vitestrequiredThe JavaScript testing framework that this package integrates with, providing the `expect` API for custom matchers.

Agent activity

23 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/stschulte/aws-sdk-client-mock-vitest ↗

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