Sikulix как написать бота

SikuliX имеет ряд особенностей, о которых я расскажу далее. Этот IDE разработан с целью автоматизации рутины, т.е. для создания роботов, в том числе и для игр.

Скрипт не вмешивается в обмен данными по сети или работу игрового клиента. Он действует как игрок : наблюдает то, что происходит на экране и выполняет действия.

Я использую IDE в связке с Python, потому примеры буду приводить на этом языке. Раньше я не программировал на Python, учился «на лету».

SikuliX — дальтоник

IDE не видит различий между картинкой в цвете и той же картинкой в серых тонах. Если в приложении (или игре) неактивная кнопка отличается от активной цветностью — то SikuliX не сможет их различить, даже если вы применяете метод exact().

Реакция клиента

Каждое действие пользователя должно сопровождаться какой то реакцией клиента. Если робот кликнул по кнопке, то нужно быть уверенным, что программа отреагировала на это нажатие.

Иначе возникает т.н. проскальзывание. Программа считает, что выполнила действие и продолжает исполнение операции дальше.

Функция routing_transition принимает в качестве аргументов два изображения. Первое — CL — картинка, на которую требуется осуществить нажатие. Второе — WT — изображение, появление которого ожидается после нажатия.

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

Не плановые события

Приложение (игра) может безсистемно требовать оперативной реакции пользователя. К примеру, всплывает какое то сообщение, требующее внимание игрока. Сообщение закрывает часть интерфейса программы, нарушая логику бота, т.к. робот продолжает искать какие то изображения в контексте выполняемой задачи.

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

Что можно сделать? Такую проверку можно организовать в отдельном потоке.

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

Вернемся к потокам чуть позже.

Горячие клавиши

Ваш робот скорее всего зациклен, т.е. будет выполнять бесконечно заложенную в него программу действий. Как бы прервать его работу, не убивая процесс javaw.exe в диспетчере задач?

Можно определить «горячие клавиши».

Теперь программа будет выполняться до тех пор, пока вы не нажмете CTRL+F1.

Возвращаясь к неплановым событиям, поточную функцию можно переписать следующим образом:

Введение.

SikuliX IDE — это среда разработки на Python для создания ботов на основе поиска картинок на экране.

Т.к. SikuliX использует Python, то вам необходимо его знать перед прочтением этой статьи. Есть много хороших и бесплатных курсов по Python, я назову лишь 2, это:

• Интерактивные курсы от SoloLearn.
• Видеокурсы от Stepik.

Теперь, перейдем к делу.

Сперва скачайте SikuliX IDE и запустите его.

Для использования данной среды, вам нужно установить Java.

Данная среда очень простая, поэтому сразу же напишем Hello World.

Пишем Hello World.

По задумке, наша будущая программа будет открывать блокнот и вводить в нем Hello World.

Сперва, с помощью комбинации Ctrl+Shift+2, выделите кнопку Windows.

Далее, введите комманду click() в редакторе SikuliX IDE, и, в качестве аргумента, передайте туда картинку Windows.

И запустите скрипт, нажав кнопку Выполнить. В итоге, мышка передвинулась к кнопке Windows и нажала на неё.

Далее, добавьте следующий код.

type("notepad"+Key.ENTER) #Вводит с клавиатуры notepad и нажимает ENTER
switchApp("Notepad") #Переключается на окно с названием содержащим "Notepad"
type("Hello World") #Вводит Hello World

Код я объяснил в комментариях, теперь запустите скрипт.

В результате, в блокноте появилась надпись Hello World.

Меняем настройки.

Разберем основные настройки.

• Settings.MoveMouseDelay — время перемещения мышки на следующую позицию (по умолчанию 0.5 сек)
• Settings.ObserverScanRate — задержка между сканированиями экрана (по умолчанию 0.33 сек)
• Settings.DelayBeforeMouseDown — задержка перед кликом (по умолчанию 0.5 сек)

Т.е, если уменьшить MouseMoveDelay до нуля, то курсор будет перемещаться мгновенно.

Подробнее о настройках вы можете узнать в документации.

Подсвечиваем цели.

Замените код Hello World, на следующее.

Разберемся как этот код работает.

1. В начале я с помощью функции find, нашел регион в котором находится наша картинка.
2. Далее, подсветил этот регион с помощью функции highlight на 1-у секунду.
3. И кликнул по нему.

В итоге, появилась красная рамка. Данная подсветка может вам помочь в отладке.

Меняем смещение и коэффициент совпадения.

