Automa Blog

Showing posts tagged with: example, Show all

Automa 2.7.0: press_and_hold

We're happy to report that Automa 2.7.0 has just been released. Besides some small bug fixes, notable new features are the commands press_and_hold(...) and release(...). These two commands can be combined to press, hold and release keyboard keys. For example, the following snippet starts the Chrome web browser and zooms in using the mouse wheel, by pressing and holding the CTRL key:

start('Chrome')
press_and_hold(CTRL)
scroll_up()
release(CTRL)

Support for these commands was added because our users and customers requested them. If you would like to request a feature, please let us know via our contact page. (Priority is given to paying customers.)

The new version can as usual be downloaded from our download page. Happy automating!

Taking screenshots with Automa

We're happy to announce that we just released version 2.5.5 of our next generation GUI automation tool, Automa. Besides a few small improvements, the new version features a command called save_screenshot(...). This command lets you save a screenshot of your entire screen contents to a file. This is very useful for debugging or further processing of the outcomes of a test / automation run.

The syntax of the new command is very simple. You merely pass a string identifying the path of where the screenshot should be saved. Automa saves the file as a PNG file, so we recommend the file ending .png. For instance:

save_screenshot(r'C:\screenshot.png')

Please note the leading r before the quotation mark in the example. This is always required when working with file paths as it instructs Automa's built-in Python interpreter to treat any backslashes in the string as plain-text backslashes (not, as normally, as escape characters).

After playing around with the new command ourselves, we found it surprisingly useful and fun to use. We hope you will feel the same. You can as always download the new version from our download page.

Happy automating!

Uninstall programs automatically

Automa can be used to automate repetitve tasks such as uninstalling programs. Take a look at the script below:

import sys
assert len(sys.argv) > 2
press(LWIN + "r")
write("control.exe appwiz.cpl")
press(ENTER)
click(sys.argv[2])
click("Uninstall")
click("Yes")
uninstall.at

In order to run this script and uninstall an application run:

>Automa.exe uninstall.at "Name of the application"

Automa 2.3: Focus on Usability

Since the last release of Automa two weeks ago, our focus has been on improving the usability of the interactive Automa console. We are extremely pleased with the results! Here are the new features:

Tab-Autocompletion

Have you ever had the need to repeatedly type a long function name such as get_name_under_mouse() in the Automa console? With the new version of Automa, you can now save a lot of typing by writing only the first few characters of the function and then pressing Tab. For instance, to enter get_name_under_mouse(), you only need to type the first two letters ge and then press Tab to have Automa automatically complete the function name for you.

When multiple completions are possible and you press Tab then you get a list of the possible completions. For example: The Automa console by default includes the commands start(...) and start_tutorial(...). If you type in st and press Tab, then the Automa console displays both commands and automatically fills in their common prefix start at the next line of input:

