bevy-testing

Bevy 0.19 — deterministic testing

When to use this skill

• Systems/plugins need a minimal App harness and direct world assertions.
• Fixed schedules, timers, messages, or observers need deterministic stepping.
• Async work must complete in tests without arbitrary sleeps.
• Rendered output needs capture-based visual regression.

Build the smallest App that owns the behaviour under test, control its clock and inputs, step it explicitly, then inspect world state or emitted output. Do not call App::run() in an ordinary unit/integration test.

Canonical pattern

use bevy::{prelude::*, time::{TimePlugin, TimeUpdateStrategy}};

#[derive(Resource, Default)]
struct TickCount(u32);

fn count_tick(mut count: ResMut<TickCount>) {
    count.0 += 1;
}

#[test]
fn fixed_system_runs_exactly_three_times() {
    let mut app = App::new();
    app.add_plugins(TimePlugin)
        .insert_resource(Time::<Fixed>::from_hz(60.0))
        .insert_resource(TimeUpdateStrategy::FixedTimesteps(1))
        .init_resource::<TickCount>()
        .add_systems(FixedUpdate, count_tick);

    // The first update initializes Bevy's real-time clock; it has zero delta.
    app.update();

    for _ in 0..3 {
        app.update();
    }

    assert_eq!(app.world().resource::<TickCount>().0, 3);
}

After the first clock-initialising update, FixedTimesteps(n) makes each app.update() advance by the fixed timestep times n and run exactly n fixed loops. Use ManualDuration when the test must exercise zero-tick frames, accumulated time, or catch-up. Use ManualInstant when exact absolute instants matter and advance its resource before each update.

Gotchas

• The first app.update() initialises real time with zero delta; warm it up before counting FixedTimesteps ticks or assert that zero-step frame deliberately.
• Running FixedUpdate directly bypasses fixed-main clock/message semantics.
• Deferred Commands are invisible until a synchronization point.
• Async completion must use an injected fake or a bounded predicate loop, never sleep.
• DefaultPlugins adds platform/render/audio state most world tests do not need.