Список поддерживаемых методов

Ниже приведён список методов, поддерживаемых qtium-драйвером, на примере использования Appium Python Client:

• Базовые методы для работы с устройством и приложениями

  • activate_app(appId: str) -> WebDriver

  • execute(command: str, arguments: None | Dict[str, Any]) -> Dict[str, str]

  • execute_async_script(script: str, args: List[str]) -> str

  • execute_script(script: str, args: List[str]) -> str

  • find_element или find_elements(locatorStrategy: str (By.ID), selector: str) -> WebElement/WebElements list

  • get_device_time(format: str | None = None) -> str

  • is_locked(None) -> bool

  • is_keyboard_shown() -> boo

  • network_connection

  • query_app_state(appName: str) -> str

  • set_network_connection(connectionType: double)

  • terminate_app(appId: str) | None

• Свойства и методы для работы с UI-элементами
  • Свойства

    • id -> str

    • location -> dict

    • rect -> dict

    • text -> str

  • Методы
    • async_click(id: str) -> None
    • click(None) -> None
    • get_property(name) -> str | bool | WebElement | dict
• Список команд для execute_script и execute_async_script, специфичных для ОС Аврора

  • app:clickContextMenuItem

  • app:enterCode

  • app:goBack

  • app:goForward

  • app:peek

  • app:pullDownTo

  • app:pushUpTo

  • app:scrollToItem

  • app:swipe

  • app:waitForPageChange

  • app:waitForPropertyChange

  • appium:setAutoPrimary

  • appium:findWindowByElement

  • appium:setWindow

  • system:shell

  • system:shellIncludeStderr

• Список методов для execute_script и execute_async_script, используемых для тестирования специальных сценариев
  • app:emulatefillMemory
  • app:emulateFreeze
  • app:emulateMemoryLeak
  • app:emulateNullPtrCrash
• Действия W3C (W3C Actions)

Базовые методы для работы с устройством и приложениями

activate_app(appId: str) -> WebDriver

Открывает приложение, если оно не запущено или запущено в фоновом режиме.

Параметр appId не используется при вызове activate_app(), но его необходимо указывать для корректного выполнения.

Возвращает ссылку на текущий объект, позволяя последовательно вызывать методы этого объекта.

Пример:

driver.activate_app('ru.omp.filemanager')

Примечание. Для работы с каждым отдельным приложением необходимо создавать отдельный экземпляр WebDriver.

Примечание. Для работы с каждым отдельным приложением необходимо создавать отдельный экземпляр WebDriver.

execute(command: str, arguments: None | Dict[str, Any]) -> Dict[str, str]

Позволяет отправить на выполнение команду, поддерживаемую Appium непосредственно в виде строки.

Возвращает JSON-ответ команды в виде объекта словаря.

Примеры:

res = driver.execute('launchApp')

или

driver.execute('queryAppState', {'appId':'ru.omp.filemanager'})
ответ: {'value': 'RUNNING_IN_FOREGROUND'}

или

driver.execute('getDeviceTimeGet')
ответ: {'value': 'Sun Dec 1 19:48:28 2024'}

или

driver.execute('isLocked')
ответ: {'value': False}

execute_async_script(script: str, args: List[str]) -> str

Позволяет асинхронно выполнить команду, специфичную для ОС Аврора из доступного набора расширений.

Этот метод отличается от execute_script тем, что команда выполняется асинхронно. Данный механизм позволяет избежать блокировки интерфейса во время обработки длительных операций. После вызова метода управление возвращается немедленно, однако сам процесс может занять некоторое время.

Пример:

driver.execute_async_script('app:swipe', 'left')
time.sleep(1)

Примечание. При использовании execute_async_script рекомендуется применять таймауты или методы app:waitForPageChange и app:waitForPropertyChange. Это особенно важно для команд, которые могут выполняться продолжительное время или зависеть от внешних условий.

execute_script(script: str, args: List[str]) -> str

Позволяет синхронно выполнить команду, специфичную для ОС Аврора из доступного набора расширений.

Пример:

driver.execute_script('app:swipe', 'left')

find_element или find_elements(locatorStrategy: str (By.ID), selector: str) -> WebElement/WebElements list