Кликните по картинке в редакторе кода и перейдите во вкладку Предпросмотр совпадений.

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

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

Далее, перейдите во вкладку Смещение цели.

Здесь, задается координата цели, относительно найденной картинки (по умолчанию это центр картинки). На эту координату, перемещается мышка, при использовании функции click().

Используем циклы.

Для примера, я создал цикл, который 5 раз перемещает мышку туда-обратно.

Функция hover перемещает мышку на координаты не кликая по ним. В качестве аргумента, я передал одно и тоже изображение, но с разным смещением.

Т.е. кнопка Windows, в нашем случае выступает в роли якоря, относительно которого вычисляются координаты.

Полезные функции.

Здесь я распишу некоторые функции, которые вам могут пригодится.

• exists(картинка) — возвращает True, если картинка найдена.
• has(картинка) — то же самое что и exists
• wait(картинка) — ждет появления картинки.
• sleep(количество_секунд) — ждет количество_секунд
• doubleClick(картинка) — двойной щелчок по картинке.

SikuliX можно интегрировать в Java проект, для этого надо скачать sikulixapi.jar, и подключить его в качестве библиотеки. Подробнее здесь.

А есть ли подобное на Android?

Конечно есть, вот известные мне варианты:

• AnkuLua — очень похож на SikuliX, однако использует язык Lua.
• auto.js — китайская программа для автоматизации действий на экране, использует JS.

Заключение.

В этой статье я рассмотрел основы SikuliX, если остались вопросы, оставляйте их в комментариях.

Итоговый результат.

В статье рассмотрен один из подходов к автоматизации тестирования пользовательского интерфейса. Он основан на использования инструмента SikuliX,  языке Python и framework’е для тестирования: unittest.

• Постановка задачи
• Что такое SikuliX?
• Развертывание SikuliX
  • Установка Java
  • Загрузка SikuliX
  • Установка SikuliX
• Краткий обзор возможностей SikuliX
• Простой пример использования SikuliX
• Разработка приложения выполняющего автоматическое тестирование интерфейса калькулятора Windows

Постановка задачи

Лучше всего мы учимся и узнаем что-то новое, когда занимаемся конкретной проблемой. Поэтому поставим для себя следующую задачу: протестировать работу штатного калькулятора MS Windows (реализация выполнена для Windows 10) в части:

• выполнение простых арифметических действий (сложение, вычитание, умножение и деление);
• извлечение квадратного корня;
• вычисление числа обратного данному.

В качестве инструмента для решения задачи выберем SikuliX.

SikuliX – это инструмент для автоматизации действий пользователя, которые он может выполнить при работе с графическим интерфейсом. На сегодняшний день, данный продукт работает в Windows, MacOS, Linux, таким образом, он позволяет протестировать большую часть современных приложений с графическим интерфейсом. SikuliX использует технологию распознавания образов на базе OpenCV для идентификации и управления элементами пользовательского интерфейса.

SikuliX поддерживает следующие языки и технологии, базирующиеся на платформе Java: Python (на базе Jython), RobotFramework, Ruby 1.9 и 2.0 (на базе JRuby), JavaScript (на базе Java Scripting Engine), Scala и т.п. Мобильные платформы пока не поддерживаются, но можно использовать эмулятор для тестирования приложения.

Развертывание SikuliX

Рассмотрим процесс установки SikuliX на операционную систему Windows.

Установка Java

Для начала нужно убедиться в том, что у вас установлена версия исполняемой среды Java 8 (у автора не получилось установить SikuliX с Java 10). Вы можете скачать дистрибутив Java и установить ее с сайта Oracle.

Для того, чтобы узнать версию Java, которая установлена на вашем компьютере, откройте консоль (нажмите Ctrl+R и введите в окне cmd, либо найдите программу cmd.exe и запустите ее) и выполните в ней команду java -version.

Загрузка SikuliX

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

Скачайте последний доступный релиз SikuliX.

Установка SikuliX

Создайте папку, в которую вы хотите установить программу, например C:SikuliX. Далее, скопируйте туда, скачанный файл sikulixsetup-x.x.x.jar. Введите в строке адреса окна команду cmd.

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

Для запуска установки введите команду:

java -jar sikulixsetup-1.1.2.jar

Спустя какое время после запуска будет представлено диалоговое окно, в котором, для продолжения установки нужно будет нажать “Yes”.

Далее необходимо выбрать одну из опций.

Pack 1 – будут установлены SikuliX IDE и поддержка скриптового языка Python (Jython) и/или Ruby (JRuby).

