Test | Vitest

test or it 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, or a set of additional options. The default timeout is 5 seconds, and can be configured globally with testTimeout.
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.
If test body is not provided, the test is marked as todo.
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.
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.
You can define boolean options by chaining properties on a function:
But you can also provide an object as a second argument instead:
They both work in exactly the same way. To use either one is purely a stylistic choice.
Options set to undefined are ignored. They don't override values from the chain, the parent suite, or tags.
Test timeout in milliseconds.
Note that if you are providing timeout as the last argument, you cannot use options anymore:
However, you can provide a timeout inside the object:
Retry configuration for the test. If a number, specifies how many times to retry. If an object, allows fine-grained retry control.
Note that the object configuration is available only since Vitest 4.1.
How many times the test will run again. If set to 0 (the default), the test will run only one time.
This can be useful for debugging flaky tests.
Custom user tags. If the tag is not specified in the configuration, the test will fail before it starts, unless strictTags is disabled manually.
Attaches custom metadata available in reporters.
Vitest merges top-level properties inherited from suites or tags. However, it does not perform a deep merge of nested objects.
Prefer using non-nested meta, if possible.
Whether this test run concurrently with other concurrent tests in the suite.
Set concurrent to false to opt out of concurrency inherited from describe.concurrent or sequence.concurrent:
Whether the test should be skipped.
Should this test be the only one running in a suite.
Whether the test should be skipped and marked as a todo.
Whether the test is expected to fail. If it does, the test will pass, otherwise it will fail.
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.
Use test.override to override fixture values for all tests within the current suite and its nested suites. This must be called at the top level of a describe block. See Overriding Fixture Values for more information.
test.scoped is deprecated in favor of test.override and will be removed in a future major version.
Alias of test.override
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.
You can also skip test by calling skip on its context dynamically:
If the condition is unknown, you can provide it to the skip method as the first arguments:
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.
Unlike test.skip, test.skipIf always sets the skip option: true if the condition is truthy, false otherwise. A falsy condition overrides skip inherited from tags, the same as test(name, { skip: false }).
Opposite of test.skipIf. It always sets the skip option: false if the condition is truthy, true otherwise.
Use test.only to only run certain tests in a given suite. This is useful when debugging.
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: