### Install vitest-mock-extended

Source: https://github.com/eratio08/vitest-mock-extended/blob/main/README.md

Install the library using npm or yarn. If you encounter 'vi is not defined' errors, ensure `globals: true` is set in your Vitest configuration.

```bash
npm install vitest-mock-extended --save-dev
```

```bash
yarn add vitest-mock-extended --dev
```

--------------------------------

### Mocking a Module with vitest.mock

Source: https://github.com/eratio08/vitest-mock-extended/blob/main/README.md

This example demonstrates how to mock a module using Vitest's `vi.mock` and `vitest-mock-extended`'s `mock` function. It's designed to be placed in a mock file (e.g., `@/libs/example.mock.ts`) and used to replace the original module's exports.

```typescript
// Mock a module
// @/libs/example.mock.ts
import { mock } from "vitest-mock-extended";
import { ExampleClient } from "@/libs/example";

vi.mock(import("@/libs/example"), async (importOriginal) => {
  const actual = await importOriginal();
  return {
    ...actual,
    // Due to vi.mock being hoisted, we have to mock here directly instead of 
    // defining an exampleMock outside and assign it to example
    example: mock<ExampleClient>(),
  };
});

// Use the mocked object
import "@/libs/example.mock"; // Mock out the actual client
import { mocked } from "vitest-mock-extended";
import { example } from "@/libs/example";

const exampleMock = mocked(example);

test("send notification", () => {
    example.function.mockResolvedValue(xxx);
    ...
});
```

--------------------------------

### Mock an Interface with vitest-mock-extended

Source: https://github.com/eratio08/vitest-mock-extended/blob/main/README.md

Use the `mock` function to create a type-safe mock of an interface. This example demonstrates mocking a `PartyProvider` interface and asserting a method call.

```typescript
import { mock } from 'vitest-mock-extended';

interface PartyProvider {
    getPartyType: () => string;
    getSongs: (type: string) => string[];
    start: (type: string) => void;
}

describe('Party Tests', () => {
    test('Mock out an interface', () => {
        const mock = mock<PartyProvider>();
        mock.start('disco party');

        expect(mock.start).toHaveBeenCalledWith('disco party');
    });

    test('mock out a return type', () => {
        const mock = mock<PartyProvider>();
        mock.getPartyType.mockReturnValue('west coast party');

        expect(mock.getPartyType()).toBe('west coast party');
    });

    test('Can specify fallbackMockImplementation', () => {
        const mockObj = mock<MockInt>(
            {},
            {
                fallbackMockImplementation: () => {
                    throw new Error('not mocked');
                },
            }
        );

        expect(() => mockObj.getSomethingWithArgs(1, 2)).toThrowError('not mocked');
    });
});
```

--------------------------------

### Mocked Type Helpers for Modules

Source: https://github.com/eratio08/vitest-mock-extended/blob/main/README.md

Use `mocked` and `mockedFn` from `vitest-mock-extended` to create strongly-typed mocks for existing objects and functions, especially useful when dealing with module hoisting issues in Vitest.

```typescript
// APIs
import { mocked, mockedFn } from "vitest-mock-extended";
import { originalObj, originalFn} from "somewhere";

const mockedObj = mocked(originalObj);
const deepMockedObj = mocked(originalObj, true);
const mockedFunction = mockedFn(originalFn);
```

--------------------------------

### Create Mock Functions with mockFn()

Source: https://github.com/eratio08/vitest-mock-extended/blob/main/README.md

Use `mockFn()` to create a `vi.fn()` that supports the `calledWith` extension, ensuring type safety for function arguments and return types.

```typescript
type MyFn = (x: number, y: number) => Promise<string>;
const fn = mockFn<MyFn>();
fn.calledWith(1, 2).mockReturnValue('str');
```

--------------------------------

### Deep Mocking with Function Property Support

Source: https://github.com/eratio08/vitest-mock-extended/blob/main/README.md

Enable `funcPropSupport` in `mockDeep` to mock properties on functions. This allows mocking scenarios where functions themselves have properties that need to be stubbed.

```typescript
import { mockDeep } from 'vitest-mock-extended';
const mockObj: DeepMockProxy<Test1> = mockDeep<Test1>({ funcPropSupport: true });
mockObj.deepProp.calledWith(1).mockReturnValue(3);
mockObj.deepProp.getNumber.calledWith(1).mockReturnValue(4);
expect(mockObj.deepProp(1)).toBe(3);
expect(mockObj.deepProp.getNumber(1)).toBe(4);
```

