Коннектор требований

Коннектор связывает пространство с проектом во внешнем трекере: загружает оттуда требования, пишет обратно в тикет ID связанных проверок и вычисленный статус покрытия, принимает события об изменении требований. Один коннектор на пространство.

Какие трекеры подходят

Модуль требований умеет работать с двумя трекерами: Jira Server и YouTrack. Остальные трекеры, которые DoQA подключает для баг-репортов — Jira Cloud, Yandex Tracker, Bitrix 24, Redmine, GitLab, Kaiten, — источником требований быть не могут и в списке «Трекер» не появятся. Если такой трекер всё же попадёт в коннектор, DoQA откажется его сохранить: «Этот трекер не поддерживается модулем требований».

Коннектор не хранит логин и токен: он ссылается на уже существующую интеграцию-трекер. Сначала администратор подключает Jira Server или YouTrack в разделе интеграций — только после этого трекер появится в списке коннектора. Подсказка в интерфейсе так и говорит: «Из уже подключённых интеграций-трекеров DoQA».

В списке предлагается по одной интеграции на тип трекера. Если в DoQA заведено несколько подключений к Jira Server, коннектор возьмёт первое из них.

YouTrack в списке «Трекер»

YouTrack показывается в списке «Трекер», только если коннектор этого пространства уже привязан к интеграции YouTrack. При настройке коннектора с нуля в списке будет Jira Server. Дальнейшие разделы этой страницы описывают оба трекера — они относятся к уже подключённому YouTrack.

Где настраивается

Пространство → «Настройки» в боковом меню → вкладка «Коннектор требований». Страница настроек открывается при правах на редактирование проекта или пространств — либо при правах на редактирование тест-кейсов, чек-листов или прогонов в этом пространстве. Из пустого списка требований туда же ведёт кнопка «Настроить коннектор».

Рядом с заголовком «Коннектор требований» — состояние подключения:

Значок	Что означает
«Не настроено»	Коннектор ещё не сохранён.
«Подключено»	Последний обмен с трекером прошёл без ошибок.
«Поле не найдено»	Указанного кастомного поля в трекере нет (трекер ответил HTTP 400). Исправьте поле и сохраните заново.
«Трекер недоступен»	Подключиться к трекеру не удалось; DoQA показывает данные из кэша.

Настройка

Трекер и проект-источник

«Трекер» — выберите подключённую интеграцию. Пока трекер не выбран, остальные настройки не показываются: набор полей зависит от интеграции.
«Проект-источник» — выберите проект трекера. DoQA подтягивает список проектов из трекера сама.
Запрос-фильтр под списком проектов — «JQL-запрос» для Jira Server или «Запрос YouTrack» для YouTrack. Работает как дополнительный фильтр внутри выбранного проекта: например, status = Open. Требования, не попавшие под фильтр, в пространство не загружаются, а уже загруженные уходят в «Архивные записи».

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

Поле для ID кейсов

Кастомное поле трекера, в которое DoQA списком пишет ID связанных проверок. Именно оно делает связь двусторонней: открыв тикет, аналитик видит, какие проверки его покрывают.

Для YouTrack рекомендуемый тип поля — «текст» (одиночное значение).

Статус покрытия

DoQA вычисляет состояние покрытия и отражает его в трекере. Настройка «Куда писать статус покрытия» определяет способ:

«Кастомное поле» (рекомендуется) — статус пишется в отдельное select-поле трекера. Не требует настройки workflow.
«Системный статус (workflow)» — DoQA двигает тикет по статусам/переходам проекта. Подходит, если в проекте трекера уже настроены нужные статусы и переходы.

Переключатель показывается, только если трекер поддерживает оба варианта. Для YouTrack доступно только кастомное поле; рекомендуемый тип поля — «перечисление» (одиночное значение).

При выборе «Кастомное поле» задайте «Поле статуса покрытия» — это отдельное поле, не то же самое, что «Поле для ID кейсов». Без него коннектор не сохранится.

Маппинг статусов покрытия

Таблица сопоставляет пять состояний покрытия DoQA со значениями в трекере. Что подставлять в правую колонку, зависит от выбранной цели: при «Кастомном поле» — опция выбранного поля, при «Системном статусе» — статус или переход workflow. Состояние без сопоставления («— не задано —») в трекер не пишется.

Четыре состояния DoQA пишет в трекер: «Нет тестов», «Все прошли», «Не все прошли», «Не прогонялись». У них в таблице стрелка вправо.

Состояние «Требуется актуализация» — единственное, которое DoQA читает из трекера. У него стрелка влево и подсказка «Этот статус выставляет аналитик в трекере — DoQA слушает его и снимает пометку». Как только значение в трекере совпадает с этим маппингом, DoQA помечает все связанные проверки требования и замораживает запись статуса в трекер до подтверждения актуализации. Подробнее — цикл актуализации.

Если маппинг пуст

Без маппинга «Требуется актуализация» цикл актуализации не запустится: DoQA не поймёт, какой статус в трекере означает «требование изменилось».

