API 索引 #

下面的变量中使用了以下类型签名

type Awaitable<T> = T | PromiseLike<T>
type TestFunction = () => Awaitable<void>

interface TestOptions {
  timeout?: number
  retry?: number
}

type Awaitable<T> = T | PromiseLike<T>
type TestFunction = () => Awaitable<void>

interface TestOptions {
  timeout?: number
  retry?: number
}

当一个测试函数返回一个 promise 时，Vitest 将等待直到它被解决以收集异步的期望值。 如果 promise 被拒绝，测试将失败。

test #

• 类型: (name: string, fn: TestFunction, timeout?: number | TestOptions) => void

• 别名: it

  test 定义了一组关于测试期望的方法。它接收测试名称和一个含有测试期望的函数。

  同时，可以提供一个超时时限（以毫秒为单位）用于指定等待多长时间后终止测试，默认为 5 秒。你也可以通过 testTimeout 选项进行全局配置。

  ts

  import { expect, test } from 'vitest'
  
  test('should work as expected', () => {
    expect(Math.sqrt(4)).toBe(2)
  })
  

  import { expect, test } from 'vitest'
  
  test('should work as expected', () => {
    expect(Math.sqrt(4)).toBe(2)
  })
  

test.skip #

• 类型: (name: string, fn: TestFunction, timeout?: number | TestOptions) => void

• 别名: it.skip

  如果你想跳过运行某些测试，但由于一些原因不想删除代码，你可以使用 test.skip 来避免运行它们。

  ts

  import { assert, test } from 'vitest'
  
  test.skip('skipped test', () => {
    // 跳过测试，没有错误
    assert.equal(Math.sqrt(4), 3)
  })
  

  import { assert, test } from 'vitest'
  
  test.skip('skipped test', () => {
    // 跳过测试，没有错误
    assert.equal(Math.sqrt(4), 3)
  })
  

test.skipIf #

• 类型: (condition: any) => Test

• 别名: it.skipIf

  在某些情况下，你可能会在不同的环境中多次运行测试，并且某些测试可能基于特定环境下运行。只要条件成立，你就可以使用 test.skipIf 跳过测试，而不是用 if 包裹测试代码。

  ts

  import { assert, test } from 'vitest'
  
  const isDev = process.env.NODE_ENV === 'development'
  
  test.skipIf(isDev)('prod only test', () => {
    // 只在生产环境下进行测试
  })
  

  import { assert, test } from 'vitest'
  
  const isDev = process.env.NODE_ENV === 'development'
  
  test.skipIf(isDev)('prod only test', () => {
    // 只在生产环境下进行测试
  })
  

test.runIf #

• 类型: (condition: any) => Test
• 别名: it.runIf

test.skipIf 的相反面。

import { assert, test } from 'vitest'

const isDev = process.env.NODE_ENV === 'development'

test.runIf(isDev)('dev only test', () => {
  // 只在开发环境下进行测试
})

import { assert, test } from 'vitest'

const isDev = process.env.NODE_ENV === 'development'

test.runIf(isDev)('dev only test', () => {
  // 只在开发环境下进行测试
})

test.only #

• 类型: (name: string, fn: TestFunction, timeout?: number) => void

• 别名: it.only

  使用 test.only 只允许特定条件的测试套件。这在调试模式下是很有用的。

  同时，可以提供一个超时时限（以毫秒为单位）用于指定等待多长时间后终止测试，默认为 5 秒。你也可以通过 testTimeout 选项进行全局配置。

  ts

  import { assert, test } from 'vitest'
  
  test.only('test', () => {
    // 仅运行此测试（以及仅标记有的其他测试）
    assert.equal(Math.sqrt(4), 2)
  })
  

  import { assert, test } from 'vitest'
  
  test.only('test', () => {
    // 仅运行此测试（以及仅标记有的其他测试）
    assert.equal(Math.sqrt(4), 2)
  })
  

  有时候只运行一个特定文件中的 only 测试用例是很有用的，这可以忽略整个测试套件中的所有其他测试用例，避免污染输出。

  为了做到这一点，运行 vitest 命令并带上包含有问题的测试的特定文件。

  # vitest interesting.test.ts
  

  # vitest interesting.test.ts
  

test.concurrent #

• 类型: (name: string, fn: TestFunction, timeout?: number) => void

