freya_testing/

lib.rs

//! Testing utilities for Freya applications.
//!
//! Simulate your app execution in a headless environment.
//!
//! Use [launch_test] or [TestingRunner] to instantiate a headless testing runner.
//!
//! # Examples
//!
//! Basic usage:
//!
//! ```rust,no_run
//! use freya::prelude::*;
//! use freya_testing::TestingRunner;
//!
//! fn app() -> impl IntoElement {
//!     let mut state = use_consume::<State<i32>>();
//!     rect().on_mouse_up(move |_| *state.write() += 1)
//! }
//!
//! fn main() {
//!     let (mut test, state) = TestingRunner::new(
//!         app,
//!         (300., 300.).into(),
//!         |runner| runner.provide_root_context(|| State::create(0)),
//!         1.,
//!     );
//!     test.sync_and_update();
//!     // Simulate a mouse click
//!     test.click_cursor((15., 15.));
//!     assert_eq!(*state.peek(), 1);
//! }
//! ```
//!
//! For a runnable example see `examples/testing_events.rs` in the repository.

use std::{
    borrow::Cow,
    cell::RefCell,
    collections::HashMap,
    fs::File,
    io::Write,
    path::PathBuf,
    rc::Rc,
    time::{
        Duration,
        Instant,
    },
};

use freya_clipboard::copypasta::{
    ClipboardContext,
    ClipboardProvider,
};
use freya_components::{
    cache::AssetCacher,
    integration::integration,
};
use freya_core::{
    integration::*,
    prelude::*,
};
use freya_engine::prelude::{
    EncodedImageFormat,
    FontCollection,
    FontMgr,
    SkData,
    TypefaceFontProvider,
    raster_n32_premul,
};
use ragnarok::{
    CursorPoint,
    EventsExecutorRunner,
    EventsMeasurerRunner,
    NodesState,
};
use torin::prelude::{
    LayoutNode,
    Size2D,
};

pub mod prelude {
    pub use freya_core::{
        events::platform::*,
        prelude::*,
    };

    pub use crate::{
        DocRunner,
        TestingRunner,
        launch_doc,
        launch_test,
    };
}

type DocRunnerHook = Box<dyn FnOnce(&mut TestingRunner)>;

pub struct DocRunner {
    app: AppComponent,
    size: Size2D,
    scale_factor: f64,
    hook: Option<DocRunnerHook>,
    image_path: PathBuf,
}

impl DocRunner {
    pub fn render(self) {
        let (mut test, _) = TestingRunner::new(self.app, self.size, |_| {}, self.scale_factor);
        if let Some(hook) = self.hook {
            (hook)(&mut test);
        }
        test.render_to_file(self.image_path);
    }

    pub fn with_hook(mut self, hook: impl FnOnce(&mut TestingRunner) + 'static) -> Self {
        self.hook = Some(Box::new(hook));
        self
    }

    pub fn with_image_path(mut self, image_path: PathBuf) -> Self {
        self.image_path = image_path;
        self
    }

    pub fn with_scale_factor(mut self, scale_factor: f64) -> Self {
        self.scale_factor = scale_factor;
        self
    }

    pub fn with_size(mut self, size: Size2D) -> Self {
        self.size = size;
        self
    }
}

pub fn launch_doc(app: impl Into<AppComponent>, path: impl Into<PathBuf>) -> DocRunner {
    DocRunner {
        app: app.into(),
        size: Size2D::new(250., 250.),
        scale_factor: 1.0,
        hook: None,
        image_path: path.into(),
    }
}

pub fn launch_test(app: impl Into<AppComponent>) -> TestingRunner {
    TestingRunner::new(app, Size2D::new(500., 500.), |_| {}, 1.0).0
}

pub struct TestingRunner {
    nodes_state: NodesState<NodeId>,
    runner: Runner,
    tree: Rc<RefCell<Tree>>,
    size: Size2D,

    accessibility: AccessibilityTree,

