Crate cortexkit_test_support 

Portable helpers for CortexKit tests. Use this crate as a dev-dependency only.

Scratch fixtures preserve failure evidence, executables are published as immutable ckdev-* copies, and daemon builders enforce an ambient-root fence.

Structs

CachedSiblingBinary

Paths to the cached Cargo target directory and the executable used by tests. A ck-* artifact is copied to a separate ckdev-* publication before running, so its execution path is not the path where Cargo wrote the build output.

ScratchDir

Owned scratch fixture. Drop removes it unless unwinding or explicitly kept.

SubcDaemonBinary

The platform daemon ck-subc, built from the subconscious sibling checkout. Its executable path is private so callers can only spawn it through a builder that redirects its directory variables and owns its process lifetime.

TestDaemon

Owns the parent pipe and process group. Drop is bounded and synchronous, so when a test panics, the daemon is torn down before the test’s scratch directory is deleted.

TestDaemonCommand

Command builder whose only spawn operation returns an owned TestDaemon. It enforces scratch-root isolation and keeps the child tied to a lifetime pipe. Unix consumers require python3 on PATH to run the process-lifetime watcher.

Constants

PRIVILEGED_TESTS_ENV

Opt-in variable for tests requiring passwordless sudo, namespaces, or root.

STABLE_BIN_DIR

Shared executable directory exempt from the scratch age sweep.

Functions

assert_test_binary_spawns

Assert that Rust test sources in these directories stage production-named artifacts with ckdev_binary before spawning them. Comments are ignored. This lexical guard covers direct paths and simple raw-path bindings, not arbitrary data flow. Pair it with dev_command for runtime name refusal. Missing directories or an empty source scan panic rather than pass silently.

build_sibling_binary

Build a sibling using a cache key derived from its current source revision and caller-selected adjacent dependency checkouts. The same dependency names are checked again after compilation to reject sources changed during the build.

cached_sibling_binary

Resolve an immutable executable, building only on a cache miss. revision may be an explicit pin rather than the live checkout’s HEAD. The builder receives a staging Cargo target directory and must produce debug/<bin>. A sibling-wide OS lock covers publication and pruning, including across processes; dropping the file releases it even when a builder panics.

cached_sibling_binary_with_target

Resolve both paths so a caller can track or restrict where Cargo writes build files separately from the executable path used to start test processes.

checked_output

Execute a prepared command, returning an error with the exit code or signal number and name on failure. Plain Command::output does not reject failed exits.

ckdev_binary

Publish a built executable under a content-addressed ckdev-* name. Already-dev-named paths pass through. Unix copies live under /tmp, never $TMPDIR, to avoid per-user temporary-directory execution assessment delays. A child writes a private staging copy, then an atomic rename publishes it. This avoids hard-link execution failures and writable descriptors inherited by concurrently spawned children. Published files are read-only, verified against their digest on reuse, and pruned after three days. Use checked_output to report failed child exits, including signal names.

ckdev_file_name

The ckdev- name for a built binary’s file name: ck-subc becomes ckdev-subc, ck becomes ckdev-ck, any other name n becomes ckdev-n, and a name that already starts with ckdev- is returned as it is. A trailing .exe stays at the end, so Windows still runs the result.

describe_exit_status

Human-readable child failure, including Unix signal kills rather than None.

dev_command

A Command for program that refuses (panics) when program has a production executable name. Use it for every test spawn of a CortexKit binary, with a path made by ckdev_binary.

exempt_production_executable

Validate a caller-supplied exact (test name, executable stem) exemption. The calling test thread must also match; exemptions cannot be borrowed. Returns program when the test named test is the one test allowed to place an executable with program’s production name (the exemption table in this crate); panics for any other test or name. A trailing .exe is ignored, so the exemption holds on Windows too.

fenced_command

Build a command with no inherited environment except the allowlisted PATH, locale, timezone, user-name, and backtrace variables. Inherited API keys, tokens, and module identity variables are removed; HOME, XDG directories, and TMPDIR instead point beneath scratch. A ck-* program is copied to a reusable ckdev-* executable before the command is constructed. Use crate::TestDaemonCommand when roots must also resist later overrides and the child must terminate with the test harness.

fenced_command_with_roots

Like fenced_command, with caller-selected directory variables redirected beneath scratch. Each pair is (variable, plain subdirectory name); built-in variables cannot be replaced. Invalid names, duplicates, and symlink roots panic. As with a standard Command, later .env calls can override these values; crate::TestDaemonCommand::fenced_root enforces them again when spawning.

fenced_subc_daemon_env

Create directories beneath scratch and return their environment assignments. HOME, all five XDG directory variables, and TMPDIR point into this test tree so a daemon and its children do not write to the user’s normal directories.

fenced_subc_env_dir

Return the scratch subdirectory assigned to a built-in directory variable, such as XDG_DATA_HOME. Unknown variable names panic rather than resolving to a directory that the child never uses.

is_production_executable_name

Executable names a test must never run a process under.

pinned_sibling_build_revision

Return a cache key combining an archived source revision with caller-supplied dependency names and full commit SHAs. Changing any dependency pin produces a new key; fetching or unpacking those source revisions is up to the caller.

privileged_tests_enabled

Returns true only for CORTEXKIT_PRIVILEGED_TESTS=1; otherwise prints a skip reason.

refuse_production_executable

Panics when program would run under a production executable name (see is_production_executable_name). Call it before spawning any CortexKit binary from a test; dev_command and ckdev_binary already do.

scratch_root

Per-process scratch root, keyed by PID and the kernel’s versioned start identity. Unsupported platforms use an unknown identity, which cleanup always preserves.

shared_scratch_root

Shared root under the system temp directory. Initialization sweeps stale fixtures.

sibling_build_revision

Include the source revisions of caller-named adjacent path-dependency checkouts in the build cache key. Missing checkouts and repo itself are skipped. Names must be plain directory names; order is significant in the hash.

sibling_cache_root

Return a user-owned directory outside the source checkouts for compiled sibling builds. Downloading or unpacking pinned source trees is the caller’s responsibility; this cache stores build outputs, not those source trees.

sibling_cargo_build

Build with a locked sibling manifest and an isolated, caller-owned target directory.

sibling_checkout

Adjacent checkout, falling back to the primary checkout’s sibling for linked worktrees. CORTEXKIT_TEST_WORKSPACE_ROOT can explicitly select the consuming workspace.

sibling_revision

Return a cache key derived from the checkout’s HEAD and source bytes, not its directory location. Staged changes, unstaged changes, and untracked non-ignored files contribute, so each local edit invalidates a cached build.

sibling_target_dir

Caller workspace’s target/sibling-target/<name>; never writes into the sibling.

sign_test_binary

Best-effort macOS signing. The explicit identity wins over CORTEXKIT_TEST_SIGNING_IDENTITY; without either, signing is skipped. Pass Some(OsStr::new("-")) to select ad-hoc signing without a certificate or a signing identity from the user’s keychain. Already-valid signatures are left alone; other platforms do nothing.

stable_executable

Single-file form of stable_executable_dir.

stable_executable_dir

Immutable content-addressed fake executables shared across processes. Do not modify or delete the returned directory. Each complete file is copied by a child and atomically renamed, so concurrent readers never see a partial write.

stage_test_binary

Compatibility staging: ck-* artifacts become ckdev-*; other names pass through.

wait_until_gone

Wait for a PID to be positively known dead. Unknown never counts as gone. On unsupported platforms the result is false after the timeout.

warm_exec_fenced

Run --version with the same environment fence used by test daemons. Assessment is best-effort; failed exits are reported with code or signal.