Using Lightyear Testing Framework (lightyear_tests::stepper)

[utgarda]

Context

I'm building a multiplayer game using Lightyear 0.24.2 and want to write integration tests for client-server interactions (entity replication, input handling) without running full graphical clients.

I discovered lightyear_tests::stepper::ClientServerStepper which looks perfect, but I'm hitting visibility issues.

Current Problem

My test code:

use lightyear_tests::stepper::ClientServerStepper;

#[test]
fn test_client_sees_replicated_entity() {
    let mut stepper = ClientServerStepper::default_no_init();
    stepper.new_client();
    stepper.server_app.add_plugins(MyProtocol);
    stepper.client_app().add_plugins(MyProtocol);
    stepper.init();
    // Test entity replication...
}

Compilation errors:

error[E0624]: associated function `default_no_init` is private
error[E0624]: method `new_client` is private
error[E0624]: method `init` is private

These are marked pub(crate) in lightyear_tests/src/stepper.rs.

Why I Need This

Without Lightyear's testing utilities, I'm stuck with:

1. Unit tests only - Miss integration issues
2. Manual testing - ./run_local.sh is slow, not CI-friendly, hard to reproduce scenarios

The ClientServerStepper pattern is exactly what I need: fast headless tests, full protocol stack, deterministic simulation, easy assertions.

Questions

1. Is lightyear_tests intended for external projects? The crate exists but all APIs are pub(crate). Should I use a different approach?

2. Would you consider publishing lightyear_tests as a public crate? Similar to bevy_ecs test utilities - this would help the ecosystem significantly.

3. What's the recommended testing strategy meanwhile?

   • Copy stepper code into my project?
   • Use path dependency with visibility changes?
   • Just rely on manual testing?

Alternative I'm Using

I wrote simpler unit tests:

#[test]
fn test_entities_spawn_with_controlled_by() {
    let mut app = App::new();
    app.add_plugins(MinimalPlugins);

    let client1 = app.world_mut().spawn_empty().id();
    spawn_entities_with_replication(&mut app.world_mut().commands(), ...);

    assert!(app.world().get::<ControlledBy>(entity).is_some());
}

This validates spawn logic but not actual replication, prediction, input buffering, or network behavior.

Reference

• My test (worked with local Lightyear where I made methods pub): server/tests/stepper_connection_test.rs
• Your examples use ClientServerStepper::default() (public) but not default_no_init() (private)

Thanks for building Lightyear - just trying to figure out best testing practices! 🙏

[cBournhonesque]

lightyear_tests was mainly intended to be used only for internal tests, but i'm open for more types to be public + publishing it if it's helpful.
I'd accept PRs that turn most of the inner types pub.
We might want to also cleanup the api a little bit

[utgarda]

I'll give it a try.
#1301

[cBournhonesque]

I published lightyear_tests v0.25.5

[utgarda]

Could you publish a new release that includes the optional steam feature in lightyear_tests?