AWS SDK Vitest Mock - API Reference - v1.0.6
    Preparing search index...

    Interface AwsCommandStub<TInput, TOutput, TClient>

    Command stub for configuring mock behaviors for a specific AWS SDK command. Provides a fluent API for setting up various mock responses and behaviors.

    const s3Mock = mockClient(S3Client);
    s3Mock.on(GetObjectCommand).resolves({ Body: 'data' });

    s3Mock.on(PutObjectCommand)
      .resolvesOnce({ ETag: '123' })
      .resolvesOnce({ ETag: '456' })
      .resolves({ ETag: 'default' });
    interface AwsCommandStub<
        TInput extends object,
        TOutput extends MetadataBearer,
        TClient extends AnyClient = AnyClient,
    > {
        resolves: (
            output: DeepPartial<TOutput>,
        ) => AwsCommandStub<TInput, TOutput, TClient>;
        rejects: (
            error: string | Error,
        ) => AwsCommandStub<TInput, TOutput, TClient>;
        callsFake: (
            fn: CommandHandler<TInput, TOutput, TClient>,
        ) => AwsCommandStub<TInput, TOutput, TClient>;
        resolvesOnce: (
            output: DeepPartial<TOutput>,
        ) => AwsCommandStub<TInput, TOutput, TClient>;
        rejectsOnce: (
            error: string | Error,
        ) => AwsCommandStub<TInput, TOutput, TClient>;
        callsFakeOnce: (
            fn: CommandHandler<TInput, TOutput, TClient>,
        ) => AwsCommandStub<TInput, TOutput, TClient>;
        resolvesStream: (
            data: StreamInput,
        ) => AwsCommandStub<TInput, TOutput, TClient>;
        resolvesStreamOnce: (
            data: StreamInput,
        ) => AwsCommandStub<TInput, TOutput, TClient>;
        resolvesWithDelay: (
            output: DeepPartial<TOutput>,
            delayMs: number,
        ) => AwsCommandStub<TInput, TOutput, TClient>;
        rejectsWithDelay: (
            error: string | Error,
            delayMs: number,
        ) => AwsCommandStub<TInput, TOutput, TClient>;
        rejectsWithNoSuchKey: (
            key?: string,
        ) => AwsCommandStub<TInput, TOutput, TClient>;
        rejectsWithNoSuchBucket: (
            bucket?: string,
        ) => AwsCommandStub<TInput, TOutput, TClient>;
        rejectsWithAccessDenied: (
            resource?: string,
        ) => AwsCommandStub<TInput, TOutput, TClient>;
        rejectsWithResourceNotFound: (
            resource?: string,
        ) => AwsCommandStub<TInput, TOutput, TClient>;
        rejectsWithConditionalCheckFailed: () => AwsCommandStub<
            TInput,
            TOutput,
            TClient,
        >;
        rejectsWithThrottling: () => AwsCommandStub<TInput, TOutput, TClient>;
        rejectsWithInternalServerError: () => AwsCommandStub<
            TInput,
            TOutput,
            TClient,
        >;
        resolvesPaginated: <T = unknown>(
            items: T[],
            options?: PaginatorOptions,
        ) => AwsCommandStub<TInput, TOutput, TClient>;
        resolvesFromFile: (
            filePath: string,
        ) => AwsCommandStub<TInput, TOutput, TClient>;
    }

    Type Parameters

    • TInput extends object
    • TOutput extends MetadataBearer
    • TClient extends AnyClient = AnyClient
    Index

    Properties

    resolves rejects callsFake resolvesOnce rejectsOnce callsFakeOnce resolvesStream resolvesStreamOnce resolvesWithDelay rejectsWithDelay rejectsWithNoSuchKey rejectsWithNoSuchBucket rejectsWithAccessDenied rejectsWithResourceNotFound rejectsWithConditionalCheckFailed rejectsWithThrottling rejectsWithInternalServerError resolvesPaginated resolvesFromFile

    Properties

    resolves: (
        output: DeepPartial<TOutput>,
    ) => AwsCommandStub<TInput, TOutput, TClient>

    Set a permanent mock response that will be used after all one-time handlers are consumed.

    Type Declaration

    s3Mock.on(GetObjectCommand).resolves({ Body: 'file contents' });
    rejects: (error: string | Error) => AwsCommandStub<TInput, TOutput, TClient>

    Set a permanent mock rejection that will be used after all one-time handlers are consumed.

    Type Declaration

    s3Mock.on(GetObjectCommand).rejects(new Error('Access denied'));
    callsFake: (
        fn: CommandHandler<TInput, TOutput, TClient>,
    ) => AwsCommandStub<TInput, TOutput, TClient>

    Set a permanent custom handler function that will be used after all one-time handlers are consumed.

    Type Declaration

    s3Mock.on(GetObjectCommand).callsFake(async (input) => {
      return { Body: `Contents of ${input.Key}` };
    });
    resolvesOnce: (
        output: DeepPartial<TOutput>,
    ) => AwsCommandStub<TInput, TOutput, TClient>

    Add a one-time mock response that will be consumed in order.

    Type Declaration

    s3Mock.on(GetObjectCommand)
      .resolvesOnce({ Body: 'first call' })
      .resolvesOnce({ Body: 'second call' });
    rejectsOnce: (error: string | Error) => AwsCommandStub<TInput, TOutput, TClient>

    Add a one-time mock rejection that will be consumed in order.

    Type Declaration

    s3Mock.on(GetObjectCommand)
      .rejectsOnce('First call fails')
      .resolves({ Body: 'second call succeeds' });
    callsFakeOnce: (
        fn: CommandHandler<TInput, TOutput, TClient>,
    ) => AwsCommandStub<TInput, TOutput, TClient>

    Add a one-time custom handler that will be consumed in order.

    Type Declaration

    s3Mock.on(GetObjectCommand)
      .callsFakeOnce(async (input) => ({ Body: 'once' }))
      .resolves({ Body: 'permanent' });
    resolvesStream: (data: StreamInput) => AwsCommandStub<TInput, TOutput, TClient>

    Set a permanent stream response for S3-like operations.

    Type Declaration

    s3Mock.on(GetObjectCommand).resolvesStream('file contents');
    resolvesStreamOnce: (
        data: StreamInput,
    ) => AwsCommandStub<TInput, TOutput, TClient>

    Set a one-time stream response for S3-like operations.

    Type Declaration

    s3Mock.on(GetObjectCommand)
      .resolvesStreamOnce('first stream')
      .resolvesStream('default stream');
    resolvesWithDelay: (
        output: DeepPartial<TOutput>,
        delayMs: number,
    ) => AwsCommandStub<TInput, TOutput, TClient>

    Set a permanent mock response with a delay in milliseconds.

    Type Declaration

    s3Mock.on(GetObjectCommand).resolvesWithDelay({ Body: 'data' }, 1000);
    rejectsWithDelay: (
        error: string | Error,
        delayMs: number,
    ) => AwsCommandStub<TInput, TOutput, TClient>

    Set a permanent mock rejection with a delay in milliseconds.

    Type Declaration

    s3Mock.on(GetObjectCommand).rejectsWithDelay('Timeout', 5000);
    rejectsWithNoSuchKey: (key?: string) => AwsCommandStub<TInput, TOutput, TClient>

    Reject with an S3 NoSuchKey error.

    Type Declaration

    s3Mock.on(GetObjectCommand).rejectsWithNoSuchKey('missing-file.txt');
    rejectsWithNoSuchBucket: (
        bucket?: string,
    ) => AwsCommandStub<TInput, TOutput, TClient>

    Reject with an S3 NoSuchBucket error.

    Type Declaration

    s3Mock.on(GetObjectCommand).rejectsWithNoSuchBucket('my-bucket');
    rejectsWithAccessDenied: (
        resource?: string,
    ) => AwsCommandStub<TInput, TOutput, TClient>

    Reject with an AccessDenied error.

    Type Declaration

    s3Mock.on(GetObjectCommand).rejectsWithAccessDenied('private-file.txt');
    rejectsWithResourceNotFound: (
        resource?: string,
    ) => AwsCommandStub<TInput, TOutput, TClient>

    Reject with a DynamoDB ResourceNotFound error.

    Type Declaration

    dynamoMock.on(GetItemCommand).rejectsWithResourceNotFound('MyTable');
    rejectsWithConditionalCheckFailed: () => AwsCommandStub<
        TInput,
        TOutput,
        TClient,
    >

    Reject with a DynamoDB ConditionalCheckFailed error.

    Type Declaration

    dynamoMock.on(PutItemCommand).rejectsWithConditionalCheckFailed();
    rejectsWithThrottling: () => AwsCommandStub<TInput, TOutput, TClient>

    Reject with a Throttling error.

    Type Declaration

    s3Mock.on(GetObjectCommand).rejectsWithThrottling();
    rejectsWithInternalServerError: () => AwsCommandStub<TInput, TOutput, TClient>

    Reject with an InternalServerError.

    Type Declaration

    s3Mock.on(GetObjectCommand).rejectsWithInternalServerError();
    resolvesPaginated: <T = unknown>(
        items: T[],
        options?: PaginatorOptions,
    ) => AwsCommandStub<TInput, TOutput, TClient>

    Set paginated responses for AWS pagination patterns.

    Tokens are automatically set to the last item of each page, which works for both DynamoDB (object tokens) and S3 (object tokens).

    Type Declaration

      • <T = unknown>(
            items: T[],
            options?: PaginatorOptions,
        ): AwsCommandStub<TInput, TOutput, TClient>

      • Type Parameters

        • T = unknown

        Parameters

        • items: T[]

          Array of items to paginate (use marshalled items for DynamoDB)

        • Optionaloptions: PaginatorOptions

          Pagination configuration options

        Returns AwsCommandStub<TInput, TOutput, TClient>

        The command stub for chaining

    import { marshall } from '@aws-sdk/util-dynamodb';

    const users = [
      { id: "user-1", name: "Alice" },
      { id: "user-2", name: "Bob" }
    ];
    const marshalledUsers = users.map(u => marshall(u));

    dynamoMock.on(ScanCommand).resolvesPaginated(marshalledUsers, {
      pageSize: 1,
      tokenKey: "LastEvaluatedKey",
      inputTokenKey: "ExclusiveStartKey"
    });

    // LastEvaluatedKey will be the marshalled last item (object, not string)
    const result = await client.send(new ScanCommand({ TableName: "Users" }));
    // result.LastEvaluatedKey = { id: { S: "user-1" }, name: { S: "Alice" } }

    const objects = [
      { Key: 'file1.txt', Size: 100 },
      { Key: 'file2.txt', Size: 200 }
    ];

    s3Mock.on(ListObjectsV2Command).resolvesPaginated(objects, {
      pageSize: 1,
      itemsKey: "Contents",
      tokenKey: "NextContinuationToken",
      inputTokenKey: "ContinuationToken"
    });

    // NextContinuationToken will be the last object from the page
    const result = await client.send(new ListObjectsV2Command({ Bucket: "bucket" }));
    // result.NextContinuationToken = { Key: 'file1.txt', Size: 100 }
    resolvesFromFile: (filePath: string) => AwsCommandStub<TInput, TOutput, TClient>

    Load response from a file. JSON files are parsed, others returned as strings.

    Type Declaration

    s3Mock.on(GetObjectCommand).resolvesFromFile('./fixtures/response.json');

    Settings

    Member Visibility

    On This Page

    Properties