Test API Reference

The following types are used in the type signatures below

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

interface TestOptions {
  /**
   * Will fail the test if it takes too long to execute
   */
  timeout?: number
  /**
   * Will retry the test specific number of times if it fails
   *
   * @default 0
   */
  retry?: number
  /**
   * Will repeat the same test several times even if it fails each time
   * If you have "retry" option and it fails, it will use every retry in each cycle
   * Useful for debugging random failings
   *
   * @default 0
   */
  repeats?: number
}

Vitest 1.3.0 deprecates the use of options as the last parameter. You will see a deprecation message until 2.0.0 when this syntax will be removed. If you need to pass down options, use test function's second argument:

import { test } from 'vitest'

test('flaky test', () => {}, { retry: 3 }) 
test('flaky test', { retry: 3 }, () => {})

When a test function returns a promise, the runner will wait until it is resolved to collect async expectations. If the promise is rejected, the test will fail.

TIP

In Jest, TestFunction can also be of type (done: DoneCallback) => void. If this form is used, the test will not be concluded until done is called. You can achieve the same using an async function, see the Migration guide Done Callback section.

Since Vitest 1.3.0 most options support both dot-syntax and object-syntax allowing you to use whatever style you prefer.

dot-syntaxobject-syntax 1.3.0+

import {  } from 'vitest'

.('skipped test', () => {
  // some logic that fails right now
})

import {  } from 'vitest'

('skipped test', { : true }, () => {
  // some logic that fails right now
})

test

Alias: it

test defines a set of related expectations. It receives the test name and a function that holds the expectations to test.

Optionally, you can provide a timeout (in milliseconds) for specifying how long to wait before terminating. The default is 5 seconds, and can be configured globally with testTimeout

import { ,  } from 'vitest'

('should work as expected', () => {
  (.(4)).(2)
})

test.extend 0.32.3+

Alias: it.extend

Use test.extend to extend the test context with custom fixtures. This will return a new test and it's also extendable, so you can compose more fixtures or override existing ones by extending it as you need. See Extend Test Context for more information.

import { expect, test } from 'vitest'

const todos = []
const archive = []

const myTest = test.extend({
  todos: async ({ task }, use) => {
    todos.push(1, 2, 3)
    await use(todos)
    todos.length = 0
  },
  archive
})

myTest('add item', ({ todos }) => {
  expect(todos.length).toBe(3)

  todos.push(4)
  expect(todos.length).toBe(4)
})

test.skip

Alias: it.skip

If you want to skip running certain tests, but you don't want to delete the code due to any reason, you can use test.skip to avoid running them.

import { ,  } from 'vitest'

.('skipped test', () => {
  // Test skipped, no error
  .(.(4), 3)
})

You can also skip test by calling skip on its context dynamically:

import { ,  } from 'vitest'

('skipped test', () => {
  .()
  // Test skipped, no error
  .(.(4), 3)
})

test.skipIf

Alias: it.skipIf

In some cases you might run tests multiple times with different environments, and some of the tests might be environment-specific. Instead of wrapping the test code with if, you can use test.skipIf to skip the test whenever the condition is truthy.

import { ,  } from 'vitest'

const  = .. === 'development'

.()('prod only test', () => {
  // this test only runs in production
})

WARNING

You cannot use this syntax, when using Vitest as type checker.

test.runIf

Alias: it.runIf

Opposite of test.skipIf.

import { ,  } from 'vitest'

const  = .. === 'development'

.()('dev only test', () => {
  // this test only runs in development
})

WARNING

You cannot use this syntax, when using Vitest as type checker.

test.only

Alias: it.only

Use test.only to only run certain tests in a given suite. This is useful when debugging.

Optionally, you can provide a timeout (in milliseconds) for specifying how long to wait before terminating. The default is 5 seconds, and can be configured globally with testTimeout.

import { ,  } from 'vitest'

.('test', () => {
  // Only this test (and others marked with only) are run
  .(.(4), 2)
})

Sometimes it is very useful to run only tests in a certain file, ignoring all other tests from the whole test suite, which pollute the output.

In order to do that run vitest with specific file containing the tests in question.

# vitest interesting.test.ts

test.concurrent

Alias: it.concurrent