Pack 2 – будут установлены библиотеки для доступа к функционалу SikuliX из Java, SikuliX IDE установлена не будет.

После выбора опции нажмите на кнопку “Setup Now”. Далее вам будет представлена сводная информация по настройкам установки, если согласны, то нажмите “Yes”.

Запустится процесс установки.

Если вы выбрали опцию Pack 1, то вам будет предложено установить Jython версии 2.7.0, согласитесь с предложенным вариантом (если у вас нет причин отказаться).

После того, как SikuliX будет установлена со всеми необходимыми компонентами, вы увидите следующее окно.

И сообщение в консоли.

Краткий обзор возможностей SikuliX

SikuliX позволяет находить на дисплее графические элементы и использовать их в качестве элементов управления. Например, если вы хотите нажать на кнопку ПУСК в Windows, необходимо в исходный код программы добавить функцию click(), в которую в качестве аргументов передается картинка кнопки ПУСК.

Ниже приведены функции, которые наиболее часто используются при работе с SikuliX.

Функции поиска элементов на экране.

wait(picture [, timeout])

Ожидание появления на экране картинки picture, время ожидания определяется timeout’ом. Если объект не появится, то будет вызвано исключение.

waitVanish(picture [, timeout])

Ожидание исчезновения с экрана картинки picture, время ожидания определяется timeout’ом. Если объект не исчезнет, то будет вызвано исключение.

exists(picture[, timeout])

Ожидание появления на экране картинки picture, время ожидания определяется timeout’ом. Если объект не появится, то будет возвращено значение None. Эту функцию удобно использовать в условных выражениях.

Эмуляция работы с мышью.

click(picture)

Выполняет нажатие левой кнопкой мыши на элементе picture.

doubleClick(picture)

Выполняет двойное нажатие левой кнопкой мыши на элементе picture.

rightClick(picture)

Выполняет нажатие правой кнопкой мыши на элементе picture.

hover(picture)

Выполняет наведение указателя мыши на элемент picture.

Эмуляция нажатий клавиш на клавиатуре.

type([picture, ]text[, modifiers])

Вводит в элемент picture текст – text. Если необходимо, то используются модификаторы – это нажатия клавиш Shift, Ctrl, Alt и т.п. Например, если необходимо нажать клавишу “1” с зажатой Alt, то решение будет выглядеть так type(“1”, KEY_ALT).

Ниже представлен простой пример, демонстрирующий работу SikuliX.

Простой пример использования SikuliX

Создадим простой пример, демонстрирующий одну из возможностей SikuliX. Задача будет состоять в том, что нужно вызвать окно “Выполнить”, ввести в нем “cmd”, нажать Enter и через появившееся окно консоли запустить Notepad.

1. Запустите SikuliX, для этого зайдите в каталог с установленной программой и запустите файл runsikulix.cmd. В результате загрузится оболочка SikuliX IDE.

2. Создайте новый проект, для этого на панели меню выберите File->New.

3. Сохраните созданный проект (мы назовем его prj).

4. Введите исходный код программы.

Особенность SikuliX состоит в том, что она может работать с графическими элементами пользовательского интерфейса, SikuliX IDE предоставляет инструменты для помещения этих элементов в исходный код программы и работы с ними.

Код программы выглядит так:

Как вы может видеть, аргументом функции click() является картинка, для того, чтобы ее туда поместить, установите курсор в нужное место программы, нажмите на кнопку “Take screenshot”, выделите на экране нужную область, и она будет помещена в редактор – в нашем случае как аргумент функции.

В текстовом виде этот код выглядит так:

click("1534932430966.png")
sleep(1)
type("cmdn")
sleep(1)
type("notepadn")
sleep(1)
type("Hello! From SikuliX")

Запустите программу, для этого нажмите на кнопку “Run”. Когда программа будет работать – не двигайте мышкой!

Разработка приложения выполняющего автоматическое тестирование интерфейса калькулятора Windows

Для построения тестирующего приложения будем использовать framework для тестирования unittest. Исходный код проекта вы можете загрузить из репозитория, содержимое которого необходимо поместить в папку с установленным SikuliX. Часть исходного кода, размещенного в статье, будет представлена в картинках для большей наглядности.

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

Создадим два класса BaseActionsTests и ExtendsActionsTests в CalcSimple.sikuli.

Класс BaseActionsTests отвечает за тестирование выполнения базовых операций: сложение, вычитание, умножение и деление. Добавим в этот класс следующие методы, используемые при запуске тестов.