Вебхуки

Вебхук доставляет в DoQA события «требование изменилось» из трекера, не дожидаясь ручного обновления. Тумблер «Принимать вебхуки» включает приём.

Тумблер выключает коннектор целиком

Несмотря на название, «Принимать вебхуки» — это выключатель всего коннектора, а не только приёма событий. Пока он выключен, DoQA не загружает требования по кнопке «Обновить из трекера», не пишет в трекер ID проверок и статус покрытия и не даёт генерировать тесты по требованию. В «Ленте операций» пропущенные операции будут помечены причиной «Коннектор выключен».

Настраивается вебхук на стороне трекера, и у Jira Server и YouTrack это делается по-разному.

Jira Server

DoQA даёт готовый URL вебхука с секретом внутри. Секрет на экране скрыт — кнопка «Скопировать» кладёт в буфер полный URL вместе с ним. Кнопка «Перевыпустить» выдаёт новый секрет; старый URL сразу перестаёт работать.

Подсказка со шагами открывается кнопкой «?» рядом с полем «Вебхук». В самой Jira: Администрирование → Система → Веб-перехватчики (WebHooks) → Создать.

Имя — любое; Статус — Включён.
URL — вставьте скопированный из DoQA.
События → Проблема: отметьте «обновлено» (и «удалено», если нужно гасить требования).
Не ставьте галочку «Исключить основу» — DoQA принимает JSON-тело.
Сохраните.

Примечание

URL содержит секрет — не публикуйте его. Адрес DoQA должен быть доступен с сервера Jira: для внешней Jira нужен публичный домен или туннель, localhost не подойдёт.

YouTrack

У YouTrack нативных вебхуков нет — вместо них ставится workflow-правило. Кнопка «Настройка вебхука YouTrack» открывает окно с готовым скриптом: URL, секрет и имя поля статуса покрытия в него уже подставлены. Секрет в URL не передаётся — скрипт отправляет его заголовком.

Кнопка доступна только после сохранения коннектора: до этого DoQA ещё не выдала URL и секрет.

Откройте Administration → Workflows.
Нажмите New workflow (или выберите существующий) и привяжите его к проекту-источнику требований.
Создайте правило (rule) и вставьте скопированный скрипт.
Сохраните workflow и убедитесь, что правило включено для нужного проекта.
Нажмите «Обновить из трекера» в DoQA, чтобы загрузить текущие требования.

Если поле статуса покрытия не выбрано, скрипт не будет отслеживать изменение покрытия — окно об этом предупредит.

Без workflow-правила модуль остаётся рабочим: данные синхронизируются по кнопке «Обновить из трекера», вебхук лишь ускоряет обновление.

Ручное обновление

Кнопка «Обновить из трекера» в блоке «Ручное обновление» перечитывает требования по фильтру коннектора. Во время работы виден прогресс («Прочитано N из M»), по завершении — сколько требований обновлено. Рядом показывается время последнего обновления или число загруженных требований.

Та же кнопка есть в шапке списка требований.

Лента операций

Под формой коннектора — «Лента операций»: что DoQA отправляла в трекер и что получала оттуда. Индикатор справа показывает «синк в норме» либо число ошибок.

Записи фильтруются по «Статусу» («Все», «OK», «Ошибки», «Пропущено») и «Операции»:

«Получение» — «Получение требования» (загрузка требований из трекера);
«Отправка» — «Отправка ID проверок в тикет» и «Отправка статуса покрытия»;
«Вебхук» — «Принят вебхук об изменении».

Отдельным цветом выделены записи «Актуализация».

Строки со статусом «Пропущено» объясняют, почему DoQA ничего не сделала:

Причина	Что это значит
«Коннектор не настроен»	В пространстве нет коннектора.
«Коннектор выключен»	Приём вебхуков выключен тумблером.
«Заморожено до актуализации»	Требование ждёт подтверждения актуализации — статус покрытия в трекер не пишется.
«Статус не сопоставлен или переход недоступен»	В маппинге нет значения для этого состояния либо трекер не даёт нужный переход.
«Повторное событие»	Вебхук с тем же событием уже обработан.

Очистка данных требований

Внизу вкладки — «Очистка данных требований». Кнопка «Очистить данные» безвозвратно удаляет из базы все загруженные в это пространство требования и все связи тест-кейсов и чек-листов с ними.

Действие необратимо

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

Не удаляются: настройки коннектора, сама интеграция и сами тест-кейсы и чек-листы. После очистки можно синхронизироваться заново.

Кнопка доступна только администраторам проекта — остальным она заблокирована с подсказкой «Действие доступно только администраторам». В диалоге подтверждения кнопка «Удалить» разблокируется через несколько секунд. По завершении DoQA сообщит, сколько требований и связей удалено.

Очистка нужна, если синхронизировались не с тем проектом или делали синхронизацию для теста. Чтобы просто перестать загружать часть требований, поменяйте фильтр коннектора: лишние записи уйдут в «Архивные записи», а связи и история сохранятся.