# gtk-test
This projects allows you to test your GTK's applications UI. It has to be used with [gtk-rs](https://gtk-rs.org) crates.
## How does it work?
It's quite simple actually (even though you have to perform a few more things on OSX to make it work as expected...) :
```rust
gtk::init().unwrap(); // You need to init GTK otherwise it'll just crash...
```
Then you build your UI as you would in normal time (using `Glade` or by hand). Only one thing actually changes: you must not call `gtk::main`!
Once you have built your UI, just call the `gtk_test` macros/functions to test it. Just one note about this though: sometimes, you need to let time for GTK to process some events. For example, if you clicked on a button and you have an associated action to it, it's more careful to use `gtk_test::wait`.
Another recommended thing is to give focus to the window in case you have to interact with it (to click on a button or to input some text...):
```rust
let w = gtk::Window::new();
// ...
w.activate_focus();
```
### General setup
When running test, you need to specify that you only want **ONE** thread. To do so:
```bash
cargo test -- --test-threads=1
```
Otherwise, GTK contexts might conflict into each others.
### Specific setup for OSX
A few more things have to be done on OSX to make this work. First, you won't be able to add the `#[test]` attribute to your functions, it doesn't work. Instead, you have to write your test just like you would write a normal binary (so with a `main` function as entry point).
A short example (you can find the full version in the `tests` folder of this repository):
```rust
fn main() {
let (w, l, b) = init_ui();
assert_text!(l, "Test");
w.activate_focus();
gtk_test::click(&b);
gtk_test::wait(1000); // to be sure that GTK has updated the label's text
assert_text!(l, "Clicked");
}
```
Then you need to add into your `Cargo.toml` file:
```toml
[[test]]
harness = false # This is the important line!
name = "basic"
```
It allows your test to be run as a "normal" binary.
### Example?
You can find a few in the tests folder. Just copy/paste it and you're good to go (don't forget to add the missing pieces in your `Cargo.toml` file!).
### Using it on CI?
It's actually possible (only tested for GitHub Actions though). You "just" need a display server. Here's what you have to add in your CI configuration file to make it work:
Install the following packages:
* libgtk-3-dev
* libxdo-dev
Then run the application in a virtual display environment using [xvfb-action.](https://github.com/GabrielBB/xvfb-action) For example:
```
- name: Run headless test
uses: GabrielBB/xvfb-action@v1
with:
run: cargo test -- --test-threads=1
```
Take a look at our `.github/workflows/linux_ci.yml` file to see how we set things up.