@stdspa/appium-linux-driver v0.0.42

Appium Linux Driver

This is Appium driver for automating linux applications using Linux's AtSpi2 framework. The driver operates in scope of W3C WebDriver protocol with several custom extensions to cover operating-system specific scenarios. Yaoshi technical consultant sponses this project and contributed the underlying linux automation framework. The automation framework is distributed as debian installer.

Requirements

Running a linux automated test requires to install the following three components:

• The forked version of Appium: https://github.com/fantonglang/appium
• This linux driver: https://github.com/fantonglang/appium-linux-driver
• Yaoshi's automation framework

Install and run forked appium

git clone https://github.com/fantonglang/appium
cd appium
yarn install
node ./

The linux driver is referenced as dependency in appium, so no need to install it explicitly.

Yaoshi automation framework

It has been tested on Ubuntu 20.04/18.04 LTS. Here is the download link for installer. Install it with the following instructions:

sudo apt-get install gdebi-core
sudo gdebi stdspalinux-ubuntu_18_04.deb

We have plan to publish the installer for deepin, and also docker image for test automation in the cloud native way.

Any requests, such as support another linux distribution; extend user interaction gestures; build a commercial product with better performance and more capabilities, please always feel free to contact me:

UI Inspector

A custom UI inspector is provided for users. It can:

• List all the running windows with their names. Window name is used as parameter to switch between windows.
• Show XML UI hierachy of a window, and validate XPath. The user experience is inspired by Appium Inspector.

Capabilities

Element Attributes

Linux driver supports the following element attributes:

More attributes could be visited via the WebElement.get_property(name: str) API. Here is an example source of UI element: <tree-item name="package.json" pid="2575" toolkit="Chromium__1.0" states="[ENABLED,FOCUSABLE,SELECTABLE,SELECTED,SENSITIVE,SHOWING,VISIBLE]" rect="[48,746,368,22]" text-align="left" explicit-name="true" class="monaco-list-row focused selected" display="block" posinset="9" level="2" xml-roles="treeitem" tag="div" id="list_id_2_37" setsize="11" />.

To get the states of an element, use the property states. e.g. to judge if the element is selected or not, write:

if contains(el.get_property('states'), 'SELECTED'):
    print('element is selected')

Element attribute values could be retrieved from the XML page source. UI inspector can also visualize element's attributes. All attributes which present in the XML page source could be used for elements location, including but not limited to the attributes in the table.

Element Location

Linux driver supports the following location strategies:

Check the integration tests for more examples on different location strategies usage.

Other Appium Standard APIs (Python webdriver client)

Element: Set Text / Set Value

Enter text or value in the input element

Arguments

Example

el.set_text('example text')

el.set_value(12)

Element: Click

Perform click gesture on an element

Arguments

No Arguments

Example

el.click()

Press Key Code

Perform press key code gesture. Key code like 'F1', 'F2', 'Delete', 'Return', 'Up', 'Down', 'Left', 'Right'. Combination key can be performed by combining the metastate like 'CONTROL', 'ALT', 'SHIFT'.

The press key code gesture can also simulate press alphabat keys like 'a', 'b', 'c', ..., 'z'. But then the keycode field should use negative value. e.g. the ascii code for 'a' is 97, then the keycode value is -97.

Arguments

Example

driver.press_keycode(65473, 8) # alt + f4
driver.press_keycode(-118, 4) # control + v

Keycode Enumeration

Metastate Enumeration

Long Press Key Code

The same with press key code, except for pressing the key for a longer time (0.5s)

Element: Get Property / Attribute

Get the element's property value.

Arguments

Example

name = el.get_property('name') # get the name property value
name = el.get_attribute('name') # get the name property value, equivalent to get_property

Element: Clear

Clear the (input) element's text

Arguments

No arguments

Example

el.clear()

Element: Screenshot

Take screenshot of the element

Arguments

Example

el.screenshot('.pics/a.png')

Screenshot

Take screenshot of the window

Arguments

Example

driver.get_screenshot_as_file('.pics/a.png')

Platform-Specific Extensions

Beside of standard W3C APIs the driver provides the following custom command extensions to execute platform specific scenarios:

linux: getDisplaySize

Get the width and height of the display

Arguments

No arguments

Example

size = driver.execute_script('linux: getDisplaySize')
print(size) # outputs: {'width': 1440, 'height': 900}

linux: mouseMove

Move the mouse to a given absolute coordinates.

Arguments

Example

driver.execute_script('linux: mouseMove', {"x": 100, "y": 100})

linux: mouseSwipe

Mouse down at (sx, sy), and move to (ex, ey), and then mouse up.

Effectively swipe from (sx, sy) to (ex, ey)

Arguments

Example

driver.execute_script('linux: mouseSwipe', {"sx": 500, "sy": 100, "ex": 500, "ey": 700})

linux: rightClick

Right click on a given absolute coordinates.

Arguments

Example

driver.execute_script('linux: rightClick', {"x": 100, "y": 100})

linux: doubleClick

Double click on a given absolute coordinates.

Arguments

Example

driver.execute_script('linux: doubleClick', {"x": 100, "y": 100})

linux: mouseScroll

Simulate mouse scroll horizontally and vertically

Arguments

Example

driver.execute_script('linux: mouseScroll', {"moveLeftSteps": 0, "moveUpSteps": -1}) # scrolls down

linux: copy

Copy a given string to the system clipboard

Arguments

Example

driver.execute_script('linux: copy', {"str": 'sample copy text'})

linux: getClipboard

Get the clipboard content

Arguments

No Arguments

Example

content = driver.execute_script('linux: getClipboard')

Application Under Test Concept

The Linux driver has the concept of Application Under Test. This is the app, whose path has been passed as appName capability. If this application is unexpectedly terminated during test session execution then an exception is going to be thrown upon any following session command invocation. In such case the driver assumes the application under test is crashed and it is impossible to proceed. Also, the Application Under Test is going to be terminated when the testing session quits.

Examples

# Python3 + PyTest
import pytest
from appium import webdriver
from appium.webdriver.common.appiumby import AppiumBy
@pytest.fixture()
def driver():
    drv = webdriver.Remote('http://localhost:4723/wd/hub', {
        # automationName capability presence is mandatory for this Linux Driver to be selected
        'automationName': 'atspi2',
        'platformName': 'linux',
        'bundleId': 'yelp',
    })
    yield drv
    drv.quit()
def test_edit_text(driver):
    find_el = driver.find_element(by=AppiumBy.NAME, value='Find')
    find_el.click()
    edit_field = driver.find_element(by=AppiumBy.XPATH, value='(//text[@name="Search"])[1]')
    edit_field.send_keys('hello world')
    edit_field = driver.find_element(by=AppiumBy.XPATH, value='(//text[@name="Search"])[1]')
    assert edit_field.text == 'hello world'
    edit_field.clear()
    edit_field = driver.find_element(by=AppiumBy.XPATH, value='(//text[@name="Search"])[1]')
    assert edit_field.text == ''

Parallel Execution

Parallel execution of multiple Linux driver instances is highly discouraged. Only one UI test must be running at the same time.

Development & Testing

This module uses the same development tools as the other Appium drivers.

Check out the source. Then run:

npm install
gulp watch

Execute npm run test to run unit tests and npm run e2e-test to run integration tests.