feat: format test tablename

docs/api/index.md

@@ -244,6 +244,39 @@ You cannot use this syntax, when using Vitest as [type checker](/guide/testing-t
   // ✓ add(2, 1) -> 3
   ```
 
+  You can also access function to custom format the test title:
+
+  ```ts
+  test.each([
+    [1, 1, 2],
+    [1, 2, 3],
+    [2, 1, 3],
+  ])(
+    (a, b, expected) => `${a} + ${b} = ${expected}`,
+    (a, b, expected) => expect(a + b).toBe(expected),
+  )
+
+  // this will return
+  // ✓ 1 + 1 = 2
+  // ✓ 1 + 2 = 3
+  // ✓ 2 + 1 = 3
+  ```
+
+  ```ts
+  test.each([
+    { a: 1, b: 1, expected: 2 },
+    { a: 1, b: 2, expected: 3 },
+    { a: 2, b: 1, expected: 3 },
+  ])(
+    ({ a, b, expected }) => `${a} + ${b} = ${expected}`,
+    ({ a, b, expected }) => expect(a + b).toBe(expected),
+  )
+
+  // this will return
+  // ✓ 1 + 1 = 2
+  // ✓ 1 + 2 = 3
+  // ✓ 2 + 1 = 3
+  ```
 
   Starting from Vitest 0.25.3, you can also use template string table.
 
@@ -263,6 +296,22 @@ You cannot use this syntax, when using Vitest as [type checker](/guide/testing-t
   })
   ```
 
+  You can also use custom format function to format the test title.
+
+  ```ts
+  test.each`
+    a               | b      | expected
+    ${1}            | ${1}   | ${2}
+    ${'a'}          | ${'b'} | ${'ab'}
+    ${[]}           | ${'b'} | ${'b'}
+    ${{}}           | ${'b'} | ${'[object Object]b'}
+    ${{ asd: 1 }}   | ${'b'} | ${'[object Object]b'}
+    `(
+    (a, b, expected) => `fmt returns ${JSON.stringify(expected)} when ${JSON.stringify(a)} is added ${JSON.stringify(b)}`,
+    ({ a, b, expected }) => expect(a + b).toBe(expected),
+  )
+  ```
+
   If you want to have access to `TestContext`, use `describe.each` with a single test.
 
 ::: warning

packages/vitest/src/runtime/suite.ts

@@ -186,13 +186,18 @@ function createSuite() {
     if (Array.isArray(cases) && args.length)
       cases = formatTemplateString(cases, args)
 
-    return (name: string, fn: (...args: T[]) => void, options?: number | TestOptions) => {
+    return (name: string | ((...args: T[]) => string), fn: (...args: T[]) => void, options?: number | TestOptions) => {
       const arrayOnlyCases = cases.every(Array.isArray)
       cases.forEach((i, idx) => {
         const items = Array.isArray(i) ? i : [i]
+        let formatNamed!: string
+        if (typeof name === 'string')
+          formatNamed = formatTitle(name, items, idx)
+        else
+          formatNamed = arrayOnlyCases ? name(...items) : name(i)
         arrayOnlyCases
-          ? suite(formatTitle(name, items, idx), () => fn(...items), options)
-          : suite(formatTitle(name, items, idx), () => fn(i), options)
+          ? suite(formatNamed, () => fn(...items), options)
+          : suite(formatNamed, () => fn(i), options)
       })
     }
   }
@@ -222,13 +227,19 @@ function createTest(fn: (
     if (Array.isArray(cases) && args.length)
       cases = formatTemplateString(cases, args)
 
-    return (name: string, fn: (...args: T[]) => void, options?: number | TestOptions) => {
+    return (name: string | ((...args: T[]) => string), fn: (...args: T[]) => void, options?: number | TestOptions) => {
       const arrayOnlyCases = cases.every(Array.isArray)
       cases.forEach((i, idx) => {
         const items = Array.isArray(i) ? i : [i]
+        let formatNamed!: string
+        if (typeof name === 'string')
+          formatNamed = formatTitle(name, items, idx)
+        else
+          formatNamed = arrayOnlyCases ? name(...items) : name(i)
+
         arrayOnlyCases
-          ? test(formatTitle(name, items, idx), () => fn(...items), options)
-          : test(formatTitle(name, items, idx), () => fn(i), options)
+          ? test(formatNamed, () => fn(...items), options)
+          : test(formatNamed, () => fn(i), options)
       })
     }
   }

packages/vitest/src/types/tasks.ts

@@ -116,22 +116,22 @@ interface SuiteEachFunction {
 
 interface TestEachFunction {
   <T extends any[] | [any]>(cases: ReadonlyArray<T>): (
-    name: string,
+    name: string | ((...args: T) => string),
     fn: (...args: T) => Awaitable<void>,
     options?: number | TestOptions,
   ) => void
   <T extends ReadonlyArray<any>>(cases: ReadonlyArray<T>): (
-    name: string,
+    name: string | ((...args: ExtractEachCallbackArgs<T>) => string),
     fn: (...args: ExtractEachCallbackArgs<T>) => Awaitable<void>,
     options?: number | TestOptions,
   ) => void
   <T>(cases: ReadonlyArray<T>): (
-    name: string,
+    name: string | ((...args: T[]) => string),
     fn: (...args: T[]) => Awaitable<void>,
     options?: number | TestOptions,
   ) => void
   (...args: [TemplateStringsArray, ...any]): (
-    name: string,
+    name: string | ((...args: any[]) => string),
     fn: (...args: any[]) => Awaitable<void>,
     options?: number | TestOptions,
   ) => void

test/core/test/each.test.ts

@@ -8,6 +8,24 @@ test.each([
   expect(a + b).toBe(expected)
 })
 
+test.each([
+  [1, 1, 2],
+  [1, 2, 3],
+  [2, 1, 3],
+])(
+  (a, b, expected) => `${a} + ${b} = ${expected}`,
+  (a, b, expected) => expect(a + b).toBe(expected),
+)
+
+test.each([
+  { a: 1, b: 1, expected: 2 },
+  { a: 1, b: 2, expected: 3 },
+  { a: 2, b: 1, expected: 3 },
+])(
+  ({ a, b, expected }) => `${a} + ${b} = ${expected}`,
+  ({ a, b, expected }) => expect(a + b).toBe(expected),
+)
+
 test.each([
   ['string', true],
   ['string', false],
@@ -194,6 +212,18 @@ ${{ asd: 1 }}   | ${'b'} | ${'[object Object]b'}
   expect(a + b).toBe(expected)
 })
 
+test.each`
+a               | b      | expected
+${1}            | ${1}   | ${2}
+${'a'}          | ${'b'} | ${'ab'}
+${[]}           | ${'b'} | ${'b'}
+${{}}           | ${'b'} | ${'[object Object]b'}
+${{ asd: 1 }}   | ${'b'} | ${'[object Object]b'}
+`(
+  (a, b, expected) => `fmt returns ${JSON.stringify(expected)} when ${JSON.stringify(a)} is added ${JSON.stringify(b)}`,
+  ({ a, b, expected }) => expect(a + b).toBe(expected),
+)
+
 test.each`
 a       | b       | expected
 ${true} | ${true} | ${true}