My Automated GUI Testing software

Back in 2010 I initially released some software that I named Automated GUI Testing, or AGT, for short. As its name implies, I used this software for running automated GUI tests. I originally created it to test “thick client” desktop applications, but it can be used to test the GUI of any application, or at least any application that you can get running on a Mac, including mobile applications that can be tested in an emulator. (It should also work on Linux and Windows systems, but I haven’t tried it on those yet.)

The software is written using JRuby, the benefits of which are:

• Scripts are written in Ruby
• You can use any Java classes and methods you want/need in your scripts
• The script syntax is simple, and is easy to read and change

I just brought the software back to life a little bit in 2019, and thought I’d share an example of how it works. To that end, here’s a sample AGT script that does the following:

• Brings a Google Chrome window to the foreground
• Opens the alvinalexander.com website in a window
• Opens a new Chrome tab
• Opens the OneMansAlaska.com site in that new tab

Back in the day this script quite possibly demonstrated the first call of an AppleScript script from JRuby, and I find that technique to be very useful for testing. I think it demonstrates the power of having Ruby, JRuby, and Java as a scripting language.

An example GUI testing script

Here’s the source code for my example GUI testing script:

require 'java'
require 'AgileGuiTesting'
require 'AGTMacOsX'

#----------------------------------------------------------------
# PURPOSE: A little script to demonstrate AGT with Google Chrome.
# PRECONDITIONS:
#   - You’re running a MacOS system
#   - Chrome is installed
#   - Chrome is not running
# POSTCONDITIONS:
#   - Chrome will be left open, with two new tabs open
#----------------------------------------------------------------

foreground 'Google Chrome'

# i should use a `wait_for_color` or `wait_for_image` call here,
# but i'm being lazy
wait 3000

c 'get the mouse out of the way'
move_mouse_animated 30, 200
wait 250

# note: the VK_* keys are defined in AGTKeys.rb, and get imported here,
# so this is not a string, it refers to `KeyEvent::VK_L`.
c 'putting focus in the Chrome url field'
apple VK_L

# note: could use VK_ENTER at the end, but that’s more work
c 'opening AA.COM ...'
type 'alvinalexander.com \n'

c 'waiting X seconds ...'
wait 4000

c 'new tab, then go to oma site'
apple 't'

# used to be a `\n` at the end of this string
c 'go to the OMA site; url field should automatically gain focus'
type 'www.onemansalaska.com \n'

I hope you’ll agree that this GUI testing script is easy to read. It would be even smaller if I left out some of the explanatory comments. One thing worth noting is that the c in the code is short for “comment,” and it’s a way of adding comments to the AGT output. Adding comments like this is an extremely useful technique for debugging when a GUI test fails.

Also, as you can see, the code doesn’t rely on X/Y coordinates to work, although AGT can do that as well. A main weakness in this script is that it uses the “wait [ms]” approach, and I would never do that in production testing code. There are better methods in AGT that let you wait for other things, such as changes to colors onscreen.

One thing that’s worth mentioning is that AGT doesn’t only have to be used for automated GUI testing. You can also use it as a GUI scripting language if you prefer. For instance, I used to use it to open ~10 browser tabs at one time for websites that I liked to visit.

Download the software

I just made my AGT software available as an open source project, and you can find it here on Github:

• github.com/alvinj/AutomatedGuiTesting

I don’t currently have a lot of documentation in the project, but hopefully there’s enough to help motivated programmers get going with it.

Reporting live from Boulder and Louisville, Colorado,
Alvin Alexander