fix(types): align describe and test callback types (#1422)

Author: 9aoy

packages/core/src/types/api.ts

@@ -80,14 +80,14 @@ export interface TestEachFn {
     cases: readonly T[],
   ): (
     description: string,
-    fn: (...args: [...T]) => MaybePromise<void>,
+    fn?: (...args: [...T]) => MaybePromise<void>,
     options?: number | TestOptions,
   ) => void;
   <T>(
     cases: readonly T[],
   ): (
     description: string,
-    fn: (...args: T[]) => MaybePromise<void>,
+    fn?: (...args: T[]) => MaybePromise<void>,
     options?: number | TestOptions,
   ) => void;
   <T extends Record<string, unknown>>(
@@ -124,10 +124,13 @@ export interface DescribeEachFn {
   ): (description: string, fn?: (param: T) => MaybePromise<void>) => void;
   <T extends readonly [unknown, ...unknown[]]>(
     cases: readonly T[],
-  ): (description: string, fn: (...args: [...T]) => MaybePromise<void>) => void;
+  ): (
+    description: string,
+    fn?: (...args: [...T]) => MaybePromise<void>,
+  ) => void;
   <T>(
     cases: readonly T[],
-  ): (description: string, fn: (param: T) => MaybePromise<void>) => void;
+  ): (description: string, fn?: (param: T) => MaybePromise<void>) => void;
   <T extends Record<string, unknown>>(
     strings: TemplateStringsArray,
     ...expressions: unknown[]
@@ -157,7 +160,7 @@ export type TestAPI<ExtraContext = object> = TestFn<ExtraContext> & {
   skipIf: (condition: boolean) => TestAPI<ExtraContext>;
 };
 
-type DescribeFn = (description: string, fn?: () => void) => void;
+type DescribeFn = (description: string, fn?: () => MaybePromise<void>) => void;
 
 export type DescribeAPI = DescribeFn & {
   each: DescribeEachFn;

website/docs/en/api/runtime-api/test-api/describe.mdx

@@ -9,12 +9,13 @@ description: describe defines a test suite. It supports chainable modifiers and
 
 ## describe
 
-- **Type:** `(name: string, fn: () => void | Promise<void>) => void`
+- **Type:** `(name: string, fn?: () => void | Promise<void>) => void`
 
 Defines a test suite that can contain multiple test cases or nested describe blocks.
+The callback can be asynchronous; Rstest waits for it during collection before running the tests declared inside it.
 
 ```ts
-import { describe, test } from '@rstest/core';
+import { describe, expect, test } from '@rstest/core';
 
 describe('math', () => {
   test('add', () => {
@@ -26,6 +27,16 @@ describe('math', () => {
 });
 ```
 
+```ts
+describe('async setup', async () => {
+  const data = await loadFixtureData();
+
+  test('uses collected data', () => {
+    expect(data).toBeDefined();
+  });
+});
+```
+
 ## describe.only
 
 Only run the describe block(s) marked with `only`.
@@ -68,7 +79,7 @@ describe.todo('should implement this suite');
 
 ## describe.each
 
-- **Type:** `describe.each(cases: ReadonlyArray<T>)(name: string, fn: (param: T) => void | Promise<void>) => void`
+- **Type:** `describe.each(cases: ReadonlyArray<T>)(name: string, fn?: (param: T) => void | Promise<void>) => void`
 
 Creates a describe block for each item in the provided array.
 
@@ -113,7 +124,7 @@ describe.each<{ a: number; b: number; expected: number }>`
 
 ## describe.for
 
-- **Type:** `describe.for(cases: ReadonlyArray<T>)(name: string, fn: (param: T) => void | Promise<void>) => void`
+- **Type:** `describe.for(cases: ReadonlyArray<T>)(name: string, fn?: (param: T) => void | Promise<void>) => void`
 
 Alternative to `describe.each` for more flexible parameter types.
 

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

@@ -13,7 +13,7 @@ Alias: `it`.
 
 ## test
 
-- **Type:** `(name: string, fn: (testContext: TestContext) => void | Promise<void>, options?: number | TestOptions) => void`
+- **Type:** `(name: string, fn?: (testContext: TestContext) => void | Promise<void>, options?: number | TestOptions) => void`
 
 Defines a test case.
 
@@ -114,7 +114,7 @@ test.todo('should implement this test');
 
 ## test.each
 
-- **Type:** `test.each(cases: ReadonlyArray<T>)(name: string, fn: (param: T) => void | Promise<void>, options?: number | TestOptions) => void`
+- **Type:** `test.each(cases: ReadonlyArray<T>)(name: string, fn?: (param: T) => void | Promise<void>, options?: number | TestOptions) => void`
 
 Runs the same test logic for each item in the provided array.
 
@@ -197,7 +197,7 @@ test.each([
 
 ## test.for
 
-- **Type:** `test.for(cases: ReadonlyArray<T>)(name: string, fn: (param: T, testContext: TestContext) => void | Promise<void>, options?: number | TestOptions) => void`
+- **Type:** `test.for(cases: ReadonlyArray<T>)(name: string, fn?: (param: T, testContext: TestContext) => void | Promise<void>, options?: number | TestOptions) => void`
 
 Alternative to `test.each` to provide `TestContext`.
 

website/docs/zh/api/runtime-api/test-api/describe.mdx

@@ -9,12 +9,13 @@ description: describe 用于定义测试套件（test suite），支持链式修
 
 ## describe
 
-- **类型：** `(name: string, fn: () => void | Promise<void>) => void`
+- **类型：** `(name: string, fn?: () => void | Promise<void>) => void`
 
 定义一个测试套件，可以包含多个测试用例或嵌套的 describe。
+回调可以是异步函数；Rstest 会在收集阶段等待它完成，然后再运行其中声明的测试。
 
 ```ts
-import { describe, test } from '@rstest/core';
+import { describe, expect, test } from '@rstest/core';
 
 describe('math', () => {
   test('add', () => {
@@ -26,6 +27,16 @@ describe('math', () => {
 });
 ```
 
+```ts
+describe('async setup', async () => {
+  const data = await loadFixtureData();
+
+  test('uses collected data', () => {
+    expect(data).toBeDefined();
+  });
+});
+```
+
 ## describe.only
 
 只运行被 only 标记的 describe 块。
@@ -68,7 +79,7 @@ describe.todo('should implement this suite');
 
 ## describe.each
 
-- **类型：** `describe.each(cases: ReadonlyArray<T>)(name: string, fn: (param: T) => void | Promise<void>) => void`
+- **类型：** `describe.each(cases: ReadonlyArray<T>)(name: string, fn?: (param: T) => void | Promise<void>) => void`
 
 为数组中的每一项生成一个 describe 块。
 
@@ -113,7 +124,7 @@ describe.each<{ a: number; b: number; expected: number }>`
 
 ## describe.for
 
-- **类型：** `describe.for(cases: ReadonlyArray<T>)(name: string, fn: (param: T) => void | Promise<void>) => void`
+- **类型：** `describe.for(cases: ReadonlyArray<T>)(name: string, fn?: (param: T) => void | Promise<void>) => void`
 
 类似 each，但参数类型更灵活。
 

website/docs/zh/api/runtime-api/test-api/test.mdx

@@ -13,7 +13,7 @@ import { ApiMeta } from '@components/ApiMeta';
 
 ## test
 
-- **类型：** `(name: string, fn: (testContext: TestContext) => void | Promise<void>, options?: number | TestOptions) => void`
+- **类型：** `(name: string, fn?: (testContext: TestContext) => void | Promise<void>, options?: number | TestOptions) => void`
 
 定义一个测试用例。
 
@@ -114,7 +114,7 @@ test.todo('should implement this test');
 
 ## test.each
 
-- **类型：** `test.each(cases: ReadonlyArray<T>)(name: string, fn: (param: T) => void | Promise<void>, options?: number | TestOptions) => void`
+- **类型：** `test.each(cases: ReadonlyArray<T>)(name: string, fn?: (param: T) => void | Promise<void>, options?: number | TestOptions) => void`
 
 对提供的数组中的每一项运行相同的测试逻辑。
 
@@ -197,7 +197,7 @@ test.each([
 
 ## test.for
 
-- **类型：** `test.for(cases: ReadonlyArray<T>)(name: string, fn: (param: T, testContext: TestContext) => void | Promise<void>, options?: number | TestOptions) => void`
+- **类型：** `test.for(cases: ReadonlyArray<T>)(name: string, fn?: (param: T, testContext: TestContext) => void | Promise<void>, options?: number | TestOptions) => void`
 
 `test.each` 的替代方案，提供 `TestContext`。