vitest_test
JavaScript and TypeScript tests run with Vitest.
Start Here#
Install Vitest in the package with the project's JavaScript package manager,
or make the vitest command available on the executable search path. For
example:
npm install --save-dev vitest
Retrieve the runnable starter when you want a complete declaration, package manifest, and sample tests:
once query example vitest_test vitest-test-minimal --format json
Copy the declaration below into once.toml, adjust srcs and any setup files
for the project, then establish discovery and run the file batches:
once test tests --format json
once query test-manifest tests --format json
once test tests --jobs 4 --format json
The first command runs the complete target. Later runs can use the resulting manifest for automatic batching and exact selection. See Testing and Scheduling for affected plans, case-level batching, and exact unit commands.
Description#
vitest_test prefers the package-local Vitest entry point, then falls back to
the installed vitest command. It uses Vitest's structured reporter, records
stable file and full-name identifiers, and writes normalized Once results.
Exact execution selects the discovered file and an anchored test name pattern.
The target kind declares Node.js and Vitest as tool requirements. A
workspace-relative runner is treated as an input, while an installed runner
is identified as part of the toolchain.
Automatic batching uses one batch per test file by default. Set batching to
case for individual cases, or target for one target batch. A complete run
must establish a current manifest before smaller batches are planned.
Once disables Vitest's mutable local cache inside the action because the
installed packages are declared inputs. Once's action cache reuses successful
test results when those inputs have not changed.
Attributes#
| Attribute | Type | Required | Default | Description |
|---|---|---|---|---|
node | string | no | node | Node.js executable name, absolute path, or workspace-relative path |
runner | string | no | automatic | Package-relative Vitest entry point or installed command. Once prefers node_modules/vitest/vitest.mjs, then searches for vitest |
config | list<string> | no | package and lock files | Dependency and runner configuration inputs |
dependencies | list<string> | no | node_modules/**/* | Installed runner and package files required during execution |
data | list<string> | no | [] | Setup, transform, snapshot, and runtime inputs |
args | list<string> | no | [] | Additional Vitest arguments |
env | map<string, string> | no | {} | Explicit test environment variables |
env_inherit | list<string> | no | [] | Host environment variables inherited by name |
batching | string | no | file | Automatic granularity: file, case, or target |
labels | list<string> | no | [] | Labels exposed through test discovery |
timeout_ms | int | no | empty | Optional timeout in milliseconds |
Dependency Edges#
deps names targets whose changes should select this test target.
Providers and Capabilities#
The target emits once_test_info and exposes test with the default,
test_results, and logs output groups.
Example#
[[target]]
name = "tests"
kind = "vitest_test"
srcs = ["tests/**/*.test.js"]
Include setup files, transforms, snapshots, and other runtime files in data.