Данные методы используются для поиска UI-элементов на странице приложения, аналогично способам, используемым при работе с qainspector.
Для поиска элемента необходимо указать стратегию поиска (элемент класса By из selenium.webdriver.common: By.NAME, By.ID, By.CLASS_NAME, By.XPATH) и локатор в соответствующем формате. Разница между find_element и find_elements только в возвращаемом значении. Первый метод возвращает первый найденный элемент в виде объекта WebElement или генерирует исключение, если элемент не найден. Второй метод возвращает список всех подходящих под критерий поиска элементов в виде объектов WebElement или пустой список при отсутствии таковых.

Примеры:

from selenium.webdriver.common.by import By
driver.find_element(By.NAME, 'Устройство')

или

from selenium.webdriver.common.by import By
driver.find_element(By.ID, 'MoreButton')

или

from selenium.webdriver.common.by import By
driver.find_element(By.CLASS_NAME, 'MainPage')

или

from selenium.webdriver.common.by import By
driver.find_element(By.XPATH, "//MiniComboBox[@value='Адрес' and @enabled='true']")

get_device_time(format: str | None = None) -> str

Возвращает дату и время с устройства.

Опционально принимает набор спецификаторов формата. По умолчанию используется формат 'E MMM d HH:mm:ss yyyy'. Информация по спецификаторам формата доступна по ссылке.

Примеры:

dt = driver.get_device_time()
device_date = driver.get_device_time('YYYY-MM-DD')
device_date = driver.get_device_time('HH:mm:ss')

или

dt = driver.execute_script('mobile:get_device_time')
device_date = driver.execute_script('mobile:get_device_time', 'YYYY-MM-DD')
device_time = driver.execute_script('mobile:get_device_time', 'HH:mm:ss')

is_locked(None) -> bool

Проверяет, заблокировано ли устройство.

Возвращает True, если заблокировано, False в противном случае.

Пример:

res = driver.is_locked();

или

res = driver.execute_script('mobile:is_locked')

is_keyboard_shown() -> bool

Проверяет, открыта ли экранная клавиатура.

Возвращает True, если открыта, False в противном случае.

Пример:

res = driver.is_keyboard_shown()

или

res = driver.execute_script('mobile:isKeyboardShown')

network_connection -> int

Возвращает текущий тип сетевого соединения на устройстве в виде целого числа.

• 0 — нет соединения;
• 1 — авиарежим;
• 2 — только Wi-Fi;
• 4 — только мобильные данные;
• 6 — все сети включены.

Пример:

connection_mode = driver.network_connection
print(f"Текущий режим сети: {connection_mode}")

query_app_state

Запрашивает состояние приложения.

Возвращает одно из следующих состояний приложения в виде строки:

• RUNNING_IN_FOREGROUND;
• RUNNING_IN_BACKGROUND;
• NOT_RUNNING.

Пример:

state = driver.query_app_state('ru.omp.filemanager')

или

state = driver.execute_script('mobile:query_app_state', 'ru.omp.filemanager')

set_network_connection(connectionType: double)

Устанавливает тип сетевого соединения на устройстве.

• 0 — нет;
• 1 — авиарежим;
• 2 — только wi-fi;
• 4 — только мобильные данные;
• 6 — все сети включены.

Примеры:

driver.set_network_connection(1)

или

driver.set_network_connection(6)

terminate_app(appId: str) -> str

Завершает приложение, если оно запущено. Если указанное приложение не активно, сервер возвращает ошибку 500, и генерируется исключение.

В случае успеха возвращает пустую строку.

Параметр appId не используется при вызове terminate_app(), но его необходимо указывать для корректного выполнения.

Пример:

driver.terminate_app('ru.omp.filemanager')

Свойства и методы для работы с UI-элементами

Для работы с UI-элементами на странице приложения сначала необходимо позиционировать их с помощью методов find_element или find_elements, а затем производить доступные действия с найденными объектами.

У элементов можно получать доступные свойства или передавать их в качестве параметров другим методам, а также вызывать методы:

• Свойства

  • id -> str

  • location -> dict

  • rect -> dict

  • text -> str

• Методы
  • async_click(id: str) -> None
  • click(None) -> None
  • get_property(name) -> str | bool | WebElement | dict

Примечание. Более подробно об этих методах можно прочитать в документации Selenium.

Свойства

id -> str

Возвращает идентификатор элемента в формате строки.

Пример:

element = driver.find_element(By.CLASS_NAME, "LabelBase")
element_id = element.id

location -> dict

Возвращает координаты элемента в формате словаря с ключами x и y.

Пример:

