Restructure library

* Restructure library with submodules
* Add Documentation with examples

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

@@ -1,8 +1,21 @@
 // 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`].
+//!
+//! ## Example
+//!
+//! ```rust
+//! // This example will send the string "Hello, world!", followed by a newline to the VNC server.
+//! // It will be handled by the remote machine as if a user was inputting text directly.
+//! write_to_console(client, "Hello, World!\n", None)?;
+//! ```
 extern crate proc_macro;
 use std::{thread::sleep, time::Duration};
 
@@ -25,7 +38,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 +47,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 +85,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 +201,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,51 @@
+//! 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.
+//!
+//! ```rust
+//! use isototest::conection::{create_vnc_client, kill_client};
+//! use isototest::action::write_to_console;
+//! use isototest::action::view::read_screen;
+//! use tokio::self;
+//! use std::process::exit;
+//!
+//! #[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 mut resolution = read_screen(&client, "screenshot.png", None, Duration::from_secs(1)).await?;
+//!
+//!     // Send a series of keypresses to the VNC server to type out the given text.
+//!     // Can be used to execute commands on the Terminal.
+//!     write_to_console(&client, "Hello World!\n".to_string(), None).await?;
+//!
+//!     // Kill VNC connection and release resources.
+//!     kill_client(&client)?;
+//! }
+//! ```
+
 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,