{"id":15530,"library":"aws-sdk-client-mock-vitest","title":"AWS SDK Client Mock Vitest Matchers","description":"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.","status":"active","version":"7.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/stschulte/aws-sdk-client-mock-vitest","tags":["javascript","typescript"],"install":[{"cmd":"npm install aws-sdk-client-mock-vitest","lang":"bash","label":"npm"},{"cmd":"yarn add aws-sdk-client-mock-vitest","lang":"bash","label":"yarn"},{"cmd":"pnpm add aws-sdk-client-mock-vitest","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides shared type definitions for AWS SDK v3, crucial for type-safe mocking and assertions.","package":"@smithy/types","optional":false},{"reason":"The core library for creating mock AWS SDK v3 clients, which this package extends with custom matchers.","package":"aws-sdk-client-mock","optional":false},{"reason":"The JavaScript testing framework that this package integrates with, providing the `expect` API for custom matchers.","package":"vitest","optional":false}],"imports":[{"note":"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`.","wrong":"import { extend } from 'aws-sdk-client-mock-vitest/extend';","symbol":"Automatic Vitest extension","correct":"import \"aws-sdk-client-mock-vitest/extend\";"},{"note":"Used for manual `expect.extend` calls, allowing explicit registration of all custom matchers, typically within a Vitest `setupFile`.","wrong":"import allCustomMatcher from 'aws-sdk-client-mock-vitest';","symbol":"allCustomMatcher","correct":"import { allCustomMatcher } from \"aws-sdk-client-mock-vitest\";"},{"note":"To extend `expect` with specific matchers only, import them individually. This pattern is useful for fine-grained control over the testing environment.","wrong":"import toHaveReceivedCommand from 'aws-sdk-client-mock-vitest';","symbol":"toHaveReceivedCommand","correct":"import { toHaveReceivedCommand } from \"aws-sdk-client-mock-vitest\";"}],"quickstart":{"code":"import { defineConfig } from \"vitest/config\";\nimport { S3Client, GetObjectCommand } from \"@aws-sdk/client-s3\";\nimport { mockClient } from \"aws-sdk-client-mock\";\n\n// vite.config.ts\nexport default defineConfig({\n  test: {\n    setupFiles: [\"./tests/setup.ts\"],\n  },\n});\n\n// tests/setup.ts\nimport \"aws-sdk-client-mock-vitest/extend\";\n\n// tests/s3.test.ts\ndescribe(\"S3 Service\", () => {\n  let s3Mock;\n\n  beforeEach(() => {\n    s3Mock = mockClient(S3Client);\n  });\n\n  afterEach(() => {\n    s3Mock.reset();\n  });\n\n  it(\"should call GetObjectCommand exactly once with correct parameters\", async () => {\n    s3Mock.on(GetObjectCommand).resolves({ Body: \"mocked-content\" });\n\n    const client = new S3Client({});\n    await client.send(new GetObjectCommand({\n      Bucket: \"my-bucket\",\n      Key: \"test-key.txt\",\n    }));\n\n    expect(s3Mock).toHaveReceivedCommandExactlyOnceWith(GetObjectCommand, {\n      Bucket: \"my-bucket\",\n      Key: \"test-key.txt\",\n    });\n  });\n});","lang":"typescript","description":"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`."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=7.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=5.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<6.1.1"},{"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);`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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)`.","cause":"The Vitest `expect` object has not been extended with the custom matchers, usually because the `setupFiles` configuration is missing or incorrect.","error":"TypeError: expect(...).toHaveReceivedCommand is not a function"},{"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.","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.","error":"Error: Vitest encountered an unexpected error... (related to Node.js version or unsupported environment)"},{"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`.","cause":"One of the package's peer dependencies (`aws-sdk-client-mock` or `@smithy/types`) is not installed or its version is incompatible.","error":"Error: Cannot find module 'aws-sdk-client-mock' or '@smithy/types'"}],"ecosystem":"npm"}