Тема
Помощь в редакторе и черновики тестов
Кроме значков в gutter и меню DoQA, плагин помогает прямо при наборе кода. Он пишет черновик теста по ручному кейсу, дополняет теги и метки из каталога, проверяет doqa.properties и предупреждает, если у двух тестов одинаковый внешний ID. Здесь же собраны ограничения плагина.
Внешний ID автотеста плагин называет «ключом автотеста». Это одно и то же: значение @DoqaId в Java и Kotlin, @doqa.id в pytest, ключ id в метаданных doqa.test в Jest. Что такое внешний ID и откуда он берётся, описано на странице Автотесты.
Тест из кейса
Действие «Создать тест из кейса…» пишет в открытый файл заготовку автотеста по ручному тест-кейсу: название кейса, привязку к нему, внешний ID, предусловия и шаги комментариями. Остаётся написать сам тест.
Как создать черновик
- Откройте файл с тестами (
.java,.kt,.kts,.pyили файл JavaScript и TypeScript с тестами Jest) и поставьте курсор на пустую строку между тестами, туда, где нужен новый тест. - Откройте меню DoQA и выберите «Создать тест из кейса…». Где найти меню, описано на странице Плагины для IDE.
- В окне «DoQA: тест из кейса» начните вводить название кейса: список обновляется по мере ввода. Стрелками выберите кейс и нажмите Enter.
Плагин вставит черновик, поставит курсор на объявление теста и покажет подсказку «Черновик из кейса #N: реализуйте шаги и включите тест. Отменить — Ctrl+Z». Вся вставка, вместе с импортами, отменяется одним Ctrl+Z.
Действие доступно в любом файле Java, Kotlin или Python, даже если тестов в нём пока нет, а также в файлах Jest. Если плагин не настроен, вместо окна поиска появится уведомление «DoQA не настроен: укажите адрес, токен и space.». Настройка описана на странице Плагины для IDE.

