├── .github
    ├── FUNDING.yml
    └── workflows
    │   ├── linux_ci.yml
    │   └── mac_ci.yml
├── .gitignore
├── Cargo.toml
├── LICENSE
├── README.md
├── src
    ├── functions.rs
    ├── lib.rs
    ├── macros.rs
    └── observer.rs
└── tests
    ├── basic.rs
    └── observer.rs


/.github/FUNDING.yml:
--------------------------------------------------------------------------------
1 | open_collective: gtk-rs
2 | 


--------------------------------------------------------------------------------
/.github/workflows/linux_ci.yml:
--------------------------------------------------------------------------------
 1 | on:
 2 |   pull_request:
 3 | 
 4 | name: Linux CI
 5 | 
 6 | jobs:
 7 |   check:
 8 |     name: Compile and Test
 9 |     runs-on: ubuntu-latest
10 |     steps:
11 |       - uses: actions/checkout@v2
12 |       - name: Install gtk3 and dependencies.
13 |         run: |
14 |           sudo apt update
15 |           sudo apt install \
16 |             libgtk-3-dev \
17 |             libxdo-dev
18 | 
19 |       - name: Install Rust
20 |         uses: actions-rs/toolchain@v1
21 |         with:
22 |           profile: minimal
23 |           toolchain: stable
24 |           override: true
25 |       
26 |       - name: Check Code
27 |         uses: actions-rs/cargo@v1
28 |         with:
29 |           command: check
30 | 
31 |       - name: Install Clippy
32 |         run: rustup component add clippy
33 | 
34 |       - name: Run Clippy
35 |         run: cargo clippy --all-targets -- -D warnings -A unknown-lints
36 |           
37 |       - name: Run headless test
38 |         uses: GabrielBB/xvfb-action@v1
39 |         with:
40 |           run: cargo test -- --test-threads=1
41 | 


--------------------------------------------------------------------------------
/.github/workflows/mac_ci.yml:
--------------------------------------------------------------------------------
 1 | on:
 2 |   pull_request:
 3 | 
 4 | name: MacOS CI
 5 | 
 6 | jobs:
 7 |   check:
 8 |     name: Compile and Test
 9 |     runs-on: macOS-latest
10 |     steps:
11 |       - uses: actions/checkout@v2
12 |       - name: Install gtk3 and dependencies.
13 |         run: brew install gtk+3
14 | 
15 |       - name: Install Rust
16 |         uses: actions-rs/toolchain@v1
17 |         with:
18 |           profile: minimal
19 |           toolchain: stable
20 |           override: true
21 |       
22 |       - name: Check Code
23 |         uses: actions-rs/cargo@v1
24 |         with:
25 |           command: check
26 | 
27 |       - name: Install Clippy
28 |         run: rustup component add clippy
29 | 
30 |       - name: Run Clippy
31 |         run: cargo clippy --all-targets -- -D warnings -A unknown-lints
32 |           
33 |       - name: Run Tests
34 |         uses: actions-rs/cargo@v1
35 |         with:
36 |           command: test
37 |           args: -- --test-threads=1
38 | 


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | Cargo.lock
2 | target
3 | 


--------------------------------------------------------------------------------
/Cargo.toml:
--------------------------------------------------------------------------------
 1 | [package]
 2 | name = "gtk-test"
 3 | version = "0.18.0"
 4 | authors = ["The Gtk-rs Project Developers"]
 5 | license = "MIT"
 6 | description = "Crate to test GTK UIs"
 7 | categories = ["api-bindings", "gui", "test"]
 8 | homepage = "https://gtk-rs.org/"
 9 | repository = "https://github.com/gtk-rs/gtk-test"