element = driver.find_element(By.ID, "MyButton")
element_location = element.location

rect -> dict

Возвращает координаты элемента в формате словаря с ключами x, y, width, height, centerx и centery.

Пример:

element = driver.find_element(By.ID, "MyButton")
element_rect = element.rect

text -> str

Возвращает текст элемента в формате строки.

Пример:

element = driver.find_element(By.ID, "MyLabel")
element_text = element.text

Методы

app:asyncClick

Выполняет асинхронный клик по указанному элементу. Этот метод отличается от click тем, что команда выполняется в фоновом режиме, не блокируя интерфейс. После вызова метода управление возвращается немедленно, но сам клик может занять некоторое время для выполнения.

Пример:

element = driver.find_element(By.ID, "MyButton")
driver.execute_script("app:asyncClick", element.id)
time.sleep(1)

Примечание. При использовании app:asyncClick рекомендуется применять таймауты или методы app:waitForPageChange и app:waitForPropertyChange.

click(None) -> None

Выполняет клик по элементу.

Пример:

element = driver.find_element(By.ID, "MyButton")
element.click()

get_property(name) -> str | bool | WebElement | dict

Возвращает значение свойства элемента по указанному имени. Тип возвращаемого значения может быть строкой, булевым значением, другим WebElement или словарем.

Пример:

element = driver.find_element(By.ID, "MyButton")
element_enabled = element.get_property("enabled")

Список команд для execute_script и execute_async_script, специфичных для ОС Аврора

app:clickContextMenuItem

Выполняет выбор элемента контекстного меню.

Примеры:

driver.execute_script('app:clickContextMenuItem', 'ContextMenu_0x12345678', 'some text label')

или

driver.execute_script('app:clickContextMenuItem', 'ContextMenu_0x12345678', index)

• ContextMenu_0x12345678 — идентификатор элемента меню, который необходимо найти до использования этого метода (например, с помощью find_element или find_elements).

app:enterCode

Используется для ввода цифрового кода с элемента "Клавиатура". Для подтверждения действия используется #, для отмены действия — *.

Пример:

driver.execute_script('app:enterCode', '12345#')

app:goBack

Выполняет действие навигации "Назад" на текущей странице.

Пример:

driver.execute_script('app:goBack')

Примечание. Не работает в приложениях со SplitView.

app:goForward

Выполняет действие навигации "Вперёд" на текущей странице.

Пример:

driver.execute_script('app:goForward')

Примечание. Не работает в приложениях со SplitView.

app:peek

Выполняет действие peek (движение от одного края экрана к другому) в выбранном направлении.

Пример:

driver.execute_script('app:peek', 'left')

Допустимые направления:

• left;
• right;
• up;
• down.

app:pullDownTo

Выполняет вытягивание вниз ("PullDown") с вызовом PullDownMenu и выбором требуемого элемента. Если элементы отображаются не в начале представления, то сначала происходит прокрутка к верху и только потом выполняется вытягивание верхнего меню. Данный метод не работает с меню, сформированными динамически.

Примеры:

driver.execute_script('app:pullDownTo', 'some text label')

или

driver.execute_script('app:pullDownTo', index)

app:pushUpTo

Выполняет действие "Вытягивание вверх" ("PushUp") с вызовом "PushUpMenu" и выбором требуемого элемента. Если элементы отображаются не в конце представления, то сначала происходит прокрутка до конца и только потом вытягивается нижнее меню. Данный метод не работает с меню, сформированными динамически.

Примеры:

driver.execute_script('app:pushUpTo', 'some text label')

или

driver.execute_script('app:pushUpTo', index)

app:scrollToItem

Выполняет прокрутку до определённого элемента. Метод завершается, когда указанный элемент становится полностью видимым или после 10 неудачных попыток изменить его положение. При неудачном пролистывании исключение не возникает.

Пример:

driver.execute_script('app:scrollToItem', 'ContextMenu_0x12345678')

• ContextMenu_0x12345678 — идентификатор элемента, который необходимо найти до использования этого метода (например, с помощью find_element или find_elements).

app:swipe

Выполняет свайп (движение от центра экрана к краям) в выбранном направлении.

Пример:

driver.execute_script('app:swipe', 'left')

Допустимые направления:

• left;
• right;
• up;
• down.

app:waitForPageChange

