How to Use the Command 'vitest' (with examples)

Vitest is a fast and modern testing framework specifically designed for Vite, which is a popular frontend build tool. It provides seamless integration and comes with solid TypeScript support and a Jest-compatible API. This robust framework supports unit, integration, and snapshot testing, making it an ideal choice for developers looking to maintain and ensure the quality of their codebase. Its various functionalities cater to different testing needs, allowing for comprehensive test execution and efficient development cycles.

Use case 1: Run all available tests

Code:

vitest run

Motivation: Developers often need to perform a complete run of all test cases to validate the entire codebase after making changes. Running all available tests ensures that no aspect of the application is left unchecked, which helps catch any regressions or bugs introduced after recent code updates.

Explanation: The vitest run command is simple and powerful—it automatically detects and runs all tests in the application. By doing so, it gives developers confidence that modifications in one part of the project do not inadvertently break unrelated functionality elsewhere.

Example output:

Test Suites: 5 passed, 5 total
Tests:       20 passed, 20 total
Snapshots:   0 total
Time:        2.456s

Use case 2: Run the test suites from the given files

Code:

vitest run path/to/file1 path/to/file2 ...

Motivation: When working on specific components or modules, developers may need to focus solely on related tests to save time. Running tests from specified files ensures that only the relevant pieces are tested, effectively speeding up the development process and providing more immediate feedback.

Explanation: In this command, vitest run is followed by the paths to specific files that contain test suites. This instructs Vitest to execute only the tests within those files, which allows for targeted testing.

Example output:

Test Suites: 2 passed, 2 total
Tests:       8 passed, 8 total
Snapshots:   0 total
Time:        0.876s

Use case 3: Run the test suites from files within the current and subdirectories, whose paths match the given regular expression

Code:

vitest run regular_expression1 regular_expression2

Motivation: This functionality is valuable when you need to run a collection of related test files that follow naming conventions or reside in specific directories, which helps streamline the testing process in larger codebases.

Explanation: The command vitest run is enhanced with one or more regular expressions. These expressions specify patterns to match against file paths, enabling Vitest to identify and run test suites located in files that fit these patterns.

Example output:

Test Suites: 3 passed, 3 total
Tests:       12 passed, 12 total
Snapshots:   0 total
Time:        1.234s

Use case 4: Run the tests whose names match the given regular expression

Code:

vitest run --testNamePattern regular_expression

Motivation: There are times when developers need to conduct tests that correspond to specific features or functionalities. By focusing on test names, this use case helps quickly validate certain aspects of the application without the overhead of unrelated tests.

Explanation: The argument --testNamePattern allows users to leverage a regular expression to specify test names of interest. This results in only the matching tests being executed by Vitest, providing a focused approach.

Example output:

Test Suites: 1 passed, 1 total
Tests:       3 passed, 3 total
Snapshots:   0 total
Time:        0.345s

Use case 5: Watch files for changes and automatically re-run related tests

Code:

vitest

Motivation: This use case is ideal for developers in active development mode. With file-watching enabled, any changes made to the codebase result in automatic retesting, allowing developers to immediately verify the effects of their modifications without manual intervention.

Explanation: Running vitest without additional arguments starts the framework in watch mode. This sets up an ongoing process that listens for file changes, automatically triggering test executions linked to those files.

Example output:

Test Suites: 2 passed, 2 total
Tests:       9 passed, 9 total
Snapshots:   0 total
Time:        2.123s
Watching for file changes...

Use case 6: Run tests with coverage

Code:

vitest run --coverage

Motivation: Test coverage provides an insightful metric on how much of your codebase is exercised by tests, identifying untested parts of an application. This helps developers ensure that critical paths are well-tested, which in turn contributes to robust software quality.

Explanation: The --coverage flag appended to vitest run tells Vitest to generate a coverage report along with executing tests. This report highlights the coverage statistics, helping identify areas that might need additional testing.

Example output:

Test Suites: 6 passed, 6 total
Tests:       24 passed, 24 total
Snapshots:   0 total
Time:        3.789s

Coverage summary:
Statements   : 85.67% (567/662)
Branches     : 78.29% (94/120)
Functions    : 88.34% (85/96)
Lines        : 87.45% (362/414)

Use case 7: Run all tests but stop immediately after the first test failure

Code:

vitest run --bail=1

Motivation: This is useful during debugging or when ensuring the build is stable enough to run tests without failures. Stopping at the first failure provides immediate feedback about the earliest issue, enabling quicker diagnosis and focus on fixing preceding problems before addressing subsequent issues.

Explanation: The --bail=1 option modifies vitest run to abort the testing process after encountering the first failing test, prioritizing error discovery and resolution over test completion.

Example output:

Test Suites: 1 failed, 4 total
Tests:       1 failed, 12 total
Error: Test "function should return 5 when providing valid input" failed.
Time:        0.234s

Use case 8: Display help

Code:

vitest --help

Motivation: Comprehensive documentation on command options and usage is crucial when you need quick references or when configuring advanced test scenarios. The help command facilitates understanding and leveraging all of Vitest’s capabilities.

Explanation: Running vitest --help displays a suite of available commands and options with descriptions, assisting users in exploring and utilizing the framework effectively.

Example output:

Usage: vitest [options]

Options:
  --version          output the version number
  --help             display help for command
  --run              run all test suites
  ...

Conclusion

Vitest offers a versatile set of command-line functionalities that address a wide array of testing scenarios, each tailored for specific needs within the development workflow. By understanding and effectively employing these use cases, developers can maintain high code quality, rapidly identify issues, and efficiently optimize their testing strategies.