describe/test api

35 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Basic Vitest imports and example usage

The basic imports from vitest are: assert, describe, expect, and it. Example: import { assert, describe, expect, it } from 'vitest'. Tests use describe for suite names, it for individual tests, expect for assertions, and assert for alternative assertion style.

Pretty-format for test titles and values

Test titles and inspected values in Vitest 5 use pretty-format for better display. test.for/test.each title placeholders support non-ASCII characters, providing better internationalization support.

test function alias

The test function has an alias: it

test first argument can be a function

The first argument to test can be a function. If the first argument is a function, its name property will be used as the name of the test. The function itself will not be called.

test function signature and default timeout

The test function has two signatures. First: function test(name: string | Function, body?: () => unknown, timeout?: number): void. Second: function test(name: string | Function, options: TestOptions, body?: () => unknown): void. The default timeout is 5 seconds (5000 milliseconds), and can be configured globally with testTimeout.

test.skip signature and behavior

test.skip prevents running certain tests. Alias: it.skip. Signature: test.skip(name: string, body?: () => unknown). Can also be used as an option in TestOptions with { skip: true }. Tests can also be skipped dynamically by calling context.skip() within the test body, optionally with a condition and message: context.skip(condition?: boolean, message?: string).

test.only signature and behavior

test.only runs only specified tests in a suite, useful for debugging. Alias: it.only. When using test.only, Vitest detects when running in CI and throws an error if any test has the only flag, unless configured via allowOnly option.

test.todo signature and behavior

test.todo stubs tests to be implemented later. Alias: it.todo. Shows an entry in the report so you know how many tests still need implementation. Vitest automatically marks a test as todo if test has no body.

test.concurrent behavior

test.concurrent marks tests to be run in parallel. Alias: it.concurrent. When using concurrent tests, Snapshots and Assertions must use expect from the local Test Context to ensure the right test is detected. If tests are synchronous, Vitest will still run them sequentially despite the concurrent flag. Can be combined with skip, only, and todo: test.skip.concurrent(), test.concurrent.skip(), test.only.concurrent(), test.concurrent.only(), test.todo.concurrent(), test.concurrent.todo().

TestOptions.timeout property

timeout is a TestOptions property of type number with default value 5_000 (5000 milliseconds). Specifies test timeout in milliseconds. If providing timeout as the last positional argument to test(), you cannot use other options. However, you can provide timeout inside the options object.

TestOptions.retry property

retry is a TestOptions property with default value 0 (configured by retry config). Type: number | { count?: number, delay?: number, condition?: RegExp | ((error: TestError) => boolean) }. count specifies how many times to retry if test fails (default 0). delay specifies milliseconds between retry attempts (default 0). condition determines if test should be retried: if RegExp, tested against error message; if function, called with TestError object, return true to retry (default undefined, retry on all errors). Functions can only be used in test files, not in vitest.config.ts. Object configuration available since Vitest 4.1.

TestOptions.repeats property

repeats is a TestOptions property of type number with default value 0. Specifies how many times the test will run again. Useful for debugging flaky tests.

TestOptions.tags property

tags is a TestOptions property of type string[] with default value []. Available since Vitest 4.1.0. Specifies custom user tags. If tag is not specified in configuration, the test will fail before it starts unless strictTags is disabled.

TestOptions.meta property

meta is a TestOptions property of type TaskMeta. Available since Vitest 4.1.0. Attaches custom metadata available in reporters. Vitest merges top-level properties inherited from suites or tags but does not perform deep merge of nested objects.

TestOptions.concurrent property

concurrent is a TestOptions property of type boolean with default value false (configured by sequence.concurrent). Determines whether the test runs concurrently with other concurrent tests in suite. Can be set to false to opt out of concurrency inherited from describe.concurrent or sequence.concurrent.

TestOptions.skip property

skip is a TestOptions property of type boolean with default value false. Determines whether the test should be skipped.

TestOptions.only property

only is a TestOptions property of type boolean with default value false. Determines whether this test should be the only one running in a suite.

TestOptions.todo property

todo is a TestOptions property of type boolean with default value false. Determines whether the test should be skipped and marked as a todo.

TestOptions.fails property

fails is a TestOptions property of type boolean with default value false. When true, the test is expected to fail. If it fails, the test passes; if it succeeds, the test fails. This flag is useful to track difference in behavior of library over time.

test.skipIf method

test.skipIf skips a test when a condition is truthy. Alias: it.skipIf. Useful for running tests multiple times with different environments when some tests are environment-specific.

test.runIf method

test.runIf runs a test when a condition is truthy. Alias: it.runIf. Opposite of test.skipIf.

test.fails method

test.fails indicates that an assertion will fail explicitly. Alias: it.fails. Tests marked with fails are tracked in test summary since Vitest 4.1.

test.each method and printf formatting

test.each runs the same test with different variables. Alias: it.each. Parameters can be injected with printf formatting in test name: %s (string), %d (number), %i (integer), %f (floating point), %j (json), %o (object), %# (0-based index), %$ (1-based index), %% (single percent). Can use object properties with $ prefix like $a or array elements like $0. Supports template literal syntax with column headers separated by | and data rows using ${value} syntax.

test.each example with object properties

import { expect, test } from 'vitest' 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 example with array element access

import { expect, test } from 'vitest' test.each([ [1, 1, 2], [1, 2, 3], [2, 1, 3], ])('add($0, $1) -> $2', (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 example with object attribute access using dot notation

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 template literal syntax

test.each supports template literal syntax where first row contains column names separated by |, and subsequent rows contain data supplied as template literal expressions using ${value} syntax.

test.each template literal example

import { expect, test } from 'vitest' 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.for method for parameterized tests

test.for is an alternative to test.each that provides TestContext. Alias: it.for. Difference from test.each: non-array arguments are handled the same, but array arguments are not spread - the array itself is passed as a parameter. Can be used with concurrent snapshots by accessing expect from the second parameter (context).

test.for example with array parameters

// test.each spreads arrays test.each([ [1, 1, 2], [1, 2, 3], [2, 1, 3], ])('add(%i, %i) -> %i', (a, b, expected) => { expect(a + b).toBe(expected) }) // test.for doesn't spread arrays test.for([ [1, 1, 2], [1, 2, 3], [2, 1, 3], ])('add(%i, %i) -> %i', ([a, b, expected]) => { expect(a + b).toBe(expected) })

test.for example with concurrent snapshots

test.concurrent.for([ [1, 1], [1, 2], [2, 1], ])('add(%i, %i)', ([a, b], { expect }) => { expect(a + b).toMatchSnapshot() })

test.describe method

test.describe is a scoped describe. Available since Vitest 4.1.0.

test with no body creates a todo test

If test body is not provided, the test is marked as todo.

test.suite method

test.suite is an alias for suite. Available since Vitest 4.1.0. Refer to describe documentation for more information.

test promise handling

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.

Give your agent this brain