• 别名: it.concurrent

  test.concurrent 将连续测试标记为并行运行。 它接收测试名称、带有要收集的测试的异步函数以及可选的超时时间（以毫秒为单位）。

  ts

  import { describe, test } from 'vitest'
  
  // 标有并发的两个测试将并发运行
  describe('suite', () => {
    test('serial test', async () => {
      /* ... */
    })
    test.concurrent('concurrent test 1', async () => {
      /* ... */
    })
    test.concurrent('concurrent test 2', async () => {
      /* ... */
    })
  })
  

  import { describe, test } from 'vitest'
  
  // 标有并发的两个测试将并发运行
  describe('suite', () => {
    test('serial test', async () => {
      /* ... */
    })
    test.concurrent('concurrent test 1', async () => {
      /* ... */
    })
    test.concurrent('concurrent test 2', async () => {
      /* ... */
    })
  })
  

  test.skip、test.only 和 test.todo 适用于并发测试。 以下所有组合均有效：

  ts

  test.concurrent(/* ... */)
  test.skip.concurrent(/* ... */) // or test.concurrent.skip(/* ... */)
  test.only.concurrent(/* ... */) // or test.concurrent.only(/* ... */)
  test.todo.concurrent(/* ... */) // or test.concurrent.todo(/* ... */)
  

  test.concurrent(/* ... */)
  test.skip.concurrent(/* ... */) // or test.concurrent.skip(/* ... */)
  test.only.concurrent(/* ... */) // or test.concurrent.only(/* ... */)
  test.todo.concurrent(/* ... */) // or test.concurrent.todo(/* ... */)
  

  在异步并发测试中使用快照时，由于 JavaScript 的限制，你需要使用 测试环境 中的 expect 来确保检测到正确的测试。

  ts

  test.concurrent('test 1', async ({ expect }) => {
    expect(foo).toMatchSnapshot()
  })
  test.concurrent('test 2', async ({ expect }) => {
    expect(foo).toMatchSnapshot()
  })
  

  test.concurrent('test 1', async ({ expect }) => {
    expect(foo).toMatchSnapshot()
  })
  test.concurrent('test 2', async ({ expect }) => {
    expect(foo).toMatchSnapshot()
  })
  

test.todo #

• 类型: (name: string) => void

• 别名: it.todo

  使用 test.todo 来存根测试，以便稍后实现。 测试报告中将显示一个条目，以便告知你还有多少测试未实现。

  ts

  // 测试的报告中将显示一个记录
  test.todo('unimplemented test')
  

  // 测试的报告中将显示一个记录
  test.todo('unimplemented test')
  

test.fails #

• 类型: (name: string, fn: TestFunction, timeout?: number) => void

• 别名: it.fails

  使用 test.fails 来指示测试断言将显式失败。

  ts

  import { expect, test } from 'vitest'
  const myAsyncFunc = () => new Promise(resolve => resolve(1))
  test.fails('fail test', async () => {
    await expect(myAsyncFunc()).rejects.toBe(1)
  })
  

  import { expect, test } from 'vitest'
  const myAsyncFunc = () => new Promise(resolve => resolve(1))
  test.fails('fail test', async () => {
    await expect(myAsyncFunc()).rejects.toBe(1)
  })
  

test.each #

• 类型: (cases: ReadonlyArray<T>, ...args: any[]) => void

