The #[ktstr_test] Macro

#[ktstr_test] registers a function as an integration test that runs inside a VM.

Basic usage

use ktstr::prelude::*;

#[ktstr_test(llcs = 2, cores = 4, threads = 2)]
fn my_test(ctx: &Ctx) -> Result<AssertResult> {
    // ctx provides cgroup manager, topology, duration, etc.
    Ok(AssertResult::pass())
}

When a scheduler with a default topology is specified, the topology can be omitted:

use ktstr::declare_scheduler;

declare_scheduler!(MY_SCHED, {
    name = "my_sched",
    binary = "scx_my_sched",
    //          numa, llcs, cores/llc, threads/core
    topology = (1,    2,    4,         1),
});

#[ktstr_test(scheduler = MY_SCHED)]
fn inherited_topo(ctx: &Ctx) -> Result<AssertResult> {
    // Inherits 1n2l4c1t from MY_SCHED
    Ok(AssertResult::pass())
}

declare_scheduler! emits a pub static MY_SCHED: Scheduler and registers a private linkme static in the KTSTR_SCHEDULERS distributed slice. The scheduler = slot expects &'static Scheduler — pass the bare MY_SCHED ident; the macro takes a reference internally.

The function must have signature fn(&ktstr::scenario::Ctx) -> anyhow::Result<ktstr::assert::AssertResult>.

What the macro generates

1. Renames the function to __ktstr_inner_{name}.
2. Registers it in the KTSTR_TESTS distributed slice via linkme.
3. Emits a #[test] wrapper that calls run_ktstr_test().

The #[test] wrapper boots a VM with the specified topology and runs the function inside it.

Attributes

All attributes are optional with defaults.

Topology

Each dimension independently inherits from Scheduler.topology when a scheduler is specified and that dimension is not explicitly set. Without a scheduler, unset dimensions use macro defaults (numa_nodes=1, llcs=1, cores=2, threads=1). The default is a single-NUMA topology, so most tests do not need to set numa_nodes. See Default topology.

Scheduler

Payloads

See Payload Definitions for authoring new Payload fixtures; tests/common/fixtures.rs carries reusable examples (SCHBENCH, SCHBENCH_HINTED, SCHBENCH_JSON).

Checking

not_starved = true enables three distinct checks: starvation (any worker with zero work units), fairness spread (max-min off-CPU% below max_spread_pct), and scheduling gaps (longest gap below max_gap_ms). Each threshold can be overridden independently. See Customize Checking for override examples and Checking for the merge chain.

Topology constraints

The gauntlet skips presets that do not satisfy these constraints. Multi-NUMA presets are excluded by default (max_numa_nodes = 1). See Gauntlet for filtering rules and Gauntlet Tests for a worked example.

Execution

See Performance Mode for details on what performance_mode enables, prerequisites, and validation behavior.

Inline scheduler config

Some schedulers (e.g. scx_layered, scx_lavd) accept a JSON config file via a CLI argument like --config /path/to/config.json. Two pieces wire this into a test:

1. Scheduler declaration — the Scheduler builder declares the arg template and the guest path via .config_file_def:

   const LAYERED_SCHED: Scheduler = Scheduler::new("layered")
       .binary(SchedulerSpec::Discover("scx_layered"))
       .config_file_def("--config {file}", "/include-files/layered.json");

   {file} in the arg template is replaced with the guest path. The framework mkdir -ps the parent and writes the config content to /include-files/layered.json inside the guest before the scheduler binary starts.

2. Test attribute — the test supplies the inline JSON via config = …:

   const LAYERED_CONFIG: &str = r#"{ "layers": [...] }"#;
   
   #[ktstr_test(scheduler = LAYERED_SCHED, config = LAYERED_CONFIG)]
   fn layered_test(ctx: &Ctx) -> Result<AssertResult> {
       Ok(AssertResult::pass())
   }

   config = "..." (string literal) and config = SOME_CONST (path to a const &'static str) are both accepted.

The pairing gate is bidirectional:

• A scheduler with config_file_def set requires config = … on every test (otherwise the scheduler binary would launch without --config).
• A scheduler without config_file_def rejects config = … on the test (the content would be silently dropped at dispatch).

Both halves are validated at compile time via a const assertion emitted by the macro AND at runtime by KtstrTestEntry::validate, so direct programmatic-entry construction sees the same gate.

For schedulers that take a config file from a host-side path instead of inline content, use Scheduler::config_file(host_path) instead of config_file_def. The framework packs the host file into the initramfs at /include-files/{filename} and prepends --config /include-files/{filename} to scheduler args; no config = … on the test is needed in that flavor.

Example with custom scheduler

Define the scheduler with declare_scheduler! (see Scheduler Definitions), then reference it in #[ktstr_test]:

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

declare_scheduler!(MY_SCHED, {
    name = "my_sched",
    binary = "scx_my_sched",
    topology = (1, 2, 4, 1),
    sched_args = ["--enable-llc", "--enable-stealing"],
});

#[ktstr_test(
    scheduler = MY_SCHED,
    not_starved = true,
    max_gap_ms = 5000,
)]
fn my_sched_basic(ctx: &Ctx) -> Result<AssertResult> {
    // Inherits 1n2l4c1t from MY_SCHED
    Ok(AssertResult::pass())
}

declare_scheduler! emits a pub static MY_SCHED: Scheduler and registers it in the KTSTR_SCHEDULERS distributed slice via a private linkme static so cargo ktstr verifier discovers it. The bare MY_SCHED ident is what #[ktstr_test(scheduler = ...)] expects. See Scheduler Definitions for the full macro grammar.

For the manual builder pattern (no distributed-slice registration), see Scheduler Definitions: Manual definition.