Помощь в редакторе и черновики тестов

Кроме значков в gutter и меню DoQA, плагин помогает прямо при наборе кода. Он пишет черновик теста по ручному кейсу, дополняет теги и метки из каталога, проверяет doqa.properties и предупреждает, если у двух тестов одинаковый внешний ID. Здесь же собраны ограничения плагина.

Внешний ID автотеста плагин называет «ключом автотеста». Это одно и то же: значение @DoqaId в Java и Kotlin, @doqa.id в pytest. Что такое внешний ID и откуда он берётся, описано на странице Автотесты.

Тест из кейса

Действие «Создать тест из кейса…» пишет в открытый файл заготовку автотеста по ручному тест-кейсу: название кейса, привязку к нему, внешний ID, предусловия и шаги комментариями. Остаётся написать сам тест.

Как создать черновик

1. Откройте файл с тестами (.java, .kt, .kts или .py) и поставьте курсор на пустую строку между тестами, туда, где нужен новый тест.
2. Откройте меню DoQA и выберите «Создать тест из кейса…». Где найти меню, описано на странице Плагины для IDE.
3. В окне «DoQA: тест из кейса» начните вводить название кейса: список обновляется по мере ввода. Стрелками выберите кейс и нажмите Enter.

Плагин вставит черновик, поставит курсор на объявление теста и покажет подсказку «Черновик из кейса #N: реализуйте шаги и включите тест. Отменить — Ctrl+Z». Вся вставка, вместе с импортами, отменяется одним Ctrl+Z.

Действие доступно в любом файле Java, Kotlin или Python, даже если тестов в нём пока нет. Если плагин не настроен, вместо окна поиска появится уведомление «DoQA не настроен: укажите адрес, токен и space.». Настройка описана на странице Плагины для IDE.

Что попадает в черновик

Разметка зависит от фреймворка. Фреймворк плагин берёт у теста под курсором, а если курсор не на тесте, то у первого теста в файле. Если тестов нет, он смотрит на импорты: по org.testng узнаёт TestNG, по org.junit.jupiter определяет JUnit 5, по org.junit.Test JUnit 4. Если по импортам не понять, пишется тест JUnit 5.

	JUnit 5	JUnit 4	TestNG	pytest
Название кейса	@DisplayName("…")	не пишется	@Test(description = "…")	@doqa.title("…")
Как тест выключен	@Disabled("Черновик из кейса #N: реализуйте шаги")	@Ignore("Черновик из кейса #N: реализуйте шаги")	enabled = false в @Test	@pytest.mark.skip(reason="Черновик из кейса #N: реализуйте шаги")
Привязка к кейсу	@DoqaCaseIds({N})	@DoqaCaseIds({N})	@DoqaCaseIds({N})	@doqa.case_ids(N)
Внешний ID	@DoqaId("<класс>.<метод>")	@DoqaId("<класс>.<метод>")	@DoqaId("<класс>.<метод>")	@doqa.id("<модуль>.<функция>")
Имя	транслитерация названия	транслитерация названия	транслитерация названия	test_ + транслитерация через _

В Kotlin разметка та же, что в Java, с двумя отличиями: привязка пишется без фигурных скобок, @DoqaCaseIds(N), а именем функции становится само название кейса в обратных кавычках, например fun `Оплата картой с 3D Secure`(). Символы, которые JVM не допускает в именах (точка, двоеточие, косая черта, угловые и квадратные скобки и т. п.), заменяются пробелами.

Внешний ID в Java и Kotlin пишется всегда: класс берётся у теста под курсором или у первого теста файла, а если тестов нет, то из пакета и имени файла. В pytest @doqa.id появляется, только если плагин нашёл rootdir pytest (pytest.ini, pyproject.toml, tox.ini, setup.cfg или setup.py): без него путь модуля неизвестен, и плагин лучше не напишет ключ, чем напишет неверный. Если модуль импортирует doqa под другим именем (import doqa as dq), декораторы пишутся через это имя (@dq.id).

Если транслитерация названия совпадает с ключевым словом Java (кейс «Default», «Return»), к имени метода добавляется case: caseDefault.

