Тема
Работа с тестами в IntelliJ
Плагин DoQA показывает прямо в редакторе, как автотест прошёл в последнем прогоне, насколько он стабилен и к какому тест-кейсу привязан. Из IDE можно привязать и отвязать кейс, закрепить внешний ID, посмотреть историю прогонов со стеком падения и поставить автотест в карантин. Эта страница о работе с тестами; установка и настройка подключения описаны на странице Плагины для IDE, а подсказки при наборе кода описаны на странице Помощь в редакторе и черновики тестов.

Значки в gutter
У каждого тестового метода слева от объявления стоит значок DoQA. Он показывает исход последнего прогона автотеста в DoQA:
| Значок | Что значит |
|---|---|
| зелёная галочка теста | последний прогон пройден |
| оранжевый кружок с крестиком | последний прогон провален |
| красный кружок с «!» | последний прогон сломан или заблокирован |
| значок пропуска | последний прогон пропущен |
| пауза | автотест в карантине, исход последнего прогона значок не показывает |
| значок неизвестного результата | DoQA вернул исход, которого плагин не знает |
К основному значку добавляются пометки:
- предупреждающий знак: DoQA считает автотест нестабильным (у автотеста в карантине пометки нет);
- маленькая стрелка: к тесту привязан кейс.
Тест, который ещё ни разу не запускался или которого нет в каталоге, показывает только привязку: галочку, если кейс привязан, и значок ⓘ, если не привязан.
Состояния стабильности и карантин считает DoQA, а не плагин: как они определяются, описано на странице Нестабильные тесты и карантин.
Подсказка значка
При наведении на значок появляется подсказка:
| Строка | Пример и смысл |
|---|---|
| первые строки | связанные кейсы, см. Связанные кейсы в подсказке |
| «Последний прогон:» | исход, дата и время, ветка; «новый сбой», если до этого тест не падал. У теста без прогонов: «Ещё не запускался» |
| «Стабильность:» | доля пройденных прогонов, например «100% из 21 прогона». У нестабильного и других особых автотестов через «·» добавляется состояние, см. Статусы как в DoQA |
| «История, от старых к новым:» | полоса последних прогонов, по значку на прогон; строкой ниже расшифровка значков, см. Статусы как в DoQA |
| «В карантине: падения не влияют на гейт» | только у автотеста в карантине |
| «Ключ автотеста:» | внешний ID теста; если плагин не может его вычислить, вместо него «вычислит адаптер» и причина в скобках |
| «Автотест в DoQA: #…» | номер автотеста в каталоге |
| карточка кейса | номер и название первого привязанного кейса, его статус, приоритет и число шагов; «Ещё кейсов: N», если привязано несколько |
| «Клик — меню DoQA» | по клику на значок открывается меню действий над этим тестом |