Синхронно ожидает изменения страницы. Метод возвращает управление в программу или после любого изменения на странице или по достижении установленного таймаута. Данный метод не работает со страницами, использующими SplitView.

Пример:

driver.execute_script('app:waitForPageChange', 1000)

• 1000 — таймаут в миллисекундах ожидания изменения.

app:waitForPropertyChange

Синхронно ожидает изменения значения свойства элемента. Метод возвращает управление в программу или после указанного изменения или по достижении установленного таймаута.

Пример:

driver.execute_script('app:waitForPropertyChange', 'ContextMenu_0x12345678', 'opened', true, 10000)

• ContextMenu_0x12345678 — идентификатор элемента, который необходимо найти до использования этого метода (например, с помощью find_element или find_elements).

Можно использовать None в качестве значения свойства, чтобы ждать любого изменения свойства, или точное значение, чтобы следить за ним.

• 10000 — таймаут в миллисекундах для ожидания изменения.

appium:setAutoPrimary

Включает или отключает автоматический выбор основного окна.

Основное окно — это окно, в котором выполняются команды теста (поиск, клик, ввод и т.д.). По умолчанию драйвер пытается выбрать основное окно автоматически. Если автоматический режим отключен, окно необходимо выбрать вручную с помощью appium:setWindow.

Аргументы, передаваемые в виде словаря:

• enabled (Boolean) — True для включения автоматического выбора, False для отключения.

Пример:

driver.execute_script("appium:setAutoPrimary", {"enabled": False})

appium:findWindowByElement

Выполняет поиск окна текущего экземпляра приложения, которое содержит элемент, соответствующий заданному селектору.

Возвращает windowId (идентификатор) первого найденного окна. Этот идентификатор можно передать в appium:setWindow для переключения контекста выполнения.

Аргументы, передаваемые в виде словаря:

• strategy — стратегия поиска элемента внутри окна. Может быть строкой или константой из selenium.webdriver.common.by.By.
• value — значение для поиска (например, имя класса, текст и т.д.).

Поддерживаемые стратегии:

Стратегия (str или By)	Описание
By.ID, "id", "object name", "accessibility id"	Поиск элемента по его id (эквивалентно objectName в QML)
By.CLASS_NAME , "class name"	Поиск элемента по имени его класса
By.PARTIAL_LINK_TEXT, "partial link text", "text", "contains"	Поиск элемента, текст которого содержит указанное значение
By.LINK_TEXT, "text_exact", "link text"	Поиск элемента, текст которого в точности равен указанному значению
By.XPATH , "xpath"	Поиск элемента с использованием выражения XPath
"property"	Поиск элемента по строке свойства

Пример:

from selenium.webdriver.common.by import By

softkeys_window = driver.execute_script("appium:findWindowByElement", {
    "strategy": By.CLASS_NAME,
    "value": "SoftKeysPanel"
})

appium:setWindow

Устанавливает текущее основное окно в то, которое идентифицируется windowId. Все последующие действия (поиск, клик, ввод и т.д.) будут выполняться в этом окне.

Примечание. Если appium:setAutoPrimary включён, драйвер может впоследствии переопределить выбор этого окна при изменении состояния приложения. Чтобы этого избежать, необходимо вызвать appium:setAutoPrimary с параметром {"enabled": False} перед установкой окна вручную.

Аргументы, передаваемые в виде словаря:

• windowId — идентификатор окна, полученный с помощью appium:findWindowByElement.

Пример:

driver.execute_script("appium:setWindow", {"windowId": softkeys_window})

system:shell

Выполняет shell-скрипт или команду на устройстве с привилегиями root. Необходимо использовать с осторожностью.

Пример:

output = driver.execute_script('system:shell', '/bin/sh', ['-c', 'ls -la /'])
print(output)

или

output = driver.execute_script('system:shell', 'ls', ['-la', '/'])
print(output)

system:shellIncludeStderr

Выполняет shell-скрипт или команду на устройстве с привилегиями root с возможностью обработки stdErr, stdOut и exitcode, возвращаемыми при выполнении скрипта. Необходимо использовать с осторожностью.

Пример:

driver.execute_script('system:shellIncludeStderr', '/bin/sh', ['-c', 'ls -la /'])
stdout = result['stdout']
stderr = result['stderr']
exitcode = result['exitcode']

Список методов для execute_script и execute_async_script, используемых для тестирования специальных сценариев

app:emulatefillMemory

