Skip to content

Latest commit

 

History

History
237 lines (157 loc) · 15.2 KB

README.md

File metadata and controls

237 lines (157 loc) · 15.2 KB
Raw

Garcon

Garcon -- Plugin for generating Kakao's Page objects from Android's layout.xml files.

Плагин для ускорения создания Page object-ов с использованием Kakao DSL.

Содержание

  1. Мотивация
  2. Возможности плагина
  3. Интеграция
  4. Использование плагина

Мотивация

Рутинная часть написания UI тестов заключается в описании всех виджетов Page Object-ов, которые есть в том или ином файле верстки. При этом надо учитывать типы виджетов, давать описываемым свойствам понятные имена, не забывать про принятый в компании формат классов Page Object-ов.

Мы в hh.ru решили ускорить процесс описания таких Page Object-ов при помощи собственного плагина для Android Studio.

Возможности плагина

Плагин добавляет три специальных Action-а (элементы контекстного меню):

  • Создание Page Object-а из файла XML-верстки
  • Создание KRecyclerItem Page Object-а из файла XML-верстки
  • Добавление Kakao-виджетов из XML-верстки в существующий Page Object

Также, плагин добавляет два live template:

  • step - для создания каркаса функции, описывающей шаг тестового кейса
  • item - для добавления типа элементов в KRecyclerView

Интеграция

Сборка архива плагина

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

Для этого:

  • Скачайте репозиторий к себе и откройте его в Intellij IDEA CE (или Ultimate)
  • Убедитесь, что у вас установлен плагин Plugin Dev Kit
  • Открыв проект, дождитесь его синхронизации
  • Найдите Gradle-таску buildPlugin (Garcon -> Tasks -> intellij -> buildPlugin) или запустите из терминала ./gradlew buildPlugin
  • Собранный zip-архив плагина будет находиться в папке ./build/distributions

Подключение плагина к Android Studio

Собранный архив плагина можно подключить к Android Studio. Для этого:

  • Откройте настройки студии (меню Preferences)
  • Выберите вкладку Plugins
  • Сверху найдите иконку с шестеренкой, нажмите на нее, и выберите пункт Install from disk
  • Укажите путь до собранного .zip-архива
  • Перезагрузите IDEA

Настройка плагина

Для корректной работы плагину требуется небольшая настройка.

Garcon добавляет собственную страницу конфигурации, которую можно найти в Preferences -> Appearance & Behavior -> Garcon.

На этой странице вы должны указать:

  • Путь к папке с конфигурацией плагина, например, /Users/user/Projects/hh-android/code-cookbook/templates/garcon (обязательно)
  • Папку, в которую будут добавляться создаваемые Page Object-ы экрана, по умолчанию (опционально)

Плагин будет искать .ftl-шаблоны внутри папки /templates внутри конфигурационной папки. То есть нужно создать примерно следующее дерево файлов:

/garcon
    /templates
        screen_page_object.ftl
        rv_item_page_object.ftl

Описание .ftl-шаблонов

Шаблон для Page Object-а экрана должен иметь имя screen_page_object.ftl. При генерации кода, плагин пробрасывает в него следующие параметры:

  • package_name -- package name будущего класса, зависит от выбора конечной папки в диалоге создания Page Object-а
  • r_file_package_name -- package name для R-класса файла верстки, из которого будет сгенерирован Page Object. Берется из AndroidManifest-файла модуля, в котором находится файл верстки
  • class_name -- имя класса, которое ввел пользователь в диалоге создания Page Object-а
  • properties_declarations_list -- список сгенерированных описаний Kakao-виджетов вида private val titleTextView = KTextView { withId(R.id.activity_main_text_view_title) }
  • import_classes_fqn_list - список fully qualified names найденных Kakao-виджетов, например com.agoda.kakao.text.KButton, com.agoda.kakao.text.KTextView и т.д.

Шаблон для RecyclerItem Page Object-а должен иметь имя rv_item_page_object.ftl. При генерации кода, плагин пробрасывает в него следующие параметры:

  • r_file_package_name -- package name для R-класса файла верстки, из которого будет сгенерирован Page Object. Берется из AndroidManifest-файла модуля, в котором находится файл верстки
  • class_name -- имя класса, которое ввел пользователь в диалоге создания Page Object-а
  • properties_declarations_list -- список сгенерированных описаний Kakao-виджетов вида private val titleTextView = KTextView { withId(R.id.activity_main_text_view_title) }
  • import_classes_fqn_list - список fully qualified names найденных Kakao-виджетов, например com.agoda.kakao.text.KButton, com.agoda.kakao.text.KTextView и т.д.

Примеры написанных шаблонов можно найти вот здесь

