cargo-nextest - Cheatsheet del Test Runner Rust di Prossima Generazione
cargo-nextest è un test runner di prossima generazione per Rust. La sua differenza architettonica principale da cargo test è che esegue ogni test nel suo processo, il che fornisce true isolation (un test non può corrompere lo stato globale di un altro), migliore parallelismo e la capacità di segnalare un test che si blocca nel processo piuttosto che perdere l”intera esecuzione. In pratica è di solito 2-3x più veloce di cargo test su suite di grandi dimensioni, con output molto più pulito, rilevamento di test instabili e partizioni per CI sharding.
Installation
| Method | Command |
|---|
| Prebuilt (fastest) | cargo install cargo-nextest --locked |
| Binary | download from the nextest releases |
| macOS (Homebrew) | brew install cargo-nextest |
| Verify | cargo nextest --version |
Basic Usage
| Command | Description |
|---|
cargo nextest run | Esegui tutti i test |
cargo nextest run -p mycrate | Un pacchetto |
cargo nextest run test_name | Filtro per substring |
cargo nextest list | Elenca i test senza eseguirli |
cargo nextest run --release | Profilo di rilascio |
cargo nextest run --no-fail-fast | Continua dopo i fallimenti |
Filtering (Filtersets)
nextest ha un linguaggio di espressione per selezionare i test.
| Expression | Selects |
|---|
-E 'test(auth)' | Test il cui nome corrisponde a auth |
-E 'package(mycrate)' | Tutti i test in un pacchetto |
-E 'kind(lib)' | Solo test lib (unit) |
-E 'binary(integration)' | Un binario di test specifico |
-E 'test(a) + test(b)' | Unione |
-E 'package(x) - test(slow)' | Differenza |
# Run integration tests for one crate, excluding slow ones
cargo nextest run -E 'package(api) and kind(test) - test(slow)'
Flaky Test Detection
# Retry failures up to 3 times; tests that pass on retry are marked FLAKY
cargo nextest run --retries 3
| Config | Effect |
|---|
--retries N | Riprova i test falliti N volte |
| Reported as FLAKY | Ha superato solo dopo un retry |
| Per-test overrides | Imposta i retry per test specifici nella configurazione |
Questa distinzione è importante: un test instabile è un problema diverso da un test in fallimento, e nextest lo fa emergere esplicitamente invece di nasconderlo dietro una riesecuzione.
Configuration
# .config/nextest.toml
[profile.default]
retries = 0
fail-fast = false
slow-timeout = { period = "30s", terminate-after = 2 }
[profile.ci]
retries = 2
failure-output = "immediate-final"
status-level = "skip"
[[profile.default.overrides]]
filter = 'test(integration)'
threads-required = 2
| Setting | Purpose |
|---|
retries | Numero di retry predefinito |
slow-timeout | Contrassegna/termina i test che superano una durata |
threads-required | Capacità di riserva per test pesanti |
failure-output | Quando stampare i dettagli di fallimento |
| Profiles | cargo nextest run -P ci |
CI Sharding
# Split the suite across 4 CI machines
cargo nextest run --partition count:1/4 # on runner 1
cargo nextest run --partition count:2/4 # on runner 2
| Mode | Splits by |
|---|
count:N/M | Round-robin per conteggio di test |
hash:N/M | Hash stabile (stesso test → stesso shard) |
Output & Reporting
| Option | Effect |
|---|
--status-level all | Mostra lo stato di ogni test |
--failure-output immediate | Stampa i fallimenti mentre accadono |
--message-format libtest-json | Output leggibile da macchina |
--profile ci | Usa le impostazioni sintonizzate per CI |
| JUnit output | Configura in nextest.toml per il reporting di CI |
Limitations
| Not supported | Why |
|---|
| Doctests | Esegui separatamente con cargo test --doc |
#[bench] | Usa criterion invece |
| Some libtest flags | Semantica di runner diversa |
Uno schema di CI comune è cargo nextest run && cargo test --doc.
nextest vs cargo test
| Aspect | cargo nextest | cargo test |
|---|
| Process model | Uno per test | Uno per binario |
| Isolation | Forte | Condivisa all”interno del binario |
| Speed | 2-3x più veloce tipico | Baseline |
| Flaky detection | Integrato | Nessuno |
| CI sharding | Integrato | Manuale |
| Doctests | No | Sì |
Resources
