Utility functions for integration testing

crates/bevy_app/src/app.rs

@@ -2,6 +2,7 @@ use crate::{CoreStage, Events, Plugin, PluginGroup, PluginGroupBuilder, StartupS
 pub use bevy_derive::AppLabel;
 use bevy_ecs::{
     prelude::{FromWorld, IntoExclusiveSystem},
+    query::{FilterFetch, WorldQuery},
     schedule::{
         IntoSystemDescriptor, RunOnce, Schedule, Stage, StageLabel, State, StateData, SystemSet,
         SystemStage,
@@ -910,6 +911,104 @@ impl App {
     }
 }
 
+// Testing adjacents tools
+impl App {
+    /// Returns the number of entities found by the [`Query`](bevy_ecs::system::Query) with the type parameters `Q` and `F`
+    ///
+    /// # Example
+    /// ```rust
+    /// # use bevy_app::App;
+    /// # use bevy_ecs::prelude::*;
+    ///
+    /// #[derive(Component)]
+    /// struct Player;
+    ///
+    /// #[derive(Component)]
+    /// struct Life(usize);
+    ///
+    /// let mut app = App::new();
+    ///
+    /// fn spawn_player(mut commands: Commands){
+    ///     commands.spawn().insert(Life(10)).insert(Player);
+    /// }
+    ///
+    /// app.add_startup_system(spawn_player);
+    /// assert_eq!(app.query_len::<&Life, With<Player>>(), 0);
+    ///
+    /// // Run the `Schedule` once, causing our startup system to run
+    /// app.update();
+    /// assert_eq!(app.query_len::<&Life, With<Player>>(), 1);
+    ///
+    /// // Running the schedule again won't cause startup systems to rerun
+    /// app.update();
+    /// assert_eq!(app.query_len::<&Life, With<Player>>(), 1);
+    /// ```
+    pub fn query_len<Q, F>(&mut self) -> usize
+    where
+        Q: WorldQuery,
+        F: WorldQuery,
+        <F as WorldQuery>::Fetch: FilterFetch,
+    {
+        self.world.query_len::<Q, F>()
+    }
+
+    /// Sends an `event` of type `E`
+    ///
+    /// # Example
+    /// ```rust
+    /// # use bevy_app::App;
+    /// # use bevy_ecs::prelude::*;
+    ///
+    /// let mut app = App::new();
+    ///
+    /// struct Message(String);
+    ///
+    /// fn print_messages(mut messages: EventReader<Message>){
+    ///     for message in messages.iter(){
+    ///         println!("{}", message.0);
+    ///     }
+    /// }
+    ///
+    /// app.add_event::<Message>().add_system(print_messages);
+    /// app.send_event(Message("Hello!".to_string()));
+    ///
+    /// // Says "Hello!"
+    /// app.update();
+    ///
+    /// // All the events have been processed
+    /// app.update();
+    /// ```
+    pub fn send_event<E: Resource>(&mut self, event: E) {
+        self.world.send_event(event);
+    }
+
+    /// Returns the number of events of the type `E` that were sent this frame
+    ///
+    /// # Example
+    /// ```rust
+    /// # use bevy_app::App;
+    /// # use bevy_ecs::prelude::*;
+    ///
+    /// // An event type
+    /// #[derive(Debug)]
+    /// struct SelfDestruct;
+    ///
+    /// let mut app = App::new();
+    /// app.add_event::<SelfDestruct>();
+    /// assert_eq!(app.events_len::<SelfDestruct>(), 0);
+    ///
+    /// app.send_event(SelfDestruct);
+    /// assert_eq!(app.events_len::<SelfDestruct>(), 1);
+    ///
+    /// // Time passes
+    /// app.update();
+    /// assert_eq!(app.events_len::<SelfDestruct>(), 0);
+    /// ```
+    pub fn events_len<E: Resource>(&self) -> usize {
+        self.world.events_len::<E>()
+    }
+}
+
 fn run_once(mut app: App) {
     app.update();
 }

crates/bevy_app/src/lib.rs

@@ -6,6 +6,7 @@ mod app;
 mod plugin;
 mod plugin_group;
 mod schedule_runner;
+mod testing_tools;
 
 #[cfg(feature = "bevy_ci_testing")]
 mod ci_testing;

crates/bevy_app/src/testing_tools.rs

@@ -0,0 +1,160 @@
+//! Tools for convenient integration testing of the ECS.
+//!
+//! Each of these methods has a corresponding method on `World`.
+
+use crate::App;
+use bevy_ecs::component::Component;
+use bevy_ecs::query::{FilterFetch, WorldQuery};
+use bevy_ecs::system::IntoSystem;
+use std::fmt::Debug;
+
+impl App {
+    /// Asserts that all components of type `C` returned by a query with the filter `F` will equal `value`
+    ///
+    /// This is commonly used with the corresponding `query_len` method to ensure that the returned query is not empty.
+    ///
+    /// WARNING: because we are constructing the query from scratch,
+    /// [`Changed`](bevy_ecs::query::Changed) and [`Added`](bevy_ecs::query::Added) filters
+    /// will always return true.
+    ///
+    /// # Example
+    /// ```rust
+    /// # use bevy_app::App;
+    /// # use bevy_ecs::prelude::*;
+    ///
+    /// #[derive(Component)]
+    /// struct Player;
+    ///
+    /// #[derive(Component, Debug, PartialEq)]
+    /// struct Life(usize);
+    ///
+    /// let mut app = App::new();
+    ///
+    /// fn spawn_player(mut commands: Commands){
+    ///     commands.spawn().insert(Life(8)).insert(Player);
+    /// }
+    ///
+    /// fn regenerate_life(mut query: Query<&mut Life>){
+    ///     for mut life in query.iter_mut(){
+    ///         if life.0 < 10 {
+    ///             life.0 += 1;
+    ///         }
+    ///     }
+    /// }
+    ///
+    /// app.add_startup_system(spawn_player).add_system(regenerate_life);
+    ///
+    /// // Run the `Schedule` once, causing our startup system to run
+    /// // and life to regenerate once
+    /// app.update();
+    /// // The `()` value for `F` will result in an unfiltered query
+    /// app.assert_component_eq::<Life, ()>(&Life(9));
+    ///
+    /// app.update();
+    /// // Because all of our entities with the `Life` component also
+    /// // have the `Player` component, these will be equivalent.
+    /// app.assert_component_eq::<Life, With<Player>>(&Life(10));
+    ///
+    /// app.update();
+    /// // Check that life regeneration caps at 10, as intended
+    /// // Filtering by the component type you're looking for is useless,
+    /// // but it's helpful to demonstrate composing query filters here
+    /// app.assert_component_eq::<Life, (With<Player>, With<Life>)>(&Life(10));
+    /// ```
+    pub fn assert_component_eq<C, F>(&mut self, value: &C)
+    where
+        C: Component + PartialEq + Debug,
+        F: WorldQuery,
+        <F as WorldQuery>::Fetch: FilterFetch,
+    {
+        self.world.assert_component_eq::<C, F>(value);
+    }
+
+    /// Asserts that when the supplied `system` is run on the world, its output will be `Ok`
+    ///
+    /// The `system` must return a `Result`: if the return value is an error the app will panic.
+    ///
+    /// For more sophisticated error-handling, consider adding the system directly to the schedule
+    /// and using [system chaining](bevy_ecs::prelude::IntoChainSystem) to handle the result yourself.
+    ///
+    /// WARNING: [`Changed`](bevy_ecs::query::Changed) and [`Added`](bevy_ecs::query::Added) filters
+    /// are computed relative to "the last time this system ran".
+    /// Because we are running a new system, these filters will always be true.
+    ///
+    /// # Example
+    /// ```rust
+    /// # use bevy_app::App;
+    /// # use bevy_ecs::prelude::*;
+    ///
+    /// #[derive(Component)]
+    /// struct Player;
+    ///
+    /// #[derive(Component, Debug, PartialEq)]
+    /// struct Life(usize);
+    ///
+    /// #[derive(Component)]
+    /// struct Dead;
+    ///
+    /// let mut app = App::new();
+    ///
+    /// fn spawn_player(mut commands: Commands){
+    ///     commands.spawn().insert(Life(10)).insert(Player);
+    /// }
+    ///
+    /// fn massive_damage(mut query: Query<&mut Life>){
+    ///     for mut life in query.iter_mut(){
+    ///         // Life totals can never go below zero
+    ///         life.0 = life.0.checked_sub(9001).unwrap_or_default();
+    ///     }
+    /// }
+    ///
+    /// fn kill_units(query: Query<(Entity, &Life)>, mut commands: Commands){
+    ///     for (entity, life) in query.iter(){
+    ///         if life.0 == 0 {
+    ///             commands.entity(entity).insert(Dead);
+    ///         }
+    ///     }
+    /// }
+    ///
+    /// app.add_startup_system(spawn_player)
+    ///    .add_system(massive_damage)
+    ///    .add_system(kill_units);
+    ///
+    /// // Run the `Schedule` once, causing both our startup systems
+    /// // and ordinary systems to run once
+    /// app.update();
+    ///
+    /// enum DeathError {
+    ///     ZeroLifeIsNotDead,
+    ///     DeadWithNonZeroLife,
+    /// }
+    ///
+    /// // Run a complex assertion on the world using a system
+    /// fn zero_life_is_dead(query: Query<(&Life, Option<&Dead>)>) -> Result<(), DeathError> {
+    ///     for (life, maybe_dead) in query.iter(){
+    ///        if life.0 == 0 {
+    ///            if maybe_dead.is_none(){
+    ///                return Err(DeathError::ZeroLifeIsNotDead);
+    ///            }
+    ///         }
+    ///
+    ///         if maybe_dead.is_some(){
+    ///             if life.0 != 0 {
+    ///                return Err(DeathError::DeadWithNonZeroLife);
+    ///             }
+    ///         }
+    ///     }
+    ///     // None of our checks failed, so our world state is clean
+    ///     Ok(())
+    /// }
+    ///
+    /// app.update();
+    /// app.assert_system(zero_life_is_dead);
+    /// ```
+    pub fn assert_system<T: 'static, E: 'static, SystemParams>(
+        &mut self,
+        system: impl IntoSystem<(), Result<T, E>, SystemParams>,
+    ) {
+        self.world.assert_system(system);
+    }
+}

crates/bevy_ecs/src/world/mod.rs

@@ -1,5 +1,6 @@
 mod entity_ref;
 mod spawn_batch;
+mod testing_tools;
 mod world_cell;
 
 pub use crate::change_detection::Mut;
@@ -13,6 +14,7 @@ use crate::{
     change_detection::Ticks,
     component::{Component, ComponentId, ComponentTicks, Components, StorageType},
     entity::{AllocAtWithoutReplacement, Entities, Entity},
+    event::Events,
     query::{FilterFetch, QueryState, WorldQuery},
     storage::{Column, SparseSet, Storages},
     system::Resource,
@@ -1144,6 +1146,36 @@ impl World {
     }
 }
 
+// Testing-adjacent tools
+impl World {
+    /// Returns the number of entities found by the [`Query`](crate::system::Query) with the type parameters `Q` and `F`
+    pub fn query_len<Q, F>(&mut self) -> usize
+    where
+        Q: WorldQuery,
+        F: WorldQuery,
+        <F as WorldQuery>::Fetch: FilterFetch,
+    {
+        let mut query_state = self.query_filtered::<Q, F>();
+        query_state.iter(self).count()
+    }
+
+    /// Sends an `event` of type `E`
+    pub fn send_event<E: Resource>(&mut self, event: E) {
+        let mut events: Mut<Events<E>> = self.get_resource_mut()
+        .expect("The specified event resource was not found in the world. Did you forget to call `app.add_event::<E>()`?");
+
+        events.send(event);
+    }
+
+    /// Returns the number of events of the type `E` that were sent this frame
+    pub fn events_len<E: Resource>(&self) -> usize {
+        let events = self.get_resource::<Events<E>>()
+        .expect("The specified event resource was not found in the world. Did you forget to call `app.add_event::<E>()`?");
+
+        events.len()
+    }
+}
+
 impl fmt::Debug for World {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         f.debug_struct("World")

crates/bevy_ecs/src/world/testing_tools.rs

@@ -0,0 +1,54 @@
+//! Tools for convenient integration testing of the ECS.
+//!
+//! Each of these methods has a corresponding method on `App`;
+//! in many cases, these are more convenient to use.
+
+use crate::component::Component;
+use crate::entity::Entity;
+use crate::schedule::{Stage, SystemStage};
+use crate::system::{In, IntoChainSystem, IntoSystem};
+use crate::world::{FilterFetch, World, WorldQuery};
+use std::fmt::Debug;
+
+impl World {
+    /// Asserts that all components of type `C` returned by a query with the filter `F` will equal `value`
+    ///
+    /// This is commonly used with the corresponding `query_len` method to ensure that the returned query is not empty.
+    ///
+    /// WARNING: because we are constructing the query from scratch,
+    /// [`Changed`](crate::query::Changed) and [`Added`](crate::query::Added) filters
+    /// will always return true.
+    pub fn assert_component_eq<C, F>(&mut self, value: &C)
+    where
+        C: Component + PartialEq + Debug,
+        F: WorldQuery,
+        <F as WorldQuery>::Fetch: FilterFetch,
+    {
+        let mut query_state = self.query_filtered::<(Entity, &C), F>();
+        for (entity, component) in query_state.iter(self) {
+            if component != value {
+                panic!(
+                    "Found component {component:?} for {entity:?}, but was expecting {value:?}."
+                );
+            }
+        }
+    }
+
+    /// Asserts that when the supplied `system` is run on the world, its output will be `true`
+    ///
+    /// WARNING: [`Changed`](crate::query::Changed) and [`Added`](crate::query::Added) filters are computed relative to "the last time this system ran".
+    /// Because we are generating a new system, these filters will always be true.
+    pub fn assert_system<T: 'static, E: 'static, Params>(
+        &mut self,
+        system: impl IntoSystem<(), Result<T, E>, Params>,
+    ) {
+        let mut stage = SystemStage::single_threaded();
+        stage.add_system(system.chain(assert_input_system_ok));
+        stage.run(self);
+    }
+}
+
+/// A chainable system that panics if its `input`'s [`Result`] is not okay
+fn assert_input_system_ok<T, E>(In(result): In<Result<T, E>>) {
+    assert!(result.is_ok());
+}