• 别名: it.each

  当你需要使用不同的变量运行相同的测试时，请使用 test.each。 你可以按照测试参数的顺序，在测试名称插入符合printf 格式的参数。

  • %s: 字符串
  • %d: 数值
  • %i: 整数
  • %f: 小数
  • %j: json 格式
  • %o: 对象
  • %#: 对应的测试参数下标
  • %%: 单个百分比符号 ('%')
  ts

  test.each([
    [1, 1, 2],
    [1, 2, 3],
    [2, 1, 3],
  ])('add(%i, %i) -> %i', (a, b, expected) => {
    expect(a + b).toBe(expected)
  })
  
  // 它将返回如下内容
  // ✓ add(1, 1) -> 2
  // ✓ add(1, 2) -> 3
  // ✓ add(2, 1) -> 3
  

  test.each([
    [1, 1, 2],
    [1, 2, 3],
    [2, 1, 3],
  ])('add(%i, %i) -> %i', (a, b, expected) => {
    expect(a + b).toBe(expected)
  })
  
  // 它将返回如下内容
  // ✓ add(1, 1) -> 2
  // ✓ add(1, 2) -> 3
  // ✓ add(2, 1) -> 3
  

  如果你使用对象作为参数，你还可以使用 $ 前缀访问对象属性：

  ts

  test.each([
    { a: 1, b: 1, expected: 2 },
    { a: 1, b: 2, expected: 3 },
    { a: 2, b: 1, expected: 3 },
  ])('add($a, $b) -> $expected', ({ a, b, expected }) => {
    expect(a + b).toBe(expected)
  })
  
  // this will return
  // ✓ add(1, 1) -> 2
  // ✓ add(1, 2) -> 3
  // ✓ add(2, 1) -> 3
  

  test.each([
    { a: 1, b: 1, expected: 2 },
    { a: 1, b: 2, expected: 3 },
    { a: 2, b: 1, expected: 3 },
  ])('add($a, $b) -> $expected', ({ a, b, expected }) => {
    expect(a + b).toBe(expected)
  })
  
  // this will return
  // ✓ add(1, 1) -> 2
  // ✓ add(1, 2) -> 3
  // ✓ add(2, 1) -> 3
  

  如果你使用对象作为参数，你还可以使用“.”访问对象属性：

  ts

  test.each`
    a             | b      | expected
    ${{ val: 1 }} | ${'b'} | ${'1b'}
    ${{ val: 2 }} | ${'b'} | ${'2b'}
    ${{ val: 3 }} | ${'b'} | ${'3b'}
  `('add($a.val, $b) -> $expected', ({ a, b, expected }) => {
    expect(a.val + b).toBe(expected)
  })
  
  // this will return
  // ✓ add(1, b) -> 1b
  // ✓ add(2, b) -> 2b
  // ✓ add(3, b) -> 3b
  

  test.each`
    a             | b      | expected
    ${{ val: 1 }} | ${'b'} | ${'1b'}
    ${{ val: 2 }} | ${'b'} | ${'2b'}
    ${{ val: 3 }} | ${'b'} | ${'3b'}
  `('add($a.val, $b) -> $expected', ({ a, b, expected }) => {
    expect(a.val + b).toBe(expected)
  })
  
  // this will return
  // ✓ add(1, b) -> 1b
  // ✓ add(2, b) -> 2b
  // ✓ add(3, b) -> 3b
  

从 Vitest 0.25.3 开始，你可以使用模板字符串表。

• 第一行应该是列名，使用 | 分隔；
• 使用 ${value} 语法作为模板文本表达式，为一个或多个后续数据行提供数据。

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
  ${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)
})

如果你想访问 TestContext，请在单个测试中使用 describe.each。

bench #

• 类型: (name: string, fn: BenchFunction, options?: BenchOptions) => void

bench 定义了一个基准。 在 Vitest 术语中，基准是定义一系列操作的函数。 Vitest 多次运行此函数以显示不同的性能结果。

Vitest 在底层使用 tinybench 库，继承其所有可用选项作为第三个参数。

import { bench } from 'vitest'

bench(
  'normal sorting',
  () => {
    const x = [1, 5, 4, 2, 3]
    x.sort((a, b) => {
      return a - b
    })
  },
  { time: 1000 }
)

import { bench } from 'vitest'

bench(
  'normal sorting',
  () => {
    const x = [1, 5, 4, 2, 3]
    x.sort((a, b) => {
      return a - b
    })
  },
  { time: 1000 }
)

export interface Options {
  /**
   * time needed for running a benchmark task (milliseconds)
   * @default 500
   */
  time?: number

  /**
   * number of times that a task should run if even the time option is finished
   * @default 10
   */
  iterations?: number

  /**
   * function to get the current timestamp in milliseconds
   */
  now?: () => number

  /**
   * An AbortSignal for aborting the benchmark
   */
  signal?: AbortSignal

  /**
   * warmup time (milliseconds)
   * @default 100ms
   */
  warmupTime?: number

  /**
   * warmup iterations
   * @default 5
   */
  warmupIterations?: number

  /**
   * setup function to run before each benchmark task (cycle)
   */
  setup?: Hook

  /**
   * teardown function to run after each benchmark task (cycle)
   */
  teardown?: Hook
}

export interface Options {
  /**
   * time needed for running a benchmark task (milliseconds)
   * @default 500
   */
  time?: number

  /**
   * number of times that a task should run if even the time option is finished
   * @default 10
   */
  iterations?: number

  /**
   * function to get the current timestamp in milliseconds
   */
  now?: () => number

  /**
   * An AbortSignal for aborting the benchmark
   */
  signal?: AbortSignal

  /**
   * warmup time (milliseconds)
   * @default 100ms
   */
  warmupTime?: number