10 | keywords = ["gtk", "gtk-rs", "GUI", "test", "gnome"]
11 | documentation = "https://docs.rs/gtk-test"
12 | edition = "2021"
13 | 
14 | [dependencies]
15 | enigo = "^0.0.14"
16 | gtk = "0.18"
17 | 
18 | [[test]]
19 | harness = false
20 | name = "basic"
21 | 
22 | [[test]]
23 | harness = false
24 | name = "observer"
25 | 


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
 1 | MIT License
 2 | 
 3 | Copyright (c) 2018 Guillaume Gomez
 4 | 
 5 | Permission is hereby granted, free of charge, to any person obtaining a copy
 6 | of this software and associated documentation files (the "Software"), to deal
 7 | in the Software without restriction, including without limitation the rights
 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 | 
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 | 
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | # gtk-test
 2 | 
 3 | This projects allows you to test your GTK's applications UI. It has to be used with [gtk-rs](https://gtk-rs.org) crates.
 4 | 
 5 | ## How does it work?
 6 | 
 7 | It's quite simple actually (even though you have to perform a few more things on OSX to make it work as expected...) :
 8 | 
 9 | ```rust
10 | gtk::init().unwrap(); // You need to init GTK otherwise it'll just crash...
11 | ```
12 | 
13 | 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`!
14 | 
15 | 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`.
16 | 
17 | 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...):
18 | 
19 | ```rust
20 | let w = gtk::Window::new();
21 | // ...
22 | w.activate_focus();
23 | ```
24 | 
25 | ### General setup
26 | 
27 | When running test, you need to specify that you only want **ONE** thread. To do so:
28 | 
29 | ```bash
30 | cargo test -- --test-threads=1
31 | ```
32 | 
33 | Otherwise, GTK contexts might conflict into each others.
34 | 
35 | ### Specific setup for OSX
36 | 
37 | 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).
38 | 
39 | A short example (you can find the full version in the `tests` folder of this repository):
40 | 
41 | ```rust
42 | fn main() {
43 |     let (w, l, b) = init_ui();
44 | 
45 |     assert_text!(l, "Test");
46 |     w.activate_focus();
47 |     gtk_test::click(&b);
48 |     gtk_test::wait(1000); // to be sure that GTK has updated the label's text
49 |     assert_text!(l, "Clicked");
50 | }
51 | ```
52 | 
53 | Then you need to add into your `Cargo.toml` file:
54 | 
55 | ```toml
56 | [[test]]
57 | harness = false # This is the important line!
58 | name = "basic"
59 | ```
60 | 
61 | It allows your test to be run as a "normal" binary.
62 | 
63 | ### Example?
64 | 
65 | 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!).
66 | 
67 | ### Using it on CI?
68 | 
69 | 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:
70 | 
71 | Install the following packages:
72 | 
73 |  * libgtk-3-dev
74 |  * libxdo-dev
75 | 
76 | Then run the application in a virtual display environment using [xvfb-action.](https://github.com/GabrielBB/xvfb-action) For example:
77 | 
78 | ```
79 | - name: Run headless test
80 |   uses: GabrielBB/xvfb-action@v1
81 |   with:
82 |     run: cargo test -- --test-threads=1
83 | ```
84 | 
85 | Take a look at our `.github/workflows/linux_ci.yml` file to see how we set things up.
86 | 


--------------------------------------------------------------------------------
/src/functions.rs:
--------------------------------------------------------------------------------
  1 | use enigo::{self, Enigo, KeyboardControllable, MouseButton, MouseControllable};
  2 | use gtk::gdk::keys::constants as key;
  3 | use gtk::gdk::keys::Key;
  4 | use gtk::glib::{Cast, ControlFlow, IsA, Object, Propagation, StaticType};
  5 | use gtk::prelude::{BinExt, ButtonExt, ContainerExt, EditableExt, ToolButtonExt, WidgetExt};
  6 | use gtk::{Bin, Button, Container, Entry, ToolButton, Widget, Window};
  7 | 
  8 | use crate::observer_new;
  9 | 
 10 | /// Simulate a click on a widget.
 11 | ///
 12 | /// ## Warning!
 13 | ///
 14 | /// Please note that the click will "fail" if the window isn't on top of all other windows (this
 15 | /// is a common issue on OSX). Don't forget to bring the button's window on top by using:
 16 | ///
 17 | /// ```ignore
 18 | /// window.activate_focus();
 19 | /// ```
 20 | ///
 21 | /// Example:
 22 | ///
 23 | /// ```
 24 | /// extern crate gtk;
 25 | /// #[macro_use]
 26 | /// extern crate gtk_test;
 27 | ///
 28 | /// use gtk::{Button, prelude::ButtonExt};
 29 | ///
 30 | /// # fn main() {
 31 | /// gtk::init().expect("GTK init failed");
 32 | /// let but = Button::new();
 33 | /// but.connect_clicked(|_| {
 34 | ///     println!("clicked");
 35 | /// });
 36 | /// gtk_test::click(&but);
 37 | /// # }
 38 | /// ```
 39 | pub fn click<W: Clone + IsA<Object> + IsA<Widget> + WidgetExt + IsA<W>>(widget: &W) {
 40 |     wait_for_draw(widget, || {
 41 |         let observer = if let Ok(tool_button) = widget.clone().dynamic_cast::<ToolButton>() {
 42 |             observer_new!(tool_button, connect_clicked, |_|)
 43 |         } else if let Ok(tool_button) = widget.clone().dynamic_cast::<Button>() {
 44 |             observer_new!(tool_button, connect_clicked, |_|)
 45 |         } else {
 46 |             observer_new!(widget, connect_button_release_event, |_, _| {
 47 |                 Propagation::Stop
 48 |             })
 49 |         };
 50 |         let allocation = widget.allocation();
 51 |         mouse_move(widget, allocation.width() / 2, allocation.height() / 2);
 52 |         let mut enigo = Enigo::new();
 53 |         enigo.mouse_click(MouseButton::Left);
 54 |         observer.wait();
 55 |     });
 56 | }
 57 | 
 58 | /// Simulate a double-click on a widget.
 59 | ///
 60 | /// ## Warning!
 61 | ///
 62 | /// Please note that the double-click will "fail" if the window isn't on top of all other windows
 63 | /// (this is a common issue on OSX). Don't forget to bring the button's window on top by using:
 64 | ///
 65 | /// ```ignore
 66 | /// window.activate_focus();
 67 | /// ```
 68 | ///
 69 | /// Example:
 70 | ///
 71 | /// ```
 72 | /// extern crate gtk;
 73 | /// #[macro_use]
 74 | /// extern crate gtk_test;
 75 | ///
 76 | /// use gtk::{FileChooserAction, FileChooserWidget, prelude::FileChooserExt};
 77 | ///
 78 | /// # fn main() {
 79 | /// gtk::init().expect("GTK init failed");
 80 | /// let fcw = FileChooserWidget::new(FileChooserAction::Open);
 81 | /// fcw.connect_file_activated(|_| {
 82 | ///     println!("double clicked");
 83 | /// });
 84 | /// gtk_test::double_click(&fcw);
 85 | /// # }
 86 | /// ```
 87 | pub fn double_click<W: Clone + IsA<Object> + IsA<Widget> + WidgetExt>(widget: &W) {
 88 |     wait_for_draw(widget, || {
 89 |         let observer = observer_new!(widget, connect_button_release_event, |_, _| {
 90 |             Propagation::Stop
 91 |         });
 92 |         let allocation = widget.allocation();
 93 |         mouse_move(widget, allocation.width() / 2, allocation.height() / 2);
 94 |         let mut enigo = Enigo::new();
 95 |         enigo.mouse_click(MouseButton::Left);
 96 |         run_loop();
 97 |         enigo.mouse_click(MouseButton::Left);
 98 |         observer.wait();
 99 |     });
100 | }
101 | 
102 | /// Move the mouse relative to the widget position.
103 | ///
104 | /// Example:
105 | ///
106 | /// ```
107 | /// extern crate gtk;
108 | /// #[macro_use]
109 | /// extern crate gtk_test;
110 | ///
111 | /// use gtk::Button;
112 | ///
113 | /// # fn main() {
114 | /// gtk::init().expect("GTK init failed");
115 | /// let but = Button::new();
116 | /// gtk_test::mouse_move(&but, 0, 0); // the mouse will be on the top-left corner of the button
117 | /// # }
118 | /// ```
119 | pub fn mouse_move<W: IsA<Object> + IsA<Widget> + WidgetExt>(widget: &W, x: i32, y: i32) {
120 |     wait_for_draw(widget, || {
121 |         let toplevel_window = widget.toplevel().and_then(|toplevel| toplevel.window());
122 |         if let (Some(toplevel), Some(toplevel_window)) = (widget.toplevel(), toplevel_window) {
123 |             let (_, window_x, window_y) = toplevel_window.origin();
124 |             if let Some((x, y)) = widget.translate_coordinates(&toplevel, x, y) {
125 |                 let x = window_x + x;
126 |                 let y = window_y + y;
127 |                 let mut enigo = Enigo::new();
128 |                 enigo.mouse_move_to(x, y);
129 |                 run_loop();
130 |             }
131 |         }
132 |     });
133 | }
134 | 
135 | /// Send a mouse press event to the given widget.
136 | ///
137 | /// ## Warning!
138 | ///
139 | /// Please note that the mouse-press event will "fail" if the window isn't on top of all other
140 | /// windows (this is a common issue on OSX). Don't forget to bring the button's window on top
141 | /// by using:
142 | ///
143 | /// ```ignore
144 | /// window.activate_focus();
145 | /// ```
146 | ///
147 | /// Example:
148 | ///
149 | /// ```
150 | /// extern crate gtk;
151 | /// #[macro_use]
152 | /// extern crate gtk_test;
153 | ///
154 | /// use gtk::{Entry, prelude::EntryExt};
155 | ///
156 | /// # fn main() {
157 | /// gtk::init().expect("GTK init failed");
158 | /// let entry = Entry::new();
159 | /// entry.connect_icon_press(|_, _, _| {
160 | ///     println!("pressed");
161 | /// });
162 | /// gtk_test::mouse_press(&entry);
163 | /// # }
164 | /// ```
165 | pub fn mouse_press<W: IsA<Object> + IsA<Widget> + WidgetExt>(widget: &W) {
166 |     wait_for_draw(widget, || {
167 |         let allocation = widget.allocation();
168 |         mouse_move(widget, allocation.width() / 2, allocation.height() / 2);
169 |         let mut enigo = Enigo::new();
170 |         enigo.mouse_down(MouseButton::Left);
171 |         run_loop();
172 |     });
173 | }
174 | 
175 | /// Send a mouse release event to the given widget.
176 | ///
177 | /// ## Warning!
178 | ///
179 | /// Please note that the mouse-release event will "fail" if the window isn't on top of all other
180 | /// windows (this is a common issue on OSX). Don't forget to bring the button's window on top
181 | /// by using:
182 | ///
183 | /// ```ignore
184 | /// window.activate_focus();
185 | /// ```
186 | ///
187 | /// Example:
188 | ///
189 | /// ```
190 | /// extern crate gtk;
191 | /// #[macro_use]
192 | /// extern crate gtk_test;
193 | ///
194 | /// use gtk::{Entry, prelude::EntryExt};
195 | ///
196 | /// # fn main() {
197 | /// gtk::init().expect("GTK init failed");
198 | /// let entry = Entry::new();
199 | /// entry.connect_icon_release(|_, _, _| {
200 | ///     println!("released");
201 | /// });
202 | /// gtk_test::mouse_release(&entry);
203 | /// # }
204 | /// ```
205 | pub fn mouse_release<W: IsA<Object> + IsA<Widget> + WidgetExt>(widget: &W) {
206 |     wait_for_draw(widget, || {
207 |         let allocation = widget.allocation();
208 |         mouse_move(widget, allocation.width() / 2, allocation.height() / 2);
209 |         let mut enigo = Enigo::new();
210 |         enigo.mouse_up(MouseButton::Left);
211 |         run_loop();
212 |     });
213 | }
214 | 
215 | /// Send a key event to the given widget.
216 | ///
217 | /// ## Warning!
218 | ///
219 | /// Please note that the enter-key event will "fail" if the window isn't on top of all other
220 | /// windows (this is a common issue on OSX). Don't forget to bring the button's window on top
221 | /// by using:
222 | ///
223 | /// ```ignore
224 | /// window.activate_focus();
225 | /// ```
226 | ///
227 | /// Example:
228 | ///
229 | /// ```
230 | /// #[macro_use]
231 | /// extern crate gtk_test;
232 | ///
233 | /// use gtk_test::gtk::{Entry, prelude::EntryExt};
234 | ///
235 | /// # fn main() {
236 | /// gtk_test::gtk::init().expect("GTK init failed");
237 | /// let entry = Entry::new();
238 | /// entry.connect_preedit_changed(|_, _| {
239 | ///     println!("key entered");
240 | /// });
241 | /// gtk_test::enter_key(&entry, gtk_test::gdk::keys::constants::Agrave);
242 | /// # }
243 | /// ```
244 | pub fn enter_key<W: Clone + IsA<Object> + IsA<Widget> + WidgetExt>(widget: &W, key: Key) {
245 |     wait_for_draw(widget, || {
246 |         let observer = observer_new!(widget, connect_key_release_event, |_, _| {
247 |             Propagation::Stop
248 |         });
249 |         focus(widget);
250 |         let mut enigo = Enigo::new();
251 |         enigo.key_click(gdk_key_to_enigo_key(key));
252 |         observer.wait();
253 |     });
254 | }
255 | 
256 | /// Send keys event to the given widget.
257 | ///
258 | /// ## Warning!
259 | ///
260 | /// Please note that the enter-key event will "fail" if the window isn't on top of all other
261 | /// windows (this is a common issue on OSX). Don't forget to bring the button's window on top
262 | /// by using:
263 | ///
264 | /// ```ignore
265 | /// window.activate_focus();
266 | /// ```
267 | ///
268 | /// Example:
269 | ///
270 | /// ```
271 | /// extern crate gtk;
272 | /// #[macro_use]
273 | /// extern crate gtk_test;
274 | ///
275 | /// use gtk::{Entry, prelude::EntryExt};
276 | ///
277 | /// # fn main() {
278 | /// gtk::init().expect("GTK init failed");
279 | /// let entry = Entry::new();
280 | /// entry.connect_preedit_changed(|_, _| {
281 | ///     println!("key entered");
282 | /// });
283 | /// gtk_test::enter_keys(&entry, "A lot of keys!");
284 | /// # }
285 | /// ```
286 | pub fn enter_keys<W: Clone + IsA<Object> + IsA<Widget> + WidgetExt>(widget: &W, text: &str) {
287 |     wait_for_draw(widget, || {
288 |         focus(widget);
289 |         let mut enigo = Enigo::new();
290 |         for char in text.chars() {
291 |             let observer = observer_new!(widget, connect_key_release_event, |_, _| {
292 |                 Propagation::Stop
293 |             });
294 |             enigo.key_sequence(&char.to_string());
295 |             observer.wait();
296 |         }
297 |     });
298 | }
299 | 
300 | /// Returns the child element which has the given name.
301 | ///
302 | /// Example:
303 | ///
304 | /// ```
305 | /// extern crate gtk;
306 | /// #[macro_use]
307 | /// extern crate gtk_test;
308 | ///
309 | /// use gtk::{prelude::BuildableExtManual, Button, prelude::ContainerExt, prelude::WidgetExt, Window, WindowType};
310 | ///
311 | /// # fn main() {
312 | /// gtk::init().expect("GTK init failed");
313 | /// let but = Button::new();
314 | /// let w = Window::new(WindowType::Toplevel);
315 | ///
316 | /// but.set_widget_name("Button");
317 | /// w.add(&but);
318 | ///
319 | /// gtk_test::find_child_by_name::<Button, Window>(&w, "Button").expect("failed to find child");
320 | /// // Or even better:
321 | /// let but: Button = gtk_test::find_child_by_name(&w, "Button").expect("failed to find child");
322 | /// # }
323 | /// ```
324 | pub fn find_child_by_name<C: IsA<Widget>, W: Clone + IsA<Object> + IsA<Widget>>(
325 |     parent: &W,
326 |     name: &str,
327 | ) -> Option<C> {
328 |     find_widget_by_name(parent, name).and_then(|widget| widget.downcast().ok())
329 | }
330 | 
331 | /// Returns the child widget which has the given name.
332 | ///
333 | /// Example:
334 | ///
335 | /// ```
336 | /// extern crate gtk;
337 | /// #[macro_use]
338 | /// extern crate gtk_test;
339 | ///
340 | /// use gtk::{Button, prelude::ContainerExt, prelude::WidgetExt, Window, WindowType};
341 | ///
342 | /// # fn main() {
343 | /// gtk::init().expect("GTK init failed");
344 | /// let but = Button::new();
345 | /// let w = Window::new(WindowType::Toplevel);
346 | ///
347 | /// but.set_widget_name("Button");
348 | /// w.add(&but);
349 | ///
350 | /// gtk_test::find_widget_by_name(&w, "Button").unwrap();
351 | /// # }
352 | /// ```
353 | pub fn find_widget_by_name<W: Clone + IsA<Object> + IsA<Widget>>(
354 |     parent: &W,
355 |     name: &str,
356 | ) -> Option<Widget> {
357 |     if let Ok(container) = parent.clone().dynamic_cast::<Container>() {
358 |         for child in container.children() {
359 |             if child.widget_name() == name {
360 |                 return Some(child);
361 |             }
362 |             if let Some(widget) = find_widget_by_name(&child, name) {
363 |                 return Some(widget);
364 |             }
365 |         }
366 |     } else if let Ok(bin) = parent.clone().dynamic_cast::<Bin>() {
367 |         if let Some(child) = bin.child() {
368 |             if child.widget_name() == name {
369 |                 return Some(child);
370 |             }
371 |             if let Some(widget) = find_widget_by_name(&child, name) {
372 |                 return Some(widget);
373 |             }
374 |         }
375 |     }
376 |     None
377 | }
378 | 
379 | /// Focus on the given widget.
380 | ///
381 | /// Example:
382 | ///
383 | /// ```
384 | /// extern crate gtk;
385 | /// #[macro_use]
386 | /// extern crate gtk_test;
387 | ///
388 | /// use gtk::{Button, prelude::WidgetExt};
389 | /// use gtk::glib::Propagation;
390 | ///
391 | /// # fn main() {
392 | /// gtk::init().expect("GTK init failed");
393 | /// let but = Button::new();
394 | ///
395 | /// but.connect_focus(|_, _| {
396 | ///     println!("focused!");
397 | ///     Propagation::Stop
398 | /// });
399 | /// gtk_test::focus(&but);
400 | /// # }
401 | /// ```
402 | pub fn focus<W: Clone + IsA<Object> + IsA<Widget> + WidgetExt>(widget: &W) {
403 |     wait_for_draw(widget, || {
404 |         if !widget.has_focus() {
405 |             widget.grab_focus();
406 |             if let Ok(entry) = widget.clone().dynamic_cast::<Entry>() {
407 |                 // Hack to make it work on Travis.
408 |                 // Should use grab_focus_without_selecting() instead.
409 |                 entry.set_position(-1);
410 |             }
411 |         }
412 |     });
413 | }
414 | 
415 | /// Send a key press event to the given widget.
416 | ///
417 | /// ## Warning!
418 | ///
419 | /// Please note that the key-press event will "fail" if the window isn't on top of all other
420 | /// windows (this is a common issue on OSX). Don't forget to bring the button's window on top
421 | /// by using:
422 | ///
423 | /// ```ignore
424 | /// window.activate_focus();
425 | /// ```
426 | ///
427 | /// Example:
428 | ///
429 | /// ```
430 | /// #[macro_use]
431 | /// extern crate gtk_test;
432 | ///
433 | /// use gtk_test::gtk::{Entry, prelude::WidgetExt};
434 | /// use gtk_test::gtk::glib::Propagation;
435 | ///
436 | /// # fn main() {
437 | /// gtk_test::gtk::init().expect("GTK init failed");
438 | /// let entry = Entry::new();
439 | /// entry.connect_key_press_event(|_, _| {
440 | ///     println!("key pressed");
441 | ///     Propagation::Stop
442 | /// });
443 | /// gtk_test::key_press(&entry, gtk_test::gdk::keys::constants::Agrave);
444 | /// # }
445 | /// ```
446 | // FIXME: don't wait the observer for modifier keys like shift?
447 | pub fn key_press<W: Clone + IsA<Object> + IsA<Widget> + WidgetExt>(widget: &W, key: Key) {
448 |     wait_for_draw(widget, || {
449 |         let observer = observer_new!(widget, connect_key_press_event, |_, _| {
450 |             Propagation::Stop
451 |         });
452 |         focus(widget);
453 |         let mut enigo = Enigo::new();
454 |         enigo.key_down(gdk_key_to_enigo_key(key));
455 |         observer.wait();
456 |     });
457 | }
458 | 
459 | /// Send a key release event to the given widget.
460 | ///
461 | /// ## Warning!
462 | ///
463 | /// Please note that the key-release event will "fail" if the window isn't on top of all other
464 | /// windows (this is a common issue on OSX). Don't forget to bring the button's window on top
465 | /// by using:
466 | ///
467 | /// ```ignore
468 | /// window.activate_focus();
469 | /// ```
470 | ///
471 | /// Example:
472 | ///
473 | /// ```
474 | /// #[macro_use]
475 | /// extern crate gtk_test;
476 | ///
477 | /// use gtk_test::gtk::{Entry, prelude::WidgetExt};
478 | /// use gtk_test::gtk::glib::Propagation;
479 | ///
480 | /// # fn main() {
481 | /// gtk_test::gtk::init().expect("GTK init failed");
482 | /// let entry = Entry::new();
483 | /// entry.connect_key_release_event(|_, _| {
484 | ///     println!("key released");
485 | ///     Propagation::Stop
486 | /// });
487 | /// gtk_test::key_release(&entry, gtk_test::gdk::keys::constants::Agrave);
488 | /// # }
489 | /// ```
490 | pub fn key_release<W: Clone + IsA<Object> + IsA<Widget> + WidgetExt>(widget: &W, key: Key) {
491 |     wait_for_draw(widget, || {
492 |         let observer = observer_new!(widget, connect_key_release_event, |_, _| {
493 |             Propagation::Stop
494 |         });
495 |         focus(widget);
496 |         let mut enigo = Enigo::new();
497 |         enigo.key_up(gdk_key_to_enigo_key(key));
498 |         observer.wait();
499 |     });
500 | }
501 | 
502 | /// Wait for events the specified amount the milliseconds.
503 | ///
504 | /// Very convenient when you need GTK to update the UI to let it process some events.
505 | ///
506 | /// Example:
507 | ///
508 | /// ```
509 | /// extern crate gtk;
510 | /// extern crate gtk_test;
511 | ///
512 | /// # fn main() {
513 | /// gtk::init().expect("GTK init failed");
514 | /// gtk_test::wait(1000); // wait for a second
515 | /// # }
516 | /// ```
517 | pub fn wait(ms: u32) {
518 |     gtk::glib::timeout_add(std::time::Duration::from_millis(ms as u64), || {
519 |         gtk::main_quit();
520 |         ControlFlow::Break
521 |     });
522 |     gtk::main();
523 | }
524 | 
525 | /// Process all pending events and then return.
526 | ///
527 | /// This function is called in all functions related to events handling (like `key_release` for
528 | /// example).
529 | ///
530 | /// Example:
531 | ///
532 | /// ```
533 | /// extern crate gtk;
534 | /// extern crate gtk_test;
535 | ///
536 | /// # fn main() {
537 | /// gtk::init().expect("GTK init failed");
538 | /// gtk_test::run_loop();
539 | /// # }
540 | /// ```
541 | pub fn run_loop() {
542 |     while gtk::events_pending() {
543 |         gtk::main_iteration();
544 |     }
545 | }
546 | 
547 | /// Wait until the given condition returns `true`.
548 | ///
549 | /// Example:
550 | ///
551 | /// ```
552 | /// extern crate gtk;
553 | /// extern crate gtk_test;
554 | ///
555 | /// # fn main() {
556 | /// gtk::init().expect("GTK init failed");
557 | /// let mut x = 0;
558 | ///
559 | /// gtk_test::wait_until_done(move || {
560 | ///     x += 1;
561 | ///     x > 10
562 | /// });
563 | /// # }
564 | /// ```
565 | pub fn wait_until_done<F: FnMut() -> bool>(mut f: F) {
566 |     while !f() {
567 |         run_loop();
568 |     }
569 | }
570 | 
571 | /// Wait for a widget to be drawn.
572 | ///
573 | /// Example:
574 | ///
575 | /// ```
576 | /// extern crate gtk;
577 | /// extern crate gtk_test;
578 | ///
579 | /// use gtk::{prelude::WidgetExt, Window, WindowType};
580 | ///
581 | /// # fn main() {
582 | /// gtk::init().expect("GTK init failed");
583 | /// let mut w = Window::new(WindowType::Toplevel);
584 | ///
585 | /// w.show_all();
586 | /// gtk_test::wait_for_draw(&w, || {
587 | ///     println!("drawn!");
588 | /// });
589 | /// # }
590 | /// ```
591 | pub fn wait_for_draw<W, F: FnOnce()>(widget: &W, callback: F)
592 | where
593 |     W: IsA<Object> + IsA<Widget> + WidgetExt,
594 | {
595 |     if widget.ancestor(Window::static_type()).is_none() {
596 |         return;
597 |     }
598 |     gtk::test_widget_wait_for_draw(widget);
599 |     callback();
600 | }
601 | 
602 | fn gdk_key_to_enigo_key(key: Key) -> enigo::Key {
603 |     use enigo::Key::*;
604 |     match key {
605 |         key::Return => Return,
606 |         key::Tab => Tab,
607 |         key::space => Space,
608 |         key::BackSpace => Backspace,
609 |         key::Escape => Escape,
610 |         key::Super_L | key::Super_R => Meta,
611 |         key::Control_L | key::Control_R => Control,
612 |         key::Shift_L | key::Shift_R => Shift,
613 |         key::Shift_Lock => CapsLock,
614 |         key::Alt_L | key::Alt_R => Alt,
615 |         key::End => End,
616 |         key::Option => Option,
617 |         key::Home => Home,
618 |         key::Page_Down => PageDown,
619 |         key::Page_Up => PageUp,
620 |         key::leftarrow => LeftArrow,
621 |         key::rightarrow => RightArrow,
622 |         key::downarrow => DownArrow,
623 |         key::uparrow => UpArrow,
624 |         key::F1 => F1,
625 |         key::F2 => F2,
626 |         key::F3 => F3,
627 |         key::F4 => F4,
628 |         key::F5 => F5,
629 |         key::F6 => F6,
630 |         key::F7 => F7,
631 |         key::F8 => F8,
632 |         key::F9 => F9,
633 |         key::F10 => F10,
634 |         key::F11 => F11,
635 |         key::F12 => F12,
636 |         _ => {
637 |             if let Some(char) = key.to_unicode() {
638 |                 Layout(char)
639 |             } else {
640 |                 Raw(*key as u16)
641 |             }
642 |         }
643 |     }
644 | }
645 | 


--------------------------------------------------------------------------------
/src/lib.rs:
--------------------------------------------------------------------------------
 1 | #![warn(missing_docs)]
 2 | 
 3 | //! Crate to test UI interactions with [gtk-rs] crates.
 4 | //!
 5 | //! [gtk-rs]: https://gtk-rs.org
 6 | //!
 7 | //! Small example:
 8 | //!
 9 | //! ```
10 | //! extern crate gtk;
11 | //! #[macro_use]
12 | //! extern crate gtk_test;
13 | //!
14 | //! use gtk::{prelude::ButtonExt, prelude::ContainerExt, prelude::GtkWindowExt, prelude::LabelExt, prelude::WidgetExt};
15 | //!
16 | //! # fn main() {
17 | //! gtk::init().expect("GTK init failed");
18 | //!
19 | //! let win = gtk::Window::new(gtk::WindowType::Toplevel);
20 | //! let but = gtk::Button::new();
21 | //!
22 | //! but.set_label(""); // Otherwise, assert_label! call will fail.
23 | //! but.connect_clicked(|b| {
24 | //!     b.set_label("clicked!");
25 | //! });
26 | //!
27 | //! win.add(&but);
28 | //! win.show_all();
29 | //! win.activate_focus(); // Very important, otherwise tests will fail on OSX!
30 | //!
31 | //! assert_label!(but, "");
32 | //! gtk_test::click(&but);
33 | //! gtk_test::wait(1000); // To be sure that GTK has updated the label's text.
34 | //! assert_label!(but, "clicked!");
35 | //! # }
36 | //! ```
37 | 
38 | mod macros;
39 | 
40 | mod functions;
41 | mod observer;
42 | 
43 | pub use functions::*;
44 | pub use gtk;
45 | pub use gtk::gdk;
46 | pub use observer::Observer;
47 | 


--------------------------------------------------------------------------------
/src/macros.rs:
--------------------------------------------------------------------------------
  1 | /// To check if the widget's label matches the given string.
  2 | ///
  3 | /// Example:
  4 | ///
  5 | /// ```
  6 | /// extern crate gtk;
  7 | /// #[macro_use]
  8 | /// extern crate gtk_test;
  9 | ///
 10 | /// use gtk::{Button, prelude::ButtonExt, prelude::LabelExt};
 11 | ///
 12 | /// # fn main() {
 13 | /// gtk::init().expect("GTK init failed");
 14 | /// let but = Button::new();
 15 | /// but.set_label("text");
 16 | /// assert_label!(but, "text");
 17 | /// # }
 18 | /// ```
 19 | #[macro_export]
 20 | macro_rules! assert_label {
 21 |     ($widget:expr, $string:expr) => {
 22 |         assert_eq!($widget.label().expect("get label"), $string.to_string());
 23 |     };
 24 | }
 25 | 
 26 | /// To check if the widget's text matches the given string.
 27 | ///
 28 | /// Example:
 29 | ///
 30 | /// ```
 31 | /// extern crate gtk;
 32 | /// #[macro_use]
 33 | /// extern crate gtk_test;
 34 | ///
 35 | /// use gtk::{Label, prelude::LabelExt};
 36 | ///
 37 | /// # fn main() {
 38 | /// gtk::init().expect("GTK init failed");
 39 | /// let label = Label::new(Some("I'm a label!"));
 40 | /// assert_text!(label, "I'm a label!");
 41 | /// # }
 42 | /// ```
 43 | #[macro_export]
 44 | macro_rules! assert_text {
 45 |     ($widget:expr, $string:expr) => {
 46 |         assert_eq!($widget.text(), $string.to_string());
 47 |     };
 48 | }
 49 | 
 50 | /// To check if the widget's title matches the given string.
 51 | ///
 52 | /// Example:
 53 | ///
 54 | /// ```
 55 | /// extern crate gtk;
 56 | /// #[macro_use]
 57 | /// extern crate gtk_test;
 58 | ///
 59 | /// use gtk::{prelude::GtkWindowExt, Window, WindowType};
 60 | ///
 61 | /// # fn main() {
 62 | /// gtk::init().expect("GTK init failed");
 63 | /// let window = Window::new(WindowType::Toplevel);
 64 | /// window.set_title("Fromage ?");
 65 | /// assert_title!(window, "Fromage ?");
 66 | /// # }
 67 | /// ```
 68 | #[macro_export]
 69 | macro_rules! assert_title {
 70 |     ($widget:expr, $string:expr) => {
 71 |         assert_eq!($widget.title().expect("get text"), $string.to_string());
 72 |     };
 73 | }
 74 | 
 75 | /// To check if the widget's name matches the given string.
 76 | ///
 77 | /// Example:
 78 | ///
 79 | /// ```
 80 | /// extern crate gtk;
 81 | /// #[macro_use]
 82 | /// extern crate gtk_test;
 83 | ///
 84 | /// use gtk::{prelude::WidgetExt, Button};
 85 | ///
 86 | /// # fn main() {
 87 | /// gtk::init().expect("GTK init failed");
 88 | /// let button = Button::new();
 89 | /// button.set_widget_name("Omelette");
 90 | /// assert_name!(button, "Omelette");
 91 | /// # }
 92 | /// ```
 93 | #[macro_export]
 94 | macro_rules! assert_name {
 95 |     ($widget:expr, $string:expr) => {
 96 |         assert_eq!($widget.widget_name(), $string.to_string());
 97 |     };
 98 | }
 99 | 
100 | /// Create a new observer for signals.
101 | ///
102 | /// Example:
103 | ///
104 | /// ```
105 | /// extern crate gtk;
106 | /// #[macro_use]
107 | /// extern crate gtk_test;
108 | ///
109 | /// use gtk::prelude::GtkWindowExt;
110 | ///
111 | /// # fn main() {
112 | /// gtk::init().expect("initialization failed");
113 | /// let window = gtk::Window::new(gtk::WindowType::Toplevel);
114 | ///
115 | /// let observer = observer_new!(window, connect_activate_focus, |_|);
116 | /// window.emit_activate_focus();
117 | /// observer.wait();
118 | /// # }
119 | /// ```
120 | ///
121 | /// You can also give a block to the macro that will be called when the signal is triggered:
122 | ///
123 | /// ```
124 | /// extern crate gtk;
125 | /// #[macro_use]
126 | /// extern crate gtk_test;
127 | ///
128 | /// use gtk::prelude::GtkWindowExt;
129 | ///
130 | /// # fn main() {
131 | /// gtk::init().expect("initialization failed");
132 | /// let window = gtk::Window::new(gtk::WindowType::Toplevel);
133 | ///
134 | /// let observer = observer_new!(window, connect_activate_focus, |w| {
135 | ///     w.set_title("Caribou !");
136 | /// });
137 | /// window.emit_activate_focus();
138 | /// observer.wait();
139 | /// assert_title!(window, "Caribou !");
140 | /// # }
141 | /// ```
142 | #[macro_export]
143 | // TODO: should remove the signal after wait()?
144 | macro_rules! observer_new {
145 |     ($widget:expr, $signal_name:ident, |$($arg:tt $(: $typ:ty)?),+|) => {{
146 |         let observer = $crate::Observer::new();
147 |         let res = (*observer.get_inner()).clone();
148 |         $widget.$signal_name(move |$($arg $(: $typ)?),+| {
149 |             *res.borrow_mut() = true;
150 |         });
151 |         observer
152 |     }};
153 |     ($widget:expr, $signal_name:ident, |$($arg:tt $(: $typ:ty)?),+| $block:block) => {{
154 |         let observer = $crate::Observer::new();
155 |         let res = (*observer.get_inner()).clone();
156 |         $widget.$signal_name(move |$($arg $(: $typ)?),+| {
157 |             *res.borrow_mut() = true;
158 |             $block
159 |         });
160 |         observer
161 |     }}
162 | }
163 | 


--------------------------------------------------------------------------------
/src/observer.rs:
--------------------------------------------------------------------------------
  1 | use std::cell::RefCell;
  2 | use std::rc::Rc;
  3 | 
  4 | /// Used to wait for a widget's signal.
  5 | ///
  6 | /// It's recommended to use it with the [`observer_new`] macro.
  7 | ///
  8 | /// Example:
  9 | ///
 10 | /// ```
 11 | /// extern crate gtk;
 12 | /// #[macro_use]
 13 | /// extern crate gtk_test;
 14 | ///
 15 | /// use gtk::prelude::GtkWindowExt;
 16 | ///
 17 | /// # fn main() {
 18 | /// gtk::init().expect("initialization failed");
 19 | /// let window = gtk::Window::new(gtk::WindowType::Toplevel);
 20 | ///
 21 | /// let observer = observer_new!(window, connect_activate_focus, |_|);
 22 | /// window.emit_activate_focus();
 23 | /// observer.wait();
 24 | /// # }
 25 | /// ```
 26 | pub struct Observer {
 27 |     result: Rc<RefCell<bool>>,
 28 | }
 29 | 
 30 | impl Observer {
 31 |     /// Returns a new observer.
 32 |     ///
 33 |     /// It's recommended to not use it directly as is but instead to use the [`observer_new`] macro.
 34 |     ///
 35 |     /// But anyway, here's an example using it as is:
 36 |     ///
 37 |     /// ```
 38 |     /// extern crate gtk;
 39 |     /// #[macro_use]
 40 |     /// extern crate gtk_test;
 41 |     ///
 42 |     /// use gtk::prelude::GtkWindowExt;
 43 |     ///
 44 |     /// # fn main() {
 45 |     /// gtk::init().expect("GTK init failed");
 46 |     ///
 47 |     /// let window = gtk::Window::new(gtk::WindowType::Toplevel);
 48 |     ///
 49 |     /// let observer = gtk_test::Observer::new();
 50 |     /// let inner = observer.get_inner().clone();
 51 |     /// window.connect_activate_focus(move |_| {
 52 |     ///     *inner.borrow_mut() = true;
 53 |     /// });
 54 |     ///
 55 |     /// window.emit_activate_focus();
 56 |     /// observer.wait();
 57 |     /// # }
 58 |     /// ```
 59 |     pub fn new() -> Observer {
 60 |         Observer {
 61 |             result: Rc::new(RefCell::new(false)),
 62 |         }
 63 |     }
 64 | 
 65 |     /// Returns the inner field. Just don't use it.
 66 |     pub fn get_inner(&self) -> &Rc<RefCell<bool>> {
 67 |         &self.result
 68 |     }
 69 | 
 70 |     /// Wait for the signal to be triggered.
 71 |     ///
 72 |     /// ```
 73 |     /// extern crate gtk;
 74 |     /// #[macro_use]
 75 |     /// extern crate gtk_test;
 76 |     ///
 77 |     /// use gtk::prelude::GtkWindowExt;
 78 |     ///
 79 |     /// # fn main() {
 80 |     /// gtk::init().expect("initialization failed");
 81 |     /// let window = gtk::Window::new(gtk::WindowType::Toplevel);
 82 |     ///
 83 |     /// let observer = observer_new!(window, connect_activate_focus, |_|);
 84 |     /// window.emit_activate_focus();
 85 |     /// observer.wait();
 86 |     /// # }
 87 |     /// ```
 88 |     pub fn wait(&self) {
 89 |         loop {
 90 |             if let Ok(ref result) = self.result.try_borrow() {
 91 |                 if **result {
 92 |                     break;
 93 |                 }
 94 |             }
 95 |             crate::run_loop();
 96 |         }
 97 |     }
 98 | }
 99 | 
100 | impl Default for Observer {
101 |     fn default() -> Self {
102 |         Self::new()
103 |     }
104 | }
105 | 


--------------------------------------------------------------------------------
/tests/basic.rs:
--------------------------------------------------------------------------------
 1 | extern crate gtk;
 2 | #[macro_use]
 3 | extern crate gtk_test;
 4 | 
 5 | use gtk::{
 6 |     prelude::ButtonExt, prelude::ContainerExt, prelude::GtkWindowExt, prelude::LabelExt,
 7 |     prelude::WidgetExt, Button, Label, Orientation, Window, WindowType,
 8 | };
 9 | use gtk::glib::Propagation;
10 | 
11 | pub fn init_ui() -> (Window, Label, Button) {
12 |     gtk::init().unwrap();
13 | 
14 |     let window = Window::new(WindowType::Toplevel);
15 |     let b = gtk::Box::new(Orientation::Vertical, 0);
16 |     let label = Label::new(Some("Test"));
17 |     let but = Button::new();
18 | 
19 |     let l = label.clone();
20 |     but.connect_clicked(move |_| {
21 |         l.set_text("Clicked");
22 |     });
23 | 
24 |     b.add(&label);
25 |     b.add(&but);
26 |     window.add(&b);
27 |     window.show_all();
28 |     window.connect_delete_event(|_, _| {
29 |         gtk::main_quit();
30 |         Propagation::Stop
31 |     });
32 |     (window, label, but)
33 | }
34 | 
35 | fn main() {
36 |     let (w, l, b) = init_ui();
37 | 
38 |     assert_text!(l, "Test");
39 |     w.activate_focus();
40 |     gtk_test::click(&b);
41 |     assert_text!(l, "Clicked");
42 | }
43 | 


--------------------------------------------------------------------------------
/tests/observer.rs:
--------------------------------------------------------------------------------
 1 | extern crate gtk;
 2 | #[macro_use]
 3 | extern crate gtk_test;
 4 | 
 5 | use gtk::{prelude::GtkWindowExt, Window, WindowType};
 6 | 
 7 | fn main() {
 8 |     gtk::init().expect("initialization failed");
 9 | 
10 |     let window = Window::new(WindowType::Toplevel);
11 | 
12 |     let observer = observer_new!(window, connect_activate_focus, |_|);
13 |     window.emit_activate_focus();
14 |     observer.wait();
15 |     let observer = observer_new!(window, connect_activate_focus, |w| {
16 |         w.set_title("Title!");
17 |     });
18 |     window.emit_activate_focus();
19 |     observer.wait();
20 |     assert_title!(window, "Title!");
21 | }
22 | 


--------------------------------------------------------------------------------