В тело теста пишутся комментарии:

• Предусловия: …, если в кейсе есть предусловия;
• по строке на каждый шаг: номер, действие и через → ожидаемый результат. Многострочный шаг склеивается в одну строку;
• Шагов в кейсе нет: опишите проверку, если шагов нет.

Недостающие импорты аннотаций, а в pytest import pytest и import doqa, плагин добавляет сам.

Пример: кейс #1041 «Оплата картой с 3D Secure» в классе com.acme.PaymentTest на JUnit 5.

@Test
@DisplayName("Оплата картой с 3D Secure")
@Disabled("Черновик из кейса #1041: реализуйте шаги")
@DoqaId("com.acme.PaymentTest.oplataKartoyS3dSecure")
@DoqaCaseIds({1041})
void oplataKartoyS3dSecure() {
    // Предусловия: пользователь авторизован, в профиле сохранена карта с 3D Secure
    // 1. Открыть корзину и нажать «Оплатить» → открыта форма оплаты
    // 2. Выбрать сохранённую карту → открыта страница подтверждения банка
    // 3. Ввести код из SMS → заказ оплачен
}

Тот же кейс в pytest, в модуле tests/test_payment.py:

@pytest.mark.skip(reason="Черновик из кейса #1041: реализуйте шаги")
@doqa.title("Оплата картой с 3D Secure")
@doqa.id("tests.test_payment.test_oplata_kartoy_s_3d_secure")
@doqa.case_ids(1041)
def test_oplata_kartoy_s_3d_secure():
    # Предусловия: пользователь авторизован, в профиле сохранена карта с 3D Secure
    # 1. Открыть корзину и нажать «Оплатить» → открыта форма оплаты
    # 2. Выбрать сохранённую карту → открыта страница подтверждения банка
    # 3. Ввести код из SMS → заказ оплачен
    pass

Почему тест выключен

Пустой тест прошёл бы с первого запуска и отчитался бы в DoQA за кейс, который никто ещё не автоматизировал. Поэтому черновик выключен до тех пор, пока вы не напишете проверку. Когда тест готов, удалите @Disabled, @Ignore, enabled = false или @pytest.mark.skip.

Внешний ID фиксируется при первом прогоне

Черновик сразу получает читаемый внешний ID: полное имя теста. Если вы переименуете метод до первого прогона, поправьте и @DoqaId: значение в аннотации не обновляется само, а после первого прогона смена ключа создаст в DoQA новый автотест без истории.

Куда вставляется черновик

• Если курсор стоит на пустой строке между членами класса, черновик встаёт на неё. Пустая строка внутри метода или между аннотацией и методом не подходит.
• Иначе черновик встаёт перед следующим после курсора тестом того же класса, а если его нет, то в конец этого класса. Черновик остаётся в том же классе, вложенном или внешнем; функции Kotlin вне класса его не притягивают.
• В pytest черновик это функция модуля: он встаёт на пустую строку вне класса и функции ниже импортов, иначе в конец файла.

Пустые строки вокруг черновика плагин добавляет с учётом тех, что уже есть: одну между членами класса в Java и Kotlin, две вокруг функции в pytest.

В Java имя метода это транслитерация названия кейса в camelCase: «Оплата картой с 3D Secure» → oplataKartoyS3dSecure. Если название пустое после транслитерации, имя будет caseN, в pytest test_case_N. Если метод с таким именем в файле уже есть, к имени добавляется номер: oplataKartoyS3dSecure2, в pytest test_…_2.

Дополнение тегов и меток

Внутри строки в @DoqaTags и @DoqaLabels (в pytest в doqa.tag и doqa.label, под каким бы именем ни был импортирован модуль doqa) плагин предлагает теги и метки, которые уже есть у автотестов в каталоге пространства. Список открывается сам сразу после открывающей кавычки; в строке списка справа подписано «тег DoQA» или «метка DoQA». В @DoqaTags предлагаются только теги, в @DoqaLabels только метки. Другие варианты дополнения, например слова из файла, внутри этих аннотаций не показываются.

