diff --git a/isototest/src/action.rs b/isototest/src/action/keyboard.rs similarity index 90% rename from isototest/src/action.rs rename to isototest/src/action/keyboard.rs index 4a8c468..75085bd 100644 --- a/isototest/src/action.rs +++ b/isototest/src/action/keyboard.rs @@ -1,8 +1,13 @@ // SPDX-FileCopyrightText: Christopher Hock // SPDX-LicenseIdentifier: GPL-2.0-or-later -//! Action +//! # Keyboard Module //! -//! This module handles interactions between the VncClient and VncServer. +//! This module handles text-based interactions between the VncClient and VncServer. +//! +//! It uses [`X11Event::KeyEvent`](https://docs.rs/vnc-rs/0.5.1/vnc/event/struct.ClientKeyEvent.html) to send +//! individual key press or release events to the VNC server. +//! +//! To view what characters and control sequences are currently supported, see [`crate::types`]. extern crate proc_macro; use std::{thread::sleep, time::Duration}; @@ -25,7 +30,7 @@ macro_rules! wait_for_frame { }; } -/// Write given text to console +/// Send given text to VNC server. /// /// Uses `X11Event`s to send keypresses to the server. According to the [RFC](https://www.rfc-editor.org/rfc/rfc6143.html#section-7.5.4) /// it does not matter whether the X-Window System is running or not. @@ -34,6 +39,8 @@ macro_rules! wait_for_frame { /// /// * client: `&VncClient` - The client to be used for connections /// * text: `String` - The text to write. +/// * framerate: `Option` - The framerate of the remote machine. Used to time intervals in +/// which key signals are sent. If `None`, signal intervals are calculated according to a default. (30FPS) /// /// # Returns /// @@ -70,7 +77,7 @@ pub async fn write_to_console( /// Encapsulate the `client.input()` function calls to avoid repitition. /// -/// Press and release a button or release it manually, if it is pressed. +/// Will put the given key into a state according to the [crate::types::KeyEventType] parameter. /// /// # Parameters /// @@ -186,7 +193,10 @@ fn framerate_to_nanos(rate: Option) -> Result { } } -/// Assign a given character its corresponding `VirtualKeyCode`. +/// Assign a given character its corresponding [`crate::types::KeyCode`]. +/// +/// Will return the u32 representation of the actualkeycode as this is required by +/// [`vnc-rs`](https://docs.rs/vnc-rs/0.5.1/vnc/event/struct.ClientKeyEvent.html) /// /// # Parameters /// diff --git a/isototest/src/action/mod.rs b/isototest/src/action/mod.rs new file mode 100644 index 0000000..e856867 --- /dev/null +++ b/isototest/src/action/mod.rs @@ -0,0 +1,3 @@ +//! This module is used to interact with the VNC server in any capacity. +pub mod keyboard; +pub mod view; diff --git a/isototest/src/view.rs b/isototest/src/action/view.rs similarity index 99% rename from isototest/src/view.rs rename to isototest/src/action/view.rs index d85aabf..05060ea 100644 --- a/isototest/src/view.rs +++ b/isototest/src/action/view.rs @@ -1,3 +1,4 @@ +//! # View module use image::{GenericImage, ImageFormat, Rgba}; use std::{ path::Path, diff --git a/isototest/src/connection.rs b/isototest/src/connection.rs index b893cd7..566b022 100644 --- a/isototest/src/connection.rs +++ b/isototest/src/connection.rs @@ -1,8 +1,6 @@ // SPDX-FileCopyrightTest: Christopher Hock // SPDX-License-Identifier: GPL-2.0-or-later -//! # Connection Module -//! //! This module handles the VncClient and its connection to the VncServer. use tokio::{self, net::TcpStream}; use vnc::{PixelFormat, VncClient, VncConnector, VncError}; @@ -64,7 +62,7 @@ pub async fn create_vnc_client( Ok(vnc) } -/// Stop VNC engine, release all resources +/// Stop VNC engine, release all resources. /// /// # Parameters /// diff --git a/isototest/src/lib.rs b/isototest/src/lib.rs index 7bd5dad..8e4e83c 100644 --- a/isototest/src/lib.rs +++ b/isototest/src/lib.rs @@ -1,4 +1,71 @@ +//! Schedule and run tests for [openQA](https://open.qa). +//! +//! This crate's only responsibility is to schedule and run tests for the openQA project. +//! To this end it connects to the test environment on a remote worker machine (VM or bare metal) which has been prepared +//! by its two "sister-libraries" `isotoenv` and `ìsotomachine` via VNC and executes commands +//! specified by the openQA test to run. +//! +//! ## Example +//! +//! To use this crate, you need to create a `VncClient` instance, which will connect you to your +//! VNC server. This instance must be passed to any function which communicated with the VNC +//! server. +//! +//! ```no_run +//! use isototest::connection::{create_vnc_client, kill_client}; +//! use isototest::action::keyboard::write_to_console; +//! use isototest::action::view::read_screen; +//! use tokio::{self}; +//! use std::process::exit; +//! use std::time::Duration; +//! +//! #[tokio::main] +//! async fn main() -> Result<(), Box> { +//! let addr = "127.0.0.1:5900"; +//! let psw = "password".to_string(); // Value irrelevant if the server does not use authentication. +//! let mut client = match create_vnc_client(addr.to_string(), Some(psw.clone())).await { +//! Ok(client) => { +//! println!("Client created. Handshake successful."); +//! client +//! }, +//! Err(e) => { +//! eprintln!("[Error] {:?}", e); +//! exit(1) +//! } +//! }; +//! +//! // Request screenshot from the remote machine, save the resolution as the client can not +//! // request it again as long as it does not change. +//! let res; +//! let mut resolution = match read_screen(&client, "screenshot.png", None, Duration::from_secs(1)).await { +//! Ok(x) => { +//! println!("Screenshot received!"); +//! res = x; +//! } +//! Err(e) => { +//! eprintln!("{}", e); +//! exit(1); +//! } +//! }; +//! +//! // Send a series of keypresses to the VNC server to type out the given text. +//! // Can be used to execute commands on the Terminal. +//! match write_to_console(&client, "Hello World!\n".to_string(), None).await { +//! Ok(_) => { +//! println!("Test text sent!"); +//! } +//! Err(e) => { +//! eprintln!("[error] {:?}", e); +//! exit(1); +//! } +//! } +//! +//! // Kill VNC connection and release resources. +//! kill_client(client).await?; +//! Ok(()) +//! } +//! ``` + pub mod action; pub mod connection; -mod types; -pub mod view; +pub(crate) mod types; diff --git a/isototest/src/types.rs b/isototest/src/types.rs index 31a66a2..cab3bce 100644 --- a/isototest/src/types.rs +++ b/isototest/src/types.rs @@ -1,6 +1,8 @@ // SPDX-FileCopyrightText: Christopher Hock // SPDX-LicenseIdentifier: GPL-2.0-or-later +//! Common types for `isototest`. + /// Type of key press. /// /// # Members @@ -8,7 +10,7 @@ /// * `Press` - To signal a press and hold of the given key. /// * `Release` - To signal the release of a given key. /// * `Tap` - To signal a tap (press & release) of the given key. -pub enum KeyEventType { +pub(crate) enum KeyEventType { Press, Release, Tap, @@ -19,7 +21,7 @@ pub enum KeyEventType { /// /// Oriented on [this table](https://theasciicode.com.ar/ascii-printable-characters/exclamation-mark-ascii-code-33.html) /// Hex reprentations taken from [here](https://www.rfc-editor.org/rfc/rfc6143.html#section-7.5.4). -pub enum KeyCode { +pub(crate) enum KeyCode { NULL = 00, SOH = 01, STX = 02,