Rust Testing Scenarios

E2E & Acceptance Testing

Crates SHOULD exercise their public API from tests/, not only from unit tests in src/.

BDD with cucumber-rs

[dev-dependencies]
cucumber = "0.23.0"  # cucumber-rs[^12]
tokio = { version = "1.53.1", features = ["macros", "rt-multi-thread"] }

# REQUIRED: a named test target with the libtest harness disabled, so that
# the `main` in tests/cucumber.rs is the entry point.
[[test]]
name = "cucumber"
harness = false

A Cucumber test target MUST set harness = false.

Why: with the default libtest harness, Cargo generates its own main and the #[tokio::main] async fn main below is never called. cargo test --test cucumber then reports “running 0 tests … test result: ok” and the build goes green having executed no scenarios at all.¹

// tests/cucumber.rs
use cucumber::{World as _, given, then, when};

#[derive(Debug, Default, cucumber::World)]
struct MyWorld {
    result: Option<String>,
}

#[given("a user is logged in")]
async fn given_logged_in(_world: &mut MyWorld) {
    // Setup
}

#[when(regex = r"^they request (.*)$")]
async fn when_request(world: &mut MyWorld, resource: String) {
    world.result = Some(fetch(&resource).await);
}

#[then(regex = r"^they receive (.*)$")]
async fn then_receive(world: &mut MyWorld, expected: String) {
    assert_eq!(world.result.as_deref(), Some(expected.as_str()));
}

#[tokio::main]
async fn main() {
    MyWorld::run("tests/features").await;
}

cucumber 0.23.0 requires Rust 1.88 or later, below the MSRV of 1.94.0 that the Rust Style Guide declares, so it adds no constraint of its own.¹

Idempotence Testing

Operations that a client MAY retry — anything behind a network, a queue, or a timeout — MUST be tested by invoking them twice and asserting on the resulting state, not on the second return value.

Reliability & Resilience Testing

Failure paths MUST be tested by injecting the failure, not by waiting for it to occur naturally.

Compatibility Testing

Crates MUST verify every platform and toolchain they claim to support.

Version Pinning with rust-toolchain.toml

The toolchain pin, the MSRV declaration, and the two CI lanes are specified in Toolchain, Edition, and MSRV. The pinned channel MUST be at least the highest rust-version in the dependency graph: cucumber 0.23.0 requires Rust 1.88 and SQLx 0.9.0 requires 1.94.0, so a 1.75 pin cannot build this guide’s own examples.¹²

CI Matrix for Multiple Targets

Matrices MUST pair each target with a host that can build and run it. A Cartesian product of os and target produces combinations such as windows-latest building x86_64-unknown-linux-gnu, for which no linker or runner is installed. Native test runs MUST be expressed as explicit include tuples; cross-compilation MUST use cargo check, which does not link or execute.³

jobs:
  # Native: host and target agree, so binaries link and run.
  test:
    name: test (${{ matrix.rust }}, ${{ matrix.target }})
    strategy:
      fail-fast: false
      matrix:
        include:
          - os: ubuntu-latest      # x64 Linux
            target: x86_64-unknown-linux-gnu
            rust: stable
          - os: windows-latest     # x64 Windows
            target: x86_64-pc-windows-msvc
            rust: stable
          - os: macos-latest       # arm64 macOS
            target: aarch64-apple-darwin
            rust: stable
          - os: ubuntu-latest
            target: x86_64-unknown-linux-gnu
            rust: beta
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8 # v1
        with:
          toolchain: ${{ matrix.rust }}
          targets: ${{ matrix.target }}
      - run: cargo test --target ${{ matrix.target }}

  # Cross: compile only. `cargo check` never links, so no cross linker or
  # emulator is required.
  cross-check:
    name: cross-check (${{ matrix.target }})
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        target:
          - aarch64-unknown-linux-gnu
          - x86_64-pc-windows-gnu
          - wasm32-unknown-unknown
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8 # v1
        with:
          toolchain: stable
          targets: ${{ matrix.target }}
      - run: cargo check --target ${{ matrix.target }}

macos-latest is an arm64 image, so aarch64-apple-darwin is its native target; x86_64-apple-darwin would need Rosetta to run the resulting test binary.³

Unicode Normalization

unic MUST NOT be used. Normalization-only work SHOULD use unicode-normalization⁴; locale-aware formatting, collation, segmentation, and case mapping SHOULD use ICU4X⁵.

Why: unic 0.9.0 was published on 3 March 2019 and carries Unicode 10 data. The current standard is Unicode 17.0.0, so unic classifies every character assigned since 2017 as unassigned and normalizes them incorrectly or not at all. unicode-normalization 0.1.25 exposes unicode_normalization::UNICODE_VERSION == (17, 0, 0), matching the current standard, and does one job well. ICU4X is the choice when the requirement is internationalization rather than normalization: it carries CLDR locale data, which no normalization crate does.⁶⁴⁵