test.concurrent marks consecutive tests to be run in parallel. It receives the test name, an async function with the tests to collect, and an optional timeout (in milliseconds).

import { ,  } from 'vitest'

// The two tests marked with concurrent will be run in parallel
('suite', () => {
  ('serial test', async () => { /* ... */ })
  .('concurrent test 1', async () => { /* ... */ })
  .('concurrent test 2', async () => { /* ... */ })
})

test.skip, test.only, and test.todo works with concurrent tests. All the following combinations are valid:

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

When running concurrent tests, Snapshots and Assertions must use expect from the local Test Context to ensure the right test is detected.

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

WARNING

You cannot use this syntax, when using Vitest as type checker.

test.sequential

Alias: it.sequential

test.sequential marks a test as sequential. This is useful if you want to run tests in sequence within describe.concurrent or with the --sequence.concurrent command option.

// with config option { sequence: { concurrent: true } }
('concurrent test 1', async () => { /* ... */ })
('concurrent test 2', async () => { /* ... */ })

.('sequential test 1', async () => { /* ... */ })
.('sequential test 2', async () => { /* ... */ })

// within concurrent suite
.('suite', () => {
  ('concurrent test 1', async () => { /* ... */ })
  ('concurrent test 2', async () => { /* ... */ })

  .('sequential test 1', async () => { /* ... */ })
  .('sequential test 2', async () => { /* ... */ })
})

test.todo

Alias: it.todo

Use test.todo to stub tests to be implemented later. An entry will be shown in the report for the tests so you know how many tests you still need to implement.

// An entry will be shown in the report for this test
test.todo('unimplemented test')

test.fails

Alias: it.fails

Use test.fails to indicate that an assertion will fail explicitly.

import { ,  } from 'vitest'

function () {
  return new ( => (1))
}
.('fail test', async () => {
  await (())..(1)
})

WARNING

You cannot use this syntax, when using Vitest as type checker.

test.each

Alias: it.each

Use test.each when you need to run the same test with different variables. You can inject parameters with printf formatting in the test name in the order of the test function parameters.

%s: string
%d: number
%i: integer
%f: floating point value
%j: json
%o: object
%#: index of the test case
%%: single percent sign ('%')

.([
  [1, 1, 2],
  [1, 2, 3],
  [2, 1, 3],
])('add(%i, %i) -> %i', (, , ) => {
  ( + ).()
})

// this will return
// ✓ add(1, 1) -> 2
// ✓ add(1, 2) -> 3
// ✓ add(2, 1) -> 3

You can also access object properties with $ prefix, if you are using objects as arguments:

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

You can also access Object attributes with ., if you are using objects as arguments:

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

Starting from Vitest 0.25.3, you can also use template string table.

First row should be column names, separated by |;
One or more subsequent rows of data supplied as template literal expressions using ${value} syntax.

.`
  a               | b      | expected
  ${1}            | ${1}   | ${2}
  ${'a'}          | ${'b'} | ${'ab'}
  ${[]}           | ${'b'} | ${'b'}
  ${{}}           | ${'b'} | ${'[object Object]b'}
  ${{ : 1 }}   | ${'b'} | ${'[object Object]b'}
`('returns $expected when $a is added $b', ({ , ,  }) => {
  ( + ).()
})

If you want to have access to TestContext, use describe.each with a single test.

TIP

Vitest processes $values with Chai format method. If the value is too truncated, you can increase chaiConfig.truncateThreshold in your config file.

WARNING

You cannot use this syntax, when using Vitest as type checker.

bench

Type: (name: string | Function, fn: BenchFunction, options?: BenchOptions) => void

bench defines a benchmark. In Vitest terms benchmark is a function that defines a series of operations. Vitest runs this function multiple times to display different performance results.

Vitest uses tinybench library under the hood, inheriting all its options that can be used as a third argument.

import {  } from 'vitest'