--------------------------------

### Deep Mocking with mockDeep

Source: https://github.com/eratio08/vitest-mock-extended/blob/main/README.md

Use `mockDeep` to mock objects where methods return other objects that also need to be mocked. Ensure the `Test1` type is available in your scope.

```typescript
import { mockDeep } from 'vitest-mock-extended';

const mockObj: DeepMockProxy<Test1> = mockDeep<Test1>();
mockObj.deepProp.getNumber.calledWith(1).mockReturnValue(4);
expect(mockObj.deepProp.getNumber(1)).toBe(4);
```

--------------------------------

### Create Custom Matcher with Same Type

Source: https://github.com/eratio08/vitest-mock-extended/blob/main/README.md

Use `MatcherCreator` to define a custom matcher where the expected and actual values share the same type. Ensure the `Matcher` logic correctly compares both values and any special properties.

```typescript
import { MatcherCreator, Matcher } from 'vitest-mock-extended';

// expectedValue is optional
export const myMatcher: MatcherCreator<MyType> = (expectedValue) =>
    new Matcher((actualValue) => {
        return expectedValue === actualValue && actualValue.isSpecial;
    });

```

--------------------------------

### Create Custom Matcher with Different Types

Source: https://github.com/eratio08/vitest-mock-extended/blob/main/README.md

When the expected value type differs from the actual value type, provide a second generic parameter to `MatcherCreator`. This allows for flexible type handling in your custom matchers.

```typescript
import { MatcherCreator, Matcher } from 'vitest-mock-extended';

// expectedValue is optional
export const myMatcher: MatcherCreator<string[], string> = (expectedValue) =>
    new Matcher((actualValue) => {
        return actualValue.includes(expectedValue);
    });

```

--------------------------------

### Deep Mocking with Fallback Implementation

Source: https://github.com/eratio08/vitest-mock-extended/blob/main/README.md

Provide a `fallbackMockImplementation` to `mockDeep` to handle calls for which no specific return value has been defined using `calledWith`. This is useful for ensuring unmocked paths throw errors.

```typescript
import { mockDeep } from 'jest-mock-extended';
const mockObj = mockDeep<Test1>({
    fallbackMockImplementation: () => {
        throw new Error('please add expected return value using calledWith');
    },
});
expect(() => mockObj.getNumber()).toThrowError('not mocked');
```

--------------------------------

### Use calledWith() for Argument Matching

Source: https://github.com/eratio08/vitest-mock-extended/blob/main/README.md

The `calledWith()` extension allows for precise argument matching in mock assertions. It provides type checking even when using matchers like `any()` or `anyString()`.

```typescript
const provider = mock<PartyProvider>();
provider.getSongs.calledWith('disco party').mockReturnValue(['Dance the night away', 'Stayin Alive']);
expect(provider.getSongs('disco party')).toEqual(['Dance the night away', 'Stayin Alive']);

// Matchers
provider.getSongs.calledWith(any()).mockReturnValue(['Saw her standing there']);
provider.getSongs.calledWith(anyString()).mockReturnValue(['Saw her standing there']);
```

--------------------------------

### Assign Mocks with MockProxy Type

Source: https://github.com/eratio08/vitest-mock-extended/blob/main/README.md

When assigning a mock to a typed variable, use `MockProxy<>` to ensure type safety and access to built-in testing functionalities like `calledWith()`.

```typescript
import { MockProxy, mock } from 'vitest-mock-extended';

describe('test', () => {
    let myMock: MockProxy<MyInterface>;

    beforeEach(() => {
        myMock = mock<MyInterface>();
    })

    test(() => {
         myMock.calledWith(1).mockReturnValue(2);
         ...
    })
});
```

--------------------------------

### Clear or Reset Mocks

Source: https://github.com/eratio08/vitest-mock-extended/blob/main/README.md

Utilize `mockClear` and `mockReset` functions, similar to `vi.fn()`, to reset the call history or fully reset mocks within your tests.

```typescript
import { mock, mockClear, mockReset } from 'vitest-mock-extended';

describe('test', () => {
   const mock: UserService = mock<UserService>();

   beforeEach(() => {
      mockReset(mock); // or mockClear(mock)
   });
   ...
})
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.