Skip to main content

Desktop App

caution

Desktop App automation is currently only available in Ruby

The Spark Desktop App driver is available if you have configured test_types in config.yml to include desktop_app or selected the test_type desktop_app in Flare.

Windows, MacOS and Linux distributions are supported but may have specific requirements. Check the list of pre-requisites before starting.

TestEvolve.desktop_app

Screen Object Model​

Similar to the page object class, elements are defined at the top of the class and these can be referenced in methods. These elements are defined as the relative path from the directory specified under image_directory in desktop_app.yml.

For an image stored in c:/my_test_evolve_project/features/support/images/ok.png the following values would be used:

image_directory: features/support/images

element: ok.png

If you are using a new module to group your screen objects, ie/ module Screens then you must add it to the World.rb file in the features/support folder.

features/support/world.rb
World(Pages, Screens)

An example of a screen object class can be found below.

module Screens
  def customer_creation_screen
    @customer_creation_screen ||= CustomerCreationScreen.new
  end

  class CustomerCreationScreen < TestEvolve::Core::ScreenObject
    element(:ok_button) { 'ok.png' }

    def select_ok
      ok_button.click
    end
  end
end

This would then be called from the step definition layer like this: customer_creation_screen.select_ok

Type​

To send a string of characters to the screen from the Screen Object class, use the following command:

type('example text')

You can also specify the interval (in seconds) between each key press, using the following command:

type('example text', interval: 0.5)

Press Key​

To send a specific character or special character to the screen from the Screen Object class, use the following command:

Pass through the key as a symbol

press_key(:enter)
press_key(:f1)
press_key(:f12)

Element​

When an element is defined there are a number of actions that can be performed on it.

The action will be performed once the defined element image has been found on the screen. This will timeout if the subimage can not be found within the timeout configured as find_timeout in desktop_app.yml.

Click​

When click is called on an element, Spark will search the screen for the defined image and click on the centre of it.

element.click

Double Click​

When double click is called on an element, Spark will search the screen for the defined image and click on the centre of it.

element.double_click

Exists​

When exists is called on an element, Spark will search the screen for the defined image and return true if the image is found. It will return false if the image is not found.

element.exists?

Exists Within (secs)​

Exists within will return true if the element image is located within the specified number of seconds. It will return false if the element image is not located in the specified number of seconds.

element.exists_within(5)

Example usage:

element(:error_message) { 'error_message.png' }

def verify_error_message
  raise 'Error message was not displayed' unless error_message.exists_within(5)
end

Offset​

Offset allows you to specify an offset from the found images location. This returns a new Region that behaves in the same way as an element.

The offset method takes the following arguments and returns a new Region.

  • offset_x: the number of pixels from the left of the element
  • offset_y: the number of pixels from the top of the element
  • width: the width (in pixels) of the region from the offset point
  • height: the height (in pixels) of the region from the offset point
element.offset(offset_x: 300, offset_y: 0, width: 200, height: 60)

Example usage:

element(:text_field_label) { 'text_field_label.png' }

def text_from_text_field
  text_field_label.offset(offset_x: 300, offset_y: 0, width: 200, height: 60).text
end

Region​

A Region is returned by an offset and is a subsection of the entire screen.

Click​

When click is called on a region, Spark click on the centre of it.

region.click

Double Click​

When double click is called on a region, Spark will click on the centre of it.

region.double_click

Text​

When text is called on a region, Spark will use an integration to Tesseract to recognise characters in the image and return the text.

region.text

Example usage:

element(:text_field_label) { 'text_field_label.png' }

def text_from_text_field
  text_field_label.offset(offset_x: 300, offset_y: 0, width: 200, height: 60).text
end

Mouse​

If you are not using a specific element and need to control the mouse directly with x and y co-ordinates then the following methods are available.

TestEvolve.mouse

Click​

To click directly on the screen at specific x and y co-ordinates, use the following command:

TestEvolve.mouse.click(x, y)

Double Click​

To double-click directly on the screen at specific x and y co-ordinates, use the following command:

TestEvolve.mouse.double_click(x, y)

Move​

To move the mouse to specific x and y co-ordinates, use the following command:

TestEvolve.mouse.move(x, y)

Other​

Lower level interactions with the mouse are also available, which allows users to create actions such as swipe or drag and drop.

Press​

To press the mouse button down:

TestEvolve.mouse.press(x, y)

Release​

To release the mouse button:

TestEvolve.mouse.release(x, y)

Keyboard​

In order to interact directly with the keyboard, the following methods are available:

TestEvolve.keyboard

Type​

To send a string of characters to the desktop application via the keyboard, use the following command:

TestEvolve.keyboard.type('example text')

You can also specify the interval (in seconds) between each key press, using the following command:

TestEvolve.keyboard.type('example text', interval: 0.5)

Press Key​

To send a specific character or special character to the desktop application via the keyboard, use the following command:

Pass through the key as a symbol

TestEvolve.keyboard.press_key(:enter)
TestEvolve.keyboard.press_key(:f1)
TestEvolve.keyboard.press_key(:f12)