setUpClass() – метод действует на уровне класса BaseActionsTests, запускается один раз перед запуском тестов класса, в нем мы проверяем, запущен ли калькулятор, переводим его в режим “Standart”. Если он не запущен, то запускаем его.

tearDownClass() – метод действует на уровне класса BaseActionsTests, запускается один раз после отработки всех тестов класса, в нем мы ничего не делаем.

setUp() – метод запускается каждый раз перед запуском любого теста, в нем мы тоже ничего не делаем.

tearDown() – метод запускается каждый раз после работы любого теста, в нем будем производить очистку экрана калькулятор, для этого нужно имитировать нажатие кнопки Esc.

Методы непосредственно тестирующие функционал калькулятора имеют следующие имена:

test_add() – тестирование операции “сложение”.

test_sub() – тестирование операции “вычитание”.

test_mul() – тестирование операции “умножение”.

test_div() – тестирование операции “деление”.

Внутренняя архитектура этих методов схожа и выполнена по следующему принципу: последовательно нажимаем на определенные кнопки, например: “1”, “+”, “4”, “=” и смотрим, совпадает ли результат с тем, что мы ожидаем.

Ниже представлен код метода test_add().

Класс ExtendsActionsTests отвечает за тестирование выполнения дополнительных операций: извлечение квадратного корня и операция вычисления обратного элемента. Содержимое методов setUpClass(), tearDownClass(), setUp() аналогично тому, что представлено в классе BaseActionsTests.

Для тестирования функционала в классе ExtendsActionsTests  используются следующие методы:

test_sqrt() – тестирование операции “извлечение квадратного корня”.

test_one_div_x() – тестирование операции “вычисление обратного элемента”.

Ниже представлен скриншот IDE с введенным кодом программы.

Создадим проект mainTest.sikuli в той же папке, в которой находится CalcSimple.sikuli. Исходный код проекта mainTest приведен ниже.

import unittest
import CalcSimple
import StringIO
import sys
import HTMLTestRunner

reload(CalcSimple)

# Create list of test cases
testList = []
testList.append(CalcSimple.BaseActionsTests)
testList.append(CalcSimple.ExtendsActionsTests)
testLoad = unittest.TestLoader()

# Assemble test cases into suite list
caseList = []
for testCase in testList:
  testSuite = testLoad.loadTestsFromTestCase(testCase)
  caseList.append(testSuite)

# Create TestSuite
suite = unittest.TestSuite(caseList)

# Run tests
if len(sys.argv) > 1 and sys.argv[1] == "html":
    runner = unittest.TextTestRunner(verbosity=1)
    filename = "Test1.html"
    output = open (filename,"wb")
    runner = HTMLTestRunner.HTMLTestRunner(
             stream=output,
             title="Test report"
         )
    runner.run(suite)
else:
    unittest.TextTestRunner(verbosity=2).run(suite)

Кратко рассмотрим содержимое файла.

1. Импортируем необходимые библиотеки.

import unittest
import CalcSimple
import StringIO
import sys
import HTMLTestRunner

2. Загружаем модуль CalcSimple.

reload(CalcSimple)

3. Создаем список тестов и заворачиваем их в TestSuite.

# Assemble test cases into suite list
caseList = []
for testCase in testList:
  testSuite = testLoad.loadTestsFromTestCase(testCase)
  caseList.append(testSuite)

# Create TestSuite
suite = unittest.TestSuite(caseList)

4. Запускаем тесты.

# Run tests
if len(sys.argv) > 1 and sys.argv[1] == "html":
    runner = unittest.TextTestRunner(verbosity=1)
    filename = "Test1.html"
    output = open (filename,"wb")
    runner = HTMLTestRunner.HTMLTestRunner(
             stream=output,
             title="Test report"
         )
    runner.run(suite)
else:
    unittest.TextTestRunner(verbosity=2).run(suite)

Для того, чтобы получить результат тестирования калькулятора в удобочитаемом виде будем использовать HTMLTestRunner.

Для запуска тестирования создайте bat файл со следующим содержимым.

java -Dsikuli.Debug=-2 -jar sikulix.jar -r projectscalcTestmainTest.sikuli --args html

и поместите этот файл в каталог, рядом с каталогом projects.

Если запустить этот файл, то после прохождения тестов будет создан файл Test1.html, содержимое которого (если все тесты прошли успешно) будет примерно таким:

When to use SikuliX?#

• You want to automate repetitive tasks in
  daily usage of applications or web pages
• While playing games you want to automate some aspects
• In IT administration you want to automate admin tasks
• Developing an application you want to do visual testing

… and you do not have the adequate tools at hand.