  /**
   * warmup iterations
   * @default 5
   */
  warmupIterations?: number

  /**
   * setup function to run before each benchmark task (cycle)
   */
  setup?: Hook

  /**
   * teardown function to run after each benchmark task (cycle)
   */
  teardown?: Hook
}

bench.skip #

• 类型: (name: string, fn: BenchFunction, options?: BenchOptions) => void

你可以使用 bench.skip 语法跳过运行某些基准测试。

import { bench } from 'vitest'

bench.skip('normal sorting', () => {
  const x = [1, 5, 4, 2, 3]
  x.sort((a, b) => {
    return a - b
  })
})

import { bench } from 'vitest'

bench.skip('normal sorting', () => {
  const x = [1, 5, 4, 2, 3]
  x.sort((a, b) => {
    return a - b
  })
})

bench.only #

• 类型: (name: string, fn: BenchFunction, options?: BenchOptions) => void

使用 bench.only 仅在指定测试套件中运行某些基准测试。这在调试时很有用。

import { bench } from 'vitest'

bench.only('normal sorting', () => {
  const x = [1, 5, 4, 2, 3]
  x.sort((a, b) => {
    return a - b
  })
})

import { bench } from 'vitest'

bench.only('normal sorting', () => {
  const x = [1, 5, 4, 2, 3]
  x.sort((a, b) => {
    return a - b
  })
})

bench.todo #

• 类型: (name: string) => void

使用 bench.todo 来存根基准测试，以便稍后实现。

import { bench } from 'vitest'

bench.todo('unimplemented test')

import { bench } from 'vitest'

bench.todo('unimplemented test')

describe #

当你在文件的顶层使用 test 或 bench 时，它们会被收集为它的隐式套件的一部分。 使用 describe 你可以在当前上下文中定义一个新套件，作为一组相关的测试或基准以及其他嵌套套件。 测试套件可让你组织测试和基准测试，从而使报告更加清晰。

// basic.spec.ts
// organizing tests

import { describe, expect, test } from 'vitest'

const person = {
  isActive: true,
  age: 32,
}

describe('person', () => {
  test('person is defined', () => {
    expect(person).toBeDefined()
  })

  test('is active', () => {
    expect(person.isActive).toBeTruthy()
  })

  test('age limit', () => {
    expect(person.age).toBeLessThanOrEqual(32)
  })
})

// basic.spec.ts
// organizing tests

import { describe, expect, test } from 'vitest'

const person = {
  isActive: true,
  age: 32,
}

describe('person', () => {
  test('person is defined', () => {
    expect(person).toBeDefined()
  })

  test('is active', () => {
    expect(person.isActive).toBeTruthy()
  })

  test('age limit', () => {
    expect(person.age).toBeLessThanOrEqual(32)
  })
})

如果你需要有测试层次结构，你还可以嵌套描述块：

// basic.bench.ts
// organizing benchmarks

import { bench, describe } from 'vitest'

describe('sort', () => {
  bench('normal', () => {
    const x = [1, 5, 4, 2, 3]
    x.sort((a, b) => {
      return a - b
    })
  })

  bench('reverse', () => {
    const x = [1, 5, 4, 2, 3]
    x.reverse().sort((a, b) => {
      return a - b
    })
  })
})

// basic.bench.ts
// organizing benchmarks

import { bench, describe } from 'vitest'

describe('sort', () => {
  bench('normal', () => {
    const x = [1, 5, 4, 2, 3]
    x.sort((a, b) => {
      return a - b
    })
  })

  bench('reverse', () => {
    const x = [1, 5, 4, 2, 3]
    x.reverse().sort((a, b) => {
      return a - b
    })
  })
})

如果你有测试或基准的层次结构，你还可以嵌套描述块：

import { describe, expect, test } from 'vitest'

const numberToCurrency = (value) => {
  if (typeof value !== 'number')
    throw new Error('Value must be a number')

  return value
    .toFixed(2)
    .toString()
    .replace(/\B(?=(\d{3})+(?!\d))/g, ',')
}

describe('numberToCurrency', () => {
  describe('given an invalid number', () => {
    test('composed of non-numbers to throw error', () => {
      expect(() => numberToCurrency('abc')).toThrowError()
    })
  })

  describe('given a valid number', () => {
    test('returns the correct currency format', () => {
      expect(numberToCurrency(10000)).toBe('10,000.00')
    })
  })
})

import { describe, expect, test } from 'vitest'

