> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt.

# Mock instance

`MockInstance` 是所有 mock 和 spy 实例的类型。

## getMockName

- **类型：** `() => string`

返回通过 `.mockName()` 设置的 mock 名称字符串。

```ts
const fn = rs.fn();
fn.mockName('myMock');
expect(fn.getMockName()).toBe('myMock');
```

## mockName

- **类型：** `(name: string) => MockInstance`

为此 mock 实例设置名称，便于调试和输出。

```ts
const fn = rs.fn();
fn.mockName('logger');
```

## mockClear

- **类型：** `() => MockInstance`

清除所有关于每次调用的信息（调用、实例、上下文、结果等）。

```ts
const fn = rs.fn();
fn(1);
fn.mockClear();
expect(fn.mock.calls.length).toBe(0);
```

## mockReset

- **类型：** `() => MockInstance`

清除所有调用信息，并将实现重置为初始状态。

```ts
const fn = rs.fn().mockImplementation(() => 1);
fn.mockReset();
// 实现已被重置
```

## mockRestore

- **类型：** `() => void`

恢复被 spy 的对象的原始方法（仅对 spy 有效）。

```ts
const obj = { foo: () => 1 };
const spy = rs.spyOn(obj, 'foo');
spy.mockRestore();
```

## Symbol.dispose


