feat: test.each support string template (#2337)

docs/api/index.md

@@ -196,7 +196,7 @@ You cannot use this syntax, when using Vitest as [type checker](/guide/testing-t
 :::
 
 ### test.each
-- **Type:** `(cases: ReadonlyArray<T>) => void`
+- **Type:** `(cases: ReadonlyArray<T>, ...args: any[]) => void`
 - **Alias:** `it.each`
 
   Use `test.each` when you need to run the same test with different variables.
@@ -243,6 +243,23 @@ You cannot use this syntax, when using Vitest as [type checker](/guide/testing-t
   // ✓ add(2, 1) -> 3
   ```
 
+  You can also access template string table.
+    * First row of variable name column headings separated with `|`
+    * One or more subsequent rows of data supplied as template literal expressions using ${value} syntax.
+
+    ```ts
+    test.each`
+      a               | b      | expected
+      ${1}            | ${1}   | ${2}
+      ${'a'}          | ${'b'} | ${'ab'}
+      ${[]}           | ${'b'} | ${'b'}
+      ${{}}           | ${'b'} | ${'[object Object]b'}
+      ${{ asd: 1 }}   | ${'b'} | ${'[object Object]b'}
+    `('returns $expected when $a is added $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
@@ -547,7 +564,7 @@ You cannot use this syntax, when using Vitest as [type checker](/guide/testing-t
 
 ### describe.each
 
-- **Type:** `(cases: ReadonlyArray<T>): (name: string, fn: (...args: T[]) => void, options?: number | TestOptions) => void`
+- **Type:** `(cases: ReadonlyArray<T>, ...args: any[]): (name: string, fn: (...args: T[]) => void, options?: number | TestOptions) => void`
 
   Use `describe.each` if you have more than one test that depends on the same data.
 
@@ -571,6 +588,25 @@ You cannot use this syntax, when using Vitest as [type checker](/guide/testing-t
   })
   ```
 
+  You can also access template string table.
+    * First row of variable name column headings separated with `|`
+    * One or more subsequent rows of data supplied as template literal expressions using ${value} syntax.
+
+    ```ts
+    describe.each`
+      a               | b      | expected
+      ${1}            | ${1}   | ${2}
+      ${'a'}          | ${'b'} | ${'ab'}
+      ${[]}           | ${'b'} | ${'b'}
+      ${{}}           | ${'b'} | ${'[object Object]b'}
+      ${{ asd: 1 }}   | ${'b'} | ${'[object Object]b'}
+    `('describe template string add($a, $b)', ({ a, b, expected }) => {
+      test(`returns ${expected}`, () => {
+        expect(a + b).toBe(expected)
+      })
+    })
+    ```
+
 ::: warning
 You cannot use this syntax, when using Vitest as [type checker](/guide/testing-types).
 :::

packages/vitest/src/runtime/suite.ts

@@ -180,8 +180,12 @@ function createSuite() {
     return createSuiteCollector(name, factory, mode, this.concurrent, this.shuffle, options)
   }
 
-  suiteFn.each = function<T>(this: { withContext: () => SuiteAPI }, cases: ReadonlyArray<T>) {
+  suiteFn.each = function<T>(this: { withContext: () => SuiteAPI }, cases: ReadonlyArray<T>, ...args: any[]) {
     const suite = this.withContext()
+
+    if (Array.isArray(cases) && args.length)
+      cases = formatTemplateString(cases, args)
+
     return (name: string, fn: (...args: T[]) => void, options?: number | TestOptions) => {
       const arrayOnlyCases = cases.every(Array.isArray)
       cases.forEach((i, idx) => {
@@ -212,9 +216,12 @@ function createTest(fn: (
 )) {
   const testFn = fn as any
 
-  testFn.each = function<T>(this: { withContext: () => TestAPI }, cases: ReadonlyArray<T>) {
+  testFn.each = function<T>(this: { withContext: () => TestAPI }, cases: ReadonlyArray<T>, ...args: any[]) {
     const test = this.withContext()
 
+    if (Array.isArray(cases) && args.length)
+      cases = formatTemplateString(cases, args)
+
     return (name: string, fn: (...args: T[]) => void, options?: number | TestOptions) => {
       const arrayOnlyCases = cases.every(Array.isArray)
       cases.forEach((i, idx) => {
@@ -272,3 +279,15 @@ function formatTitle(template: string, items: any[], idx: number) {
   }
   return formatted
 }
+
+function formatTemplateString(cases: any[], args: any[]): any[] {
+  const header = cases.join('').trim().replace(/ /g, '').split('\n').map(i => i.split('|'))[0]
+  const res: any[] = []
+  for (let i = 0; i < Math.floor((args.length) / header.length); i++) {
+    const oneCase: Record<string, any> = {}
+    for (let j = 0; j < header.length; j++)
+      oneCase[header[j]] = args[i * header.length + j] as any
+    res.push(oneCase)
+  }
+  return res
+}

packages/vitest/src/types/tasks.ts

@@ -130,6 +130,11 @@ interface TestEachFunction {
     fn: (...args: T[]) => Awaitable<void>,
     options?: number | TestOptions,
   ) => void
+  (...args: [TemplateStringsArray, ...any]): (
+    name: string,
+    fn: (...args: any[]) => Awaitable<void>,
+    options?: number | TestOptions,
+  ) => void
 }
 
 type ChainableTestAPI<ExtraContext = {}> = ChainableFunction<

test/core/test/each.test.ts

@@ -169,3 +169,42 @@ test.each([
   expect(value1).toBeNull()
   expect(value2).toBeNull()
 })
+
+describe.each`
+a             | b      | expected
+${1}          | ${1}   | ${2}
+${'a'}        | ${'b'} | ${'ab'}
+${[]}         | ${'b'} | ${'b'}
+${{}}         | ${'b'} | ${'[object Object]b'}
+${{ asd: 1 }} | ${'b'} | ${'[object Object]b'}
+`('describe template string add($a, $b)', ({ a, b, expected }) => {
+  test(`returns ${expected}`, () => {
+    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'}
+`('returns $expected when $a is added $b', ({ a, b, expected }) => {
+  expect(a + b).toBe(expected)
+})
+
+test.each`
+a       | b       | expected
+${true} | ${true} | ${true}
+`('($a && $b) -> $expected', ({ a, b, expected }) => {
+  expect(a && b).toBe(expected)
+})
+
+test.each`
+a             | b              | expected
+${{ val: 1 }} | ${{ val: 2 }}} | ${3}
+`('($a && $b) -> $expected', ({ a, b, expected }) => {
+  expect(a.val + b.val).toBe(expected)
+})
+