Список тегов и меток плагин загружает при первом дополнении и обновляет не чаще раза в 10 минут. Теги автотестов из открытых файлов добавляются в список, когда плагин обновляет их статусы. Если DoQA недоступен или в каталоге нет ни одного тега и метки, плагину нечего предложить. Чем теги отличаются от меток, описано на страницах адаптеров, например Адаптер JUnit 5.

Проверка doqa.properties

В файле doqa.properties плагин подсвечивает строки, которые JVM-адаптер DoQA прочитал бы не так, как вы ожидаете. Наведите курсор на подсвеченное место, чтобы увидеть текст предупреждения.

Что не так	Текст предупреждения
Ключ, которого адаптер не знает	«Адаптер DoQA не знает ключ «…»: он будет пропущен»
Ключ с префиксом doqa.	«В файле ключи пишутся без префикса doqa.: адаптер не узнает «…»»
Значение ссылается на переменную: ${…} или $NAME	«Ссылки на переменные в файле не раскрываются: адаптер сочтёт ключ незаданным»
Не номер из цифр в ID (spaceId, configurationId, testRunId, ciRunId)	«Нужен номер из цифр: адаптер передаст значение в DoQA как есть»
Не целое число или число вне диапазона в числовой настройке (batchSize, retries, requestTimeoutMs и др.)	«Нужно целое число: иначе адаптер возьмёт значение по умолчанию»
Непонятное значение флага (importRealtime, certValidation)	«Адаптер поймёт «…» как false: пишите true или false»
Неизвестный режим в adapterMode	«Режим: 0 или selective, 1 или existing, 2 или new»
Неизвестное значение reporting	«Варианты: auto, api, files, off; иначе сработает auto»
url без http:// или https://	«Адрес начинается с http:// или https://»
token в файле под контролем версий	«Токен в файле под контролем версий: передайте его через DOQA_TOKEN»

В строке показывается одно предупреждение: сначала проверяется ключ, потом значение. Для флагов адаптер понимает true/false, yes/no, on/off, y/n и 1/0, для adapterMode числа 0–2 и названия режимов.

Значения плагин читает так же, как адаптер: раскрывает экранирования (\uXXXX, \:), склеивает строку, продолженную обратной косой чертой, а числа разбирает как Java, поэтому 01 и +1 в adapterMode верны.

Регистр, дефисы и подчёркивания в именах ключей адаптер не различает, плагин тоже: spaceId, space_id и SPACE-ID это один ключ. Старые имена privateToken и projectId плагин считает синонимами token и spaceId. Пустое значение не проверяется.

Токен считается закоммиченным, если файл лежит в репозитории системы контроля версий, не игнорируется и уже добавлен в неё. Для файла из .gitignore предупреждения нет.

Имена ключей и значения тоже дополняются. На месте ключа плагин предлагает ключи, которых в файле ещё нет, с коротким описанием каждого. После = или : предлагаются допустимые значения: true/false для флагов, selective, existing и new для adapterMode, auto, api, files и off для reporting. Полный список ключей и их смысл есть на странице Адаптер JUnit 5.

Нужен плагин Properties

Проверка и дополнение работают, только если в IDE есть плагин Properties. В IntelliJ IDEA он встроен, в других IDE его может не быть.

Повторяющийся внешний ID

Если у двух тестов одинаковый @DoqaId (в pytest @doqa.id), DoQA сочтёт их одним автотестом и смешает их прогоны. Инспекция «Повторяющийся ключ автотеста (@DoqaId, doqa.id)» находит такие повторы в открытом файле и в остальных файлах проекта и подсвечивает значение аннотации. Текст предупреждения: «Ключ «…» повторяется (…): DoQA сочтёт тесты одним автотестом». В скобках перечислены другие тесты этого файла с тем же ключом («у имяМетода») и другие файлы, где он встречается («в ИмяФайла.java»).

Чтобы исправить повтор, поставьте курсор на подсвеченное значение, нажмите Alt+Enter и выберите «DoQA: заменить на «…»». Плагин запишет вместо повторяющегося ключа читаемый: полное имя теста, например com.acme.CheckoutTest.addsItemToCart. Этого варианта нет, если у теста уже стоит его читаемый ключ: тогда поменяйте ключ у другого теста или впишите свой.

