docs: add expect API (#370)

Author: 9aoy

website/docs/en/api/rstest/mockFunctions.mdx

@@ -80,3 +80,8 @@ Clears all mocks properties and reset each mock's implementation to its original
 - **Type:** `() => Rstest`
 
 Reset all mocks and restore original descriptors of spied-on objects.
+
+## More
+
+- [Mock Matchers](../test-api/expect#mock-matchers)
+- [MockInstance API](./mockInstance)

website/docs/en/api/test-api/_meta.json

@@ -1 +1 @@
-["test", "describe", "hooks"]
+["expect", "test", "describe", "hooks"]

website/docs/en/api/test-api/expect.mdx

@@ -0,0 +1,318 @@
+---
+title: Expect
+overviewHeaders: [2, 3]
+---
+
+# Expect
+
+`expect` is used to assert values in tests. It provides a rich set of matchers, supports chainable modifiers, soft assertions, polling, and snapshot testing.
+
+## expect
+
+- **Type:** `<T>(actual: T, message?: string) => Assertion<T>`
+
+Creates an assertion object for the given value.
+
+```ts
+import { expect } from '@rstest/core';
+
+expect(1 + 1).toBe(2);
+expect('hello').toBeDefined();
+expect([1, 2, 3]).toContain(2);
+```
+
+## expect.not
+
+Negates the assertion.
+
+```ts
+expect(1 + 1).not.toBe(3);
+expect('foo').not.toBeUndefined();
+```
+
+## expect.soft
+
+- **Type:** `<T>(actual: T, message?: string) => Assertion<T>`
+
+Performs a soft assertion. The test will continue even if the assertion fails, and all failures will be reported at the end.
+
+```ts
+expect.soft(1 + 1).toBe(3); // will not stop the test
+expect.soft(1 + 2).toBe(4);
+```
+
+## expect.poll
+
+- **Type:** `<T>(actual: () => T, options?: { interval?: number, timeout?: number, message?: string }) => Assertion<T>`
+
+Polls the value returned by the function until the assertion passes or timeout.
+
+```ts
+await expect.poll(() => getStatus()).toBe('ready');
+```
+
+## expect.unreachable
+
+- **Type:** `(message?: string) => never`
+
+Marks a code path as unreachable. Throws if called.
+
+```ts
+if (shouldNotHappen) {
+  expect.unreachable('This should never happen');
+}
+```
+
+## expect.assertions
+
+- **Type:** `(expected: number) => void`
+
+Asserts that a certain number of assertions are called during a test.
+
+```ts
+expect.assertions(2);
+expect(1 + 1).toBe(2);
+expect(2 + 2).toBe(4);
+```
+
+## expect.hasAssertions
+
+- **Type:** `() => void`
+
+Asserts that at least one assertion is called during a test.
+
+```ts
+expect.hasAssertions();
+expect(1 + 1).toBe(2);
+```
+
+## expect.addEqualityTesters
+
+- **Type:** `(testers: Array<Tester>) => void`
+
+Adds custom equality testers for use in assertions.
+
+```ts
+expect.addEqualityTesters([
+  (a, b) => {
+    if (typeof a === 'number' && typeof b === 'number') {
+      return Math.abs(a - b) < 0.01;
+    }
+  },
+]);
+expect(0.1 + 0.2).toEqual(0.3); // true with custom tester
+```
+
+## expect.addSnapshotSerializer
+
+- **Type:** `(serializer: SnapshotSerializer) => void`
+
+Adds a custom serializer for snapshot testing.
+
+```ts
+expect.addSnapshotSerializer({
+  test: (val) => typeof val === 'string' && val.startsWith('secret:'),
+  print: (val) => '***MASKED***',
+});
+expect('secret:123').toMatchSnapshot(); // snapshot will be masked
+```
+
+## expect.getState / expect.setState
+
+- **Type:**
+  - `getState: () => MatcherState`
+  - `setState: (state: Partial<MatcherState>) => void`
+
+Gets or sets the internal matcher state.
+
+```ts
+const state = expect.getState();
+console.log(state.currentTestName);
+expect.setState({ currentTestName: 'custom name' });
+console.log(expect.getState().currentTestName); // will output 'custom name'
+```
+
+## Matchers
+
+### Common matchers
+
+Common matchers are used to assert basic value comparisons, type checks, and structure checks. They cover most day-to-day assertions for numbers, strings, objects, arrays, and more.
+
+- `toBe(value)`. Checks strict equality using `Object.is`.
+- `toEqual(value)`. Checks deep equality (recursively checks all fields).
+- `toStrictEqual(value)`. Checks deep equality, including undefined properties and array sparseness.
+- `toBeTruthy()`. Checks if the value is truthy.
+- `toBeFalsy()`. Checks if the value is falsy.
+- `toBeNull()`. Checks if the value is `null`.
+- `toBeUndefined()`. Checks if the value is `undefined`.
+- `toBeDefined()`. Checks if the value is not `undefined`.
+- `toBeNaN()`. Checks if the value is `NaN`.
+- `toBeGreaterThan(number)`. Checks if the value is greater than the given number.
+- `toBeGreaterThanOrEqual(number)`. Checks if the value is greater than or equal to the given number.
+- `toBeLessThan(number)`. Checks if the value is less than the given number.
+- `toBeLessThanOrEqual(number)`. Checks if the value is less than or equal to the given number.
+- `toBeCloseTo(number, numDigits?)`. Checks if a number is close to another number, optionally with a given precision.
+- `toContain(item)`. Checks if an array or string contains the given item.
+- `toContainEqual(item)`. Checks if an array contains an item (using deep equality).
+- `toMatch(stringOrRegExp)`. Checks if a string matches a regex or substring.
+- `toMatchObject(object)`. Checks if an object matches a subset of properties.
+- `toHaveLength(length)`. Checks if an object has a `.length` property with the given value.
+- `toHaveProperty(path, value?)`. Checks if an object has a property at the given path, optionally with a specific value.
+- `toBeInstanceOf(class)`. Checks if the value is an instance of the given class.
+- `toBeTypeOf(type)`. Checks if the value is of the given type (e.g. 'string').
+- `toSatisfy(fn)`. Checks if the value satisfies the provided function.
+- `toBeOneOf(array)`. Checks if the value is one of the values in the given array.
+- `toThrowError(expected?)`. Checks if a function throws an error, optionally matching the error message or type.
+
+```ts
+// Equality
+expect(1 + 1).toBe(2);
+expect({ a: 1 }).toEqual({ a: 1 });
+expect([1, undefined]).toStrictEqual([1, undefined]);
+expect(2).toBeOneOf([1, 2, 3]);
+
+// Type & Definition
+expect(null).toBeNull();
+expect(undefined).toBeUndefined();
+expect('foo').toBeDefined();
+expect('bar').toBeTypeOf('string');
+expect(new Date()).toBeInstanceOf(Date);
+expect(NaN).toBeNaN();
+expect('hello').toBeTruthy();
+expect('').toBeFalsy();
+
+// Number Comparison
+expect(5).toBeGreaterThan(3);
+expect(5).toBeGreaterThanOrEqual(5);
+expect(3).toBeLessThan(5);
+expect(3).toBeLessThanOrEqual(3);
+expect(0.1 + 0.2).toBeCloseTo(0.3, 5);
+
+// Array / Object / String
+expect([1, 2, 3]).toContain(2);
+expect([{ a: 1 }]).toContainEqual({ a: 1 });
+expect('hello world').toMatch(/world/);
+expect({ a: 1, b: 2 }).toMatchObject({ a: 1 });
+expect('abc').toHaveLength(3);
+expect({ foo: { bar: 1 } }).toHaveProperty('foo.bar', 1);
+
+// Function / Exception
+expect(() => {
+  throw new Error('fail');
+}).toThrowError('fail');
+expect(3).toSatisfy((x) => x % 3 === 0 || x % 3 === 1);
+```
+
+### Mock matchers
+
+Mock matchers are used to assert how mock functions (created by `rstest.fn` or `rstest.spyOn`) are called, what they return, and their call order. They are essential for verifying function interactions in unit tests.
+
+- `toHaveBeenCalled()`. Checks if a mock function was called at least once.
+- `toHaveBeenCalledTimes(times)`. Checks if a mock function was called a specific number of times.
+- `toHaveBeenCalledWith(...args)`. Checks if a mock function was called with specific arguments.
+- `toHaveBeenCalledBefore(mock)`. Checks if a mock was called before another mock.
+- `toHaveBeenCalledAfter(mock)`. Checks if a mock was called after another mock.
+- `toHaveBeenCalledExactlyOnceWith(...args)`. Checks if a mock was called exactly once with specific arguments.
+- `toHaveBeenLastCalledWith(...args)`. Checks if a mock was last called with specific arguments.
+- `toHaveBeenNthCalledWith(n, ...args)`. Checks if a mock was called with specific arguments on the nth call.
+- `toHaveReturned()`. Checks if a mock function returned at least once.
+- `toHaveReturnedTimes(times)`. Checks if a mock function returned a specific number of times.
+- `toHaveReturnedWith(value)`. Checks if a mock function returned a specific value.
+- `toHaveLastReturnedWith(value)`. Checks if a mock function last returned a specific value.
+- `toHaveNthReturnedWith(n, value)`. Checks if a mock function returned a specific value on the nth call.
+- `toHaveResolved()`. Checks if a promise resolved at least once.
+- `toHaveResolvedTimes(times)`. Checks if a promise resolved a specific number of times.
+- `toHaveResolvedWith(value)`. Checks if a promise resolved with a specific value.
+- `toHaveLastResolvedWith(value)`. Checks if a promise last resolved with a specific value.
+- `toHaveNthResolvedWith(n, value)`. Checks if a promise resolved with a specific value on the nth call.
+
+```ts
+const mockFn = rstest.fn((x) => x + 1);
+mockFn(1);
+
+expect(mockFn).toHaveBeenCalled();
+expect(mockFn).toHaveBeenCalledTimes(1);
+expect(mockFn).toHaveBeenCalledWith(1);
+```
+
+### Snapshot matchers
+
+Snapshot matchers are used to compare values, errors, or files against previously recorded snapshots, making it easy to track changes in output over time.
+
+- `toMatchSnapshot()`. Compares the value to a saved snapshot.
+- `toMatchInlineSnapshot()`. Compares the value to an inline snapshot in the test file.
+- `toThrowErrorMatchingSnapshot()`. Checks if a thrown error matches a saved snapshot.
+- `toThrowErrorMatchingInlineSnapshot()`. Checks if a thrown error matches an inline snapshot in the test file.
+- `toMatchFileSnapshot(filepath)`. Compares the value to a snapshot saved in a specific file.
+
+```ts
+expect('hello world').toMatchSnapshot();
+
+expect(() => {
+  throw new Error('fail');
+}).toThrowErrorMatchingSnapshot();
+```
+
+### Promise matchers
+
+- `resolves`. Asserts on the resolved value of a Promise.
+- `rejects`. Asserts on the rejected value of a Promise.
+
+```ts
+await expect(Promise.resolve('ok')).resolves.toBe('ok');
+await expect(Promise.reject(new Error('fail'))).rejects.toThrow('fail');
+```
+
+### Asymmetric matchers
+
+Asymmetric matchers are helpers that allow for flexible matching of values, such as partial matches, type matches, or pattern matches. They are useful for writing more expressive and less brittle tests.
+
+- `expect.anything()`. Matches any value except null or undefined.
+- `expect.any(constructor)`. Matches any value of the given type.
+- `expect.closeTo(number, precision?)`. Matches a number close to the expected value.
+- `expect.arrayContaining(array)`. Matches an array containing the expected elements.
+- `expect.objectContaining(object)`. Matches an object containing the expected properties.
+- `expect.stringContaining(string)`. Matches a string containing the expected substring.
+- `expect.stringMatching(stringOrRegExp)`. Matches a string matching the expected pattern.
+
+```ts
+expect({ a: 1 }).toEqual({ a: expect.anything() });
+
+expect(1).toEqual(expect.any(Number));
+
+expect(0.1 + 0.2).toEqual(expect.closeTo(0.3, 5));
+
+expect([1, 2, 3]).toEqual(expect.arrayContaining([2, 1]));
+
+expect({ a: 1, b: 2 }).toEqual(expect.objectContaining({ a: 1 }));
+
+expect('hello world').toEqual(expect.stringContaining('world'));
+
+expect('hello world').toEqual(expect.stringMatching(/^hello/));
+```
+
+### Custom matchers
+
+You can extend expect with custom matchers:
+
+```ts
+expect.extend({
+  toBeDivisibleBy(received, argument) {
+    const pass = received % argument === 0;
+    if (pass) {
+      return {
+        message: () =>
+          `expected ${received} not to be divisible by ${argument}`,
+        pass: true,
+      };
+    } else {
+      return {
+        message: () => `expected ${received} to be divisible by ${argument}`,
+        pass: false,
+      };
+    }
+  },
+});
+
+expect(10).toBeDivisibleBy(2);
+```

website/docs/zh/api/rstest/mockFunctions.mdx

@@ -80,3 +80,8 @@ expect(spy).toHaveBeenCalled();
 - **类型：** `() => Rstest`
 
 重置所有 mock，并恢复被 mock 的对象的原始描述符。
+
+## 更多
+
+- [Mock 匹配器](../test-api/expect#mock-matchers)
+- [MockInstance API](./mockInstance)

website/docs/zh/api/test-api/_meta.json

@@ -1 +1 @@
-["test", "describe", "hooks"]
+["expect", "test", "describe", "hooks"]