Debug scenarios

When using AppCUI and needing to test the interface, it is recommended to write unit tests using the App::debug(...) method. This method allows one to write a succession of system events (mouse clicks, keys being pressed, etc.) and validate whether the output is the expected one. This succession of commands is considered an event script, formed from multiple commands, each command written on a line. A command can have parameters. You can also use // to comment out a command.

General format for a script

Command-1(param1,param2,param3)
Command-2()
// comment

Remarks:

• App::debug(...) will panic if the script is incorrect (a command is not valid, the number of parameters is incorrect, etc.).
• AppCUI allows only one instance at a time (this is done via a mutex object). If you have multiple unit tests and you try to run them with the cargo test command, you might get an error as cargo might try to use multiple threads to do this, and it is likely that one thread might try to start an AppCUI application while another one is already running on another thread. The solution in this case is to run the tests using a single thread:

cargo test -- --test-threads=1

Mouse related commands

Mouse related commands are a set of commands that simulate various mouse events

Keyboard related commands

Usually the key parameter can have several forms:

• key
• modifier-1+key
• modifier-1+modifier-2+key
• modifier-1+modifier-2+modifier-3+key

where the list of all keys supported by this command is:

• F-commands (F1 to F12)
• Letters (A to Z) - with upper case
• Numbers (0 to 9)
• Arrows (Up, Down, Left, Right)
• Navigation keys (PageUp, PageDown, Home, End)
• Deletion and Insertions (Delete , Backspace, Insert)
• White-spaces (Space, Tab)
• Other (Enter, Escape)

and the list of modifiers consists of Shift, Ctrl, and Alt.

Paint related commands

System events

Clipboard commands

Validation commands

Example

Let's consider a scenario where we want to test if moving a window with a mouse works as expected. For this we will create a test function, with the following code:

#[test]
fn check_if_window_can_be_moved() {
    let script = "
        Paint('initial state')
        CheckHash(0xB1471A30B30F5C6C)
        Mouse.Drag(30,3,35,5)
        Paint('window was moved')
        CheckHash(0x419533D4BBEFE538)
    ";
    let mut a = App::debug(60, 10, script).build().unwrap();
    let w = Window::new("Title", layout!("a:c,w:20,h:5"), window::Flags::None);
    a.add_window(w);
    a.run();
}

Let's break the event script in pieces and see exactly what is supposed to happen:

1. Paint('initial state') - this will print the virtual screen. It should look like the following (but with colors):

    +================================================================+
    | Name  : initial state                                          |
    | Hash  : 0xB1471A30B30F5C6C                                     |
    | Cursor: Hidden                                                 |
    | ---------------------------------------------------------------|
    |             11111111112222222222333333333344444444445555555555 |
    |   012345678901234567890123456789012345678901234567890123456789 |
    | ---------------------------------------------------------------|
    | 0 ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ |
    | 1 ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ |
    | 2 ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ |
    | 3 ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒╔════ Title ════[x]╗▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ |
    | 4 ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒║                  ║▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ |
    | 5 ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒║                  ║▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ |
    | 6 ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒║                  ║▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ |
    | 7 ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒╚══════════════════╝▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ |
    | 8 ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ |
    | 9 ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ |
    | ---------------------------------------------------------------|

We can inspect whether the position of the window is correct. We can also see the hash computed for the entire virtual screen: 0xB1471A30B30F5C6C (this can help us perform further checks).

2. CheckHash(0xB1471A30B30F5C6C) - this computes the hash for the entire virtual screen and then checks it against the expected one. The usual scenario here is that we first apply a Paint command, validate it, and then write the CheckHash command with the hash obtained from the Paint command. This way, if something changes in the logic or code of the program, the new hash will be different. If the hash for the virtual screen is not as expected, the application will panic. If used in a test, this behavior will fail the test.

3. Mouse.Drag(30,3,35,5) this command does the following:

   • moves the mouse to the (30,3) coordinate (over the title of the window)
   • click and hold the left mouse button
   • moves the mouse to a new position (35,5) (since we hold the mouse button, we expect the window to move as well)
   • releases the left mouse button

4. Paint('window was moved') now we should see something like the following. Notice that indeed, the window was moved to a new position. We also have a new hash for the virtual screen: 0x419533D4BBEFE538

    +================================================================+
    | Name  : window was moved                                       |
    | Hash  : 0x419533D4BBEFE538                                     |
    | Cursor: Hidden                                                 |
    | -------------------------------------------------------------- |
    |             11111111112222222222333333333344444444445555555555 |
    |   012345678901234567890123456789012345678901234567890123456789 |
    | -------------------------------------------------------------- |
    | 0 ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ |
    | 1 ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ |
    | 2 ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ |
    | 3 ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ |
    | 4 ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ |
    | 5 ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒╔════ Title ════[x]╗▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ |
    | 6 ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒║                  ║▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ |
    | 7 ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒║                  ║▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ |
    | 8 ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒║                  ║▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ |
    | 9 ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒╚══════════════════╝▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ |
    | -------------------------------------------------------------- |

5. CheckHash(0x419533D4BBEFE538) - finally we check the new hash to see if it matches the one we expect.

Remark: Using unit tests (while it works with the Paint command activated) might look strange on the actual screen (especially if all you need is to validate an example). As such, it is best that after an example such as the previous one has been validated, you add another command at the beginning of the script: Paint.Enable(false). This will not change the logic of the script; instead, it will not print anything on the screen. The final test function should then look like this:

use appcui::prelude::*;

#[test]
fn check_if_window_can_be_moved() {
    let script = "
        Paint.Enable(false)
        Paint('initial state')
        CheckHash(0xB1471A30B30F5C6C)
        Mouse.Drag(30,3,35,5)
        Paint('window was moved')
        CheckHash(0x419533D4BBEFE538)
    ";
    let mut a = App::debug(60, 10, script).build().unwrap();
    let w = Window::new("Title", layout!("a:c,w:20,h:5"), window::Flags::None);
    a.add_window(w);
    a.run();
}

and its execution should produce an output similar to the next one:

running 1 test
test check_if_window_can_be_moved ... ok