🎓 A1Learner
🔍

Rust Testing the Other Platform's Code

Platform-gated code is code that the compiler removes on other platforms. Code for another platform is not compiled on this machine at all.

A seam you can swap

Keep the platform fact behind one tiny function. Real code calls home_key() and never asks where the answer came from:

#[cfg(not(test))]
fn home_key() -> &'static str {
    if cfg!(windows) { "USERPROFILE" } else { "HOME" }
}

A fake takes the seat during tests

The same name, gated on cfg(test), replaces the real one in test builds. The shared logic then runs against a known answer:

#[cfg(test)]
fn home_key() -> &'static str {
    "TEST_HOME"
}

The test that spends the fake

The logic under test cannot tell the difference. It calls home_key() and gets the test answer:

#[test]
fn logic_uses_the_fake() {
    assert_eq!(describe_home(), "the home folder is named by TEST_HOME");
}

Let tests compile the other side

any(..., test) widens a gate for test builds. This Windows module is normally invisible here. Under cargo test it compiles, and its own test runs:

#[cfg(any(target_os = "windows", test))]
mod win_bits {
    pub fn greeting() -> String {
        let path = ["C:", "Users"].join("\\");
        format!("home lives at {path}")
    }
}

Ask another target's compiler

A target you have installed can be checked without owning its machine. This command type-checks your crate as WebAssembly, wasm branches included:

// in your terminal:
// $ cargo check --target wasm32-unknown-unknown

Example

#[cfg(not(test))]
fn home_key() -> &'static str {
    if cfg!(windows) { "USERPROFILE" } else { "HOME" }
}

#[cfg(test)]
fn home_key() -> &'static str {
    "TEST_HOME"
}

fn describe_home() -> String {
    format!("the home folder is named by {}", home_key())
}

fn main() {
    println!("{}", describe_home());
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn logic_uses_the_fake() {
        assert_eq!(describe_home(), "the home folder is named by TEST_HOME");
    }
}

Key points

  • Uncompiled code is unchecked code.
  • A cfg'd-out branch can hold typos, old names and wrong types.
  • Your build stays green.
  • Thin seams are the main defence: the smaller the platform-gated surface, the more of your program the everyday build checks
  • The any(platform, test) trick only checks bodies written in portable Rust.
  • A call to a platform-only API still cannot compile here — that is what per-target CI builds are for
  • A fake and its real twin are never compiled together, so keep their signatures in lockstep yourself
  • Checking is not running — but an unchecked branch is worse than either.

In this example, one name has two bodies, and cfg picks exactly one per build. A normal run keeps the cfg(not(test)) body, so main prints the real answer for this machine: HOME. Under cargo test, the cfg(test) body takes the seat, and describe_home() runs against TEST_HOME. The test below passes — it was run, and it passes. The shared logic is now checked on every machine. The platform fact itself can only be real on its own platform.

Note

cargo check --target needs the target installed first (rustup target add).

Try it Yourself

Edit the code, then press Run.

Running is simulated · Rust Playground

Exercise

Why can a Windows-only function be broken for weeks while every local build stays green?