Restructure library

* Restructure library with submodules
* Add Documentation with examples

isototest/src/action.rs → isototest/src/action/keyboard.rs

@@ -1,8 +1,13 @@
 // SPDX-FileCopyrightText: Christopher Hock <[email protected]>
 // 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<f64>` - 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<f64>) -> Result<Duration, VncError> {
     }
 }
 
-/// 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
 ///

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;

isototest/src/view.rs → isototest/src/action/view.rs

@@ -1,3 +1,4 @@
+//! # View module
 use image::{GenericImage, ImageFormat, Rgba};
 use std::{
     path::Path,

isototest/src/connection.rs

@@ -1,8 +1,6 @@
 // SPDX-FileCopyrightTest: Christopher Hock <[email protected]>
 // 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
 ///

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<dyn std::error::Error>> {
+//!     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;

isototest/src/types.rs

@@ -1,14 +1,16 @@
 // SPDX-FileCopyrightText: Christopher Hock <[email protected]>
 // SPDX-LicenseIdentifier: GPL-2.0-or-later
 
+//! Common types for `isototest`.
+
 /// Type of key press.
 ///
 /// # Members
 ///
 /// * `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,