Связанные кейсы в подсказке
Первая строка подсказки говорит, какие кейсы связаны с автотестом в DoQA. Если связи в DoQA и ID в @DoqaCaseIds (doqa.case_ids в pytest) расходятся, плагин показывает и то и другое:
| Ситуация | Что написано |
|---|---|
| в DoQA есть связи | «ID связанных кейсов в DoQA: 15, 16» |
связей в DoQA нет, но ID кейсов стоят в @DoqaCaseIds | «ID кейсов в @DoqaCaseIds: 15 (в DoQA ещё не привязаны, привяжутся при следующем прогоне)» |
| связи есть и там и там, но ID различаются | первая строка про DoQA, ниже отдельной строкой «В @DoqaCaseIds: …» |
| связей нет нигде | «Связанных кейсов в DoQA нет» |
Кейсы из @DoqaCaseIds DoQA привяжет сам при следующем прогоне теста: адаптер передаёт их вместе с результатом. Кейсы, которых нет в пространстве, не привязываются и не создаются.
В тестах Jest вместо @DoqaCaseIds в этих строках написано, где стоят ID: caseIds (метаданные doqa.test), doqa.metadata (вызов в теле теста) или caseIds и doqa.metadata, например «ID кейсов в doqa.metadata: 2401». Подробнее в разделе Кейс в doqa.metadata.
Если плагин не может сопоставить тест с автотестом в DoQA, ниже идёт отдельная строка с причиной:
- «Автотеста ещё нет в каталоге DoQA: он появится после первого прогона»;
- «Каталог DoQA ещё не проверен: связи в DoQA неизвестны», например пока каталог грузится или не выбрано пространство;
- «Ключ автотеста вычислит адаптер при запуске, поэтому связи в DoQA не проверить»;
- «Ключ с плейсхолдером: у каждого набора параметров свой автотест, связи в DoQA не проверить», если в ключе есть плейсхолдер (
@DoqaId("LOGIN-{browser}")).
Пока каталог не проверен, первая строка говорит только о коде: «ID кейсов в @DoqaCaseIds: 15» или «В @DoqaCaseIds кейсов нет». Про связи в DoQA плагин в этом случае ничего не утверждает.
Статусы как в DoQA
Исходы прогонов и состояния автотеста плагин называет так же, как веб-интерфейс DoQA.
Исход прогона в строке «Последний прогон:» и в истории прогонов: «Пройден», «Провален», «Сломан», «Заблокирован», «Пропущен».
Полоса «История, от старых к новым:» повторяет колонку «История» в каталоге автотестов: один значок на прогон, слева старые, справа новые.
| Значок | Прогон |
|---|---|
✓ | Пройден |
✗ | Провален |
! | Сломан или Заблокирован |
· | Пропущен; сюда же попадают прогоны, которые не начинались |
Под полосой плагин расшифровывает только те значки, которые в ней есть, например «✓ Пройден, ✗ Провален». DoQA отдаёт полосу одной отметкой на сломанные и заблокированные прогоны, поэтому точный статус ! плагин называет, только если такая отметка одна и стоит у последнего прогона: «Сломан» или «Заблокирован». Для остальных смотрите историю прогонов.
Состояние автотеста после «·» в строке «Стабильность:»: «Нестабильный», «Сломан», «В карантине», «Отключён», «Исправлен». У стабильного автотеста состояние не пишется.
Откуда берутся данные
Значки читают данные только из кэша плагина и сами в сеть не обращаются. Кэш наполняется:
- при открытии файла с тестами;
- по действию «Обновить статусы в файле»;
- в фоне, когда в файле появляется тест, которого кэш ещё не знает: новый тест или только что закреплённый ключ. Запрос уходит после короткой паузы в наборе.
Автоматическое обновление (при открытии файла и в фоне) работает, пока в настройках включено «Подтягивать статусы при открытии файла с тестами». Действие «Обновить статусы в файле» работает всегда.
Кэш хранится на диске, отдельно для каждого сервера и пространства, и переживает правку файла и перезапуск IDE. Если DoQA недоступен, значки показывают последние известные данные, а в подсказке появляется строка «DoQA недоступен: данные от ДД.ММ.ГГГГ ЧЧ:ММ».
Статус не обновился
Если результат нового прогона уже виден в DoQA, а значок старый, выполните «Обновить статусы в файле». Плагин перечитает каталог для всех тестов файла и покажет подсказку «Статусы обновлены: тестов в файле — N».
Где открыть меню DoQA
Все действия собраны в меню DoQA: кнопка в главном тулбаре, Ctrl+Alt+Shift+D, «Tools» → «DoQA» и контекстное меню редактора, подробнее в разделе Где найти действия. Действия над одним тестом есть ещё в двух местах:
| Где | Что открывается |
|---|---|
| клик по значку в gutter | действия над этим тестом, курсор переходит на тест |
| Alt+Enter на аннотациях или объявлении теста | до трёх действий: «DoQA: привязать ручной кейс»; «DoQA: закрепить ключ автотеста», если у теста ещё нет @DoqaId; «DoQA: открыть привязанный кейс», если кейс привязан |
Действия над одним тестом работают с тестом под курсором: курсор может стоять на аннотациях, объявлении или в теле метода. Если курсор вне теста, плагин подсказывает «Поставьте курсор в тестовый метод.».


Действия
| Действие | Что делает | Когда доступно |
|---|---|---|
| «Статус теста» | подсказка у курсора: связанные кейсы, фреймворк, ключ автотеста, автотест в каталоге, последний прогон, стабильность | открыт файл с тестами |
| «История прогонов и падения» | окно с последними прогонами и стеком падения, см. История прогонов | курсор в тесте |
| «Карточка кейса» | шаги и ожидаемый результат привязанного кейса во всплывающем окне | к тесту привязан кейс |
| «Открыть кейс в DoQA» | привязанный кейс в браузере | к тесту привязан кейс |
| «Привязать ручной кейс к тесту» | поиск кейса, аннотация @DoqaCaseIds в коде и связь в DoQA | открыт файл с тестами |
| «Отвязать кейс…» | снимает связь в DoQA и убирает ID кейса из аннотации | к тесту привязан кейс |
| «Закрепить @DoqaId у теста» | записывает внешний ID в код, см. Закрепление @DoqaId | открыт файл с тестами |
| «Поместить в карантин…» / «Снять с карантина» | ставит автотест в карантин или снимает его; подпись зависит от текущего состояния | курсор в тесте |
| «Скопировать ключ автотеста» | копирует внешний ID теста в буфер обмена | открыт файл с тестами |
| «Создать тест из кейса…» | черновик теста по ручному кейсу, см. Тест из кейса | открыт файл с тестами |
| «Закрепить @DoqaId во всём файле» | закрепляет ключи у всех тестов файла без @DoqaId | в файле есть тесты |
| «Обновить статусы в файле» | перечитывает каталог для тестов открытого файла | открыт файл с тестами |
| «Каталог автотестов» | список автотестов пространства, см. Каталог автотестов | всегда |
| «Настройки DoQA…» | страница «Settings» → «Tools» → «DoQA» | всегда |
В файлах pytest вместо @DoqaId и @DoqaCaseIds плагин пишет декораторы @doqa.id и @doqa.case_ids, и названия действий меняются: «Закрепить @doqa.id у теста», «Закрепить @doqa.id во всём файле». В тестах Jest плагин пишет ключи id и caseIds в метаданные doqa.test (кейс иногда вызовом doqa.metadata в теле теста), а действия называются «Закрепить id у теста» и «Закрепить id во всём файле», см. Тесты Jest.
Результаты и ошибки приходят уведомлениями IDE, а ответы о конкретном месте в коде показываются подсказкой у курсора. Модальный диалог появляется только там, где нужен выбор или подтверждение. Правки кода, которые делает плагин, отменяются одним Ctrl+Z.
Плагин не настроен
Если адрес DoQA или пространство не заданы, действия, которым нужен сервер, показывают уведомление «DoQA не настроен: укажите адрес, токен и space.» с кнопкой «Открыть настройки». Настройка описана на странице Плагины для IDE.
Статус теста
«Статус теста» сначала перечитывает каталог, а затем показывает у курсора подсказку:
- первые строки: связанные кейсы, как в подсказке значка, с теми же пояснениями, если автотест не найден в каталоге или ключ не вычисляется;
- «Фреймворк:» со значением JUnit 5, JUnit 4, TestNG, pytest или Jest;
- «Ключ автотеста:» с внешним ID; если он не вычисляется, ниже «Ключ не вычислен:» с причиной;
- «Автотест в DoQA:» с номером и названием автотеста, если он есть в каталоге; если его ещё нет, об этом говорит строка «Автотеста ещё нет в каталоге DoQA: он появится после первого прогона» среди первых строк;
- «Последний прогон:» и «Стабильность:», если прогоны были.
Если для файла не выбрано пространство, вместо строки об автотесте стоит «Space DoQA для этого файла не выбран в настройках: каталог не проверен».
Привязка кейса
- Поставьте курсор в тест и выберите «Привязать ручной кейс к тесту» (в Alt+Enter это «DoQA: привязать ручной кейс»).
- Откроется попап «DoQA: кейс для <имя метода>». Сразу, без ввода, в нём появляются кейсы из верхних папок дерева. Сверху стоят кейсы, похожие на тест по названию: они выделены жирным и помечены «похож», внизу подсказка «Сверху — похожие на тест. Enter — привязать, Esc — закрыть».
- Начните вводить название: список обновляется по мере ввода. Стрелки двигают выбор.
- Нажмите Enter или дважды щёлкните по кейсу.
Плагин добавляет ID кейса в @DoqaCaseIds над тестом (импорт дописывается сам, существующие ID сохраняются) и создаёт связь в DoQA. Появляется уведомление «Кейс #N «название» привязан к тесту …» с кнопкой «Открыть кейс». Привязка только добавляет связь: прежние связи теста не снимаются.