const numberToCurrency = (value) => {
  if (typeof value !== 'number')
    throw new Error('Value must be a number')

  return value
    .toFixed(2)
    .toString()
    .replace(/\B(?=(\d{3})+(?!\d))/g, ',')
}

describe('numberToCurrency', () => {
  describe('given an invalid number', () => {
    test('composed of non-numbers to throw error', () => {
      expect(() => numberToCurrency('abc')).toThrowError()
    })
  })

  describe('given a valid number', () => {
    test('returns the correct currency format', () => {
      expect(numberToCurrency(10000)).toBe('10,000.00')
    })
  })
})

describe.skip #

• 类型: (name: string, fn: TestFunction, options?: number | TestOptions) => void

  在测试套件中使用 describe.skip 避免运行特定的描述块。

  ts

  import { assert, describe, test } from 'vitest'
  
  describe.skip('skipped suite', () => {
    test('sqrt', () => {
      // 跳过测试套件，不会有错误
      assert.equal(Math.sqrt(4), 3)
    })
  })
  

  import { assert, describe, test } from 'vitest'
  
  describe.skip('skipped suite', () => {
    test('sqrt', () => {
      // 跳过测试套件，不会有错误
      assert.equal(Math.sqrt(4), 3)
    })
  })
  

describe.skipIf #

• 类型: (condition: any) => void

  在某些情况下，你可能会在不同的环境中多次运行套件，并且某些套件可能是特定于环境的。你可以使用 describe.skipIf 在条件为真时跳过套件，而不是用 if 包装套件。

  ts

  import { assert, test } from 'vitest'
  
  const isDev = process.env.NODE_ENV === 'development'
  
  describe.skipIf(isDev)('prod only test', () => {
    // this test only runs in production
  })
  

  import { assert, test } from 'vitest'
  
  const isDev = process.env.NODE_ENV === 'development'
  
  describe.skipIf(isDev)('prod only test', () => {
    // this test only runs in production
  })
  

describe.only #

• 类型: (name: string, fn: TestFunction, options?: number | TestOptions) => void

  使用 describe.only 仅运行指定的测试套件。

  ts

  // 仅运行此测试套件（以及仅标有的其他测试套件）
  describe.only('suite', () => {
    test('sqrt', () => {
      assert.equal(Math.sqrt(4), 3)
    })
  })
  
  describe('other suite', () => {
    // ... 测试套件将会被跳过
  })
  

  // 仅运行此测试套件（以及仅标有的其他测试套件）
  describe.only('suite', () => {
    test('sqrt', () => {
      assert.equal(Math.sqrt(4), 3)
    })
  })
  
  describe('other suite', () => {
    // ... 测试套件将会被跳过
  })
  

  有时候只运行一个特定文件中的 only 测试用例是很有用的，这可以忽略整个测试套件中的所有其他测试用例，避免污染输出。

  为了做到这一点，运行 vitest 命令并带上包含有问题的测试的特定文件。

  # vitest interesting.test.ts
  

  # vitest interesting.test.ts
  

describe.concurrent #

• 类型: (name: string, fn: TestFunction, options?: number | TestOptions) => void

  使用 describe.concurrent 在测试套件中将每个测试标记为并发。

  ts

  // 该测试套件中的所有测试都将并行运行
  describe.concurrent('suite', () => {
    test('concurrent test 1', async () => {
      /* ... */
    })
    test('concurrent test 2', async () => {
      /* ... */
    })
    test.concurrent('concurrent test 3', async () => {
      /* ... */
    })
  })
  

  // 该测试套件中的所有测试都将并行运行
  describe.concurrent('suite', () => {
    test('concurrent test 1', async () => {
      /* ... */
    })
    test('concurrent test 2', async () => {
      /* ... */
    })
    test.concurrent('concurrent test 3', async () => {
      /* ... */
    })
  })
  

  .skip，.only 和 .todo 可以与并发测试套件一起使用。以下所有组合均有效：

  ts

  describe.concurrent(/* ... */)
  describe.skip.concurrent(/* ... */) // or describe.concurrent.skip(/* ... */)
  describe.only.concurrent(/* ... */) // or describe.concurrent.only(/* ... */)
  describe.todo.concurrent(/* ... */) // or describe.concurrent.todo(/* ... */)
  

  describe.concurrent(/* ... */)
  describe.skip.concurrent(/* ... */) // or describe.concurrent.skip(/* ... */)
  describe.only.concurrent(/* ... */) // or describe.concurrent.only(/* ... */)
  describe.todo.concurrent(/* ... */) // or describe.concurrent.todo(/* ... */)
  

