Introduce a crate to write unit tests of Dioxus apps

Cargo.toml

@@ -49,6 +49,7 @@ members = [
     "packages/asset-resolver",
     "packages/depinfo",
     "packages/component-manifest",
+    "packages/test",
 
     # CLI harnesses, all included
     "packages/cli-harnesses/*",
@@ -209,6 +210,7 @@ wgpu_context = { version = "0.1", default-features = false }
 wgpu = { version = "26.0" }
 vello = "0.6"
 bevy = "0.17"
+taffy = "0.9.2"
 
 
 # a fork of pretty please for tests - let's get off of this if we can!
@@ -220,7 +222,7 @@ tracing = "0.1.41"
 tracing-futures = "0.2.5"
 tracing-subscriber = { version = "0.3.19", default-features = false }
 toml = "0.8"
-tokio = "1.48"
+tokio = { version = "1.48", features = ["time"] }
 tokio-util = { version = "0.7.15" }
 tokio-stream = { version = "0.1.17" }
 slab = "0.4.10"

packages/native-dom/src/events.rs

@@ -1,3 +1,4 @@
+use blitz_dom::Node;
 use blitz_traits::events::{BlitzKeyEvent, BlitzMouseButtonEvent, MouseEventButton};
 use dioxus_html::{
     geometry::{ClientPoint, ElementPoint, PagePoint, ScreenPoint},
@@ -229,3 +230,7 @@ impl HasFocusData for NativeFocusData {
         self as &dyn std::any::Any
     }
 }
+
+pub fn synthetic_click_event(node: &Node, modifiers: Modifiers) -> Box<dyn Any> {
+    Box::new(NativeClickData(node.synthetic_click_event_data(modifiers)))
+}

packages/native-dom/src/lib.rs

@@ -14,6 +14,7 @@ mod events;
 mod mutation_writer;
 pub use blitz_dom::DocumentConfig;
 pub use dioxus_document::DioxusDocument;
+pub use events::synthetic_click_event;
 
 use blitz_dom::{ns, LocalName, Namespace, QualName};
 type NodeId = usize;

packages/test/Cargo.toml

@@ -0,0 +1,23 @@
+[package]
+name = "dioxus-test"
+version = { workspace = true }
+authors = ["Bradford Hovinen"]
+edition = "2024"
+description = "Test library for Dioxus based on native renderer"
+license = "MIT OR Apache-2.0"
+repository = "https://github.com/DioxusLabs/dioxus/"
+homepage = "https://dioxuslabs.com/learn/0.7/getting_started"
+keywords = ["dom", "ui", "gui", "react", "testing"]
+
+[dependencies]
+blitz-dom = { workspace = true }
+dioxus-core = { workspace = true }
+dioxus-html = { workspace = true }
+dioxus-native-dom = { workspace = true }
+taffy = { workspace = true }
+tokio = { workspace = true }
+tracing = { workspace = true }
+
+[dev-dependencies]
+dioxus = { workspace = true }
+tokio = { version = "1.48", features = ["rt", "macros"] }

packages/test/src/element.rs

@@ -0,0 +1,177 @@
+use dioxus_core::{ElementId, Event};
+use dioxus_html::{
+    Modifiers, PlatformEventData,
+    geometry::{Coordinates, euclid::Point2D},
+};
+use dioxus_native_dom::{DioxusDocument, synthetic_click_event};
+use std::rc::Rc;
+
+/// A reference to DOM node managed by a [crate::Tester].
+///
+/// This provides facilities for interacting with the node, querying its layout properties, and
+/// obtaining its content.
+pub struct TestElement<'doc> {
+    pub(crate) document: &'doc DioxusDocument,
+    pub(crate) node: &'doc blitz_dom::Node,
+}
+
+impl<'vdom> TestElement<'vdom> {
+    /// Synonym of [TestElement::click].
+    pub fn tap(&self) {
+        self.click()
+    }
+
+    /// Dispatches a `click` event on this element.
+    ///
+    /// The exact location of the click is unspecified.
+    ///
+    /// If the element has an `onclick` handler, it will be invoked once [crate::Tester::pump] is
+    /// called.
+    pub fn click(&self) {
+        self.send_event(
+            "click",
+            Event::new(
+                Rc::new(PlatformEventData::new(synthetic_click_event(
+                    self.node,
+                    Modifiers::empty(),
+                ))),
+                true,
+            ),
+        )
+    }
+
+    /// Sends an event with the given `name` to this element.
+    ///
+    /// The event is registered with the Dioxus runtime. A subsequent call to [crate::Tester::pump]
+    /// causes the event handler to be invoked, if one is present.
+    ///
+    /// If no event handler is registered corresponding to the event `name`, then this method has no
+    /// effect.
+    ///
+    /// This operates directly on the element, so that is is guaranteed to receive the event. This
+    /// might not reflect how the element would respond in reality. For example, a click at the
+    /// coordinates of a button which is behind a frost element will not reach the button. But this
+    /// method behaves as though it would.
+    ///
+    /// The `event` parameter must contain a [PlatformEventData] with a payload corresponding to the
+    /// specific event type. This method panics if the event payload has the wrong type.
+    pub fn send_event(&self, name: &str, event: Event<PlatformEventData>) {
+        let propagates = event.propagates();
+        self.document.vdom.runtime().handle_event(
+            name,
+            Event::new(event.data, propagates),
+            self.get_element_id()
+                .expect("Expected element to have a Dioxus ID"),
+        );
+    }
+
+    /// Returns a `String` consisting of the HTML of this element and all of its children.
+    pub fn outer_html(&self) -> String {
+        self.node.outer_html()
+    }
+
+    /// Returns a `String` consisting of the HTML of this element's children, not including this
+    /// element itself.
+    pub fn inner_html(&self) -> String {
+        let inner_html_parts: Vec<_> = self
+            .node
+            .children
+            .iter()
+            .filter_map(|child_id| {
+                self.document
+                    .get_node(*child_id)
+                    .map(|child| child.outer_html())
+            })
+            .collect();
+        inner_html_parts.join("")
+    }
+
+    /// Returns the calculated [Coordinates] of the centre of this element.
+    pub fn center(&self) -> Coordinates {
+        let upper_left = self.upper_left();
+        let lower_right = self.lower_right();
+        Coordinates::new(
+            upper_left.screen().lerp(lower_right.screen(), 0.5),
+            upper_left.client().lerp(lower_right.client(), 0.5),
+            upper_left.element().lerp(lower_right.element(), 0.5),
+            upper_left.page().lerp(lower_right.page(), 0.5),
+        )
+    }
+
+    /// Returns the calculated [Coordinates] of the upper-left corner of this element.
+    pub fn upper_left(&self) -> Coordinates {
+        let upper_left = self.node.final_layout.location;
+        Coordinates::new(
+            Self::to_point2d(upper_left),
+            Self::to_point2d(upper_left),
+            Self::to_point2d(upper_left),
+            Self::to_point2d(upper_left),
+        )
+    }
+
+    /// Returns the calculated [Coordinates] of the upper-right corner of this element.
+    pub fn upper_right(&self) -> Coordinates {
+        let mut upper_right = self.node.final_layout.location;
+        upper_right.x += self.node.final_layout.content_box_width();
+        Coordinates::new(
+            Self::to_point2d(upper_right),
+            Self::to_point2d(upper_right),
+            Self::to_point2d(upper_right),
+            Self::to_point2d(upper_right),
+        )
+    }
+
+    /// Returns the calculated [Coordinates] of the lower-left corner of this element.
+    pub fn lower_left(&self) -> Coordinates {
+        let mut lower_left = self.node.final_layout.location;
+        lower_left.y += self.node.final_layout.content_box_height();
+        Coordinates::new(
+            Self::to_point2d(lower_left),
+            Self::to_point2d(lower_left),
+            Self::to_point2d(lower_left),
+            Self::to_point2d(lower_left),
+        )
+    }
+
+    /// Returns the calculated [Coordinates] of the lower-right corner of this element.
+    pub fn lower_right(&self) -> Coordinates {
+        let mut lower_right = self.node.final_layout.location;
+        lower_right.x += self.node.final_layout.content_box_width();
+        lower_right.y += self.node.final_layout.content_box_height();
+        Coordinates::new(
+            Self::to_point2d(lower_right),
+            Self::to_point2d(lower_right),
+            Self::to_point2d(lower_right),
+            Self::to_point2d(lower_right),
+        )
+    }
+
+    fn to_point2d<Space>(point: taffy::geometry::Point<f32>) -> Point2D<f64, Space> {
+        Point2D::new(point.x as f64, point.y as f64)
+    }
+
+    /// Returns the calculated size of this element as a tuple (width, height) in screen pixels.
+    pub fn size(&self) -> (f32, f32) {
+        let height = self.node.final_layout.content_box_height();
+        let width = self.node.final_layout.content_box_width();
+        (width, height)
+    }
+
+    fn get_element_id(&self) -> Option<ElementId> {
+        self.node
+            .element_data()?
+            .attrs
+            .iter()
+            .find(|attr| *attr.name.local == *"data-dioxus-id")
+            .and_then(|attr| attr.value.parse::<usize>().ok())
+            .map(ElementId)
+    }
+}
+
+impl<'doc> std::fmt::Debug for TestElement<'doc> {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("TestElement")
+            .field("node", &self.node)
+            .finish()
+    }
+}