Как подбираются похожие кейсы: плагин сравнивает слова из @DisplayName, @DoqaTitle, description у TestNG и имени метода (у Jest из названия теста и title в метаданных doqa.test) со словами в названиях кейсов, с учётом окончаний. Смысла он не понимает: тест addsItemToCart не найдёт кейс «Добавление товара в корзину».
Поиск останавливается на 50 кейсах: если совпадений больше, внизу попапа появляется «Показаны не все совпадения — уточните запрос».
Что происходит с внешним ID при привязке:
- тест, которого в DoQA ещё нет, привязывается под читаемым ключом, и плагин сразу закрепляет его в
@DoqaId. В каталоге не появится автотест с хэшем вместо имени; - тест, который уже есть в каталоге, сохраняет свой ключ. Если это хэш, в уведомлении будет «Ключ автотеста — хэш: переименование теста его сменит.» и кнопка «Закрепить @DoqaId»;
- если ключ по тексту файла не вычислить, плагин попросит ввести его в диалоге «DoQA: ключ автотеста» и тоже закрепит в коде.
- у строк
eachв Jest ключ не спрашивается: кейс записывается только в код, и адаптер привяжет его к каждой строке при следующем прогоне. Так же с тестом Jest, у которого ключ не вычислен и не может быть закреплён, см. Кейс в doqa.metadata.
Карточка кейса
Карточку привязанного кейса открывает действие «Карточка кейса» или Ctrl+клик по ID в @DoqaCaseIds (doqa.case_ids в pytest). Во всплывающем окне «Кейс #N»:
- название кейса;
- статус, приоритет, статус автоматизации и путь по папкам;
- «Предусловия»;
- «Шаги» с ожидаемым результатом каждого шага («Ожидается:»);
- «Ожидаемый результат» кейса;
- ссылка «Открыть в DoQA».
Если к тесту привязано несколько кейсов, действие сначала предлагает выбрать один. Когда DoQA недоступен, показывается карточка из кэша, если плагин уже загружал её раньше.

Отвязка кейса
- Выберите «Отвязать кейс…». Если кейсов несколько, выберите нужный в списке.
- Подтвердите в диалоге: «Отвязать кейс #N «название» от теста …?». Под вопросом сказано, что будет сделано: «Связь в DoQA будет снята.» и «id уберётся из @DoqaCaseIds.».
- Нажмите «Отвязать».
ID убирается и из аннотации: иначе следующий прогон привязал бы кейс снова. В тесте Jest ID убирается из caseIds и из вызовов doqa.metadata, см. Кейс в doqa.metadata.

