Test

The test directive is used to define individual test cases. Like describe, it supports several modifiers to enhance workflow, filter which tests are executed, and mark tests as pending or expected to fail.

test

Defines a single test with a description and an implementation. Accepts an optional timeout (in milliseconds).

Example:

test('adds numbers', () => {
    expect(1 + 2).toBe(3);
});

test.skip

Skips a test, preventing it from running but showing it in reports.

test.skip('temporarily disabled', () => { 
    /* This code will NOT run */
});

test.only

Runs only those tests marked with .only. All other tests are skipped.
If multiple test.only cases exist, all of them will run (not just one).
This affects only the individual tests marked with .only.

test.only('runs exclusively', () => {
    expect(true).toBe(true);
});
test.only('this will also run', () => {
    expect(1).toBe(1);
});

NOTE

If several test.only tests exist, all will run. If used alongside describe.only, both describe.only and test.only will filter and run all their respective marked tests.

test.todo

Defines a test that acts as a reminder and isn't executed. It will not run, just appear in test outputs to indicate planned or pending tests.

test.todo('write this later');
test.todo('write this later2', () => {
    
});

test.failing

Marks the test as expected to fail. Useful for documenting known issues or regressions.

test.failing('bug still exists', () => {
    throw new Error('this will fail as expected');
});

test.each

Used for parameterized/data-driven testing, letting you run the same test logic against multiple data sets.
Supports both array and template table formats.

Array Example:

test.each(1, 2, 3)('is positive: %s', (value) => {
    expect(value).toBeGreaterThan(0);
});

Template Table Example:

test.each` a | b | sum ${ 1 } | ${ 2 } | ${ 3 } ${ 2 } | ${ 5 } | ${ 7 }`
('adds $a + $b -> $sum', ({ a, b, sum }) => {
    expect(a + b).toBe(sum);
});

// OR

test.each`
    a       | b      | sum
    ${ 1 }  | ${ 2 } | ${ 3 }
    ${ 2 }  | ${ 5 } | ${ 7 }
`('adds $a + $b -> $sum', ({ a, b, sum }) => {
    expect(a + b).toBe(sum);
});

See the tests/each section for more advanced usage, options, and best practices on parameterized test suites.

Writing Asynchronous Tests

All variations of test (test, test.skip, test.only, test.each, etc.) support asynchronous testing in two primary ways:

1. Promise-based / async functions:

   Use async as a prefix, and optionally specify a timeout:

   test('resolves promise', async () => {
     await expect(fetchData()).resolves.toBeDefined();
   });

2. Callback (done) style:

   Accept a done callback parameter—call it when your async work is finished:

   test.each([1, 2, 3])('is positive: %s', (value, done) => {
     expect(value).toBeGreaterThan(0);
     done();
   }, 5000);

• You can use both styles with all test variations, including .only, .skip, .failing, etc.
• If the async test exceeds its timeout (default or specified), it will fail with a timeout error.

Timeout

You can provide a timeout as the last argument for any form of test to control its maximum allowed execution time.

test('...', () => {
    // ...
}, 5000);

Summary

• test: Defines an individual test.
• test.skip: Skip specific tests (not-runnable, but visible).
• test.only: Run ONLY specific tests — multiple .only tests all run if present; the rest are skipped.
• test.todo: Mark tests as planned for the future (not runnable).
• test.failing: Mark as expected to fail.
• test.each: Repeat with all combinations of input parameters (data-driven).