Использование плагина

Action-ы

Все три добавленных Action-а доступны только из двух мест:

  • Во вкладке навигации вы выбрали файл верстки (должен находиться в Android-модуле внутри папки layout-*) и нажали Cmd + N.
  • Находясь в коде XML-файла верстки (который находится в Android-модуле внутри папки layout-*), вы нажали Cmd + N.

Каждый из Action-ов работает по следующей схеме:

  • Показ диалога для настройки собственных параметров
  • Сбор всех XML-тэгов разных View внутри XML-верстки, отмеченных идентификаторами (у View должен быть установлен аттрибут android:id="@+id/....)

Важно!

Плагин НЕ СОБИРАЕТ View, вложенные в верстку через <include>

  • Преобразование собранных тэгов в описание Kakao-виджетов (KTextView, KView, и т.д.) в следующий вид:
private val myWidgetContainer = KView { withId(R.id.activity_main_container_my_widget) }
  • Проброс сконвертированных виджетов для дальнейшей обработки.

Generate Page Object Action

Данный Action предназначен для генерации Page Object-а Kakao-экрана (наследника класса com.agoda.kakao.screen.Screen) из XML-файла с версткой.

При нажатии на пункт меню Generate Page Object появится специальный диалог, в котором можно

  • набрать название будушего класса
  • выбрать package и папку, в которой будет сгенерирован класс Page Object-а

После нажатия на кнопку Ok собранные плагином Kakao-виджеты будут проброшены в описанный вами .ftl-шаблон screen_page_object.ftl. Сгенерированный шаблоном код будет добавлен в качестве нового файла в указанную папку.

Пример описанного шаблона можно найти здесь.

Если в диалоге проставить галочку Open in editor, то сгенерированный файл откроется в редакторе кода.

Generate RecyclerItem Page Object

Данный Action предназначен для генерации RecyclerItem Page Object-а Kakao (наследника класса KRecyclerItem<>) из XML-файла с версткой.

При нажатии на пункт меню Generate RecyclerItem Page Object появится специальный диалог, в котором можно

  • набрать название будушего класса
  • выбрать класс-наследник com.agoda.kakao.screen.Screen, куда будет добавлен класс Page Object-а

После нажатия на кнопку Ok собранные плагином Kakao-виджеты будут проброшены в описанный вами .ftl-шаблон rv_item_page_object.ftl. Сгенерированный шаблоном код будет добавлен в качестве нового класса в указанный класс.

Пример описанного шаблона можно найти здесь.

Если в диалоге проставить галочку Open in editor, то в редакторе кода будет открыт модифицированный класс.

Collect Kakao Views Into...

Данный Action предназначен для добавления Kakao-виджетов, сгенерированных из XML-верстки, в существующий класс Page Object-а.

При нажатии на пункт меню Collect Kakao Views Into... появится диалог, в котором можно будет выбрать класс-наследник com.agoda.kakao.screen.Screen, куда будут добавлены собранные Kakao-виджеты.

После нажатия на кнопку Ok собранные плагином Kakao-виджеты будут проброшены в указанный вами класс Page Object-а.

Если в диалоге проставить галочку Open in editor, то в редакторе кода будет открыт модифицированный класс.

Live templates

Помимо Action-ов плагин добавляет два live template–а для ускорения описания Page Object-ов. Генерируемый live template-ами код можно модифицировать внутри IDEA через меню:

Preferences -> Editor -> Live templates -> Garcon

Live template - step

Данный live template можно вызвать внутри класса-наследника com.agoda.kakao.screen.Screen и внутри специального класса ru.hh.android.core_tests.page.ScreenIntentions, в котором мы описываем действия и проверки Page Object-ов.

После ввода ключевого слова step и нажатия Tab, будет подставлен шаблон для добавления новой функции описания тестового шага, согласно принятому внутри hh.ru соглашению:

fun TestContext<TestCase>.function_name() {
    step("step_description") {
        // TODO
    }
}

Live template - item

Данный live template можно вызвать внутри описания типов элементов KRecyclerView:

private val recycler = KRecyclerView({ withId(R.id.fragment_autosearch_recycler) }) {
    itemType(AutosearchScreen::ItemAutosearchList)
    // Вот здесь можно вызывать описанный live template - `item`
}

После ввода ключевого слова item и нажатия Tab, будет подставлен шаблон для добавления нового типа элемента KRecyclerView:

itemType(class_name::item_type_description)

Здесь:

  • class_name - название класса, внутри которого объявляется KRecyclerView
  • item_type_description - название класса, описывающего KRecyclerItem

Лицензия

Плагин является open-source утилитой и распостраняется под лиценцией MIT.