在异步并发测试中使用快照时，由于 JavaScript 的限制，你需要使用 测试环境 中的 expect 来确保检测到正确的测试。

describe.concurrent('suite', () => {
  test('concurrent test 1', async ({ expect }) => {
    expect(foo).toMatchSnapshot()
  })
  test('concurrent test 2', async ({ expect }) => {
    expect(foo).toMatchSnapshot()
  })
})

describe.concurrent('suite', () => {
  test('concurrent test 1', async ({ expect }) => {
    expect(foo).toMatchSnapshot()
  })
  test('concurrent test 2', async ({ expect }) => {
    expect(foo).toMatchSnapshot()
  })
})

describe.shuffle #

• 类型: (name: string, fn: TestFunction, options?: number | TestOptions) => void

  Vitest 提供了一种通过 CLI 标志 --sequence.shuffle 或配置选项 sequence.shuffle 来随机运行所有测试的方法，但是如果你只想让测试套件的一部分以随机顺序运行测试，可以使用此标志对其进行标记。

  ts

  describe.shuffle('suite', () => {
    test('random test 1', async () => {
      /* ... */
    })
    test('random test 2', async () => {
      /* ... */
    })
    test('random test 3', async () => {
      /* ... */
    })
  })
  // 执行顺序依赖于 sequence.seed 的配置选项(默认为 Date.now())
  

  describe.shuffle('suite', () => {
    test('random test 1', async () => {
      /* ... */
    })
    test('random test 2', async () => {
      /* ... */
    })
    test('random test 3', async () => {
      /* ... */
    })
  })
  // 执行顺序依赖于 sequence.seed 的配置选项(默认为 Date.now())
  

.skip，.only 和 .todo 可以与并发测试套件一起使用。以下所有组合均有效：

describe.todo #

• 类型: (name: string) => void

  使用 describe.todo 将稍后实现的测试套件进行存档。测试报告中将显示一个记录，以便你知道还多少条未实现的测试。

  ts

  // 测试套件的报告中将显示一个记录
  describe.todo('unimplemented suite')
  

  // 测试套件的报告中将显示一个记录
  describe.todo('unimplemented suite')
  

describe.each #

• 类型: (cases: ReadonlyArray<T>, ...args: any[]): (name: string, fn: (...args: T[]) => void, options?: number | TestOptions) => void

  如果你有多个测试依赖相同的数据，可以使用 describe.each。

  ts

  describe.each([
    { a: 1, b: 1, expected: 2 },
    { a: 1, b: 2, expected: 3 },
    { a: 2, b: 1, expected: 3 },
  ])('describe object add($a, $b)', ({ a, b, expected }) => {
    test(`returns ${expected}`, () => {
      expect(a + b).toBe(expected)
    })
  
    test(`returned value not be greater than ${expected}`, () => {
      expect(a + b).not.toBeGreaterThan(expected)
    })
  
    test(`returned value not be less than ${expected}`, () => {
      expect(a + b).not.toBeLessThan(expected)
    })
  })
  

  describe.each([
    { a: 1, b: 1, expected: 2 },
    { a: 1, b: 2, expected: 3 },
    { a: 2, b: 1, expected: 3 },
  ])('describe object add($a, $b)', ({ a, b, expected }) => {
    test(`returns ${expected}`, () => {
      expect(a + b).toBe(expected)
    })
  
    test(`returned value not be greater than ${expected}`, () => {
      expect(a + b).not.toBeGreaterThan(expected)
    })
  
    test(`returned value not be less than ${expected}`, () => {
      expect(a + b).not.toBeLessThan(expected)
    })
  })
  

  从 Vitest 0.25.3 开始，你可以使用模板字符串表。

  • 第一行应该是列名，使用 | 分隔；
  • 使用 ${value} 语法作为模板文本表达式，为一个或多个后续数据行提供数据。
  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)
    })
  })
  

  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)
    })
  })
  

expect #