Повторы в других файлах плагин находит после того, как в фоне прочитает файлы проекта. Сразу после открытия проекта предупреждение может появиться с задержкой. Инспекция включена по умолчанию; её уровень меняется в «Settings» → «Editor» → «Inspections», группа «DoQA».

Смена ключа у существующего автотеста

Если автотест с этим ключом уже есть в DoQA, новый ключ станет новым автотестом, и история прогонов останется у старого. Меняйте ключ у того теста, который появился позже.

Ограничения

Поддерживаются Java, Kotlin и Python. Плагин понимает тесты JUnit 5, JUnit 4, TestNG и pytest, то есть те же фреймворки, для которых есть адаптеры. Тесты JUnit 3 (extends TestCase без аннотаций) плагин не видит.

Плагин читает текст файла. Он не опирается на компилятор, поэтому работает в любой IDE на платформе IntelliJ. Необычно отформатированное объявление теста плагин пропускает, а не размечает наугад.

Наследование из других файлов не видно. Тесты базового класса не показываются у наследника. Если @RunWith(Parameterized.class) или @Test на классе достались от базового класса, внешний ID, который вычислил плагин, может не совпасть с тем, что пришлёт адаптер. В таких классах закрепите @DoqaId: явный ключ плагин и адаптер читают одинаково.

В pytest плагин знает только сам файл и конфигурацию pytest. Ему не видны conftest.py, плагины pytest, pytest_generate_tests, --rootdir в командной строке, параметры из других модулей и метки allure.id базового класса из другого модуля. Не показываются тесты базового класса у наследника, тесты-лямбды (test_x = lambda: …) и алиасы (test_b = test_a). Имена сопоставляются с масками python_files, python_classes и python_functions с учётом регистра, как pytest на Linux и macOS. Значки в gutter для Python есть в PyCharm и в IDE с плагином Python; действия меню работают в любой IDE.

pytest без аргументов из каталога выше конфигурации. Если pytest.ini лежит в tests/, а pytest без аргументов запускают из корня репозитория, pytest этот файл не видит, и внешние ID у него получатся другие. Плагин показывает ID для запуска из tests/ или с аргументом (pytest tests).

Значки в gutter показывают сохранённые данные. Каталог плагин загружает в фоне при открытии файла и по действию «Обновить статусы в файле». Пока данных нет, значок показывает только то, что размечено в коде.

История прогонов, отвязка кейса и карантин требуют версии DoQA, которая принимает для них API-токен. Остальные запросы плагина сервер принимает с персональным API-токеном, а эти три на части серверов пока принимает только из веб-интерфейса. Тогда плагин не станет говорить, что токен недействителен, и не предложит открыть настройки, а покажет сообщение:

Сервер DoQA пока не принимает API-токен для истории прогонов: эта возможность появится после обновления DoQA

Для отвязки кейса и карантина в сообщении вместо истории прогонов названо само действие. Токен менять не нужно: всё остальное в плагине работает. Когда сервер обновят, эти действия заработают без перенастройки плагина. На совсем старых версиях DoQA история может показать падение без стека.

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

Дополнение тегов и меток видит первые 200 автотестов пространства. Теги и метки, которые есть только у автотестов дальше в каталоге, предлагаются, лишь если эти автотесты уже встречались плагину в открытых файлах.

Поиск кейсов ограничен. Поиск останавливается на 50 кейсах. Если нашлось больше, внизу окна появится «Показаны не все совпадения — уточните запрос».

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

Пока нет: проверки «кейс устарел» и окна с деревом покрытия.

Смотрите также

• Плагины для IDE: установка плагина, токен и выбор пространства
• Работа с тестами в IntelliJ: значки в gutter, привязка кейса, закрепление @DoqaId, история прогонов
• Автотесты: что такое внешний ID и как DoQA опознаёт автотест
• Адаптеры для тестовых фреймворков: разметка, которую пишет и читает плагин
• Каталог автотестов: откуда берутся теги, метки и статусы