Уточнение описания элемента

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

Когда это нужно

Функция уточнения описания особенно полезна в двух случаях. Первый — когда тест падает с ошибкой «элемент не найден». Это означает, что система не смогла обнаружить элемент по текущему описанию на странице. Второй случай — когда тест выполнился, но взаимодействие произошло не с тем элементом, который вы ожидали. Например, вместо кнопки «Сохранить» в форме система нажала похожую кнопку в другой части интерфейса.

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

Открытие режима описания

Для работы с описаниями элементов сначала откройте форму одиночного запуска шага — тот самый режим, где вы можете проверить выполнение отдельного шага теста. В дебаг режиме над скриншотом появится кнопка «Define Element». Нажатие на эту кнопку переключит интерфейс в специальный режим описания элемента.

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

Выбор цвета выделения

Перед тем как начать выделять элемент, выберите цвет рамки из трёх доступных вариантов: красный, синий или зелёный. Выбор цвета важен для контрастности — если элемент находится на красном фоне, красная рамка будет плохо видна, и вам будет сложно точно выделить область. В таком случае используйте синий или зелёный цвет. По умолчанию выбран красный цвет, но вы можете переключиться на любой другой в любой момент.

Цвет рамки также влияет на то, как система видит выделенную область — она учитывает контрастность выделения относительно интерфейса, что может повысить точность описания.

Выделение элемента

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

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

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

Если вы выделили неточно или хотите попробовать другую область, нажмите кнопку «Clear Selection» — текущее выделение исчезнет, и вы сможете выделить элемент заново.

Режим размышлений

В верхней части интерфейса, в разделе «Request Options», находится переключатель «Thinking Mode». Когда он включён, платформа использует внутреннее «размышление» перед тем, как сгенерировать описание. Это означает, что система сначала анализирует контекст элемента, его положение на странице, окружающие элементы, и только потом формирует итоговое описание.

Режим размышлений генерирует более подробные описания. Для сложных элементов или элементов без явного текста (иконки, кнопки с символами) это может дать более точный результат. Однако для простых элементов излишняя детализация может снизить надёжность поиска. Режим незначительно увеличивает время обработки запроса. Попробуйте оба варианта и выберите тот, который лучше работает для вашего элемента.

Получение описания

Когда элемент выделен, кнопка «Get Description» становится активной. Нажмите её, чтобы запросить описание элемента.

Результат описания

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

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

Копирование и использование описания

Рядом с полученным описанием находится кнопка «Copy description». Нажмите её, чтобы скопировать описание в буфер обмена.

Вставьте скопированное описание в поле редактирования шага. Описание можно использовать как есть, или при необходимости немного отредактировать для большей ясности.

Проверка описания

После того как вы вставили описание в шаг, рекомендуется проверить, правильно ли система его интерпретирует. Для этого нажмите кнопку «Check» в форме одиночного запуска шага.

При нажатии на «Check» произойдёт несколько вещей автоматически. Форма описания элемента закроется, режим выделения сбросится, и вы вернётесь в обычный режим проверки. На экране отобразится аннотированный скриншот с точкой или областью, где система нашла элемент по вашему описанию, а также плашка с координатами и временем обработки.

Это позволяет визуально убедиться, что описание работает правильно и система находит именно тот элемент, который вам нужен. Если координаты совпадают с вашими ожиданиями — отлично, можно сохранить и перезапустить тест-кейс. Если нет — попробуйте уточнить описание или вернуться в режим «Define Element» и выделить область иначе.

Повторное выделение

Если первое описание не подошло или вы хотите попробовать описать элемент по-другому, не нужно закрывать дебаг режим. Просто еще раз нажмите на кнопку «Define Element», выделите новую область на скриншоте (или ту же самую, но с другим цветом рамки для наглядности), и снова нажмите «Get Description».

Можно экспериментировать с разными границами выделения — иногда небольшое изменение области даёт более точное или более универсальное описание.

Переключение между шагами

Платформа сохраняет состояние дебаг режима для каждого шага, поэтому вы можете свободно переключаться между шагами, не теряя прогресс. Когда вы открываете дебаг режим для одного шага, а затем переходите к другому, состояние первого шага сохранится.

Это работает и для режима описания элементов — вы можете находиться в режиме «Define Element» для одного шага, переключиться на дебаг режим другого шага, а затем вернуться обратно. Ваше выделение и полученные описания останутся на месте.

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

Что делать при ошибках

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

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

Если ошибка повторяется, попробуйте включить режим «Thinking Mode», если он был выключен, или измените цвет выделения — иногда это помогает модели лучше распознать элемент.

Технические ограничения

Минимальный размер выделяемой области — 10 на 10 пикселей. Если вы попытаетесь выделить область меньше, кнопка «Get Description» останется неактивной. Также убедитесь, что выделение полностью находится внутри границ скриншота.

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

Советы по эффективному использованию

Чтобы получать максимально точные описания, старайтесь выделять элемент с небольшим отступом — захватывайте сам элемент, но не слишком много пустого пространства вокруг. Если элемент имеет подпись или иконку, включите их в выделение.

Для кнопок и ссылок выделяйте всю кликабельную область целиком. Для полей ввода выделяйте только само поле, куда нужно ввести текст, без захвата меток и лейблов.

Если элемент расположен в списке или таблице, выделяйте только сам элемент, а не строку или ячейку целиком, если это возможно. Однако если элемент уникален только в контексте строки (например, кнопка «Удалить» в третьей строке таблицы), можно выделить область шире, чтобы захватить контекст.

Помните, что платформа описывает всю выделенную область и может использовать окружение для более точного описания. Если вы хотите получить описание, которое включает контекст (например, «кнопка под заголовком» или «поле справа от метки»), выделите область так, чтобы окружение было достаточно характерным и помогало однозначно идентифицировать нужное место и не попадало в саму область.