TestSuite

The TestSuite class represents a single suite. This class is only available in the main thread. Refer to the "Runner API" if you are working with runtime tasks.

The TestSuite instance always has a type property with the value of suite. You can use it to distinguish between different task types:

if (task.type === 'suite') {
  task; // TestSuite
}

project

This references the TestProject that the test belongs to.

module

This is a direct reference to the TestModule where the test is defined.

name

This is a suite name that was passed to the describe function.

import { describe } from 'vitest';

// [!code word:'the validation logic']
describe('the validation logic', () => {
  // ...
});

fullName

The name of the suite including all parent suites separated with > symbol. This suite has a full name "the validation logic > validating cities":

import { describe, test } from 'vitest';

// [!code word:'the validation logic']
// [!code word:'validating cities']
describe('the validation logic', () => {
  describe('validating cities', () => {
    // ...
  });
});

id

This is suite's unique identifier. This ID is deterministic and will be the same for the same suite across multiple runs. The ID is based on the project name, module ID and suite order.

The ID looks like this:

1223128da3_0_0_0
^^^^^^^^^^ the file hash
           ^ suite index
             ^ nested suite index
               ^ test index

TIP

You can generate file hash with generateFileHash function from vitest/node which is available since Vitest 3:

import { generateFileHash } from 'vitest/node';

const hash = generateFileHash(
  '/file/path.js', // relative path
  undefined // the project name or `undefined` is not set
);

DANGER

Don't try to parse the ID. It can have a minus at the start: -1223128da3_0_0_0.

location

The location in the module where the suite was defined. Locations are collected only if includeTaskLocation is enabled in the config. Note that this option is automatically enabled if --reporter=html, --ui or --browser flags are used.

The location of this suite will be equal to { line: 3, column: 1 }:

import { describe } from 'vitest'

describe('the validation works correctly', () => {
  // ...
})

parent

Parent suite. If the suite was called directly inside the module, the parent will be the module itself.

options

interface TaskOptions {
  readonly each: boolean | undefined;
  readonly fails: boolean | undefined;
  readonly concurrent: boolean | undefined;
  readonly shuffle: boolean | undefined;
  readonly retry: number | undefined;
  readonly repeats: number | undefined;
  readonly mode: 'run' | 'only' | 'skip' | 'todo';
}

The options that suite was collected with.

children

This is a collection of all suites and tests inside the current suite.

for (const task of suite.children) {
  if (task.type === 'test') {
    console.log('test', task.fullName);
  } else {
    // task is TaskSuite
    console.log('suite', task.name);
  }
}

WARNING

Note that suite.children will only iterate the first level of nesting, it won't go deeper. If you need to iterate over all tests or suites, use children.allTests() or children.allSuites(). If you need to iterate over everything, use recursive function:

function visit(collection: TestCollection) {
  for (const task of collection) {
    if (task.type === 'suite') {
      // report a suite
      visit(task.children);
    } else {
      // report a test
    }
  }
}

ok

function ok(): boolean;

Checks if the suite has any failed tests. This will also return false if suite failed during collection. In that case, check the errors() for thrown errors.

state

function state(): TestSuiteState;

Checks the running state of the suite. Possible return values:

• pending: the tests in this suite did not finish running yet.
• failed: this suite has failed tests or they couldn't be collected. If errors() is not empty, it means the suite failed to collect tests.
• passed: every test inside this suite has passed.
• skipped: this suite was skipped during collection.

WARNING

Note that test module also has a state method that returns the same values, but it can also return an additional queued state if the module wasn't executed yet.

errors

function errors(): TestError[];

Errors that happened outside of the test run during collection, like syntax errors.

import { describe } from 'vitest';

describe('collection failed', () => {
  throw new Error('a custom error');
});

WARNING

Note that errors are serialized into simple objects: instanceof Error will always return false.

meta 3.1.0+

function meta(): TaskMeta;

Custom metadata that was attached to the suite during its execution or collection. The meta can be attached by assigning a property to the task.meta object during a test run:

import { test } from 'vitest';

describe('the validation works correctly', task => {
  // assign "decorated" during collection
  task.meta.decorated = false;

  test('some test', ({ task }) => {
    // assign "decorated" during test run, it will be available
    // only in onTestCaseReady hook
    task.suite.meta.decorated = false;
  });
});

TIP

If metadata was attached during collection (outside of the test function), then it will be available in onTestModuleCollected hook in the custom reporter.