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,48 @@ 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>()
+    }
+}
+
 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,71 @@
+//! 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 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);
+    }
+}

crates/bevy_ecs/src/event.rs

@@ -373,6 +373,26 @@ impl<T: Resource> Events<T> {
         }
     }
 
+    /// Iterate over all of the events in this collection
+    ///
+    /// WARNING: This method is stateless, and, because events are double-buffered,
+    /// repeated calls (even in adjacent frames) will result in double-counting events.
+    ///
+    /// In most cases, you want to create an `EventReader` to statefully track which events have been seen.
+    pub fn iter_stateless(&self) -> impl DoubleEndedIterator<Item = &T> {
+        let fresh_events = match self.state {
+            State::A => self.events_a.iter().map(map_instance_event),
+            State::B => self.events_b.iter().map(map_instance_event),
+        };
+
+        let old_events = match self.state {
+            State::B => self.events_a.iter().map(map_instance_event),
+            State::A => self.events_b.iter().map(map_instance_event),
+        };
+
+        old_events.chain(fresh_events)
+    }
+
     /// Iterates over events that happened since the last "update" call.
     /// WARNING: You probably don't want to use this call. In most cases you should use an
     /// `EventReader`. You should only use this if you know you only need to consume events

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,
@@ -761,6 +763,35 @@ impl World {
         self.get_non_send_unchecked_mut_with_id(component_id)
     }
 
+    /// Get a mutable smart pointer to the [`Events`] [`Resource`] corresponding to type `E`
+    ///
+    /// ```rust
+    /// use bevy_ecs::world::World;
+    /// use bevy_ecs::event::Events;
+    ///
+    /// #[derive(Debug)]
+    /// struct Message(String);
+    ///
+    /// let mut world = World::new();
+    /// world.insert_resource(Events::<Message>::default());
+    ///
+    /// world.events::<Message>().send(Message("Hello World!".to_string()));
+    /// world.events::<Message>().send(Message("Welcome to Bevy!".to_string()));
+    ///
+    /// // Cycles the event buffer; typically automatically done once each frame
+    /// // using `app.add_event::<E>()`
+    /// world.events::<Message>().update();
+    ///
+    /// for event in world.events::<Message>().iter_stateless(){
+    ///     dbg!(event);
+    /// }
+    /// ```
+    pub fn events<E: Resource>(&mut self) -> Mut<Events<E>> {
+        self.get_resource_mut::<Events<E>>().expect(
+            "No Events<E> resource found. Did you forget to call `.init_resource` or `.add_event`?",
+        )
+    }
+
     /// For a given batch of ([Entity], [Bundle]) pairs, either spawns each [Entity] with the given
     /// bundle (if the entity does not exist), or inserts the [Bundle] (if the entity already exists).
     /// This is faster than doing equivalent operations one-by-one.
@@ -1144,6 +1175,20 @@ 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()
+    }
+}
+
 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,34 @@
+//! 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::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:?}."
+                );
+            }
+        }
+    }
+}