rust_test
Rust test target.
Description#
Compiles a Rust test crate with rustc --test, then runs the produced test
binary through Once's generic test capability. The target can model unit tests
from a library root, or integration tests by setting crate_root to a test
crate entry file and depending on the library under test.
The runner uses the Rust test harness list output to populate
once.test_results.v1, stores the native test output, and returns the test
binary exit status to Once.
Attributes#
| Attribute | Type | Required | Default | Description |
|---|---|---|---|---|
crate_name | string | no | target name | Rust crate name passed to rustc; - and . are rewritten as _ when omitted |
crate_root | string | no | src/lib.rs | Package-relative test crate root |
edition | string | no | 2021 | Rust edition passed to rustc |
features | list<string> | no | [] | Cargo feature names lowered to --cfg=feature=... flags |
crate_features | list<string> | no | [] | Bazel-compatible alias for features |
target | string | no | host target | Rust target triple passed to rustc --target |
env | map<string, string> | no | {} | Environment variables for rustc |
rustc_env | map<string, string> | no | {} | Rust compiler environment variables |
rustc_env_files | list<string> | no | [] | Files with NAME=value entries merged into the rustc environment before env and rustc_env |
rustc_flags | list<string> | no | [] | Additional rustc flags appended after Once-managed flags |
cap_lints | string | no | empty | Optional rustc lint cap passed as --cap-lints |
linker | string | no | inferred | Optional linker path passed as -C linker=... |
linker_flags | list<string> | no | [] | Additional linker flags lowered to -C link-arg=... |
native_linkopts | list<string> | no | [] | Linker flags propagated to downstream native consumers when this target is used as native input |
exported_linker_flags | list<string> | no | [] | Buck-compatible alias for native linker flags propagated to downstream native consumers |
exported_post_linker_flags | list<string> | no | [] | Buck-compatible propagated linker flags appended after normal exported linker flags |
linker_script | string | no | empty | Package-relative linker script passed to the linker and included in the compile action inputs |
data | list<string> | no | [] | Runtime data file globs available to the test runner and propagated from Rust dependencies |
compile_data | list<string> | no | [] | Bazel-compatible compile-time data file globs included in the rustc action inputs |
crate_aliases | map<string, string> | no | {} | Map dependency label, package name, or crate name to the local extern crate name |
aliases | map<string, string> | no | {} | Bazel-compatible alias map from dependency label or crate name to local extern crate name |
named_deps | map<string, string> | no | {} | Buck-compatible alias map from local extern crate name to dependency label or crate name |
cargo_package | string | no | empty | Cargo package name used to select direct external deps from a cargo_dependencies dependency set |
build_script | string | no | empty | Package-relative Cargo build script path run before rustc |
build_script_tools | list<string> | no | [] | Host tool names the build script invokes; each is resolved on the search path during graph loading |
cargo_config_env | map<string, string> | no | {} | Environment declared by Cargo configuration, applied below env, rustc_env, and test_env |
args | list<string> | no | [] | Arguments passed to the compiled test binary |
test_env | map<string, string> | no | {} | Environment variables passed to the test runner |
test_cwd | string | no | workspace root | Package-relative working directory for the test process |
env_inherit | list<string> | no | [] | Host environment variable names inherited by the test runner before test_env overrides |
crate | target | no | empty | Reserved Bazel-compatible reference to an already-built crate under test |
use_libtest_harness | bool | no | true | Whether to use the Rust libtest harness. Only true is supported |
labels | list<string> | no | [] | Labels exposed through once_test_info for test discovery |
timeout_ms | int | no | Optional test timeout in milliseconds |
Accepted but unsupported attributes: default_deps, doc_deps, doc_env, doc_link_style,
doc_linker_flags, doc_named_deps, link_deps, link_style,
mapped_srcs, proc_macro_deps, rpath, runtime_dependency_handling,
and rustdoc_flags. Non-empty values under [target.attrs] fail validation.
Use the dependency roles with the same names under [target.dependencies].
Dependency Edges#
| Edge | Accepts | Description |
|---|---|---|
deps | rust_crate, rust_proc_macro, rust_dependency_set, c_provider | Rust crate dependencies consumed through --extern; C provider libraries and linker options are linked into the test executable |
proc_macro_deps | rust_proc_macro | Procedural macros compiled for the execution host and passed to rustc through --extern |
link_deps | c_provider | Native libraries and linker options consumed by the test executable |
bin_deps | rust_binary | Executables the test spawns, exposed to the compiler and the test process as CARGO_BIN_EXE_<binary name> |
Providers#
The target emits rust_test and once_test_info.
Capabilities#
| Capability | Output groups |
|---|---|
build | binary |
test | default, test_results, logs |
Outputs#
| Output | Location |
|---|---|
| Test binary | .once/out/<target>/<crate_name> or .exe on Windows |
| Test results | .once/out/<target>/test/test_results.json |
| Test log | .once/out/<target>/test/rust-libtest.log |
| Native runner output | .once/out/<target>/test/native_results.txt |
Environment#
The test process starts with a cleared environment. Once gives it a private
HOME under the target's output directory, the standard system tool
directories on PATH, the package's CARGO_* description, a
CARGO_BIN_EXE_<name> entry for every bin_deps executable, and any
cargo_config_env entries. env_inherit names host variables to add, and
test_env overrides everything else.
Limitations#
A test that reads CARGO_BIN_EXE_<name> through the env! macro captures the
path at compile time, so the value belongs to the compiling action's execution
root. That is the same root the test runs in for an ordinary local build, but
not under a sandbox policy or remote execution, where each action gets its own
root. A test that reads the variable at run time instead works in every mode.
Test and run processes start with a fixed search path holding the standard system tool directories. A test that invokes a program found there depends on that program, and the action key records the search path rather than the contents of what it finds, so a system tool upgraded in place does not invalidate a cached test result. Pin such a tool through a target that declares it instead of relying on the search path.
The test capability runs only host-target test binaries. A cross-target
rust_test can still be built, but running it needs a platform runner that is
not part of this target kind yet.
Example#
[[target]]
name = "hello"
kind = "rust_library"
srcs = ["src/**/*.rs"]
[target.attrs]
crate_name = "hello"
edition = "2021"
[[target]]
name = "hello_tests"
kind = "rust_test"
srcs = ["tests/**/*.rs"]
deps = ["./hello"]
[target.attrs]
crate_name = "hello_tests"
crate_root = "tests/greeting_test.rs"
edition = "2021"
labels = ["unit"]