test collection

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

TestCollection.allSuites() method signature

The allSuites method has signature: function allSuites(): Generator<TestSuite, undefined, void>. It filters all suites that are part of this collection and its children. Example usage: for (const suite of module.children.allSuites()) { if (suite.errors().length) { console.log('failed to collect', suite.errors()) } }

TestCollection.allTests() method signature

The allTests method has signature: function allTests(state?: TestState): Generator<TestCase, undefined, void>. It filters all tests that are part of this collection and its children. You can pass down a state value to filter tests by the state. Example usage: for (const test of module.children.allTests()) { if (test.result().state === 'pending') { console.log('test', test.fullName, 'did not finish') } }

TestCollection.tests() method signature

The tests method has signature: function tests(state?: TestState): Generator<TestCase, undefined, void>. It filters only the tests that are part of this collection. You can pass down a state value to filter tests by the state.

TestCollection.suites() method signature

The suites method has signature: function suites(): Generator<TestSuite, undefined, void>. It filters only the suites that are part of this collection.

TestCollection.size property

The size property returns the number of tests and suites in the collection. This number includes only tests and suites at the top-level, it doesn't include nested suites and tests.

TestCollection represents collection of top-level suites and tests

TestCollection represents a collection of top-level suites and tests in a suite or a module. It also provides useful methods to iterate over itself.

TestCollection methods return iterators for performance

Most TestCollection methods return an iterator instead of an array for better performance in case you don't need every item in the collection. If you prefer working with an array, you can spread the iterator: [...children.allSuites()].

TestCollection.at() method signature

The at method has signature: function at(index: number): TestCase | TestSuite | undefined. It returns the test or suite at a specific index. This method accepts negative indexes.

TestCollection itself is an iterator

The collection itself is an iterator. You can iterate over it directly using for...of loop: for (const child of module.children) { console.log(child.type, child.name) }

TestCollection.array() method signature

The array method has signature: function array(): (TestCase | TestSuite)[]. It returns the same collection but as an array. This is useful if you want to use Array methods like map and filter that are not supported by the TestCollection implementation.

TestSuite.options interface

TestSuite.children property

The children property is a TestCollection of all suites and tests inside the current suite. It will only iterate the first level of nesting and won't go deeper. To iterate over all tests or suites recursively, use children.allTests() or children.allSuites() methods, or implement a recursive function.

TestSuite.state() method

The state() method checks the running state of the suite and returns TestSuiteState. Possible return values are: pending (tests in this suite did not finish running yet), failed (suite has failed tests or couldn't be collected), passed (every test inside this suite has passed), or skipped (suite was skipped during collection).

TestSuite.errors() method

The errors() method returns TestError[] array containing errors that happened outside of the test run during collection, such as syntax errors. Note that errors are serialized into simple objects, so instanceof Error will always return false.

TestSuite.meta() method

The meta() method returns TaskMeta containing custom metadata that was attached to the suite during its execution or collection. Since Vitest 4.1, metadata can be attached by providing a meta object during test collection. Suite metadata will be inherited by tests since Vitest 4.1. Metadata attached during collection (outside the test function) will be available in the onTestModuleCollected hook in custom reporters.

TestSuite.logs() method

The logs() method returns ReadonlyArray<UserConsoleLog> containing console logs recorded during test collection of the suite. This includes logs from the suite block and beforeAll hooks, but not logs from test functions.

TestSuite.toTestSpecification() method

The toTestSpecification() method returns a new TestSpecification that can be used to filter or run this specific test suite. Available since Vitest 4.1.

TestSuite.module property

The module property is a direct reference to the TestModule where the test suite is defined.

TestSuite.ok() method

The ok() method checks if the suite has any failed tests and returns a boolean. It will return false if the suite failed during collection. In that case, check the errors() method for thrown errors.

TestSuite type property value

The TestSuite class always has a type property with the value of 'suite'. This can be used to distinguish between different task types.

TestSuite class availability

The TestSuite class is only available in the main thread. For working with runtime tasks, refer to the Runner API tasks.

TestSuite.project property

The project property references the TestProject that the test suite belongs to.

TestSuite.name property

The name property is the suite name that was passed to the describe function.

TestSuite.fullName property

The fullName property is the name of the suite including all parent suites separated with the > symbol.

TestSuite.id property structure

The id property is a suite's unique identifier that is deterministic and will be the same for the same suite across multiple runs. The ID format is: 1223128da3_0_0_0, where the first 10 characters are the file hash, followed by suite index, nested suite index, and test index separated by underscores. The ID can have a minus sign at the start. The file hash can be generated using the generateFileHash function from 'vitest/node' available since Vitest 3.

TestSuite.location property

The location property indicates the location in the module where the suite was defined, with line and column numbers. Locations are collected only if includeTaskLocation is enabled in the config. This option is automatically enabled if --reporter=html, --ui or --browser flags are used.

TestSuite.parent property

The parent property references the parent suite. If the suite was called directly inside the module, the parent will be the module itself.

Test tags for organizing and filtering tests

Tags let you label tests to organize them into groups and filter tests by tag or apply shared options like timeout or automatic retries. Define tags in configuration with name and optional test options. Apply tags to tests with { tags: ['flaky', 'db'] }. Filter tags via CLI with --tags-filter using and/&&, or/||, not/!, * wildcard, and () grouping.

Give your agent this brain