Что попадает в черновик
Разметка зависит от фреймворка. Фреймворк плагин берёт у теста под курсором, а если курсор не на тесте, то у первого теста в файле. Если тестов нет, он смотрит на импорты: по org.testng узнаёт TestNG, по org.junit.jupiter JUnit 5, по org.junit.Test JUnit 4. Если по импортам не понять, пишется тест JUnit 5. В файлах .py всегда пишется тест pytest, в файлах JavaScript и TypeScript тест Jest.
| JUnit 5 | JUnit 4 | TestNG | pytest | Jest | |
|---|---|---|---|---|---|
| Название кейса | @DisplayName("…") | не пишется | @Test(description = "…") | @doqa.title("…") | название теста: doqa.test.skip('…', …) |
| Как тест выключен | @Disabled("Черновик из кейса #N: реализуйте шаги") | @Ignore("Черновик из кейса #N: реализуйте шаги") | enabled = false в @Test | @pytest.mark.skip(reason="Черновик из кейса #N: реализуйте шаги") | doqa.test.skip и комментарий // Черновик из кейса #N: реализуйте шаги |
| Привязка к кейсу | @DoqaCaseIds({N}) | @DoqaCaseIds({N}) | @DoqaCaseIds({N}) | @doqa.case_ids(N) | caseIds: [N] |
| Внешний ID | @DoqaId("<класс>.<метод>") | @DoqaId("<класс>.<метод>") | @DoqaId("<класс>.<метод>") | @doqa.id("<модуль>.<функция>") | id: '<файл> > <describe> > <название>' |
| Имя | транслитерация названия | транслитерация названия | транслитерация названия | 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).
В Jest черновик это вызов doqa.test.skip с метаданными id и caseIds. Название теста это название кейса без транслитерации. Внешний ID это читаемый ключ Jest: путь файла, цепочка describe и название. Если путь файла в проекте Jest или цепочку describe определить нельзя (например, не найден конфиг Jest), плагин пишет только caseIds, без id. Если doqa в файле ещё не импортирован, плагин добавит импорт в стиле файла: import { doqa } from '@doqa-tms/jest'; или const { doqa } = require('@doqa-tms/jest');. Если имя doqa в файле занято чем-то другим, адаптер импортируется как doqaTms.
Если транслитерация названия совпадает с ключевым словом Java (кейс «Default», «Return»), к имени метода добавляется case: caseDefault.
В тело теста пишутся комментарии:
Предусловия: …, если в кейсе есть предусловия;- по строке на каждый шаг: номер, действие и через
→ожидаемый результат. Многострочный шаг склеивается в одну строку; Шагов в кейсе нет: опишите проверку, если шагов нет.
Недостающие импорты аннотаций, а в pytest import pytest и import doqa, плагин добавляет сам.
Пример: кейс #1041 «Оплата картой с 3D Secure» в классе com.acme.PaymentTest на JUnit 5.
java
@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:
python
@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Тот же кейс в Jest, в блоке describe('Оплата') файла tests/payment.test.js:
js
describe('Оплата', () => {
doqa.test.skip('Оплата картой с 3D Secure', { id: 'tests.payment > Оплата > Оплата картой с 3D Secure', caseIds: [1041] }, () => {
// Черновик из кейса #1041: реализуйте шаги
// Предусловия: пользователь авторизован, в профиле сохранена карта с 3D Secure
// 1. Открыть корзину и нажать «Оплатить» → открыта форма оплаты
// 2. Выбрать сохранённую карту → открыта страница подтверждения банка
// 3. Ввести код из SMS → заказ оплачен
});
});Почему тест выключен
Пустой тест прошёл бы с первого запуска и отчитался бы в DoQA за кейс, который никто ещё не автоматизировал. Поэтому черновик выключен до тех пор, пока вы не напишете проверку. Когда тест готов, удалите @Disabled, @Ignore, enabled = false, @pytest.mark.skip или .skip у doqa.test.skip.
Внешний ID фиксируется при первом прогоне
Черновик сразу получает читаемый внешний ID: полное имя теста. Если вы переименуете метод до первого прогона, поправьте и @DoqaId (в Jest id): значение в аннотации не обновляется само, а после первого прогона смена ключа создаст в DoQA новый автотест без истории.
Куда вставляется черновик
Если курсор стоит на пустой строке между членами класса, черновик встаёт на неё. Пустая строка внутри метода или между аннотацией и методом не подходит.
Иначе черновик встаёт перед следующим после курсора тестом того же класса, а если его нет, то в конец этого класса. Черновик остаётся в том же классе, вложенном или внешнем; функции Kotlin вне класса его не притягивают.
В pytest черновик это функция модуля: он встаёт на пустую строку вне класса и функции ниже импортов, иначе в конец файла.
В Jest черновик встаёт в блок
describe, в котором стоит курсор: на пустую строку между тестами самого блока (пустая строка внутри объекта, условия, функции или многострочной строки не подходит), иначе перед следующим тестом этого блока, иначе перед закрывающей скобкой блока. Если курсор внеdescribe, черновик встаёт на пустую строку под курсором ниже импортов, иначе перед следующим тестом верхнего уровня, иначе в конец файла. Внутрь теста черновик не попадает.
Пустые строки вокруг черновика плагин добавляет с учётом тех, что уже есть: одну между членами класса в Java и Kotlin, две вокруг функции в pytest, одну между тестами в Jest.
В Java имя метода это транслитерация названия кейса в camelCase: «Оплата картой с 3D Secure» → oplataKartoyS3dSecure. Если название пустое после транслитерации, имя будет caseN, в pytest test_case_N. Если метод с таким именем в файле уже есть, к имени добавляется номер: oplataKartoyS3dSecure2, в pytest test_…_2. В Jest название теста это название кейса; если в блоке уже есть тест с таким названием, к нему добавляется номер в скобках: Оплата картой с 3D Secure (2).
Дополнение тегов и меток
Внутри строки в @DoqaTags и @DoqaLabels (в pytest в doqa.tag и doqa.label, под каким бы именем ни был импортирован модуль doqa, в Jest в массивах tags: [...] и labels: [...] метаданных doqa.test и doqa.metadata) плагин предлагает теги и метки, которые уже есть у автотестов в каталоге пространства. Список открывается сам сразу после открывающей кавычки; в строке списка справа подписано «тег DoQA» или «метка DoQA». В @DoqaTags и tags предлагаются только теги, в @DoqaLabels и labels только метки. В Jest дополнение работает только в файле, который импортирует doqa из @doqa-tms/jest: массив tags: [ встречается и в коде, не связанном с DoQA. Другие варианты дополнения, например слова из файла, внутри этих аннотаций не показываются.

Список тегов и меток плагин загружает при первом дополнении и обновляет не чаще раза в 10 минут. Теги автотестов из открытых файлов добавляются в список, когда плагин обновляет их статусы. Если DoQA недоступен или в каталоге нет ни одного тега и метки, плагину нечего предложить. Чем теги отличаются от меток, описано на страницах адаптеров, например Адаптер JUnit 5.
Проверка doqa.properties
В файле doqa.properties плагин подсвечивает строки, которые адаптер DoQA прочитал бы не так, как вы ожидаете. Плагин знает ключи JVM-адаптеров и адаптера Jest @doqa-tms/jest. Наведите курсор на подсвеченное место, чтобы увидеть текст предупреждения.

| Что не так | Текст предупреждения |
|---|---|
| Ключ, которого адаптер не знает | «Адаптер 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» |
Неизвестное значение executionOrder | «Варианты: jest или plan; иначе сработает порядок Jest» |
url без http:// или https:// | «Адрес начинается с http:// или https://» |
token в файле под контролем версий | «Токен в файле под контролем версий: передайте его через DOQA_TOKEN» |
В строке показывается одно предупреждение: сначала проверяется ключ, потом значение. Для флагов адаптер понимает true/false, yes/no, on/off, y/n и 1/0, для adapterMode числа 0–2 и названия режимов, для executionOrder значения jest и plan в любом регистре и с пробелами по краям, как их читает адаптер Jest.
Значения плагин читает так же, как адаптер: раскрывает экранирования (\uXXXX, \:), склеивает строку, продолженную обратной косой чертой, а числа разбирает как Java, поэтому 01 и +1 в adapterMode верны.
Регистр, дефисы и подчёркивания в именах ключей адаптер не различает, плагин тоже: spaceId, space_id и SPACE-ID это один ключ. Старые имена privateToken и projectId плагин считает синонимами token и spaceId. Пустое значение не проверяется.
Два ключа нужны только адаптеру Jest:
| Ключ | Что задаёт | Что проверяет плагин |
|---|---|---|
projectName | название проекта Jest. Оно входит в ключ автотеста, и плагин берёт его отсюда, если оно не задано во втором аргументе withDoqa | как любой текст: только ссылки на переменные |
executionOrder | порядок тестов: jest (по умолчанию) или plan, в порядке плана DoQA | значение jest или plan |
Эти ключи плагин не подсвечивает и в doqa.properties проектов на JUnit, TestNG и pytest: проверка общая для всех адаптеров.

Токен считается закоммиченным, если файл лежит в репозитории системы контроля версий, не игнорируется и уже добавлен в неё. Для файла из .gitignore предупреждения нет.
Имена ключей и значения тоже дополняются. На месте ключа плагин предлагает ключи, которых в файле ещё нет, с коротким описанием каждого. После = или : предлагаются допустимые значения: true/false для флагов, selective, existing и new для adapterMode, auto, api, files и off для reporting, jest и plan для executionOrder. Полный список ключей и их смысл есть на странице Адаптер JUnit 5.
Нужен плагин Properties
Проверка и дополнение работают, только если в IDE есть плагин Properties. В IntelliJ IDEA он встроен, в других IDE его может не быть.
Повторяющийся внешний ID
Если у двух тестов одинаковый @DoqaId (в pytest @doqa.id, в Jest id в метаданных doqa.test), DoQA сочтёт их одним автотестом и смешает их прогоны. Инспекция «Повторяющийся ключ автотеста (@DoqaId, doqa.id)» находит такие повторы в открытом файле и в остальных файлах проекта и подсвечивает значение аннотации. Текст предупреждения: «Ключ «…» повторяется (…): DoQA сочтёт тесты одним автотестом». В скобках перечислены другие тесты этого файла с тем же ключом («у имяМетода») и другие файлы, где он встречается («в ИмяФайла.java»).

Чтобы исправить повтор, поставьте курсор на подсвеченное значение, нажмите Alt+Enter и выберите «DoQA: заменить на «…»». Плагин запишет вместо повторяющегося ключа читаемый: полное имя теста, например com.acme.CheckoutTest.addsItemToCart, в Jest tests.cart > Корзина > добавляет товар. Этого варианта нет, если у теста уже стоит его читаемый ключ: тогда поменяйте ключ у другого теста или впишите свой.
Повторы в других файлах плагин находит после того, как в фоне прочитает файлы проекта. Сразу после открытия проекта предупреждение может появиться с задержкой. Из файлов JavaScript и TypeScript заранее читаются только тестовые файлы по шаблонам Jest по умолчанию (__tests__, *.test.*, *.spec.*). Тесты из файлов с другими именами, например по своему testMatch, участвуют в проверке, когда такой файл открыт в редакторе. Инспекция включена по умолчанию; её уровень меняется в «Settings» → «Editor» → «Inspections», группа «DoQA».
Смена ключа у существующего автотеста
Если автотест с этим ключом уже есть в DoQA, новый ключ станет новым автотестом, и история прогонов останется у старого. Меняйте ключ у того теста, который появился позже.
Ограничения
Поддерживаются Java, Kotlin, Python, JavaScript и TypeScript. Плагин понимает тесты JUnit 5, JUnit 4, TestNG, pytest и Jest, то есть те же фреймворки, для которых есть адаптеры (для Jest это адаптер @doqa-tms/jest, см. README адаптера Jest). Другие фреймворки JavaScript, например Vitest или Mocha, плагин не видит. Тесты 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.
В Jest плагин знает только сам файл и ближайший конфиг Jest. Ему не видны переменные окружения (DOQA_PROJECT_NAME, DOQA_CONFIG), флаги командной строки Jest (--rootDir, --config, --selectProjects) и конфиг выше ближайшего. Файл doqa.properties плагин ищет в каталоге конфига, как будто Jest запускают оттуда. Вызов doqa.metadata({ id }) или doqa.metadata({ caseIds }) из функции другого модуля ему тоже не виден. Если название проекта задаётся переменной DOQA_PROJECT_NAME, хэш у плагина и у адаптера разойдётся: задайте projectName во втором аргументе withDoqa или закрепите id. Значки в gutter для JavaScript и TypeScript есть в IntelliJ IDEA Ultimate, WebStorm и других IDE с плагином JavaScript; действия меню работают в любой IDE.
Кейсы из doqa.metadata в Jest. Вызов doqa.metadata({ caseIds }) плагин засчитывает в любом месте верхнего уровня тела теста. Если тест упадёт раньше вызова, этот результат придёт в DoQA без кейсов; сам плагин всегда ставит вызов первой строкой. У пропущенного теста (xit, .skip) плагин показывает кейсы из doqa.metadata, хотя адаптер их не получит, пока тест пропущен. Вызов doqa.metadata без caseIds (например, только с title) плагин не дополняет, а вставляет рядом новый.
В Jest плагин отказывается там, где ID неоднозначен. Обычный test.each без плейсхолдеров в названии, метаданные вида { id, ...CONST }, id, заданный выражением, константа метаданных или конфига, которую меняют после объявления (даже если меняют другой ключ), doqa.test.each с подстановкой в названии и данными из переменной и doqa.metadata({ id }) в любом хуке (даже в beforeAll, где id на деле не меняется) плагин показывает без ключа, хотя адаптер в этих случаях выдал бы один ID. Причины перечислены в разделе Когда плагин не вычисляет ID.
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, история прогонов, тесты Jest - Автотесты: что такое внешний ID и как DoQA опознаёт автотест
- Адаптеры для тестовых фреймворков: разметка, которую пишет и читает плагин
- Каталог автотестов: откуда берутся теги, метки и статусы