    events_receiver: futures_channel::mpsc::UnboundedReceiver<EventsChunk>,
    events_sender: futures_channel::mpsc::UnboundedSender<EventsChunk>,

    requested_focus_strategy: Rc<RefCell<Option<AccessibilityFocusStrategy>>>,

    font_manager: FontMgr,
    font_collection: FontCollection,

    platform: Platform,

    animation_clock: AnimationClock,
    ticker_sender: RenderingTickerSender,

    default_fonts: Vec<Cow<'static, str>>,
    scale_factor: f64,
}

impl TestingRunner {
    pub fn new<T>(
        app: impl Into<AppComponent>,
        size: Size2D,
        hook: impl FnOnce(&mut Runner) -> T,
        scale_factor: f64,
    ) -> (Self, T) {
        let (events_sender, events_receiver) = futures_channel::mpsc::unbounded();
        let app = app.into();
        let mut runner = Runner::new(move || integration(app.clone()).into_element());

        runner.provide_root_context(GlobalContexts::default);

        runner.provide_root_context(ScreenReader::new);

        let (ticker_sender, ticker) = RenderingTicker::new();
        runner.provide_root_context(|| ticker);

        let animation_clock = runner.provide_root_context(AnimationClock::new);

        runner.provide_root_context(AssetCacher::create);

        let tree = Tree::default();
        let tree = Rc::new(RefCell::new(tree));

        let requested_focus_strategy: Rc<RefCell<Option<AccessibilityFocusStrategy>>> =
            Rc::new(RefCell::new(None));

        let platform = runner.provide_root_context({
            let requested_focus_strategy = requested_focus_strategy.clone();
            || Platform {
                focused_accessibility_id: State::create(ACCESSIBILITY_ROOT_ID),
                focused_accessibility_node: State::create(accesskit::Node::new(
                    accesskit::Role::Window,
                )),
                root_size: State::create(size),
                scale_factor: State::create(scale_factor),
                custom_scale_factor: State::create(1.0),
                navigation_mode: State::create(NavigationMode::NotKeyboard),
                preferred_theme: State::create(PreferredTheme::Light),
                is_app_focused: State::create(true),
                accent_color: State::create(AccentColor::default()),
                sender: Rc::new(move |user_event| {
                    match user_event {
                        UserEvent::FocusAccessibilityNode(strategy) => {
                            requested_focus_strategy.borrow_mut().replace(strategy);
                        }
                        UserEvent::RequestRedraw
                        | UserEvent::SetCursorIcon(_)
                        | UserEvent::SetCustomScaleFactor(_)
                        | UserEvent::Erased(_) => {
                            // Nothing
                        }
                    }
                }),
            }
        });

        runner.provide_root_context(|| {
            let clipboard: Option<Box<dyn ClipboardProvider>> = ClipboardContext::new()
                .ok()
                .map(|c| Box::new(c) as Box<dyn ClipboardProvider>);

            State::create(clipboard)
        });

        runner.provide_root_context(|| tree.borrow().accessibility_generator.clone());

        let hook_result = hook(&mut runner);

        let mut font_collection = FontCollection::new();
        let def_mgr = FontMgr::default();
        let provider = TypefaceFontProvider::new();
        let font_manager: FontMgr = provider.into();
        font_collection.set_default_font_manager(def_mgr, None);
        font_collection.set_dynamic_font_manager(font_manager.clone());
        font_collection.paragraph_cache_mut().turn_on(false);

        runner.provide_root_context(|| font_collection.clone());

        let nodes_state = NodesState::default();
        let accessibility = AccessibilityTree::default();

        let mut runner = Self {
            runner,
            tree,
            size,

            accessibility,
            platform,

            nodes_state,
            events_receiver,
            events_sender,

            requested_focus_strategy,

            font_manager,
            font_collection,

            animation_clock,
            ticker_sender,

            default_fonts: default_fonts(),
            scale_factor,
        };

        runner.sync_and_update();

        (runner, hook_result)
    }