packages/test/src/lib.rs

@@ -0,0 +1,103 @@
+#![cfg_attr(docsrs, feature(doc_cfg))]
+#![allow(clippy::test_attr_in_doctest)] // The doctests need to show examples of tests
+//! A testing crate for Dioxus.
+//!
+//! This crate facilitates rendering, interacting with, and querying the DOM in tests of Dioxus
+//! apps. Tests have fairlz precise control over both the rendering lifecycle and asynchronous
+//! operations. Thus they can assert both on the final outcome of interactions, such as the
+//! rendered data obtained from a call to a backend, as well as intermediate states, such as the
+//! presence of a spinner while loading data.
+//!
+//! This uses the dioxus-native crate to manage the DOM, which in turn uses
+//! [Blitz](https://crates.io/crates/blitz) for layout. It does not depend on a browser or any
+//! other external process.
+//!
+//! Tests operate "headless", so they cannot render their state to the screen.
+//!
+//! ## Usage
+//!
+//! Tests can construct a [Tester] instance to render and interact with the DOM. To construct a
+//! [Tester], the test can invoke the [render] function on a Dioxus component. They must invoke the
+//! `build` to trigger the initial layout. The tester provides methods for querying elements by
+//! CSS selector or by test ID.
+//!
+//! ```
+//! use dioxus::prelude::*;
+//! use dioxus_test::render;
+//!
+//! #[component]
+//! fn MyComponent() -> Element {
+//!     rsx! {
+//!         div {
+//!              class: "test-component",
+//!              "Hello, world!"
+//!         }
+//!     }
+//! }
+//!
+//! #[test]
+//! fn my_component_renders_correctly() {
+//!     let tester = render(MyComponent).build();
+//!     assert_eq!(
+//!         tester.find_by_css_selector(".test-component").unwrap().inner_html(),
+//!         "Hello, world!"
+//!     );
+//! }
+//! ```
+//!
+//! [Tester] also provides methods for interacting with elements and driving the runtime. After
+//! interacting with an element, the test must call [Tester::pump] to cause the event handler to be
+//! invoked.
+//!
+//! ```
+//! use dioxus::prelude::*;
+//! use dioxus_test::render;
+//!
+//! #[component]
+//! fn MyComponent() -> Element {
+//!     let mut text = use_signal(|| "Click me!");
+//!     rsx! {
+//!         button {
+//!              class: "test-button",
+//!              onclick: move |_| {
+//!                  *text.write() = "Don't click any more!";
+//!              },
+//!              {text}
+//!         }
+//!     }
+//! }
+//!
+//! #[tokio::test]
+//! async fn my_component_changes_button_text_on_click() {
+//!     let mut tester = render(MyComponent).build();
+//!     tester.find_first_by_css_selector(".test-button").unwrap().click();
+//!     tester.pump().await;
+//!     assert_eq!(
+//!         tester.find_first_by_css_selector(".test-button").unwrap().inner_html(),
+//!         "Don't click any more!"
+//!     );
+//! }
+//! ```
+//!
+//! ## Asynchronous operations
+//!
+//! The method [Tester::pump] returns control to the async runtime and thus drives any asynchronous
+//! operations such as requests to the backend. If any rendering depends on the result of a request,
+//! then the test must invoke [Tester::pump] to resolve that.
+//!
+//! The test can also assert on the state of the DOM while backend requests are in flight.
+//!
+//! ## Limitations
+//!
+//! Interactions with the DOM operate directly on elements, not on the screen. So if, say, the test
+//! dispatches a click on an element which is covered by a frost, the element will respond as though
+//! it were reachable even though it would not be in reality.
+//!
+//! The layout system is limited by what the Blitz layout system can support. Since Blitz is not
+//! complete as of the time of writing, computed layouts will often not be as in reality.
+
+mod element;
+mod tester;
+
+pub use element::TestElement;
+pub use tester::{Tester, TesterError, render};