Эмулирует использование всей свободной и доступной памяти. Выделяет память в цикле до тех пор, пока операционная система не уничтожит процесс. Принимает количество мегабайт для выделения памяти оператором new() и таймаут (в миллисекундах) для одной итерации цикла.

Примеры:

• C выделением 100 Мб и ожиданием 5 сек после каждого выделения в цикле:

  driver.execute_script('app:emulatefillMemory', 100, 5000)
  

• C выделением 100 Мб и стандартным ожиданием (3 сек) на каждой итерации цикла:

  driver.execute_script('app:emulatefillMemory', 100)
  

app:emulateFreeze

Эмулирует зависание приложения до истечения заданного таймаута (в миллисекундах). По умолчанию таймаут составляет 10 секунд (10000 мс).

Примеры:

• C таймаутом 5 сек:

  driver.execute_script('app:emulateFreeze', '5000')
  

• C таймаутом по умолчанию:

  driver.execute_script('app:emulateFreeze')
  

app:emulateMemoryLeak

Эмулирует утечку памяти. Принимает количество мегабайт для выделения памяти оператором new() и таймаут (в миллисекундах) после выделения.

Примеры:

• C выделением 100 Mб и ожиданием 5 сек:

  driver.execute_script('app:emulateMemoryLeak', 100, 5000)
  

• C выделением 100 Mб и стандартным ожиданием (3 сек):

  driver.execute_script('app:emulateMemoryLeak', 100)
  

app:emulateNullPtrCrash

Эмулирует аварийное завершение программы из-за обращения к нулевому указателю.

Пример:

driver.execute_script('app:emulateNullPtrCrash')

Действия W3C (W3C Actions)

W3C Actions API — это стандартизированный способ эмуляции сложных действий пользовательского ввода (касания, нажатия клавиш, прокрутка колесом мыши). Он позволяет выстраивать последовательности элементарных действий и выполнять их на устройстве.

Основной принцип работы заключается в создании цепочки действий с помощью ActionChains, её последующем выполнении через метод perform() и сбросе состояния ввода с помощью reset_actions().

Для создания последовательностей используются следующие "строительные блоки":

• actions.w3c_actions.pointer_action — действия указателя (касания экрана):
  • move_to_location(x, y) — перемещает указатель в абсолютные экранные координаты;
  • move_to(origin=element, x=0, y=0) — перемещает указатель относительно центра указанного элемента;
  • pointer_down(button=0) / pointer_up(button=0) — имитирует нажатие/отпускание пальца (для сенсорного ввода используется button=0);
  • pause(seconds) — добавляет паузу в последовательность действий.
• actions.w3c_actions.key_action — действия с клавиатурой:
  • key_down(value) / key_up(value) — нажимает/отпускает клавишу.
• actions.w3c_actions.wheel_action — действия колеса прокрутки:
  • scroll_by_amount(x, y) — прокручивает на указанное смещение по осям X и Y.
• actions.perform() — отправляет собранную последовательность действий драйверу на выполнение;
• actions.reset_actions() — сбрасывает состояние ввода на устройстве. Рекомендуется вызывать после сложных цепочек действий.

Пример реализации свайпа с помощью W3C Actions:

from selenium.webdriver import ActionChains
from selenium.webdriver.common.actions import interaction
from selenium.webdriver.common.actions.action_builder import ActionBuilder
from selenium.webdriver.common.actions.pointer_input import PointerInput

def swipe(self, x_1: int, y_1: int, x_2: int, y_2: int) -> None:
    actions = ActionChains(self.driver, duration=300)
    actions.w3c_actions = ActionBuilder(self.driver, mouse=PointerInput(interaction.POINTER_TOUCH, 'touch'))
    actions.w3c_actions.pointer_action.move_to_location(x=x_1, y=y_1)
    actions.w3c_actions.pointer_action.pointer_down()
    actions.w3c_actions.pointer_action.move_to_location(x=x_2, y=y_2)
    actions.w3c_actions.pointer_action.release()
    actions.w3c_actions.pointer_action.pause(duration=5000)
    actions.perform()

Примечания:

• Координаты задаются в пикселях устройства, с точкой отсчёта (0,0) в левом верхнем углу экрана.
• Можно создавать несколько источников ввода (например, для имитации жестов несколькими пальцами), добавляя шаги для каждого из них перед вызовом perform().
• Этот механизм является предпочтительным для эмуляции пользовательских жестов.