Running Tests

Tests run via cargo ktstr test --kernel ../linux, which resolves the kernel and wraps cargo nextest run to boot KVM virtual machines for each #[ktstr_test] entry. Raw cargo nextest run remains available as a fallback once a kernel is in place via the discovery chain.

Quick reference

# Run all tests
cargo ktstr test --kernel ../linux

# Run a specific test
cargo ktstr test --kernel ../linux -- -E 'test(sched_basic_proportional)'

# Run ignored gauntlet tests
cargo ktstr test --kernel ../linux -- --run-ignored ignored-only -E 'test(gauntlet/)'

Run analysis

Each test invocation writes a *.ktstr.json sidecar per variant into {CARGO_TARGET_DIR or "target"}/ktstr/{kernel}-{project_commit}/. cargo ktstr stats list enumerates runs; cargo ktstr stats compare, list-values, list-metrics, and show-host operate on those sidecars. See Runs for the directory layout, last-writer-wins semantics, and the comparison workflow.

Budget-based test selection

Set KTSTR_BUDGET_SECS to select the subset of tests that maximizes feature coverage within a time budget. Useful for CI pipelines or quick smoke tests.

# Run the best 5 minutes of tests
KTSTR_BUDGET_SECS=300 cargo ktstr test --kernel ../linux

# Budget applies to gauntlet variants too
KTSTR_BUDGET_SECS=600 cargo ktstr test --kernel ../linux -- --run-ignored all

The selector encodes each test as a bitset of properties (scheduler, topology class, SMT, workload characteristics) and greedily picks tests with the highest marginal coverage per estimated second. Duration estimates account for VM boot overhead based on vCPU count.

A summary is printed to stderr during --list:

ktstr budget: 42/1200 tests, 295/300s used, 38/38 configurations covered

When KTSTR_BUDGET_SECS is not set, all tests are listed as usual.

Custom scheduler

Declare a scheduler with declare_scheduler! and reference the bare const from #[ktstr_test(scheduler = ...)]:

use ktstr::declare_scheduler;
use ktstr::prelude::*;

declare_scheduler!(MY_SCHED, {
    name = "my_sched",
    binary = "scx_my_sched",
});

#[ktstr_test(scheduler = MY_SCHED)]
fn my_sched_test(ctx: &Ctx) -> Result<AssertResult> {
    Ok(AssertResult::pass())
}

The binary is injected into the VM’s initramfs and started before scenarios run. See Test a New Scheduler for the full end-to-end workflow, and Payload Definitions for the #[derive(Payload)] macro that handles binary-kind workloads (schbench, fio, etc.) — distinct from the scheduler-under-test surface.