Кейсы на классе
Если ID кейса записан в @DoqaCaseIds на классе, для одного теста его не отвязать. Плагин подскажет: «Кейс #N указан в @DoqaCaseIds на классе: для одного теста его не отвязать. Перенесите @DoqaCaseIds на методы или уберите id с класса.»
Отвязать нельзя и последний ID из @DoqaCaseIds метода, если свои ID есть у класса: без аннотации на методе адаптер возьмёт ID класса и привяжет их к тесту. Подсказка в этом случае начинается со слов «#N — последний id в @DoqaCaseIds метода».
Читаемый ключ и закрепление @DoqaId
Если в коде нет явного внешнего ID, адаптер вычисляет его сам, чаще всего как хэш сигнатуры теста (junit5:3c9ce9…). Такой ключ меняется при переименовании теста, и DoQA заводит новый автотест без истории, см. Внешний ID. Закрепление записывает ключ в код аннотацией @DoqaId, и дальше тест можно переименовывать и переносить.
Плагин предлагает читаемый ключ, то есть полное имя теста, как в Allure: com.acme.CheckoutTest.addsItemToCart, для pytest tests.unit.test_cart.TestCart.test_adds. Он уникален там же, где уникально полное имя класса или модуля.
Сменить ключ автотеста, который DoQA уже знает, нельзя без потери истории: новый ключ означает новый автотест. Поэтому «Закрепить @DoqaId у теста» (в Alt+Enter это «DoQA: закрепить ключ автотеста») выбирает ключ так:
| Ситуация | Что делает плагин |
|---|---|
ключ уже читаемый: DOQA-123 из названия теста, ALLURE-42 из Allure | закрепляет его как есть |
| теста в DoQA ещё нет | закрепляет читаемый ключ и подсказывает «Новый тест: в DoQA его ещё нет, поэтому ключ читаемый.» |
| тест уже есть в DoQA под хэшем | спрашивает, что закрепить (см. ниже) |
| читаемый ключ уже занят другим автотестом | просит ввести другой ключ, по умолчанию предлагает <ключ>-2 |
| ключ по тексту файла не вычислить | просит ввести ключ, по умолчанию предлагает читаемый |
у теста уже есть @DoqaId | ничего не пишет, подсказка «@DoqaId уже стоит: …» |
@DoqaId стоит на классе | ничего не пишет: под ключом класса отчитываются все его тесты. Подсказка «Ключ задан на классе (…), под ним отчитываются все тесты класса. Чтобы закрепить ключ у отдельного теста, уберите @DoqaId с класса.» |
Когда тест уже есть в DoQA под хэшем, диалог «DoQA: @DoqaId» объясняет: «Тест уже есть в DoQA под ключом-хэшем (автотест #N). Читаемый ключ заведёт новый автотест: история прогонов останется у старого, привязки кейсов плагин перенесёт.» Ниже показаны оба ключа: «Читаемый ключ:» и «Текущий ключ:».
- «Сохранить историю» (выбрано по умолчанию): закрепить текущий ключ-хэш. История остаётся, но ключ нечитаемый.
- «Читаемый ключ»: закрепить читаемый ключ. Привязки кейсов плагин переносит на новый ключ и сообщает об этом уведомлением «Кейсы #… привязаны к новому ключу …. История прогонов осталась у автотеста #N. Ctrl+Z вернёт ключ в коде, но не привязки в DoQA.». Кейс в DoQA привязан к одному автотесту, поэтому у старого автотеста привязки пропадают.
- «Отмена»: ничего не менять.
Если пространство не выбрано, плагин не может проверить каталог. Тогда диалог тот же, но вопрос другой: «Каталог DoQA не проверен: плагин не настроен…», и по умолчанию выбран «Читаемый ключ».

После записи у курсора появляется подсказка «Закреплено: @DoqaId("…")» и «Отменить — Ctrl+Z».
Весь файл
«Закрепить @DoqaId во всём файле» проставляет ключи всем тестам файла без @DoqaId, у которых ключ вычисляется. Тесты класса с @DoqaId на самом классе пропускаются. Правило то же, но без вопроса по каждому тесту: тесты, которых в DoQA нет, получают читаемый ключ, а тесты с историей сохраняют текущий. Перед записью плагин один раз спрашивает подтверждение, например: «Проставить @DoqaId у 5 тест(ов): читаемый ключ — у 3 (в DoQA их ещё нет); текущий ключ — у 2 (сохраняется история прогонов).». Если каталог проверить не удалось, везде записываются текущие ключи, о чём сказано в том же диалоге.
История прогонов и падения
«История прогонов и падения» открывает окно «DoQA: история прогонов — <имя метода>» с последними 30 прогонами автотеста. Окно не модальное: его можно держать открытым рядом с кодом, пока чините тест.
- Сверху показана сводка: стабильность, состояние («Нестабильный», «Сломан» и другие, см. Статусы как в DoQA), «В карантине» и полоса последних прогонов с расшифровкой: «История: ✓✗! (✓ Пройден, ✗ Провален, ! Сломан)».
- Таблица: «Результат», «Прогон», «Когда», «Ветка», «Окружение», «Длительность». В колонке «Результат» статус прогона: «Пройден», «Провален», «Сломан», «Заблокирован» или «Пропущен». Прогон, который DoQA отметил как нестабильный, помечен «Нестабильный».
- Внизу показан выбранный прогон: заголовок с номером, исходом, временем, веткой, коммитом и окружением, затем сообщение об ошибке и стек. Строки стека ведут в код проекта. У тестов Jest ссылками становятся строки стека Node вида
tests/cart.test.js:12:5, кроме строк изnode_modules. - При открытии выбран последний проваленный или сломанный прогон.
- Кнопка «Открыть в DoQA» ведёт на автотест в веб-интерфейсе.

Если автотеста ещё нет в каталоге, плагин подскажет «Автотеста … ещё нет в DoQA: он появится после первого прогона.». Если у теста ключ с плейсхолдером (@DoqaId("LOGIN-{browser}")), у каждого набора параметров свой автотест и история для теста целиком недоступна.
Версия DoQA
История, отвязка кейса и карантин работают, только если сервер DoQA принимает для этих запросов персональный API-токен. На сервере, где это ещё не так, плагин напишет, что сервер DoQA пока не принимает API-токен для истории прогонов (отвязки, карантина) и эта возможность появится после обновления DoQA. Токен при этом в порядке, менять его не нужно. Подробнее в разделе Ограничения.
Карантин
- Выберите «Поместить в карантин…».
- В диалоге «DoQA: карантин» при желании укажите причину: «Падения автотеста в карантине не влияют на гейт качества. Причина (необязательно):».
- Нажмите «OK». У курсора появится «<имя метода> в карантине.», значок в gutter сменится на паузу.
Если автотест уже в карантине, то же действие называется «Снять с карантина» и спрашивает: «Снять … с карантина? Его падения снова будут влиять на гейт.».
Плагин не передаёт ветку: карантин ставится и снимается для автотеста целиком. Что карантин меняет и как DoQA снимает его сам, описано на странице Нестабильные тесты и карантин.

Каталог автотестов
«Каталог автотестов» показывает автотесты пространства в попапе, первые 200. В заголовке стоит «Автотесты DoQA: N», а если автотестов больше, «Автотесты DoQA: 200 из N — наберите часть имени».
- В строке показаны название автотеста, внешний ID серым (если он отличается от названия) и привязанные кейсы: «кейсы: 1041, 7» или «кейсов нет».
- Ввод текста фильтрует список по названию и внешнему ID.
- Enter открывает привязанный кейс в браузере. Если кейсов нет, копирует внешний ID и сообщает «Кейсы к автотесту не привязаны. Ключ скопирован: …».
Полный каталог с фильтрами, стабильностью и массовыми действиями есть в веб-интерфейсе, см. Каталог автотестов.

Тесты Jest
Плагин работает с тестами Jest, которые отчитываются в DoQA через адаптер @doqa-tms/jest. Отдельной страницы об адаптере в этом руководстве пока нет, всё о нём написано в README адаптера Jest.
В Jest нет аннотаций, поэтому разметка DoQA хранится в метаданных doqa.test, во втором аргументе вызова. Внешний ID это ключ id, привязка к кейсам это caseIds, теги и метки лежат в tags и labels:
js
doqa.test('добавляет товар', { id: 'CART-ADD', caseIds: [1041] }, () => {
// …
});Кейсы можно передать и вызовом doqa.metadata({ caseIds: [...] }) в теле теста: так плагин привязывает кейс к тестам, которые нельзя превратить в doqa.test, см. Кейс в doqa.metadata.
Значки в gutter у тестов Jest показывают IDE с плагином JavaScript: IntelliJ IDEA Ultimate и WebStorm. Действия меню работают в любой IDE на платформе IntelliJ.
Какие тесты видит плагин
Файлы. Плагин читает файлы .js, .cjs, .mjs, .jsx, .ts, .cts, .mts и .tsx.
Проект Jest. От каталога файла плагин поднимается вверх и берёт ближайший каталог, где лежит jest.config.js (или .ts, .mjs, .cjs, .mts, .cts, .json) либо package.json с ключом "jest". Так же конфиг выбирает Jest, если запустить его из этого каталога. Конфиг плагин читает как текст: module.exports = … или export default …, обёртку withDoqa(config, options) и константы модуля.
Тестовые файлы. Тестом считается файл, который Jest запустил бы по шаблонам по умолчанию: всё в каталоге __tests__, а также *.test.* и *.spec.*. Если в конфиге задан свой testMatch или testRegex, тестом может быть любой файл JavaScript или TypeScript. Файлы из node_modules не читаются. Если конфига нет, плагин читает только файл, который импортирует @doqa-tms/jest или @jest/globals.
Тесты. Это вызовы test и it с модификаторами .only, .skip, .concurrent, .todo, .failing и .each, а также xit, xtest, fit и doqa.test. Имя, под которым импортирован doqa, не важно: import { doqa as dq }, const { doqa } = require(…), import * as adapter. Блоки describe, xdescribe и fdescribe задают цепочку названий. Если test импортирован из другого модуля, например import { test } from 'vitest', это не тест Jest, и плагин его пропускает.
Значок в gutter стоит у строки с вызовом теста.
Внешний ID теста Jest
Плагин вычисляет внешний ID по тем же правилам, что и адаптер:
idиз метаданныхdoqa.test. Значение берётся как есть, пробелы по краям не обрезаются. Если в теле теста отдельной инструкцией стоитdoqa.metadata({ id: '…' }), адаптер берёт этотid, и плагин тоже.- Номер из названия теста:
[DOQA-123]или@DOQA:123дают ключDOQA-123. - Иначе хэш:
jest:и SHA-1 от строк, соединённых переводом строки: название проекта, путь файла, названия блоковdescribeпо порядку и название теста.
Из чего собирается хэш:
- путь файла считается от
rootDirпроекта Jest и пишется через/.rootDirэто каталог конфига или значениеrootDirиз конфига; - название проекта берётся из
projectNameво втором аргументеwithDoqa(адаптер не различает в ключе регистр,-и_, поэтому подходят иproject-name, иproject_name), затем изprojectNameв файлеdoqa.propertiesрядом с конфигом, затем изdisplayNameпроекта. Если ничего из этого не задано, строка пустая; - название теста у
doqa.test.eachэто шаблон, напримерроль %s. Поэтому все строки данныхdoqa.test.eachотносятся к одному автотесту. У обычногоtest.eachкаждая строка становится отдельным автотестом с названием, которое Jest собирает из шаблона и данных.
Внешний ID длиннее 255 символов адаптер обрезает до 255, плагин тоже.
Пример. В проекте с jest.config.js в корне и без названия проекта тест добавляет товар из блока describe('Корзина') в файле tests/cart.test.js получит ключ jest:e6b5a5d6d483742d113a6dbd93151ed704c70f2e. После переименования теста или переноса в другой блок ключ станет другим, и DoQA заведёт новый автотест. Чтобы этого не случилось, закрепите id.
Когда плагин не вычисляет ID
Если по тексту файла и конфига нельзя получить тот же ID, что вычислит адаптер при запуске, плагин ключ не показывает. В подсказке у значка вместо ключа написано «вычислит адаптер» и причина:
| Ситуация | Причина в подсказке |
|---|---|
| конфига Jest нет ни в каталоге файла, ни выше | «не найден конфиг Jest (jest.config.* или ключ «jest» в package.json), а от него зависят путь файла и название проекта в id» |
| в одном каталоге два конфига | «в одном каталоге несколько конфигов Jest: Jest не запустится, пока не останется один» |
конфиг собирается кодом: функция, импорт, spread; конфиг меняют после объявления (config.displayName = …, module.exports.rootDir = …) | «конфиг Jest собирается кодом (функция, импорт, spread): rootDir и название проекта из текста не прочитать» |
rootDir задан выражением | «rootDir в конфиге Jest задан не строковым литералом, а путь файла в id считается от него» |
projectName или displayName задан выражением, объект опций withDoqa меняют после объявления | «projectName или displayName в конфиге Jest задан не литералом, а название проекта входит в id» |
в конфиге есть список projects | «в конфиге Jest задан список projects: к какому проекту относится файл и как он называется, из текста не понять» |
обычный test.each или describe.each | «test.each или describe.each: у каждой строки данных свой автотест, название строки формирует Jest» |
номер DOQA в данных each или в шаблоне ([DOQA-%d]); у doqa.test.each с подстановкой в названии данные заданы не литералом (переменная, модуль), и номер может прийти из них | «номер DOQA в параметрах теста: у разных наборов параметров разные id» |
название теста не строка: шаблон с ${…}, склейка, переменная | «название теста задано не строковым литералом» |
название describe не строка | «название describe задано не строковым литералом» |
тест объявлен внутри функции: хелпер, цикл forEach | «тест объявлен внутри функции: в какой describe он попадёт и сколько раз, по тексту не понять» |
метаданные не объект в вызове и не константа модуля, константу меняют после объявления (META.id = …, повторное присваивание), id не строка | «метаданные doqa.test заданы не литералом объекта или id в них не строка» |
id: '' | «id в метаданных doqa.test пустой: DoQA не примет автотест без id» |
doqa.metadata({ id }) в хуке, во вспомогательной функции или под условием; doqa.metadata взят под другим именем (const { metadata } = doqa) | «id задаётся вызовом doqa.metadata в хуке, функции или условии: какой id окажется у теста, по тексту не понять» |
Для таких тестов закрепите id в метаданных doqa.test: явный ключ плагин и адаптер читают одинаково. Явный id плагин читает, даже если не понял конфиг Jest: конфиг нужен только для хэша.
Как проверяли
Правила вычисления сверены с настоящим Jest 30 и адаптером @doqa-tms/jest: на 29 проектах с разными конфигурациями ключи плагина совпали с ключами адаптера, а в остальных случаях плагин назвал причину отказа.
Что плагин пишет в код
Привязка кейса и закрепление ключа записывают caseIds и id в метаданные doqa.test. Обычный test или it плагин превращает в doqa.test. Было:
js
const { Cart } = require('../src/cart');
describe('Корзина', () => {
test('добавляет товар', () => {
// …
});
});Стало после привязки кейса #2401 к тесту, которого в DoQA ещё нет:
js
const { Cart } = require('../src/cart');
const { doqa } = require('@doqa-tms/jest');
describe('Корзина', () => {
doqa.test('добавляет товар', { id: 'tests.cart > Корзина > добавляет товар', caseIds: [2401] }, () => {
// …
});
});Как устроена правка:
- модификаторы сохраняются:
xitиxtestстановятсяdoqa.test.skip,fitстановитсяdoqa.test.only,.concurrentостаётся на месте; - импорт
doqaплагин пишет в стиле файла:import { doqa } from '@doqa-tms/jest';илиconst { doqa } = require('@doqa-tms/jest');. Он встаёт после последнего импорта верхнего уровня, а без импортов после начальных комментариев, чтобы docblock Jest остался первым. Еслиdoqaуже импортирован под другим именем, плагин пишет через это имя. Если имяdoqaв файле занято чем-то другим, адаптер импортируется какdoqaTms:const { doqa: doqaTms } = require('@doqa-tms/jest');; - у существующего
doqa.testплагин меняет только нужный ключ, остальные ключи и форматирование объекта не трогает. В однострочный объект ключ добавляется в конец строки, в многострочный новой строкой с тем же отступом; - в
caseIdsновые ID добавляются к старым; - отвязка убирает ID из
caseIds. Если ID был последним, из объекта уходит весь ключcaseIds, а пустой объект убирается из вызова.
Некоторые тесты нельзя превратить в doqa.test, не изменив их поведение. Для них кейс пишется вызовом doqa.metadata в теле теста, см. Кейс в doqa.metadata.
Кейс в doqa.metadata
Адаптер @doqa-tms/jest собирает ID кейсов из двух мест: из caseIds в метаданных doqa.test и из вызова doqa.metadata({ caseIds: [...] }) в теле теста. Второй способ подходит любому тесту, у которого есть тело. Поэтому, если doqa.test изменил бы тест, плагин записывает кейс вызовом doqa.metadata первой строкой тела:
| Тест | Почему не doqa.test |
|---|---|
обычный test.each или it.each | doqa.test.each свёл бы строки данных в один автотест, и строки потеряли бы историю |
таблица each задана шаблонной строкой (test.each`…`) | doqa.test.each принимает только массив строк |
тест принимает колбэк done | doqa.test не передаёт колбэк done |
test.failing | у doqa.test нет режима failing |
метаданные doqa.test заданы не объектом в самом вызове или caseIds в них не массив чисел | плагин не может поправить их, не сломав |
Если в теле уже есть такой вызов с caseIds, новый ID дописывается в него, второй вызов не появляется. Иначе плагин вставляет новый вызов первой строкой тела, с отступом тела, и добавляет импорт doqa так же, как для doqa.test (при занятом имени через doqaTms). Если у стрелочной функции тело это выражение ((n) => expect(n).toBe(n)), плагин делает из него блок: сначала вызов, затем return прежнего выражения. Обычный test, которому ничто не мешает, по-прежнему становится doqa.test.
Пример с test.each. Было:
js
describe('Корзина', () => {
test.each([[1, 100], [3, 300]])('сумма для %i шт.', (qty, expected) => {
const cart = new Cart();
cart.add('A-1', 100, qty);
expect(cart.total()).toBe(expected);
});
});Стало после привязки кейса #2401:
js
const { doqa } = require('@doqa-tms/jest');
describe('Корзина', () => {
test.each([[1, 100], [3, 300]])('сумма для %i шт.', (qty, expected) => {
doqa.metadata({ caseIds: [2401] });
const cart = new Cart();
cart.add('A-1', 100, qty);
expect(cart.total()).toBe(expected);
});
});Каждая строка данных остаётся отдельным автотестом со своим ключом, и кейс #2401 получают обе строки, как у параметризованного теста JUnit с @DoqaCaseIds.
Пример с колбэком done. Было:
js
test('пустая корзина', (done) => {
loadCart((cart) => {
expect(cart.items).toHaveLength(0);
done();
});
});Стало:
js
test('пустая корзина', (done) => {
doqa.metadata({ caseIds: [2401] });
loadCart((cart) => {
expect(cart.items).toHaveLength(0);
done();
});
});После такой привязки уведомление добавляет «ID записан в doqa.metadata в теле теста.».
Связь в DoQA. У каждой строки each свой автотест, а ключи строк Jest собирает только при запуске. Поэтому для строк each плагин не спрашивает ключ и не создаёт связь в DoQA: кейс записывается только в код, и адаптер привяжет его к каждой строке при следующем прогоне. Уведомление: «Кейс #N «…» записан в doqa.metadata теста …. У каждой строки each свой автотест: адаптер привяжет кейс к каждой из них при следующем прогоне.».
То же с тестом, у которого плагин не вычислил ключ и не может его закрепить (например, тест с done без конфига Jest): кейс пишется только в код, а в уведомлении «Ключ автотеста вычислит адаптер: он привяжет кейс при следующем прогоне.». Если ключ такого теста вычислен, связь в DoQA создаётся сразу, под тем ключом, который пришлёт адаптер.

Какие вызовы плагин читает. Вызов doqa.metadata({ caseIds: [2401, 2402] }) засчитывается, если он стоит отдельной инструкцией на верхнем уровне тела теста (await перед ним допустим), а caseIds это массив чисел. Имя, под которым импортирован doqa, не важно. Кейсы из вызова плагин складывает с caseIds из метаданных doqa.test и показывает вместе: в подсказке значка и в «Статусе теста» это строка «ID кейсов в doqa.metadata: 2401», а если кейсы есть и там и там, «ID кейсов в caseIds и doqa.metadata: …». Ctrl+клик по ID в вызове открывает карточку кейса.
Если caseIds в вызове не литерал, вызов стоит в условии, хуке или вспомогательной функции либо doqa.metadata взят под другим именем (const { metadata } = doqa), плагин не гадает, какие кейсы получит тест. Он показывает те, что видит, и добавляет строку «Не все ID кейсов видны в исходнике: часть задана не литералом или вызовом doqa.metadata в условии, хуке или функции». Если вызов с caseIds стоит в хуке, такая строка появляется у всех тестов файла.
![Тест test.each с doqa.metadata({ caseIds: [2401] }) первой строкой тела и подсказка «Статус теста»: «ID кейсов в doqa.metadata: 2401», фреймворк Jest, ключ не вычислен, у каждой строки данных свой автотест](/assets/jest_metadata_status.BhW8LQ92.png)
Отвязка. «Отвязать кейс…» убирает ID везде, где он записан: и из caseIds в метаданных doqa.test, и из вызовов doqa.metadata. Если ID был последним в вызове, уходит ключ caseIds, а если в вызове больше ничего нет, удаляется весь вызов. В диалоге подтверждения сказано «id уберётся из doqa.metadata.». Если кейсы теста задаются ещё и там, где плагин их не прочитает или не поправит, диалог предупреждает: «Внимание: кейсы теста задаются и там, где плагин их не прочитает или не поправит (…) — проверьте их вручную.».

У строк each отвязка снимает кейс только в коде: связи строк в DoQA плагин найти не может, потому что не знает их ключей. Блок, сделанный из тела-выражения, после отвязки остаётся блоком, а добавленный импорт doqa остаётся в файле.
Когда плагин не пишет в код
Плагин не пишет в код и объясняет почему, если правка изменила бы поведение теста или сломала бы его.
Привязка кейса:
| Что в коде | Сообщение |
|---|---|
test.todo | «у test.todo нет тела: привяжите кейс, когда тест будет написан» |
пропущенный тест (xit, .skip), который нельзя сделать doqa.test, например test.skip.each | «тест пропускается (skip), а doqa.metadata в его теле не выполнится — кейс не привязался бы, пока тест пропущен» |
| функция теста передана ссылкой, а не написана в самом вызове | «функция теста задана не в самом вызове — добавьте doqa.metadata({ caseIds: [...] }) в её тело вручную» |
имя doqa внутри теста занято (параметр, локальное объявление) | «имя doqa внутри теста занято параметром или локальным объявлением — переименуйте его, и плагин сможет привязать кейс» |
Закрепление id (ключ пишется только в метаданные doqa.test, поэтому здесь отказов больше):
| Что в коде | Сообщение |
|---|---|
test.todo | «у test.todo нет тела, а doqa.test требует функцию теста» |
test.failing | «у doqa.test нет режима failing» |
тест принимает колбэк done | «тест принимает колбэк done, а doqa.test его не передаёт — перепишите тест на async» |
обычный test.each (каждая строка данных сейчас отдельный автотест) | «у test.each каждая строка данных — отдельный автотест, а doqa.test.each свёл бы их в один: строки потеряли бы историю» |
таблица each задана шаблонной строкой (test.each`…`) | «таблица each задана шаблонной строкой, а doqa.test.each принимает только массив строк» |
| метаданные заданы не объектом в самом вызове | «метаданные doqa.test заданы не объектом в самом вызове — поправьте их вручную» |
id задан через doqa.metadata в теле теста | «id задаётся вызовом doqa.metadata в теле теста — поправьте его там» |
id может заменить doqa.metadata в хуке, функции или условии | «id может заменить вызов doqa.metadata во время прогона — закреплённый ключ не сработал бы» |
Отвязка отказывает, только если ID некуда убрать: ни caseIds в метаданных, ни вызова doqa.metadata, который плагин может поправить. Например, «caseIds в метаданных задан не списком чисел в самом вызове — поправьте его вручную».
При привязке кейса к тесту, у которого нельзя закрепить id, кейс записывается, а id нет.
Читаемый ключ Jest
Читаемый ключ теста Jest собирается из пути файла и названий, разделитель >:
text
tests.cart > Корзина > добавляет товарПервая часть это путь файла от rootDir через точки, без расширения и без .test или .spec: tests/cart.test.js даёт tests.cart. Точка внутри имени каталога или файла заменяется на _. Дальше идут названия блоков describe и название теста. Если у проекта есть название, оно стоит первым: web > tests.cart > Корзина > добавляет товар.
Читаемого ключа нет, если название теста или describe не строка, тест объявлен внутри функции, проект Jest не определён или ключ длиннее 255 символов. Тогда при закреплении плагин просит ввести ключ, как для теста, у которого ключ не вычисляется.
Действия с ключом в тестах Jest называются «Закрепить id у теста» и «Закрепить id во всём файле», а после записи плагин показывает «Закреплено: id: '…'». Правила выбора ключа те же, что в разделе Читаемый ключ и закрепление @DoqaId. Ctrl+клик по ID в caseIds и в вызове doqa.metadata открывает карточку кейса.
Ограничения
Если по тексту файла нельзя получить тот же внешний ID, что вычислит адаптер (например, у метода есть параметры или имя задано константой), плагин ключ не показывает и называет причину. Для таких тестов закрепите @DoqaId, а в Jest id в метаданных doqa.test: явный ключ плагин и адаптер читают одинаково. Причины для Jest собраны в разделе Когда плагин не вычисляет ID. Полный список есть в разделе Ограничения страницы «Помощь в редакторе и черновики тестов».
Смотрите также
- Плагины для IDE: установка плагина, токен и выбор пространства
- Помощь в редакторе и черновики тестов: черновик теста из кейса, дополнение тегов, проверка
doqa.properties, повторяющийся@DoqaId - Каталог автотестов: тот же каталог в веб-интерфейсе
- Нестабильные тесты и карантин: как DoQA определяет стабильность и что делает карантин
- Адаптеры для тестовых фреймворков: как адаптер вычисляет внешний ID