>>> st<TAB>
start(          start_tutorial(
>>> start

Another cool feature of the Tab completion is that it can show you the properties and methods of an object. Want to know which methods a string object has? Just append a dot . to the object and press Tab:

>>> my_string = "Hello World!"
>>> my_string.<TAB>
my_string.capitalize( my_string.islower(    my_string.rpartition(
my_string.center(     my_string.isspace(    my_string.rsplit(
my_string.count(      my_string.istitle(    my_string.rstrip(
my_string.decode(     my_string.isupper(    my_string.split(
my_string.encode(     my_string.join(       my_string.splitlines(
my_string.endswith(   my_string.ljust(      my_string.startswith(
my_string.expandtabs( my_string.lower(      my_string.strip(
my_string.find(       my_string.lstrip(     my_string.swapcase(
my_string.format(     my_string.partition(  my_string.title(
my_string.index(      my_string.replace(    my_string.translate(
my_string.isalnum(    my_string.rfind(      my_string.upper(
my_string.isalpha(    my_string.rindex(     my_string.zfill(
my_string.isdigit(    my_string.rjust(
>>> 

Finally, if you press Tab without having entered anything, then you get a quick overview of the most important commands and properties available to you:

>>> <TAB>
about(                start_tutorial(       BKSP
clear(                switch_to(            CTRL
click(                wait_until(           DEL
doubleclick(          write(                DIVIDE
drag(                 Application(          DOWN
exit(                 Button(               END
find_all(             CheckBox(             ENTER
get_name_under_mouse( ComboBox(             ESC
help(                 Config(               HOME
highlight(            GUIElement(           INS
history(              Image(                LEFT
hover(                ListItem(             LWIN
kill(                 MenuItem(             MULTIPLY
playback(             NoWorkWindowError(    PGDN
press(                Point(                PGUP
quit(                 RadioButton(          PRTSC
rightclick(           Text(                 RIGHT
save(                 TextField(            SHIFT
scroll_down(          TimeoutExpired(       SPACE
scroll_left(          TreeItem(             SUBTRACT
scroll_right(         Window(               TAB
scroll_up(            ADD                   UP
start(                ALT
>>> 

Context-sensitive help

Some mistakes in Automa are easy to make, especially for novice users. Consider the following line:

>>> press(Enter)

The problem here is that Enter is not defined: The Enter key is stored as a constant variable in Automa and the Python coding guidelines state that such variables should have all-uppercase names. The correct name of the variable in Automa is therefore ENTER.

When you type the above command, Automa now gives you a hint that you might have meant something else:

>>> press(Enter)
NameError: name 'Enter' is not defined
 
Did you maybe mean
        press(ENTER)
?
>>> 

Here are some other context-sensitive hints that were added in this release:

>>> sleep(5)
NameError: name 'sleep' is not defined
 
To wait for a specific event, you can use wait_until(...). Eg:
        wait_until(Button('Save').exists)
If you wish to wait for a number of seconds, you need to import `sleep`
from Python`s time module:
        from time import sleep
        sleep(5)
>>>
>>> enter('Hello World!')
NameError: name 'enter' is not defined
 
Did you maybe mean
        write('Hello World!')
?
>>>
>>> type('test.txt', into='File name')
TypeError: type() takes 1 or 3 arguments
 
Did you maybe mean
        write('test.txt', into='File name')
?
>>> 

Pasting via CTRL+V

Previously, it was only possible to paste into the Automa console using a right-click:

Pasting into the Automa console via rightclick

Now, this is also possible by just pressing CTRL + V.

clear()

Windows users will be familiar with the well-known command cls. This function clears the contents of a console window so you can see more clearly and not be distracted by any previously entered commands. We have implemented this functionality in Automa with the new command clear. You can simply call it as follows:

>>> clear()

Rewriting history

Consider the following commands:

>>> def f():
...     print 1
...     print 3
...
>>> 

The user has forgotten print 2 in his function definition and would like to change this. The new version of Automa makes this particularly easy: You can revoke the commands you previously entered using the Arrow Up and Down keys. So, to modify the function definition, you press Up three times and Enter to get the line

>>> def f():

Then, you press Down once and Enter to get the next line

...     print 1

Now you can enter the line that was forgotten by typing:

...     print 2

The function definition can then be completed by pressing Down again and twice confirming with Enter. With very few keystrokes, you have thus changed the function definition to:

>>> def f():
...     print 1
...     print 2
...     print 3
...
>>>

While this is a simple feature, it comes in surprisingly useful.

As always, you can download the latest version of Automa from our download page.

Happy automating! :-)

Automa 2.1: Deadly!

We just released version 2.1 of Automa. It contains a deadly (but very useful ;-) ) new feature.

The typical steps in a GUI automation case are:

  1. Start the application you wish to automate.
  2. Perform GUI automation.
  3. Close the application.

The last step ensures that the system is left in the same state as before the automation, and thus ready for the next automation run. In particular, you want to kill all applications and windows opened by the GUI automation before.

A problem with step 3. is that sometimes unexpected windows might have popped up in the GUI automation in step 2., which the logic in step 3. is not prepared to handle (think "Automatic Updates"). Another problem is that sometimes closing the application might bring up additional windows or pop-ups such as "You have unmodified changes. Do you want to save?".

The solution to these problems is to not close the application and its opened windows using normal GUI operations such as click("File", "Exit"). Instead, one simply wants to kill the entire application, just like what you do when you force-close a program using the Windows task manager.

The new version of Automa brings with it a new command kill(...) and a new predicate Application(...) that lets you do just that. When you start an application via start(...), you now get an Application object as a result:

>>> start("Notepad")
Application("Untitled - Notepad")

The result corresponds to the same-named entry in the "Applications" tab of the Windows task manager:

Notepad Application in the task manager

After you have performed your automation, you can use the new kill(...) command to close your application and all associated windows:

notepad = start("Notepad")
# Perform GUI Automation
kill(notepad)

Independently of which windows were open in the application (eg. a "Save As" dialog) or would have opened during a normal closing ("Do you want to save?"), the kill(...) statement closes the open application. This ensures that your test system is left in exactly the same state it was in before the automation, and is thus ready for the next automation run.

The two new features of course seamlessly combine with Automa's existing API:

>>> notepad = start("Notepad")
>>> start("Calculator")
Application('Calculator')
>>> switch_to(notepad)
>>> find_all(Application())
[Application('Untitled - Notepad'), Application('Calculator')]
>>> kill("Calculator")
>>> find_all(Application())
[Application('Untitled - Notepad')]
>>> kill(notepad)
>>> find_all(Application())
[]

Deadly, useful or both? See for yourself on our download page ;-)

Happy automating!

Automa 2.0.2: Graphical debugging, drag & drop

Despite the fact that our last (major) release was just a few days ago, we already have a small but we think extremely useful little update for you :-)

We added two new commands, the first of which is highlight(...). It allows you to highlight GUI element occurrences on the screen. For instance, when you are working with Notepad, you can now execute the following command:

highlight(MenuItem("File"))

As a result, the "File" menu entry will be highlighted with a red rectangle. You can see this in the following screenshot:

Result of the new highlight command

This can be extremely useful, especially in cases where you have multiple GUI elements with the same name, and need to find a way of distinguishing between them.

The second command is one we should have added a long time ago. It's called drag(...) and is used to perform a drag and drop operation. For example:

drag("File", to="Folder")

Sweet and simple. Just how we like Automa's API to be.

For more information on the new commands, please see our docs section. Information on highlight(...) is also there, in the subsection Console Commands.

Happy automating!

Automa 2.0: Speed up your scripts!

It's been a long way, but we finally made it: Version 2.0 of our next generation GUI automation tool Automa is live. It's time for a little recap...

Full-time work on Automa began in April 2012. The first basic version was published in October of the same year. It lacked many features, but was enough to give out to users and get feedback on. This - your! - feedback has been driving Automa's development ever since: We made Automa's support for international characters ö, ä, ê, é etc. incredibly simple. We gave real-life examples and videos of the things you can do with Automa and refined its API to truly make it the simplest GUI automation tool out there. We won a prize and went to CeBIT. At the same time, we added WPF support and made Automa 66% faster. Then came the fine-tuning: improved window handling, more commands, Java support, more detailed search, even more commands and finally, much improved image search algorithms. Phew!

With all these features already implemented, you might ask "what's next?" Well, how about the ability to:

Speed up your Automa scripts by 40%

The new version of Automa adds a Config class that can be used to fine-tune Automa's behaviour. For example:

Config.auto_wait_enabled = False

This line tells Automa to disable the auto-wait functionality. When auto-wait is enabled, Automa automatically waits after performing GUI actions, such as start, click or write. The amount of time waited is calculated dynamically, using criteria such as the current CPU usage. This makes Automa scripts very stable, however Automa is conservative when it comes to deciding how long to wait and so might sometimes wait longer than absolutely necessary. To speed up the execution of your scripts, the property auto_wait_enabled can thus be used to disable the automatic wait facility. This is useful in cases where you know that waiting is not required, or when you already are synchronizing your script with the command wait_until.

Another configuration value exposed by the Config class is wait_interval_secs:

Config.wait_interval_secs = 0.3

When auto_wait_enabled is true and Automa waits after performing a GUI action, wait_interval_secs determines how often Automa checks whether the action has completed. Setting this property to a lower value such as for instance 0.1 can thus also be used to speed up you scripts.

The results? We used the above properties to fine-tune and selectively disable auto-wait, like so:

 
>>> Config.auto_wait_enabled = False
>>> write("John", into="Name")
>>> press(TAB)
>>> write("Smith")
>>> Config.auto_wait_enabled = True
>>> click("Submit")

Similar modifications were performed on all of Automa's regression test scripts. This reduced the time taken to run the scripts from 14 minutes to just under 10 minutes, a speed improvement of roughly 40%!

We also added several other small but useful properties to the new Config class. You can read all about them on our documentation page.

New commands for scrolling

Just for the sake of completeness, we should mention that we added commands that allow you to simulate scrolling the mouse wheel: scroll_up, scroll_down, scroll_left, scroll_right. You can find more information about them on our documentation page.

As always, we'd be very happy to hear your comments or questions in the "Comments" section below.

Happy automating!

Automa 1.7.0: Support for Java Apps

We just released version 1.7.0 of our next generation GUI automation tool Automa. The main new feature is that it is now possible to automate Java applications (for instance using Swing, AWT or SWT). Here's an example video of Automa being used to automate the Java-based text editor jEdit:

To run this example for yourself, you need to install the Java Runtime Environment version 7u6 or higher and jEdit. You also need to configure your Java Runtime Environment as outlined in our documentation. Once you have done this, you can run the following script, which is the one used in the video above:

start("jEdit")
if Window("Tip of the Day").exists:
    switch_to(Window("Tip of the Day"))
    click("Close")
 
click("File", "New")
write("Hello World!")
press(CTRL + 's')
write("C:\\", into="Path")
press(ENTER)
write("HelloWorld.txt", into="File name")
click("Save")
click("File", "Exit")
jEdit.at

The next version of Automa will feature improved image search algorithms and means for reading data from tables, so stay tuned :-)

Happy automating!

Automa 1.5.1: Window switching

We just released a new version of our next generation GUI automation tool Automa. In addition to several small improvements and bug fixes, it includes a new command switch_to that lets you switch to a given window.

In its basic form, switch_to takes a string argument that identifies the window to be switched to by its title:

switch_to("Notepad")
switch_to("Chrome")

If multiple windows with a matching title exist, a WindowAmbiguousError is raised. If none exist, a WindowNotFoundError is raised.

A simple example of the basic form of switch_to is given below. It starts Notepad and the Windows Calculator, performs some calculations in the Calculator and copies and pastes the result into Notepad:

 
start("Notepad")
start("Calculator")
press(1, ADD, 2, ENTER)
press(CTRL + 'c')
switch_to("Notepad")
press(CTRL + 'v')
press(CTRL + 's')

The second form of switch_to takes a Window as its argument. This type of object is now returned by the start command:

>>> start("Calculator")
Window("Calculator")

The result Window("Calculator") tells us that a window with title Calculator was opened. If you store this object in a variable, you can switch to it later using switch_to:

calculator = start("Calculator")
 
# Perform some other operations that may switch away from Calc...
 
# Switch back to Calc:
switch_to(calculator)

Of course, if you never switch away from the windows you operate with, you do not need to use switch_to - Automa remembers the window your last command operated with and switches to it automatically, if required. switch_to is only necessary when you need to handle multiple open windows at the same time. The following example shows a case where that is necessary:

notepad_1 = start("Notepad")
notepad_2 = start("Notepad")
switch_to(notepad_1)
write("Hello World!")
press(CTRL + 'a', CTRL + 'c')
switch_to(notepad_2)
press(CTRL + 'v')

As always, you can download the current version of Automa from our download page. Since Automa does not require installation, it also doesn't require un-installation: To upgrade from a previous version, simply to download (and possibly unzip) the latest release. Happy automating! :-)

Website testing using Python and Automa

After each release, we download the newest version of Automa from our website, in exactly the same way as our users would do. We then quickly launch it to make sure everything works. We do this to make sure that the newest version of our product was deployed to the server and that it is not corrupted in any way.

The steps required to download the file can be easily automated using.. Automa! And, by using Python's unittest library, we can add some assertions to make sure that the website is working correctly and that the file was indeed downloaded. Today I quickly wrote the appropriate test script which I would like to share.

In order to start, you need to download Automa ZIP archive and extract it somewhere to your disk (for example, extract contents of Automa.zip into C:\Automa). Then edit (or add) the PYTHONPATH environment variable so that it contains the path to the library.zip file (for example,  PYTHONPATH=C:\Automa\library.zip). This allows importing and using the Automa API in your Python scripts:

from automa.api import *

Then, in any text editor (for example, notepad) you can write a test script which uses Automa's API, save it with the *.py extension and run using Python interpreter. In order to test the downloading of Automa works fine, I wrote the following test case:

from automa.api import *
from os.path import expanduser, exists, join
import unittest
 
class TestAutomaWebsite(unittest.TestCase):
    def setUp(self):
        start("firefox")
 
    def test_download(self):
        # get downloads directory
        zip_path = join(expanduser("~"), "Downloads", "Automa.zip")
        self.assertFalse(exists(zip_path ))
 
        click(Image("location.png"))
        write("http://www.getautoma.com/")
        press(ENTER)
 
        # assert that the website is up and running and has been loaded
        self.assertTrue(Image("automa_logo.png").exists)
        click("Download")
        click(Image("name_field.png"))
        write("Tytus")
        press(TAB)
        write("BugFree Software")
        press(TAB)
        write("tytus@getautoma.com")
 
        # if zip is not selected, then select it
        zip_radio_button = Image("zip_radio_button.png")
        if (zip_radio_button.exists):
            click(zip_radio_button)
        click(Image("download_button.png"))
 
        # if Firefox opens window asking what to do with the file..
        if (Image("download_window.png").exists):
            click("Save File")
            click("OK")
 
        # close the "Downloads" window
        press(ALT + F4)
 
        # make sure that the correct page is displayed
        self.assertTrue(Image("registration_complete.png"))
 
        # check that Automa.zip has been downloaded
        self.assertTrue(exists(zip_path))
 
    def tearDown(self):
        # close Firefox
        press(ALT + F4)
 
if __name__ == "__main__":
    unittest.main()

As you can see, I used multiple *.png images in the test script. With Automa, you always have the choice of using either the image-based or text-based automation. Normally, the text-based automation is preferred as it is more robust and test scripts do not break if GUI elements change visually. However, in some cases, for example when it is difficult to refer to UI elements by text (for example, when they don't have any label assigned to them), you can always fall back to *.png images. In the above script I used the following images:

location.png:location.png
automa_logo.png:automa_logo.png
name_field.png:name_field.png
zip_radio_button.png:zip_radio_button.png
download_button.png:download_button.png
download_window.png:download_window.png
registration_complete.png:registration_complete.png

In order to run the test script, I saved it together with all the images in one directory and run the python interpreter from the command prompt:

Test Run Success

And this is it! After running this automated test script I am sure that our website is up and running and that Automa.zip can be downloaded without any issues. You can try it yourself by downloading the archive below which contains the test_automa_download.py script together with all the images.

TestAutomaDownload.zip

Happy testing and automating! As always, we'd be very happy to hear what you think about our tool in the comments below :-)