('normal sorting', () => {
  const  = [1, 5, 4, 2, 3]
  .((, ) => {
    return  - 
  })
}, { : 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
}

bench.skip

Type: (name: string | Function, fn: BenchFunction, options?: BenchOptions) => void

You can use bench.skip syntax to skip running certain benchmarks.

import {  } from 'vitest'

.('normal sorting', () => {
  const  = [1, 5, 4, 2, 3]
  .((, ) => {
    return  - 
  })
})

bench.only

Type: (name: string | Function, fn: BenchFunction, options?: BenchOptions) => void

Use bench.only to only run certain benchmarks in a given suite. This is useful when debugging.

import {  } from 'vitest'

.('normal sorting', () => {
  const  = [1, 5, 4, 2, 3]
  .((, ) => {
    return  - 
  })
})

bench.todo

Type: (name: string | Function) => void

Use bench.todo to stub benchmarks to be implemented later.

import {  } from 'vitest'

.('unimplemented test')

describe

When you use test or bench in the top level of file, they are collected as part of the implicit suite for it. Using describe you can define a new suite in the current context, as a set of related tests or benchmarks and other nested suites. A suite lets you organize your tests and benchmarks so reports are more clear.

// basic.spec.ts
// organizing tests

import { , ,  } from 'vitest'

const  = {
  : true,
  : 32,
}

('person', () => {
  ('person is defined', () => {
    ().()
  })

  ('is active', () => {
    (.).()
  })

  ('age limit', () => {
    (.).(32)
  })
})

// basic.bench.ts
// organizing benchmarks

import { ,  } from 'vitest'

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

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

You can also nest describe blocks if you have a hierarchy of tests or benchmarks:

import { , ,  } from 'vitest'

function (: number | string) {
  if (typeof  !== 'number')
    throw new ('Value must be a number')

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

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

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

describe.skip

Alias: suite.skip

Use describe.skip in a suite to avoid running a particular describe block.

import { , ,  } from 'vitest'

.('skipped suite', () => {
  ('sqrt', () => {
    // Suite skipped, no error
    .(.(4), 3)
  })
})

describe.skipIf

Alias: suite.skipIf

In some cases, you might run suites multiple times with different environments, and some of the suites might be environment-specific. Instead of wrapping the suite with if, you can use describe.skipIf to skip the suite whenever the condition is truthy.

import { ,  } from 'vitest'

const  = .. === 'development'

.()('prod only test suite', () => {
  // this test suite only runs in production
})

WARNING

You cannot use this syntax when using Vitest as type checker.

describe.runIf

Alias: suite.runIf

Opposite of describe.skipIf.

import { , ,  } from 'vitest'

const  = .. === 'development'

.()('dev only test suite', () => {
  // this test suite only runs in development
})

WARNING

You cannot use this syntax, when using Vitest as type checker.

describe.only

Type: (name: string | Function, fn: TestFunction, options?: number | TestOptions) => void

Use describe.only to only run certain suites

// Only this suite (and others marked with only) are run
.('suite', () => {
  ('sqrt', () => {
    .(.(4), 3)
  })
})

('other suite', () => {
  // ... will be skipped
})

Sometimes it is very useful to run only tests in a certain file, ignoring all other tests from the whole test suite, which pollute the output.

In order to do that run vitest with specific file containing the tests in question.

# vitest interesting.test.ts

describe.concurrent

Alias: suite.concurrent

describe.concurrent in a suite marks every tests as concurrent

// All tests within this suite will be run in parallel
.('suite', () => {
  ('concurrent test 1', async () => { /* ... */ })
  ('concurrent test 2', async () => { /* ... */ })
  .('concurrent test 3', async () => { /* ... */ })
})

.skip, .only, and .todo works with concurrent suites. All the following combinations are valid:

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

When running concurrent tests, Snapshots and Assertions must use expect from the local Test Context to ensure the right test is detected.

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

WARNING

You cannot use this syntax, when using Vitest as type checker.

describe.sequential

Alias: suite.sequential

describe.sequential in a suite marks every test as sequential. This is useful if you want to run tests in sequence within describe.concurrent or with the --sequence.concurrent command option.

.('suite', () => {
  ('concurrent test 1', async () => { /* ... */ })
  ('concurrent test 2', async () => { /* ... */ })

  .('', () => {
    ('sequential test 1', async () => { /* ... */ })
    ('sequential test 2', async () => { /* ... */ })
  })
})

describe.shuffle

Alias: suite.shuffle

Vitest provides a way to run all tests in random order via CLI flag --sequence.shuffle or config option sequence.shuffle, but if you want to have only part of your test suite to run tests in random order, you can mark it with this flag.

.('suite', () => {
  ('random test 1', async () => { /* ... */ })
  ('random test 2', async () => { /* ... */ })
  ('random test 3', async () => { /* ... */ })
})
// order depends on sequence.seed option in config (Date.now() by default)

.skip, .only, and .todo works with random suites.

WARNING

You cannot use this syntax, when using Vitest as type checker.

describe.todo

Alias: suite.todo

Use describe.todo to stub suites to be implemented later. An entry will be shown in the report for the tests so you know how many tests you still need to implement.

// An entry will be shown in the report for this suite
describe.todo('unimplemented suite')

describe.each

Alias: suite.each

Use describe.each if you have more than one test that depends on the same data.

.([
  { : 1, : 1, : 2 },
  { : 1, : 2, : 3 },
  { : 2, : 1, : 3 },
])('describe object add($a, $b)', ({ , ,  }) => {
  (`returns ${}`, () => {
    ( + ).()
  })

  (`returned value not be greater than ${}`, () => {
    ( + )..()
  })

  (`returned value not be less than ${}`, () => {
    ( + )..()
  })
})

Starting from Vitest 0.25.3, you can also use template string table.

First row should be column names, separated by |;
One or more subsequent rows of data supplied as template literal expressions using ${value} syntax.

.`
  a               | b      | expected
  ${1}            | ${1}   | ${2}
  ${'a'}          | ${'b'} | ${'ab'}
  ${[]}           | ${'b'} | ${'b'}
  ${{}}           | ${'b'} | ${'[object Object]b'}
  ${{ : 1 }}   | ${'b'} | ${'[object Object]b'}
`('describe template string add($a, $b)', ({ , ,  }) => {
  (`returns ${}`, () => {
    ( + ).()
  })
})

WARNING

You cannot use this syntax, when using Vitest as type checker.

Setup and Teardown

These functions allow you to hook into the life cycle of tests to avoid repeating setup and teardown code. They apply to the current context: the file if they are used at the top-level or the current suite if they are inside a describe block. These hooks are not called, when you are running Vitest as a type checker.

beforeEach

Type: beforeEach(fn: () => Awaitable<void>, timeout?: number)

Register a callback to be called before each of the tests in the current context runs. If the function returns a promise, Vitest waits until the promise resolve before running the test.

Optionally, you can pass a timeout (in milliseconds) defining how long to wait before terminating. The default is 5 seconds.

import { beforeEach } from 'vitest'

beforeEach(async () => {
  // Clear mocks and add some testing data after before each test run
  await stopMocking()
  await addUser({ name: 'John' })
})

Here, the beforeEach ensures that user is added for each test.

Since Vitest v0.10.0, beforeEach also accepts an optional cleanup function (equivalent to afterEach).

import { beforeEach } from 'vitest'

beforeEach(async () => {
  // called once before each test run
  await prepareSomething()

  // clean up function, called once after each test run
  return async () => {
    await resetSomething()
  }
})

afterEach

Type: afterEach(fn: () => Awaitable<void>, timeout?: number)

Register a callback to be called after each one of the tests in the current context completes. If the function returns a promise, Vitest waits until the promise resolve before continuing.

Optionally, you can provide a timeout (in milliseconds) for specifying how long to wait before terminating. The default is 5 seconds.

import { afterEach } from 'vitest'

afterEach(async () => {
  await clearTestingData() // clear testing data after each test run
})

Here, the afterEach ensures that testing data is cleared after each test runs.

TIP

Vitest 1.3.0 added onTestFinished hook. You can call it during the test execution to cleanup any state after the test has finished running.

beforeAll

Type: beforeAll(fn: () => Awaitable<void>, timeout?: number)

Register a callback to be called once before starting to run all tests in the current context. If the function returns a promise, Vitest waits until the promise resolve before running tests.

Optionally, you can provide a timeout (in milliseconds) for specifying how long to wait before terminating. The default is 5 seconds.

import { beforeAll } from 'vitest'

beforeAll(async () => {
  await startMocking() // called once before all tests run
})

Here the beforeAll ensures that the mock data is set up before tests run.

Since Vitest v0.10.0, beforeAll also accepts an optional cleanup function (equivalent to afterAll).

import { beforeAll } from 'vitest'

beforeAll(async () => {
  // called once before all tests run
  await startMocking()

  // clean up function, called once after all tests run
  return async () => {
    await stopMocking()
  }
})

afterAll

Type: afterAll(fn: () => Awaitable<void>, timeout?: number)

Register a callback to be called once after all tests have run in the current context. If the function returns a promise, Vitest waits until the promise resolve before continuing.

Optionally, you can provide a timeout (in milliseconds) for specifying how long to wait before terminating. The default is 5 seconds.

import { afterAll } from 'vitest'

afterAll(async () => {
  await stopMocking() // this method is called after all tests run
})

Here the afterAll ensures that stopMocking method is called after all tests run.

Test Hooks

Vitest provides a few hooks that you can call during the test execution to cleanup the state when the test has finished runnning.

WARNING

These hooks will throw an error if they are called outside of the test body.

onTestFinished 1.3.0+

This hook is always called after the test has finished running. It is called after afterEach hooks since they can influence the test result. It receives a TaskResult object with the current test result.

import { onTestFinished, test } from 'vitest'

test('performs a query', () => {
  const db = connectDb()
  onTestFinished(() => db.close())
  db.query('SELECT * FROM users')
})

WARNING

If you are running tests concurrently, you should always use onTestFinished hook from the test context since Vitest doesn't track concurrent tests in global hooks:

import { test } from 'vitest'

test.concurrent('performs a query', ({ onTestFinished }) => {
  const db = connectDb()
  onTestFinished(() => db.close())
  db.query('SELECT * FROM users')
})

This hook is particularly useful when creating reusable logic:

// this can be in a separate file
function getTestDb() {
  const db = connectMockedDb()
  onTestFinished(() => db.close())
  return db
}

test('performs a user query', async () => {
  const db = getTestDb()
  expect(
    await db.query('SELECT * from users').perform()
  ).toEqual([])
})

test('performs an organization query', async () => {
  const db = getTestDb()
  expect(
    await db.query('SELECT * from organizations').perform()
  ).toEqual([])
})

TIP

This hook is always called in reverse order and is not affected by sequence.hooks option.

onTestFailed

This hook is called only after the test has failed. It is called after afterEach hooks since they can influence the test result. It receives a TaskResult object with the current test result. This hook is useful for debugging.

import { onTestFailed, test } from 'vitest'

test('performs a query', () => {
  const db = connectDb()
  onTestFailed((e) => {
    console.log(e.result.errors)
  })
  db.query('SELECT * FROM users')
})

WARNING

If you are running tests concurrently, you should always use onTestFailed hook from the test context since Vitest doesn't track concurrent tests in global hooks:

import { test } from 'vitest'

test.concurrent('performs a query', ({ onTestFailed }) => {
  const db = connectDb()
  onTestFailed((result) => {
    console.log(result.errors)
  })
  db.query('SELECT * FROM users')
})

Test API Reference ​

test ​

test.extend 0.32.3+ ​

test.skip ​

test.skipIf ​

test.runIf ​

test.only ​

test.concurrent ​

test.sequential ​

test.todo ​

test.fails ​

test.each ​

bench ​

bench.skip ​

bench.only ​

bench.todo ​

describe ​

describe.skip ​

describe.skipIf ​

describe.runIf ​

describe.only ​

describe.concurrent ​

describe.sequential ​

describe.shuffle ​

describe.todo ​

describe.each ​

Setup and Teardown ​

beforeEach ​

afterEach ​

beforeAll ​

afterAll ​

Test Hooks ​

onTestFinished 1.3.0+ ​

onTestFailed ​

Test API Reference

test

test.extend 0.32.3+

test.skip

test.skipIf

test.runIf

test.only

test.concurrent

test.sequential

test.todo

test.fails

test.each

bench

bench.skip

bench.only

bench.todo

describe

describe.skip

describe.skipIf

describe.runIf

describe.only

describe.concurrent

describe.sequential

describe.shuffle

describe.todo

describe.each

Setup and Teardown

beforeEach

afterEach

beforeAll

afterAll

Test Hooks

onTestFinished 1.3.0+

onTestFailed