vitest/docs/api/index.md

API Reference

The following types are used in the type signatures below

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

test

test defines a set of related expectations. Default timeout for tests is 5 seconds, and can be configured globally with testTimeout.

Type: (name: string, fn: TestFunction, timeout?: number) => void Alias: it

import { test, expect } from 'vitest'

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

test.skip

Use .skip to avoid running certain tests

Type: (name: string, fn: TestFunction, timeout?: number) => void

test.skip("skipped test", () => {
  // Test skipped, no error
  assert.equal(Math.sqrt(4), 3);
});

test.only

Use .only to only run certain tests in a given suite

Type: (name: string, fn: TestFunction, timeout?: number) => void

it.only("test", () => {
    // Only this test (and others marked with only) are run
    assert.equal(Math.sqrt(4), 2);
  });
});

test.concurrent

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

Type: (name: string, fn: TestFunction, timeout?: number) => void

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

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

test.concurrent(...)
test.skip.concurrent(...), test.concurrent.skip(...)
test.only.concurrent(...), test.concurrent.only(...)
test.todo.concurrent(...), test.concurrent.todo(...)

test.todo

Use .todo to stub tests to be implemented later

Type: (name: string) => void

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

describe

Defines a new suite, as a set of related tests and nested suites. A suite lets you organize your tests so reports are more clear.

describe.skip

Use .skip in a suite to avoid avoid running it

Type: (name: string, fn: TestFunction, timeout?: number) => void

describe.skip("skipped suite", () => {
  test("sqrt", () => {
    // Suite skipped, no error
    assert.equal(Math.sqrt(4), 3);
  });
});

describe.only

Use .only to only run certain suites

Type: (name: string, fn: TestFunction, timeout?: number) => void

// Only this suite (and others marked with only) are run
describe.only("suite", () => {
  test("sqrt", () => {
    assert.equal(Math.sqrt(4), 3);
  });
});

describe.concurrent

.concurrent in a suite marks every tests as concurrent

Type: (name: string, fn: TestFunction, timeout?: number) => void

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

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

describe.concurrent(...)
describe.skip.concurrent(...), describe.concurrent.skip(...)
describe.only.concurrent(...), describe.concurrent.only(...)
describe.todo.concurrent(...), describe.concurrent.todo(...)

describe.todo

Use .todo to stub suites to be implemented later

Type: (name: string) => void

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