[Added in v0.10.2](https://github.com/web-infra-dev/rstest/releases/tag/v0.10.2)

- **类型：** `() => void`

当 mock 离开 `using` 作用域时调用 `mockRestore()`。

```ts
const obj = { foo: () => 1 };

{
  using spy = rs.spyOn(obj, 'foo').mockImplementation(() => 2);
  expect(obj.foo()).toBe(2);
}

expect(obj.foo()).toBe(1);
```

## getMockImplementation

- **类型：** `() => Function | undefined`

返回当前的 mock 实现函数（如有）。

```ts
const fn = rs.fn(() => 123);
const impl = fn.getMockImplementation();
```

## mockImplementation

- **类型：** `(fn: Function) => MockInstance`

为 mock 设置实现函数。

```ts
const fn = rs.fn();
fn.mockImplementation((a, b) => a + b);
```

## mockImplementationOnce

- **类型：** `(fn: Function) => MockInstance`

仅为下一次调用设置实现函数。

```ts
const fn = rs.fn();
fn.mockImplementationOnce(() => 1);
fn(); // 返回 1
fn(); // 返回 undefined
```

## withImplementation

- **类型：** `(fn: Function, callback: () => any) => MockInstance | Promise<MockInstance>`

临时替换 mock 的实现函数，在 callback 执行期间生效，执行完毕后恢复原实现。返回该 mock 实例（callback 为异步时返回 resolve 为该实例的 promise）。

```ts
const fn = rs.fn(() => 1);
fn.withImplementation(
  () => 2,
  () => {
    expect(fn()).toBe(2);
  },
);
expect(fn()).toBe(1);
```

## mockReturnThis

- **类型：** `() => this`

使 mock 在调用时返回 `this`。

```ts
const fn = rs.fn();
fn.mockReturnThis();
const obj = { fn };
expect(obj.fn()).toBe(obj);
```

## mockReturnValue

- **类型：** `(value: any) => MockInstance`

使 mock 总是返回指定的值。

```ts
const fn = rs.fn();
fn.mockReturnValue(42);
expect(fn()).toBe(42);
```

## mockReturnValueOnce

- **类型：** `(value: any) => MockInstance`

使 mock 仅在下一次调用时返回指定的值。

```ts
const fn = rs.fn();
fn.mockReturnValueOnce(1);
expect(fn()).toBe(1);
expect(fn()).toBe(undefined);
```

## mockThrow


[Added in v0.11.4](https://github.com/web-infra-dev/rstest/releases/tag/v0.11.4)

- **类型：** `(value: unknown) => MockInstance`

使 mock 在每次调用时抛出指定的值。

```ts
const fn = rs.fn().mockThrow(new Error('fail'));
expect(() => fn()).toThrow('fail');
```

## mockThrowOnce


[Added in v0.11.4](https://github.com/web-infra-dev/rstest/releases/tag/v0.11.4)

- **类型：** `(value: unknown) => MockInstance`

使 mock 仅在下一次调用时抛出指定的值。

```ts
const fn = rs.fn(() => 'ok').mockThrowOnce(new Error('fail'));
expect(() => fn()).toThrow('fail');
expect(fn()).toBe('ok');
```

## mockResolvedValue

- **类型：** `(value: any) => MockInstance`

使 mock 返回一个 Promise，resolve 为指定的值。

```ts
const fn = rs.fn();
fn.mockResolvedValue(123);
await expect(fn()).resolves.toBe(123);
```

## mockResolvedValueOnce

- **类型：** `(value: any) => MockInstance`

使 mock 仅在下一次调用时返回一个 Promise，resolve 为指定的值。

```ts
const fn = rs.fn();
fn.mockResolvedValueOnce(1);
await expect(fn()).resolves.toBe(1);
await expect(fn()).resolves.toBe(undefined);
```

## mockRejectedValue

- **类型：** `(error: any) => MockInstance`

使 mock 返回一个 Promise，reject 为指定的错误。

```ts
const fn = rs.fn();
fn.mockRejectedValue(new Error('fail'));
await expect(fn()).rejects.toThrow('fail');
```

## mockRejectedValueOnce

- **类型：** `(error: any) => MockInstance`

使 mock 仅在下一次调用时返回一个 Promise，reject 为指定的错误。

```ts
const fn = rs.fn();
fn.mockRejectedValueOnce(new Error('fail'));
await expect(fn()).rejects.toThrow('fail');
await expect(fn()).resolves.toBe(undefined);
```

## mock

mock 的上下文，包括调用参数、返回值、实例、上下文等。

```ts
const fn = rs.fn((a, b) => a + b);
fn(1, 2);
expect(fn.mock.calls[0]).toEqual([1, 2]);
```

### mock.calls

- **类型：** `Array<Parameters<T>>`

包含每次调用 mock 函数的参数的数组。

```ts
const fn = rs.fn((a, b) => a + b);
fn(1, 2);
fn(3, 4);
console.log(fn.mock.calls); // [[1, 2], [3, 4]]
```

### mock.instances

- **类型：** `Array<ReturnType<T>>`

包含通过 mock 作为构造函数实例化的所有实例的数组。

```ts
const Fn = rs.fn(function () {
  this.x = 1;
});
const a = new Fn();
const b = new Fn();
console.log(Fn.mock.instances); // [a, b]
```

### mock.contexts

- **类型：** `Array<ReturnType<T>>`

包含每次调用 mock 函数时的 `this` 上下文的数组。

```ts
const fn = rs.fn();
const context = {};

fn.apply(context);
fn.call(context);

fn.mock.contexts[0] === context;
fn.mock.contexts[1] === context;
```

### mock.invocationCallOrder

- **类型：** `Array<number>`

表示 mock 被调用顺序的数字数组，所有 mock 共享。索引从 `1` 开始。

```ts
const fn1 = rs.fn();
const fn2 = rs.fn();
fn1();
fn2();
fn1();
console.log(fn1.mock.invocationCallOrder); // [1, 3]
console.log(fn2.mock.invocationCallOrder); // [2]
```

### mock.lastCall

- **类型：** `Parameters<T> | undefined`

mock 函数最后一次调用的参数，若未调用则为 `undefined`。

```ts
const fn = rs.fn();
fn(1, 2);
fn(3, 4);
console.log(fn.mock.lastCall); // [3, 4]
```

### mock.results

- **类型：** `Array<MockResult<ReturnType<T>>>`

包含每次调用 mock 函数的结果（返回值、抛出的错误或未完成调用）的数组。

```ts
const fn = rs.fn((a, b) => a + b);
fn(1, 2);
try {
  fn();
  throw new Error('fail');
} catch {}
console.log(fn.mock.results);
// [{ type: 'return', value: 3 }, { type: 'throw', value: Error }]
```

### mock.settledResults

- **类型：** `Array<MockSettledResult<Awaited<ReturnType<T>>>>`

包含所有异步调用的最终结果（fulfilled 或 rejected）的数组。

```ts
const fn = rs.fn(async (x) => {
  if (x > 0) return x;
  throw new Error('fail');
});
await fn(1);
try {
  await fn(0);
} catch {}
console.log(fn.mock.settledResults);
// [{ type: 'fulfilled', value: 1 }, { type: 'rejected', value: Error }]
```