#Describe

describe defines a test suite. It supports chainable modifiers and parameterized methods for flexible and organized test grouping.

#describe

• Type: (name: string, fn: () => void | Promise<void>) => void

Defines a test suite that can contain multiple test cases or nested describe blocks.

import { describe, test } from '@rstest/core';

describe('math', () => {
  test('add', () => {
    // ...
  });
  test('sub', () => {
    // ...
  });
});

#describe.only

Only run the describe block(s) marked with only.

describe.only('only this suite', () => {
  // ...
});

#describe.skip

Skip the describe block(s) marked with skip.

describe.skip('Skip the test cases in this suite', () => {
  // ...
});

It should be noted that the skip tag is only used to skip test cases, and the code inside the describe block will still be executed. This is because Rstest needs to collect information about test cases to ensure that all features work properly, even if they are marked as skipped. For example, in snapshot tests, it determines whether a snapshot is outdated or marked as skipped.

describe.skip('a', () => {
  console.log('will run');
  test('b', () => {
    console.log('will not run');
    expect(0).toBe(0);
  });
});

#describe.todo

Mark a describe block as todo.

describe.todo('should implement this suite');

#describe.each

• Type: describe.each(cases: ReadonlyArray<T>)(name: string, fn: (param: T) => void | Promise<void>) => void

Creates a describe block for each item in the provided array.

describe.each([
  { a: 1, b: 2 },
  { a: 2, b: 3 },
])('math $a + $b', ({ a, b }) => {
  test('add', () => {
    // ...
  });
});

#describe.for

• Type: describe.for(cases: ReadonlyArray<T>)(name: string, fn: (param: T) => void | Promise<void>) => void

Alternative to describe.each for more flexible parameter types.

describe.for([
  [1, 2],
  [2, 3],
])('math $0 + $1', ([a, b]) => {
  test('add', () => {
    // ...
  });
});

#describe.runIf

Run the describe block only if the condition is true.

describe.runIf(process.env.RUN_EXTRA === '1')('conditionally run', () => {
  // ...
});

#describe.skipIf

Skip the describe block if the condition is true.

describe.skipIf(process.platform === 'win32')('skip on Windows', () => {
  // ...
});

#describe.concurrent

Run the tests in the describe block concurrently.

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

#describe.sequential

Run the tests in the describe block sequentially (default behavior).

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

#Chainable modifiers

describe supports chainable modifiers, so you can use them together. For example:

• describe.only.runIf(condition) (or describe.runIf(condition).only) will only run the describe block if the condition is true.
• describe.skipIf(condition).concurrent (or describe.concurrent.skipIf(condition)) will skip the describe block if the condition is true, otherwise run the tests concurrently.
• describe.runIf(condition).concurrent (or describe.concurrent.runIf(condition)) will only run the describe block concurrently if the condition is true.
• describe.only.concurrent (or describe.concurrent.only) will only run the describe block concurrently.
• ......