• 类型: ExpectStatic & (actual: any) => Assertions

  expect 用来创建断言。在当前上下文中，可以使用 assertions 方法来断言一个语句。 Vitest 默认提供 chai 进行断言，同时基于 chai 实现兼容 Jest 的断言语句。

  例如，这里会断言 input 的值是否等于 2 ，如果它们不相等，断言则会抛出错误，并且测试失败。

  ts

  import { expect } from 'vitest'
  
  const input = Math.sqrt(4)
  
  expect(input).to.equal(2) // chai API
  expect(input).toBe(2) // jest API
  

  import { expect } from 'vitest'
  
  const input = Math.sqrt(4)
  
  expect(input).to.equal(2) // chai API
  expect(input).toBe(2) // jest API
  

  从技术上来说，这里并没有使用 test 方法，所以我们在控制台会看到 Nodejs 的报错，而不是 Vitest 的报错。想要了解更多关于 test 的信息，请参阅 test 章节。

  此外，expect 可用于静态访问匹配器功能，这个后面会介绍。

not #

使用 not 将会否定断言。举例，此代码断言 input 的值不等于 2。如果它们相等，断言则会抛出错误，并且测试失败。

import { expect, test } from 'vitest'

const input = Math.sqrt(16)

expect(input).not.to.equal(2) // chai API
expect(input).not.toBe(2) // jest API

import { expect, test } from 'vitest'

const input = Math.sqrt(16)

expect(input).not.to.equal(2) // chai API
expect(input).not.toBe(2) // jest API

toBe #

• 类型: (value: any) => Awaitable<void>

  toBe 可用于断言基础对象是否相等，或者对象是否共享相同的引用。它相当于调用了 expect(Object.is(3, 3)).toBe(true)。 如果对象不相同，但你想检查它们的结构是否相同，则可以使用 toEqual。

  例如，下面的测试将会检查 stock 是否有 13 个苹果。

  ts

  import { expect, test } from 'vitest'
  
  const stock = {
    type: 'apples',
    count: 13,
  }
  
  test('stock has 13 apples', () => {
    expect(stock.type).toBe('apples')
    expect(stock.count).toBe(13)
  })
  
  test('stocks are the same', () => {
    const refStock = stock // 相同的引用
  
    expect(stock).toBe(refStock)
  })
  

  import { expect, test } from 'vitest'
  
  const stock = {
    type: 'apples',
    count: 13,
  }
  
  test('stock has 13 apples', () => {
    expect(stock.type).toBe('apples')
    expect(stock.count).toBe(13)
  })
  
  test('stocks are the same', () => {
    const refStock = stock // 相同的引用
  
    expect(stock).toBe(refStock)
  })
  

  尽量不要将 toBe 与浮点数一起使用。由于 JavaScript 会对它们进行四舍五入，例如 0.1 + 0.2 的结果严格来说并不是 0.3 。如果需要可靠地断言浮点数，请使用 toBeCloseTo 进行断言。

toBeCloseTo #

• 类型: (value: number, numDigits?: number) => Awaitable<void>

  使用 toBeCloseTo 进行浮点数的比较。可以选择使用 numDigits 参数限制小数点后的检查位数。例如：

  ts

  import { expect, test } from 'vitest'
  
  test.fails('decimals are not equal in javascript', () => {
    expect(0.2 + 0.1).toBe(0.3) // 0.2 + 0.1 is 0.30000000000000004
  })
  
  test('decimals are rounded to 5 after the point', () => {
    // 0.2 + 0.1 is 0.30000 | "000000000004" removed
    expect(0.2 + 0.1).toBeCloseTo(0.3, 5)
    // nothing from 0.30000000000000004 is removed
    expect(0.2 + 0.1).not.toBeCloseTo(0.3, 50)
  })
  

  import { expect, test } from 'vitest'
  
  test.fails('decimals are not equal in javascript', () => {
    expect(0.2 + 0.1).toBe(0.3) // 0.2 + 0.1 is 0.30000000000000004
  })
  
  test('decimals are rounded to 5 after the point', () => {
    // 0.2 + 0.1 is 0.30000 | "000000000004" removed
    expect(0.2 + 0.1).toBeCloseTo(0.3, 5)
    // nothing from 0.30000000000000004 is removed
    expect(0.2 + 0.1).not.toBeCloseTo(0.3, 50)
  })
  

toBeDefined #

• 类型: () => Awaitable<void>

  toBeDefined 断言检查值是否不等于 undefined 。在检查函数是否有返回值时非常有用。

  ts

  import { expect, test } from 'vitest'
  
  const getApples = () => 3
  
  test('function returned something', () => {
    expect(getApples()).toBeDefined()
  })
  

  import { expect, test } from 'vitest'
  
  const getApples = () => 3
  
  test('function returned something', () => {
    expect(getApples()).toBeDefined()
  })
  

toBeUndefined #