[dependencies]
unicode-normalization = "0.1.25"  # Unicode 17.0.0 data

# For locale-aware i18n rather than normalization
[dependencies]
icu = "2.3.1"  # ICU4X[^47]

Normalization fixtures MUST be written with explicit Unicode escapes. Editors and clipboards silently normalize pasted text, so two literals that look different on screen can hold identical code points, which turns the assertion into a no-op or an outright failure.

use unicode_normalization::UnicodeNormalization as _;

#[must_use]
pub fn nfc(text: &str) -> String {
    text.nfc().collect()
}

#[test]
fn normalization_makes_the_two_spellings_equal() {
    // "café" with a precomposed U+00E9, versus "e" + U+0301 combining acute.
    let precomposed = "caf\u{e9}";  // NFC
    let decomposed = "cafe\u{301}"; // NFD

    // Different code points before normalization.
    assert_ne!(precomposed, decomposed);
    assert_eq!(precomposed.chars().count(), 4);
    assert_eq!(decomposed.chars().count(), 5);

    // Equal after normalization.
    assert_eq!(nfc(precomposed), nfc(decomposed));
}

#[test]
fn unicode_data_version_is_current() {
    assert_eq!(unicode_normalization::UNICODE_VERSION, (17, 0, 0));
}

// BAD: both literals are precomposed, so `assert_ne!` fails immediately.
let s1 = "café";  // claims NFC
let s2 = "café";  // claims NFD, but holds the same U+00E9

# BAD: unreleased since 2019, Unicode 10 data.
unic = "0.9"

sqlx Compile-Time Checked Queries

SQLx² 0.9 MUST be used, and the runtime and TLS backends MUST be selected explicitly. The repository moved from launchbadge/sqlx to transact-rs/sqlx; the old URL redirects but MUST NOT be used in new links.

Why: SQLx has no default runtime or TLS backend. runtime-tokio, runtime-smol, and runtime-async-global-executor are mutually exclusive choices, and TLS is a separate axis: tls-none, tls-native-tls, or one of the tls-rustls-* variants which differ in cryptographic provider and certificate store. Leaving TLS unstated works locally over a Unix socket and fails on a managed database that requires TLS. default-features = false makes the choice explicit rather than inheriting any, macros, migrate, and json.²

[dependencies]
sqlx = { version = "0.9.0", default-features = false, features = [
    "runtime-tokio",             # runtime: exactly one
    "tls-rustls-ring-webpki",    # TLS: pick explicitly, or tls-none
    "postgres",
    "macros",                    # query_as!, query_scalar!, sqlx::test
    "migrate",
] }

# BAD: SQLx 0.7, the pre-0.9 combined feature name, and no TLS decision.
sqlx = { version = "0.7", features = ["runtime-tokio-rustls", "postgres"] }

The checked macros need schema access at compile time. Either DATABASE_URL MUST be set when building, or offline metadata MUST be committed:

cargo install sqlx-cli --version 0.9.0 --locked --no-default-features \
  --features postgres,rustls
cargo sqlx prepare        # writes .sqlx/, which MUST be committed
SQLX_OFFLINE=true cargo check

Why: without one of the two, cargo check fails with “error: set DATABASE_URL to use query macros online, or run cargo sqlx prepare to update the query cache” — including in CI, where the database usually does not exist. Committing .sqlx/ keeps the check reproducible and makes a schema change visible in review.

use sqlx::PgPool;

#[sqlx::test]
async fn test_query_correctness(pool: PgPool) -> sqlx::Result<()> {
    // Compile-time verified query
    let user = sqlx::query_as!(
        User,
        "SELECT id, name, email FROM users WHERE id = $1",
        1
    )
    .fetch_one(&pool)
    .await?;

    assert_eq!(user.id, 1);
    Ok(())
}

Where compile-time checking is not wanted, the runtime API needs neither a database at build time nor offline metadata:

use sqlx::PgPool;

#[derive(Debug, sqlx::FromRow)]
pub struct User {
    pub id: i64,
    pub name: String,
    pub email: String,
}

/// Loads one user by primary key.
///
/// # Errors
///
/// Returns the driver error when the row is missing or the query fails.
pub async fn fetch_user(pool: &PgPool, id: i64) -> sqlx::Result<User> {
    sqlx::query_as::<_, User>("SELECT id, name, email FROM users WHERE id = $1")
        .bind(id)
        .fetch_one(pool)
        .await
}