🦄 refactor: Simplify test apis, add doc

- Merge a lot of functions into script_run

.github/workflows/CI.yml

@@ -37,11 +37,11 @@ jobs:
           - runner: ubuntu-latest
             target: ppc64le
     steps:
+      - uses: actions/checkout@v4
       - name: Install dependencies
         run: |
           sudo apt-get update
           sudo apt-get install -y pkg-config libssl-dev openssl
-      - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
         with:
           python-version: 3.x
@@ -72,11 +72,11 @@ jobs:
           - runner: ubuntu-latest
             target: armv7
     steps:
+      - uses: actions/checkout@v4
       - name: Install dependencies
         run: |
           sudo apt-get update
           sudo apt-get install -y pkg-config libssl-dev openssl
-      - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
         with:
           python-version: 3.x
@@ -103,10 +103,10 @@ jobs:
           - runner: windows-latest
             target: x86
     steps:
+      - uses: actions/checkout@v4
       - name: Install dependencies
         run: |
           choco install -y openssl
-      - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
         with:
           python-version: 3.x
@@ -133,10 +133,10 @@ jobs:
           - runner: macos-14
             target: aarch64
     steps:
+      - uses: actions/checkout@v4
       - name: Install dependencies
         run: |
           brew install [email protected]
-      - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
         with:
           python-version: 3.x

.gitignore

@@ -1,6 +1,7 @@
 /target
 *.log
 *.cast
+*.deprecated
 
 # Byte-compiled / optimized / DLL files
 

src/exec/cli_api.rs

@@ -3,16 +3,18 @@ use std::error::Error;
 use crate::cli::tty::InnerTty;
 
 pub trait CliTestApi: InnerTty {
-    fn script_run(&mut self, script: &str, timeout: u32) -> Result<(), Box<dyn Error>>;
-    fn assert_script_run(&mut self, script: &str, timeout: u32) -> Result<(), Box<dyn Error>>;
+    /// 
+    /// 
+    /// You may found this func includes assert_script_run and script_output 
+    fn script_run(&mut self, script: &str, timeout: u32) -> Result<String, Box<dyn Error>>;
     fn background_script_run(&mut self, script: &str) -> Result<(), Box<dyn Error>>;
     fn writeln(&mut self, script: &str) -> Result<(), Box<dyn Error>>;
-    fn wait_serial(&mut self, expected: &str, timeout: u32) -> Result<(), Box<dyn Error>>;
-    // fn script_output(&mut self, script: &str) -> Result<Vec<u8>, Box<dyn Error>>;
-    // fn validate_script_output(&mut self, script: &str, expected_output: &str) -> Result<(), Box<dyn Error>>;
+    fn wait_serial(&mut self, expected: &str, timeout: u32) -> Result<String, Box<dyn Error>>;
 }
 
 pub trait SudoCliTestApi: CliTestApi {
-    fn script_sudo(&mut self, script: &str, timeout: u32) -> Result<(), Box<dyn Error>>;
-    fn assert_script_sudo(&mut self, script: &str, timeout: u32) -> Result<(), Box<dyn Error>>;
+    ///
+    /// 
+    /// You may found this func includes assert_script_sudo and script_output
+    fn script_sudo(&mut self, script: &str, timeout: u32) -> Result<String, Box<dyn Error>>;
 }

src/exec/cli_exec.rs