    pub fn set_fonts(&mut self, fonts: HashMap<&str, &[u8]>) {
        let mut provider = TypefaceFontProvider::new();
        for (font_name, font_data) in fonts {
            let ft_type = self
                .font_collection
                .fallback_manager()
                .unwrap()
                .new_from_data(font_data, None)
                .unwrap_or_else(|| panic!("Failed to load font {font_name}."));
            provider.register_typeface(ft_type, Some(font_name));
        }
        let font_manager: FontMgr = provider.into();
        self.font_manager = font_manager.clone();
        self.font_collection.set_dynamic_font_manager(font_manager);
    }

    pub fn set_default_fonts(&mut self, fonts: &[Cow<'static, str>]) {
        self.default_fonts.clear();
        self.default_fonts.extend_from_slice(fonts);
        self.tree.borrow_mut().layout.reset();
        self.tree.borrow_mut().text_cache.reset();
        self.tree.borrow_mut().measure_layout(
            self.size,
            &mut self.font_collection,
            &self.font_manager,
            &self.events_sender,
            self.scale_factor,
            &self.default_fonts,
        );
        self.tree.borrow_mut().accessibility_diff.clear();
        self.accessibility.focused_id = ACCESSIBILITY_ROOT_ID;
        self.accessibility.init(&mut self.tree.borrow_mut(), "");
        self.sync_and_update();
    }

    /// Run a closure inside the app runtime.
    pub fn run_in<T>(&self, run: impl FnOnce() -> T) -> T {
        self.runner.run_in(run)
    }

    pub async fn handle_events(&mut self) {
        self.runner.handle_events().await
    }

    pub fn handle_events_immediately(&mut self) {
        self.runner.handle_events_immediately()
    }

    pub fn sync_and_update(&mut self) {
        if let Some(strategy) = self.requested_focus_strategy.borrow_mut().take() {
            self.tree
                .borrow_mut()
                .accessibility_diff
                .request_focus(strategy);
        }

        while let Ok(events_chunk) = self.events_receiver.try_recv() {
            match events_chunk {
                EventsChunk::Processed(processed_events) => {
                    let events_executor_adapter = EventsExecutorAdapter {
                        runner: &mut self.runner,
                    };
                    events_executor_adapter.run(&mut self.nodes_state, processed_events);
                }
                EventsChunk::Batch(events) => {
                    for event in events {
                        self.runner.handle_event(
                            event.node_id,
                            event.name,
                            event.data,
                            event.bubbles,
                        );
                    }
                }
            }
        }

        let mutations = self.runner.sync_and_update();
        let result = self
            .runner
            .run_in(|| self.tree.borrow_mut().apply_mutations(mutations));
        if let Some(strategy) = result.auto_focus {
            self.requested_focus_strategy.borrow_mut().replace(strategy);
        }
        self.tree.borrow_mut().measure_layout(
            self.size,
            &mut self.font_collection,
            &self.font_manager,
            &self.events_sender,
            self.scale_factor,
            &self.default_fonts,
        );

        let accessibility_update = self.accessibility.process_updates(
            &mut self.tree.borrow_mut(),
            &self.events_sender,
            "",
        );

        self.platform
            .focused_accessibility_id
            .set_if_modified(accessibility_update.focus);
        let node_id = self.accessibility.focused_node_id().unwrap();
        let tree = self.tree.borrow();
        let layout_node = tree.layout.get(&node_id).unwrap();
        self.platform
            .focused_accessibility_node
            .set_if_modified(AccessibilityTree::create_node(
                node_id,
                layout_node,
                &tree,
                "",
            ));
    }

    /// Poll async tasks and events every `step` time for a total time of `duration`.
    /// This is useful for animations for instance.
    pub fn poll(&mut self, step: Duration, duration: Duration) {
        let started = Instant::now();
        while started.elapsed() < duration {
            self.handle_events_immediately();
            self.sync_and_update();
            std::thread::sleep(step);
            self.ticker_sender.notify();
        }
    }

    /// Poll async tasks and events every `step`, N times.
    /// This is useful for animations for instance.
    pub fn poll_n(&mut self, step: Duration, times: u32) {
        for _ in 0..times {
            self.handle_events_immediately();
            self.sync_and_update();
            std::thread::sleep(step);
            self.ticker_sender.notify();
        }
    }

    pub fn send_event(&mut self, platform_event: PlatformEvent) {
        let mut events_measurer_adapter = EventsMeasurerAdapter {
            tree: &mut self.tree.borrow_mut(),
            scale_factor: self.scale_factor,
        };
        let processed_events = events_measurer_adapter.run(
            &mut vec![platform_event],
            &mut self.nodes_state,
            self.accessibility.focused_node_id(),
        );
        self.events_sender
            .unbounded_send(EventsChunk::Processed(processed_events))
            .unwrap();
    }

    pub fn move_cursor(&mut self, cursor: impl Into<CursorPoint>) {
        self.send_event(PlatformEvent::Mouse {
            name: MouseEventName::MouseMove,
            cursor: cursor.into(),
            button: Some(MouseButton::Left),
        })
    }

    pub fn write_text(&mut self, text: impl ToString) {
        let text = text.to_string();
        self.send_event(PlatformEvent::Keyboard {
            name: KeyboardEventName::KeyDown,
            key: Key::Character(text),
            code: Code::Unidentified,
            modifiers: Modifiers::default(),
        });
        self.sync_and_update();
    }

    pub fn press_key(&mut self, key: Key) {
        self.send_event(PlatformEvent::Keyboard {
            name: KeyboardEventName::KeyDown,
            key,
            code: Code::Unidentified,
            modifiers: Modifiers::default(),
        });
        self.sync_and_update();
    }

    pub fn press_cursor(&mut self, cursor: impl Into<CursorPoint>) {
        let cursor = cursor.into();
        self.send_event(PlatformEvent::Mouse {
            name: MouseEventName::MouseDown,
            cursor,
            button: Some(MouseButton::Left),
        });
        self.sync_and_update();
    }

    pub fn release_cursor(&mut self, cursor: impl Into<CursorPoint>) {
        let cursor = cursor.into();
        self.send_event(PlatformEvent::Mouse {
            name: MouseEventName::MouseUp,
            cursor,
            button: Some(MouseButton::Left),
        });
        self.sync_and_update();
    }

    pub fn click_cursor(&mut self, cursor: impl Into<CursorPoint>) {
        let cursor = cursor.into();
        self.send_event(PlatformEvent::Mouse {
            name: MouseEventName::MouseDown,
            cursor,
            button: Some(MouseButton::Left),
        });
        self.sync_and_update();
        self.send_event(PlatformEvent::Mouse {
            name: MouseEventName::MouseUp,
            cursor,
            button: Some(MouseButton::Left),
        });
        self.sync_and_update();
    }

    pub fn press_touch(&mut self, location: impl Into<CursorPoint>) {
        self.send_event(PlatformEvent::Touch {
            name: TouchEventName::TouchStart,
            location: location.into(),
            finger_id: 0,
            phase: TouchPhase::Started,
            force: None,
        });
        self.sync_and_update();
    }

    pub fn move_touch(&mut self, location: impl Into<CursorPoint>) {
        self.send_event(PlatformEvent::Touch {
            name: TouchEventName::TouchMove,
            location: location.into(),
            finger_id: 0,
            phase: TouchPhase::Moved,
            force: None,
        });
        self.sync_and_update();
    }

    pub fn release_touch(&mut self, location: impl Into<CursorPoint>) {
        self.send_event(PlatformEvent::Touch {
            name: TouchEventName::TouchEnd,
            location: location.into(),
            finger_id: 0,
            phase: TouchPhase::Ended,
            force: None,
        });
        self.sync_and_update();
    }

    pub fn scroll(&mut self, cursor: impl Into<CursorPoint>, scroll: impl Into<CursorPoint>) {
        let cursor = cursor.into();
        let scroll = scroll.into();
        self.send_event(PlatformEvent::Wheel {
            name: WheelEventName::Wheel,
            scroll,
            cursor,
            source: WheelSource::Device,
        });
        self.sync_and_update();
        // Refresh hover states after the scroll
        self.send_event(PlatformEvent::Mouse {
            name: MouseEventName::MouseMove,
            cursor,
            button: None,
        });
        self.sync_and_update();
    }

    pub fn animation_clock(&mut self) -> &mut AnimationClock {
        &mut self.animation_clock
    }

    pub fn render(&mut self) -> SkData {
        let mut surface = raster_n32_premul((self.size.width as i32, self.size.height as i32))
            .expect("Failed to create the surface.");

        let render_pipeline = RenderPipeline {
            font_collection: &mut self.font_collection,
            font_manager: &self.font_manager,
            tree: &self.tree.borrow(),
            canvas: surface.canvas(),
            scale_factor: self.scale_factor,
            background: Color::WHITE,
        };
        render_pipeline.render();

        let image = surface.image_snapshot();
        let mut context = surface.direct_context();
        image
            .encode(context.as_mut(), EncodedImageFormat::PNG, None)
            .expect("Failed to encode the snapshot.")
    }

    pub fn render_to_file(&mut self, path: impl Into<PathBuf>) {
        let path = path.into();

        let image = self.render();

        let mut snapshot_file = File::create(path).expect("Failed to create the snapshot file.");

        snapshot_file
            .write_all(&image)
            .expect("Failed to save the snapshot file.");
    }

    pub fn find<T>(
        &self,
        matcher: impl Fn(TestingNode, &dyn ElementExt) -> Option<T>,
    ) -> Option<T> {
        let mut matched = None;
        {
            let tree = self.tree.borrow();
            tree.traverse_depth(|id| {
                if matched.is_some() {
                    return;
                }
                let element = tree.elements.get(&id).unwrap();
                let node = TestingNode {
                    tree: self.tree.clone(),
                    id,
                };
                matched = matcher(node, element.as_ref());
            });
        }

        matched
    }

    pub fn find_many<T>(
        &self,
        matcher: impl Fn(TestingNode, &dyn ElementExt) -> Option<T>,
    ) -> Vec<T> {
        let mut matched = Vec::new();
        {
            let tree = self.tree.borrow();
            tree.traverse_depth(|id| {
                let element = tree.elements.get(&id).unwrap();
                let node = TestingNode {
                    tree: self.tree.clone(),
                    id,
                };
                if let Some(result) = matcher(node, element.as_ref()) {
                    matched.push(result);
                }
            });
        }

        matched
    }
}

pub struct TestingNode {
    tree: Rc<RefCell<Tree>>,
    id: NodeId,
}

impl TestingNode {
    pub fn layout(&self) -> LayoutNode {
        self.tree.borrow().layout.get(&self.id).cloned().unwrap()
    }

    pub fn children(&self) -> Vec<Self> {
        let children = self
            .tree
            .borrow()
            .children
            .get(&self.id)
            .cloned()
            .unwrap_or_default();

        children
            .into_iter()
            .map(|child_id| Self {
                id: child_id,
                tree: self.tree.clone(),
            })
            .collect()
    }

    pub fn is_visible(&self) -> bool {
        let layout = self.layout();
        let effect_state = self
            .tree
            .borrow()
            .effect_state
            .get(&self.id)
            .cloned()
            .unwrap();

        effect_state.is_visible(&self.tree.borrow().layout, &layout.area)
    }

    pub fn element(&self) -> Rc<dyn ElementExt> {
        self.tree
            .borrow()
            .elements
            .get(&self.id)
            .cloned()
            .expect("Element does not exist.")
    }
}