feat: Add spies

packages/aws-sdk-client-mock-jest/src/jestMatchers.ts

@@ -1,7 +1,7 @@
 /* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-empty-interface */
 import assert from 'assert';
 import type {MetadataBearer} from '@smithy/types';
-import type {AwsCommand, AwsStub} from 'aws-sdk-client-mock';
+import type {AwsCommand, AwsStub, AwsSpy} from 'aws-sdk-client-mock';
 import type {SinonSpyCall} from 'sinon';
 
 interface AwsSdkJestMockBaseMatchers<R> extends Record<string, any> {
@@ -147,7 +147,7 @@ interface AwsSdkJestMockAliasMatchers<R> {
  * import { mockClient } from "aws-sdk-client-mock";
  * import { ScanCommand } from "@aws-sdk/client-dynamodb";
  *
- * const awsMock = mockClient(DynamoDBClient);
+ * const awsMock = mockClient(DynamoDBClient); // or `spyClient(DynamoDBClient)`
  *
  * awsMock.on(ScanCommand).resolves({
  *   Items: [{ Info: { S: '{ "val": "info" }' }, LockID: { S: "fooId" } }],
@@ -172,7 +172,7 @@ declare global {
     }
 }
 
-type ClientMock = AwsStub<any, any, any>;
+type ClientMock = AwsStub<any, any, any> | AwsSpy<any, any, any>;
 type AnyCommand = AwsCommand<any, any>;
 type AnySpyCall = SinonSpyCall<[AnyCommand]>;
 type MessageFunctionParams<CheckData> = {
@@ -218,7 +218,7 @@ const processMatch = <CheckData = undefined>({ctx, mockClient, command, check, m
     );
 
     const calls = mockClient.calls();
-    const commandCalls = mockClient.commandCalls(command);
+    const commandCalls = (mockClient as AwsSpy<any, any, any>).commandCalls(command);
 
     const {pass, data} = check({calls, commandCalls});
 

packages/aws-sdk-client-mock/src/awsClientSpy.ts

@@ -0,0 +1,118 @@
+import {Client, MetadataBearer} from '@smithy/types';
+import {match, SinonSpyCall, SinonSpy} from 'sinon';
+import {AwsCommand} from './commonTypes';
+import {spyClient} from './spyClient';
+
+/**
+ * Type for {@link AwsSpy} class,
+ * but with the AWS Client class type as the only generic parameter.
+ *
+ * @example
+ * ```ts
+ * const sns = new SNSCLient({});
+ * let snsSpy: AwsClientSpy<SNSClient>;
+ * snsSpy = spyClient(sns);
+ * ```
+ */
+export type AwsClientSpy<TClient> =
+    TClient extends Client<infer TInput, infer TOutput, infer TConfiguration> ? AwsSpy<TInput, TOutput, TConfiguration> : never;
+
+/**
+ * Wrapper on the mocked `Client#send()` method, allowing you to inspect
+ * calls to it.
+ *
+ * Without any configuration, `Client#send()` invocation returns `undefined`.
+ *
+ * To define resulting variable type easily, use {@link AwsClientSpy}.
+ */
+export class AwsSpy<TInput extends object, TOutput extends MetadataBearer, TConfiguration> {
+
+    /**
+     * Underlying `Client#send()` method Sinon spy.
+     *
+     * Install `@types/sinon` for TypeScript typings.
+     */
+    public send: SinonSpy<[AwsCommand<TInput, TOutput>], Promise<TOutput>>;
+
+    constructor(
+        private client: Client<TInput, TOutput, TConfiguration>,
+        send: SinonSpy<[AwsCommand<TInput, TOutput>], Promise<TOutput>>,
+    ) {
+        this.send = send;
+    }
+
+    /** Returns the class name of the underlying spied client class */
+    clientName(): string {
+        return this.client.constructor.name;
+    }
+
+    /**
+     * Resets spy. It will replace the spy with a new one, with clean history.
+     */
+    reset(): AwsSpy<TInput, TOutput, TConfiguration> {
+        /* sinon.spy.reset() does not remove the fakes which in some conditions can break subsequent spies,
+         * so instead of calling send.reset(), we recreate the spy.
+         * See: https://github.com/sinonjs/sinon/issues/1572
+         * We are only affected by the broken reset() behavior of this bug, since we always use matchers.
+         */
+        const newSpy = spyClient(this.client);
+        this.send = newSpy.send;
+        return this;
+    }
+
+    /** Resets spy's calls history. */
+    resetHistory(): AwsSpy<TInput, TOutput, TConfiguration> {
+        this.send.resetHistory();
+        return this;
+    }
+
+    /** Replaces spy with original `Client#send()` method. */
+    restore(): void {
+        this.send.restore();
+    }
+
+    /**
+     * Returns recorded calls to the spy.
+     * Clear history with {@link resetHistory} or {@link reset}.
+     */
+    calls(): SinonSpyCall<[AwsCommand<TInput, TOutput>], Promise<TOutput>>[] {
+        return this.send.getCalls();
+    }
+
+    /**
+     * Returns n-th recorded call to the spy.
+     */
+    call(n: number): SinonSpyCall<[AwsCommand<TInput, TOutput>], Promise<TOutput>> {
+        return this.send.getCall(n);
+    }
+
+    /**
+     * Returns recorded calls of given Command only.
+     * @param commandType Command type to match
+     * @param input Command payload to match
+     * @param strict Should the payload match strictly (default false, will match if all defined payload properties match)
+     */
+    commandCalls<TCmd extends AwsCommand<any, any>,
+        TCmdInput extends TCmd extends AwsCommand<infer TIn, any> ? TIn : never,
+        TCmdOutput extends TCmd extends AwsCommand<any, infer TOut> ? TOut : never,
+    >(
+        commandType: new (input: TCmdInput) => TCmd,
+        input?: Partial<TCmdInput>,
+        strict?: boolean,
+    ): SinonSpyCall<[TCmd], Promise<TCmdOutput>>[] {
+        return this.send.getCalls()
+            .filter((call): call is SinonSpyCall<[TCmd], Promise<TCmdOutput>> => {
+                const isProperType = call.args[0] instanceof commandType;
+                const inputMatches = this.createInputMatcher(input, strict).test(call.args[0]);
+                return isProperType && inputMatches;
+            });
+    }
+
+    private createInputMatcher<TCmdInput extends TInput>(input?: Partial<TCmdInput>, strict = false) {
+        return input !== undefined ?
+            match.has('input', strict ? input : match(input))
+            : match.any;
+    }
+}
+
+

packages/aws-sdk-client-mock/src/awsClientStub.ts

@@ -1,5 +1,6 @@
-import {Client, Command, MetadataBearer} from '@smithy/types';
+import {Client, MetadataBearer} from '@smithy/types';
 import {match, SinonSpyCall, SinonStub} from 'sinon';
+import { AwsCommand } from './commonTypes';
 import {mockClient} from './mockClient';
 
 export type AwsClientBehavior<TClient> =
@@ -354,7 +355,6 @@ export class CommandBehavior<TInput extends object, TOutput extends MetadataBear
     }
 }
 
-export type AwsCommand<Input extends ClientInput, Output extends ClientOutput, ClientInput extends object = any, ClientOutput extends MetadataBearer = any> = Command<ClientInput, Input, ClientOutput, Output, any>;
 type CommandResponse<TOutput> = Partial<TOutput> | PromiseLike<Partial<TOutput>>;
 
 export interface AwsError extends Partial<Error>, Partial<MetadataBearer> {

packages/aws-sdk-client-mock/src/commonTypes.ts

@@ -0,0 +1,3 @@
+import {Command, MetadataBearer} from '@smithy/types';
+
+export type AwsCommand<Input extends ClientInput, Output extends ClientOutput, ClientInput extends object = any, ClientOutput extends MetadataBearer = any> = Command<ClientInput, Input, ClientOutput, Output, any>;

packages/aws-sdk-client-mock/src/index.ts

@@ -1,2 +1,5 @@
+export * from './commonTypes';
 export * from './mockClient';
 export * from './awsClientStub';
+export * from './spyClient';
+export * from './awsClientSpy';

packages/aws-sdk-client-mock/src/sinon.ts

@@ -1,4 +1,4 @@
-import {SinonStub} from 'sinon';
+import {SinonStub, SinonSpy} from 'sinon';
 
 export interface MaybeSinonProxy {
     isSinonProxy?: boolean;
@@ -7,3 +7,7 @@ export interface MaybeSinonProxy {
 export const isSinonStub = (obj: unknown): obj is SinonStub =>
     ((obj as MaybeSinonProxy).isSinonProxy || false)
     && (obj as SinonStub).restore !== undefined;
+
+export const isSinonSpy = (obj: unknown): obj is SinonSpy =>
+    ((obj as MaybeSinonProxy).isSinonProxy || false)
+    && (obj as SinonSpy).restore !== undefined;

packages/aws-sdk-client-mock/src/spyClient.ts

@@ -0,0 +1,38 @@
+import {Client, Command, MetadataBearer} from '@smithy/types';
+import {SinonSpy, spy} from 'sinon';
+import {isSinonSpy, isSinonStub} from './sinon';
+import {AwsClientSpy, AwsSpy} from './awsClientSpy';
+
+/**
+ * Creates and attaches a spy of the `Client#send()` method. Only this single method is replaced.
+ * If method is already a spy, it's replaced.
+ * @param client `Client` type or instance to replace the method
+ * @return Stub allowing to configure Client's behavior
+ */
+export const spyClient = <TInput extends object, TOutput extends MetadataBearer, TConfiguration>(
+    client: InstanceOrClassType<Client<TInput, TOutput, TConfiguration>>,
+): AwsClientSpy<Client<TInput, TOutput, TConfiguration>> => {
+    const instance = isClientInstance(client) ? client : client.prototype;
+
+    const send = instance.send;
+    if (isSinonSpy(send) || isSinonStub(send)) {
+        send.restore();
+    }
+
+    const sendStub = spy(instance, 'send') as SinonSpy<[Command<TInput, any, TOutput, any, any>], Promise<TOutput>>;
+
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+    return new AwsSpy<TInput, TOutput, TConfiguration>(instance, sendStub);
+};
+
+type ClassType<T> = {
+    prototype: T;
+};
+
+type InstanceOrClassType<T> = T | ClassType<T>;
+
+/**
+ * Type guard to differentiate `Client` instance from a type.
+ */
+const isClientInstance = <TClient extends Client<any, any, any>>(obj: InstanceOrClassType<TClient>): obj is TClient =>
+    (obj as TClient).send !== undefined;