---

What is a visual workflow?#

Something like that we do every day sitting in front of our PC:

• we want to achieve something
• we use an application for that (e.g. the browser to access web content)
• the following steps might be repeated several times
  • we click some buttons, links or other visuals
  • we wait for the app to react and show the expected result on the screen
  • we fill in some text somewhere and press some keys like TAB or ENTER
  • we might have to click some button to go on
  • we wait some more for some expected reaction or result

This is a visual workflow.

---

Visual Automation#

So again taking the above workflow, now using SikuliX commands:

Using the SikuliX IDE, you can setup and maintain your visual workflows including capturing and organizing the needed images. Besides SikuliX’s basic commands, you do not need any programming or scripting knowledge. Only when you would like to optimize, repeat a more than basic linear workflow, you have to dive deeper into the scripting language of your choice (currently supported in the IDE: Python, and Ruby).

---

Visual Testing#

In software testing sooner or later testers want to check some visual content against their expectation. This might be the presentation of GUI elements on the screen or the visual content of some part of the screen.

SikuliX can be integrated in various ways into such testing environments, either on the scripting level or using the Java based API (where the SikuliX features are implemented). Prominent examples for this approach are RobotFramework or Cucumber.

A combination of GUI aware tools and SikuliX already exists (e.g. together with Selenium for web apps).

---

How SikuliX handles images#

To use images with the features of SikuliX like click(someImage), you need to store these images as image files preferably in the PNG format someImage.png somewhere on the file system or the net.

An image in this sense is some rectangular pixel area taken from the screen. With SikuliX we use the phrase capture or make a screenshot as the process of getting the image from the screen and saving it in an image file for later use in the image search process.

Capturing is supported by the IDE or programmatically via the respective SikuliX features. You might use any capture tool instead to get your images (as mentioned preferably in PNG format).

How SikuliX loads images at runtime:

• bundle path: the images are stored together with the script file (.py for Python, .rb for Ruby) in a folder named someScript.sikuli or someScript, where the scriptfile must be named the same as the folder (e.g. someScript.py). This all is automatically assured, when working with the SikuliX IDE.
• image path: additionally SikuliX supports a list of places as an image path. Possible places are folders in the file system, folders in a jar-file and folders somewhere in the net. The bundle path always is the first entry. There are functions available to manage your own image path. When an image has to be loaded (exception: the absolute path is given), the places are sequentially checked for the existence of the image. The first matching place wins.

---

Finding images on the screen#

SikuliX uses the OpenCV package for finding an image on the screen.

The SikuliX feature is based on OpenCV’s method matchTemplate(), which is rather good explained on their example page. If you are not familiar with how it works, you should just have a look there and then come back to here and read further.

A basic feature in Sikulix is to wait for an image to appear in a given region:

The matchTemplate() expects an even sized or larger image (base), where the given image (target) should be searched. To prepare that, we internally make a screenshot (using Java Robot class) of the screen area defined by the given aRegion. This now is the base image and held in memory. The target image is also created as in memory image read form the image file. Both images then are converted to the needed OpenCV objects (CVMat).

Now we run the matchTemplate() function and get a matrix in the size of the base image, that contains for each pixel a similarity score for the target image compared pixel by pixel with it’s top left corner at this pixel location.

Sikulix implements a still-there-feature: before searching in the search region, it is first checked, whether the image is still in the same place as at the time of the last search (if the search region contains this last match). On success, this preflight operation usually takes some milliseconds, which speeds up workflows if they contain repetitive tasks with the same images.

Images showing up multiple times#

Not knowing the magic behind SikuliX’s search feature and the matchTemplate()function, people always wonder, why images showing up multiple times on the screen, are not found in some regular order (e.g. top left to bottom right). That this is not the case is caused by the implementation of the matchTemplate() function as some statistical numeric matrix calculations. So never expect SikuliX to return the top left appearance of a visual being more than once on the screen at time of search. The result is not predictable in this sense.

If you want to find a specific item of these multiple occurrences, you have to restrict the search region, so that only the one you are looking for is found.

For cases where this is not suitable or if you want to cycle through all appearances, we have the findAll() method, that returns a list of matches in decreasing result score order. You might work through this list according to their position on the screen by using their (x,y) top left corner coordinates. findAll internally evaluates the search result matrix, by repetitively looking for the next max value after having “switched off” some area around the last max.

---

Glossary#

In this list you can find words and phrases together with a short explanation, that are used in the context of SikuliX.

capture get a rectengular area of pixels from a monitor/screen, that can be stored as an image file