@@ -71,7 +71,7 @@ impl InnerTty for CliTester {
 }
 
 impl CliTestApi for CliTester {
-    fn wait_serial(&mut self, expected: &str, timeout: u32) -> Result<(), Box<dyn Error>> {
+    fn wait_serial(&mut self, expected: &str, timeout: u32) -> Result<String, Box<dyn Error>> {
         let begin = Instant::now();
         let mut buf = Vec::new();
         info!("Waiting for string {{{}}}", expected);
@@ -94,9 +94,10 @@ impl CliTestApi for CliTester {
             }
         }
 
-        Ok(())
+        let res = String::from_utf8(buf)?;
+        Ok(res)
     }
-    fn script_run(&mut self, script: &str, timeout: u32) -> Result<(), Box<dyn Error>> {
+    fn script_run(&mut self, script: &str, timeout: u32) -> Result<String, Box<dyn Error>> {
         let mut cmd = script.to_owned();
         let echo_content_rand = String::from_utf8(rand_string(8)).unwrap();
 
@@ -106,27 +107,7 @@ impl CliTestApi for CliTester {
 
         self.run_command(&cmd)?;
 
-        let res = self.wait_serial(&echo_content_rand, timeout);
-        if let Err(e) = res {
-            if e.to_string() == "Timeout" {
-                return Ok(());
-            }
-            return Err(e);
-        }
-        Ok(())
-    }
-    fn assert_script_run(&mut self, script: &str, timeout: u32) -> Result<(), Box<dyn Error>> {
-        let mut cmd = script.to_owned();
-        let echo_content_rand = String::from_utf8(rand_string(8)).unwrap();
-
-        cmd += "&& echo ";
-        cmd += &echo_content_rand;
-        cmd += " \n";
-
-        self.run_command(&cmd)?;
-
-        self.wait_serial(&echo_content_rand, timeout)?;
-        Ok(())
+        self.wait_serial(&echo_content_rand, timeout)
     }
     fn background_script_run(&mut self, script: &str) -> Result<(), Box<dyn Error>> {
         let mut cmd = script.to_owned();

src/exec/cli_exec_sudo.rs

@@ -64,19 +64,12 @@ impl InnerTty for SudoCliTester {
 }
 
 impl CliTestApi for SudoCliTester {
-    fn wait_serial(&mut self, expected: &str, timeout: u32) -> Result<(), Box<dyn std::error::Error>> {
+    fn wait_serial(&mut self, expected: &str, timeout: u32) -> Result<String, Box<dyn std::error::Error>> {
         self.inner.wait_serial(expected, timeout)
     }
-    fn script_run(&mut self, script: &str, timeout: u32) -> Result<(), Box<dyn std::error::Error>> {
+    fn script_run(&mut self, script: &str, timeout: u32) -> Result<String, Box<dyn std::error::Error>> {
         self.inner.script_run(script, timeout)
     }
-    fn assert_script_run(
-        &mut self,
-        script: &str,
-        timeout: u32,
-    ) -> Result<(), Box<dyn std::error::Error>> {
-        self.inner.assert_script_run(script, timeout)
-    }
     fn background_script_run(&mut self, script: &str) -> Result<(), Box<dyn std::error::Error>> {
         self.inner.background_script_run(script)
     }
@@ -90,19 +83,10 @@ impl SudoCliTestApi for SudoCliTester {
         &mut self,
         script: &str,
         timeout: u32,
-    ) -> Result<(), Box<dyn std::error::Error>> {
+    ) -> Result<String, Box<dyn std::error::Error>> {
         let mut cmd = String::from("sudo ");
         cmd += script;
         cmd += "\n";
         self.inner.script_run(&cmd, timeout)
     }
-    fn assert_script_sudo(
-        &mut self,
-        script: &str,
-        timeout: u32,
-    ) -> Result<(), Box<dyn std::error::Error>> {
-        let mut cmd = String::from("sudo ");
-        cmd += script;
-        self.inner.assert_script_run(&cmd, timeout)
-    }
 }

src/exec/gui_api.rs

@@ -0,0 +1,28 @@
+//! Api for GUI part testing
+//! 
+//! For GUI part, basicially we need to check the following:
+//! - Is the current screen is the expected screen?
+//! - Does the screen have the expected elements?
+//! - Can we interact with the screen?
+
+use std::error::Error;
+
+use crate::gui::screen::Screen;
+
+use super::needle::Needle;
+
+/// The API can used for testing, with bypass [`Screen`] operations.
+pub trait GuiTestApi: Screen {
+    /// Check if the current screen is the expected screen
+    fn assert_screen(&mut self, needle: Needle) -> Result<(), Box<dyn Error>>;
+    /// Check and click the target position
+    /// 
+    /// Suggest using assert_screen and click seperately, as futher consider adding relative position etc.
+    fn assert_screen_click(&mut self, needle: Needle) -> Result<(), Box<dyn Error>>;
+
+    /// Wait until current screen changed
+    fn wait_screen_change(&mut self, timeout: u32) -> Result<(), Box<dyn Error>>;
+
+    /// Wait and assert the screen won't change in timeout
+    fn wait_still_screen(&mut self, timeout: u32) -> Result<(), Box<dyn Error>>;
+}

src/exec/mod.rs

@@ -0,0 +1,6 @@
+pub mod cli_api;
+pub mod cli_exec;
+pub mod cli_exec_sudo;
+pub mod gui_api;
+
+pub mod needle;

src/exec/needle.rs

@@ -0,0 +1,69 @@
+//! Object to match the GUI
+//!
+//! We can't do the same thing as the CLI part: give a string and wait for
+//! it. We need to match the GUI with a needle.
+
+use image::RgbaImage;
+use serde::{Deserialize, Serialize};
+
+#[derive(Serialize, Deserialize)]
+#[serde(tag = "type")]
+pub enum Needle {
+    /// Basic needle, just compare the screen with given image to see if the similarity is enough
+    Basic(Vec<Area>),
+    // In future, consider adding more needle types,
+    // like using neural network to match the screen
+    // to get a better flexibility
+}
+
+/// Needle type
+/// OpenQA needle compatible, with same definition
+///
+/// See <https://open.qa/docs/#_needle>
+#[derive(Serialize, Deserialize)]
+pub enum NeedleType {
+    #[serde(rename = "match")]
+    Match,
+    #[serde(rename = "ocr")]
+    Ocr, // Currently not supported
+    #[serde(rename = "exclude")]
+    Exclude,
+}
+
+/// Click point
+/// OpenQA needle compatible, with same definition
+///
+/// See <https://open.qa/docs/#_needle>
+#[derive(Serialize, Deserialize)]
+pub struct ClickPoint {
+    pub xpos: u32,
+    pub ypos: u32,
+}
+
+/// Area to match
+/// OpenQA needle compatible, with same definition
+///
+/// See <https://open.qa/docs/#_needle>
+#[derive(Serialize, Deserialize)]
+pub struct Area {
+    /// X coordinate of the top left corner
+    pub x: u32,
+    /// Y coordinate of the top left corner
+    pub y: u32,
+    /// Width of the area
+    pub width: u32,
+    /// Height of the area
+    pub height: u32,
+    /// Type of the needle
+    pub needle: NeedleType,
+    /// The similarity threshold
+    #[serde(rename = "match")]
+    pub match_threhold: f32,
+    /// The click point
+    pub click_point: Option<ClickPoint>,
+    /// The image to match
+    ///
+    /// This field should be auto added by needle readers
+    #[serde(skip_serializing, skip_deserializing)]
+    pub target: Option<RgbaImage>,
+}

src/lib.rs

@@ -3,13 +3,7 @@
 pub mod consts;
 pub mod cli;
 pub mod gui;
-pub mod exec {
-    pub mod cli_api;
-    pub mod cli_exec;
-    pub mod cli_exec_sudo;
-
-    pub mod runner;
-}
+pub mod exec;
 pub mod devhost {
     pub mod devhost;
     pub mod sdwirec;