• 类型: () => Awaitable<void>

  与 toBeDefined 相反，toBeUndefined 断言检查值是否等于 undefined 。在检查函数是否没有返回任何内容时非常有用。

  ts

  import { expect, test } from 'vitest'
  
  function getApplesFromStock(stock) {
    if (stock === 'Bill')
      return 13
  }
  
  test('mary doesn\'t have a stock', () => {
    expect(getApplesFromStock('Mary')).toBeUndefined()
  })
  

  import { expect, test } from 'vitest'
  
  function getApplesFromStock(stock) {
    if (stock === 'Bill')
      return 13
  }
  
  test('mary doesn\'t have a stock', () => {
    expect(getApplesFromStock('Mary')).toBeUndefined()
  })
  

toBeTruthy #

• 类型: () => Awaitable<void>

  toBeTruthy 会将检查值转换为布尔值，断言该值是否为 true 。该方法在当你不关心检查值的内容，而只想知道它是否可以转换为 true 时很有用。

  例如下面这段代码，我们就不需要关心 stocks.getInfo 的返回值，可能是复杂的对象、字符串或者是其他内容，代码仍然可以运行。

  ts

  import { Stocks } from './stocks'
  const stocks = new Stocks()
  stocks.sync('Bill')
  if (stocks.getInfo('Bill'))
    stocks.sell('apples', 'Bill')
  

  import { Stocks } from './stocks'
  const stocks = new Stocks()
  stocks.sync('Bill')
  if (stocks.getInfo('Bill'))
    stocks.sell('apples', 'Bill')
  

  所以如果我们想测试 stocks.getInfo 是否为 true，我们可以这样写：

  ts

  import { expect, test } from 'vitest'
  import { Stocks } from './stocks'
  const stocks = new Stocks()
  
  test('if we know Bill stock, sell apples to him', () => {
    stocks.sync('Bill')
    expect(stocks.getInfo('Bill')).toBeTruthy()
  })
  

  import { expect, test } from 'vitest'
  import { Stocks } from './stocks'
  const stocks = new Stocks()
  
  test('if we know Bill stock, sell apples to him', () => {
    stocks.sync('Bill')
    expect(stocks.getInfo('Bill')).toBeTruthy()
  })
  

  JavaScript 中除了 false ，0 ，'' ，null ，undefined 和 NaN，其他一切都是为真。

toBeFalsy #

• 类型: () => Awaitable<void>

  toBeFalsy 会将检测值转换为布尔值，断言该值是否为 false。该方法在当你不关心该检查值的内容，但只想知道它是否可以转换为 false 时很有用。

  例如下面这段代码，我们就不需要关心 stocks.stockFailed 的返回值，可能是复杂的对象、字符串或者是其他内容，代码仍然可以运行。

  ts

  import { Stocks } from './stocks'
  const stocks = new Stocks()
  stocks.sync('Bill')
  if (!stocks.stockFailed('Bill'))
    stocks.sell('apples', 'Bill')
  

  import { Stocks } from './stocks'
  const stocks = new Stocks()
  stocks.sync('Bill')
  if (!stocks.stockFailed('Bill'))
    stocks.sell('apples', 'Bill')
  

  所以如果我们想测试 stocks.stockFailed 是否为 false，我们可以这样写：

  ts

  import { expect, test } from 'vitest'
  import { Stocks } from './stocks'
  const stocks = new Stocks()
  
  test('if Bill stock hasn\'t failed, sell apples to him', () => {
    stocks.syncStocks('Bill')
    expect(stocks.stockFailed('Bill')).toBeFalsy()
  })
  

  import { expect, test } from 'vitest'
  import { Stocks } from './stocks'
  const stocks = new Stocks()
  
  test('if Bill stock hasn\'t failed, sell apples to him', () => {
    stocks.syncStocks('Bill')
    expect(stocks.stockFailed('Bill')).toBeFalsy()
  })
  

  JavaScript 中除了 false ，0 ，'' ，null ，undefined 和 NaN，其他一切都是为真。

toBeNull #

• 类型: () => Awaitable<void>

  toBeNull 将简单地断言检查值是否为 null。 是 .toBe(null) 的别名。

  ts

  import { expect, test } from 'vitest'
  
  function apples() {
    return null
  }
  
  test('we don\'t have apples', () => {
    expect(apples()).toBeNull()
  })
  

  import { expect, test } from 'vitest'
  
  function apples() {
    return null
  }
  
  test('we don\'t have apples', () => {
    expect(apples()).toBeNull()
  })