С чего начать

Что TestSpot делает

Тест-кейсы и результаты

В Test Cases хранятся ручные и автоматизированные кейсы. Launch объединяет результаты выбранного набора; в смешанном CI Launch ручные строки можно выполнить в интерфейсе.

Отправка результатов из CI

TestSpot принимает сырые результаты в формате Allure Report со статусами, шагами, попытками и вложениями. Если тесты уже используют адаптер Allure Report, переписывать их не нужно: настройте передачу результатов в TestSpot через CLI или загрузите архив результатов.

Анализ результатов

Для анализа результатов доступны категории падений, метрики и правила инсайтов. Подключённая модель добавляет сводки, сравнения и группировку ошибок. Возможности и условия доступности ИИ.

Работа с ассистентами

Внешний агент подключается через MCP и действует с правами владельца API-токена. Встроенный ассистент помогает читать данные и искать ответы в документации.

Как устроена эта документация

Поиск. Нажмите / в любом месте страницы — фокус перейдёт в поиск, он ищет и по заголовкам разделов, и по тексту. Стрелки и Enter работают без мыши.

Быстрый старт

Создайте кейс, выполните его вручную и завершите Launch. В документации используются английские названия UI; язык интерфейса можно переключить на русский в меню пользователя.

1. Аккаунт

Аккаунты создаёт администратор: Admin → Access → форма добавления пользователя (имя, email, временный пароль, роль Viewer / Writer / Admin). Логин — всегда email. Для Admin нужно минимум 12 символов, для Writer и Viewer — 8. Пароль должен содержать заглавную и строчную буквы, цифру и спецсимвол; пробелы в начале и конце не допускаются. Правила создания и сброса паролей.

Если в Admin → Access включён переключатель Self-registration, человек может зарегистрироваться сам и получит роль Writer. Это единственный самостоятельный путь: письма с приглашением в продукте нет, восстановления пароля по email — тоже. Пароль сбрасывает администратор, кнопкой Set a new password в строке пользователя.

2. Проект

Кнопка New Project в шапке открывает пошаговый мастер: имя, описание, дальше — создание. Проект — единица изоляции: доступ, поля, окружения, интеграции и метрики у каждого свои.

Создавать проекты может администратор всегда, а Writer — только если в Admin → Access включено Writers can create projects.

3. Первый тест-кейс

1. Откройте Test Cases и создайте кейс: название, шаги (действие и ожидаемый результат), при необходимости — предусловия.
2. Проставьте, что нужно: приоритет, важность, теги, владельца. Какие из этих полей вообще показываются и какие обязательны — решает проект, см. Fields.
3. Сохраните как Draft, пока кейс не готов: обязательные поля проверяются только при сохранении в Review или Active, черновик можно оставить недописанным.

Повторяющийся фрагмент («залогиниться», «открыть корзину») выносите в Shared Steps и подключайте по ссылке — правка в одном месте меняет все кейсы, которые его используют.

4. Первый Launch

1. В Test Cases выделите кейсы и нажмите Run.
2. Выберите Manual и подтвердите запуск. Если проект требует ревью, сначала получите одобрение кейсов.
3. В созданном Launch выполните сценарии и отметьте Pass, Fail или Skip.
4. Нажмите Finish run. Оставшиеся untested станут skipped.

Чтобы сохранить набор для следующих запусков, создайте Test Plan. Готовый отчёт загружается через Launches → Import.

5. Подключить автотесты

Чтобы прогоны из CI сами попадали в TestSpot, нужно три вещи:

1. Токен. Страница API tokens → New token, доступ Read & write. Секрет показывается один раз — сразу положите его в секреты CI. Заводите его от сервисного аккаунта, а не от своего: см. почему.
2. Переменные в пайплайне — TESTPILOT_URL, TESTPILOT_TOKEN, TESTPILOT_PROJECT.
3. Обёртку вокруг тестовой команды в джобе:
   bashКопировать

   curl -fsS -H "Authorization: Bearer $TESTPILOT_TOKEN" \
     "$TESTPILOT_URL/api/downloads/cli" -o testpilot.mjs
   
   node testpilot.mjs run --results allure-results -- npx playwright test

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

Полностью — на странице «CLI и CI». Если отчёт уже лежит готовым архивом, ничего подключать не нужно: Launches → Import → Test results.

Что дальше

Основные понятия

Словарь продукта — и точные правила там, где интуиция обычно подводит: как считается pass rate, чем вид запуска отличается от его состава и кто должен отметить строку руками.

Сущности

Как считается pass rate

Pass rate = 100 × passed / (passed + failed + broken + unknown). Результаты skipped и untested в расчёт не входят.

Если таких результатов ещё нет, Launch показывает —. Значение 0 % означает, что среди учтённых результатов нет passed; оно не означает, что выполнены все запланированные тесты.

Например, из 100 строк выполнены три и все прошли: pass rate — 100 %, выполнено — 3 из 100. Оценивайте успешность вместе с прогрессом.

Вид запуска и состав запуска — разные вещи

Вид (kind) говорит, откуда запуск взялся:

Состав (composition) — вычисляемая характеристика того же запуска: какая доля строк выполняется вручную, а какая автоматически. Значения — automated, manual, mixed; рядом с видом это отдельный чип. Автоматический по виду запуск вполне может быть смешанным по составу.

Есть и третий, независимый признак — чем прогон был запущен: вручную, из CI или по расписанию. Он не совпадает ни с видом, ни с составом: план по расписанию, который отмечают руками, — это вид manual и запуск «по расписанию» одновременно. В списке он виден системными тегами from-test-plan и scheduled.

Роль каждого вида, правило состава и статусы прогона — в разделе «Запуски».

Кто должен отметить строку руками

В Manual вручную выполняют все строки, в том числе автоматизированные кейсы. В CI вручную отмечают строки без селектора автоматизации.

Для ручной части доступны назначение исполнителей и прогресс по ним. Строки без исполнителя входят в Unassigned.

Вердикты человека и статусы результата

UI предлагает ручные вердикты Pass, Fail и Skip; отдельного Blocked нет. Статус результата не заменяет статус самого тест-кейса.

Виды тест-планов

Новые активные строки датасета автоматически включаются в план, если их не исключить. Такой план запускается только через CI. Состав плана из датасетов.

Жизненный цикл плана, статусы строк датасета и остальные настройки — в разделе «Тест-планы и датасеты».

Флаки

Флаки-тест (Flaky) — тест с нестабильным результатом. Признак flaky устанавливается при загрузке Allure Report, если его передала последняя попытка либо итоговый статус — passed после попытки failed или broken. Последняя попытка определяет итоговый статус, предыдущие видны как retries.

Раздел Flaky & Failed помогает отличить текущие падения от нестабильных тестов и увидеть восстановившиеся проверки. Как разбирать проблемы с тестами.

Поля кейса

Набор полей задаётся в Fields проекта. Для встроенных полей доступны Off, Optional и Required; Test plans нельзя сделать обязательным.

К встроенным относятся Priority, Severity, Risk, Tags, Reviewer, Owner, Description, Preconditions, Expected result и Test plans. Есть и кастомные поля проекта.

Для ручных кейсов обязательные поля проверяются при сохранении в Active или Review. Draft и Deprecated допускают незаполненные поля. Сохранение метаданных уже импортированного Auto-кейса не проходит ту же проверку обязательности.

Priority: P0–P3; Severity: Critical, High, Medium, Low; Risk: High, Medium, Low.

Проекты и обзор

Где что лежит: дашборд поверх всех проектов, каталог проектов, боковое меню внутри проекта и два разных способа быстро куда-то перейти.

Учебный проект

Кнопка Начать обучение в онбординге создаёт личную песочницу с кейсами магазина, результатами и примером дефекта. Учебные данные не входят в общие списки, поиск и рабочую аналитику.

1. Создайте свой кейс: заполните название, действие и ожидаемый результат. Остальные поля доступны через Дополнительные поля.
2. Выделите кейсы галочками и нажмите Запустить в панели массовых действий.
3. Отметьте результат каждого выбранного кейса и завершите запуск. Явный Skip засчитывается как выполненное упражнение; закрытие запуска без отметок — нет.
4. Разберите готовое падение и связанный дефект. Для работы через MCP используйте номера проекта и запуска из задания.

Подсказки ведут по одному действию и продолжают первое незавершённое упражнение при возвращении. Их можно свернуть; при ошибке сохранения введённые данные остаются для повторной попытки. В боковом меню сначала видны кейсы, запуски и дефекты; Все разделы открывает остальные возможности.

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

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

Overview — дашборд поверх всех проектов

На главной (/) выберите Все проекты или Избранные. Если у вас есть закреплённые проекты, по умолчанию открываются избранные. Закрепление личное, число избранных проектов не ограничено.

• Ищите проекты по имени или номеру, фильтруйте по статусу последнего запуска.
• Выберите карточки или список, сортировку по последнему запуску, имени или числу кейсов. Закреплённые проекты остаются первыми.
• Если ничего не найдено, нажмите Сбросить поиск и фильтры. Выбранный список «Все проекты / Избранные» сохранится.

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

Карточки содержат описание, владельца, количество кейсов и запусков, дату и статус последнего запуска любого типа, включая нагрузочный. Запуски в корзине не учитываются. Сводка рядом с поиском охватывает все доступные проекты независимо от фильтра: активные запуски, падения в запусках за сегодня и количество тест-кейсов вне корзины. «Сегодня» начинается в полночь по времени сервера. Падения — результаты Failed и Broken в запусках, созданных сегодня; один кейс может учитываться несколько раз, если выполнялся в разных запусках.

All Projects — каталог

Адрес /projects. Здесь проекты разделены на закреплённые и остальные. Кнопка Pin поднимает проект в начало списка и на главной странице. Поиск понимает и имя, и #id. Список разделён на Pinned to Overview и всё остальное, а при активном поиске сворачивается в один плоский список результатов.

Проекты представлены карточками с владельцем, состоянием, числом тест-кейсов и прогонов. Счётчики ведут прямо к тест-кейсам и прогонам. Кнопка закрепления доступна и в каталоге, и на главной странице. Индикатор внизу карточки показывает статус последнего запуска: Completed означает завершение, а не успешное прохождение всех тестов. Running показывается только для выполняющегося запуска; без запусков — No runs yet.

Создание проекта

Кнопка New Project в шапке — пошаговый мастер: имя, описание, создание. Кто может: всегда администратор; Writer — если в Admin → Access включено Writers can create projects.

Боковое меню проекта

Разделы сгруппированы по смыслу:

* Datasets появляется только при включённой функции Eval tests. † Reviews — только при включённой политике ревью. Оба раздела не «серые», а отсутствуют: заход по прямому адресу перебрасывает обратно.

График Quality Trend на Overview проекта показывает до 30 последних завершённых запусков с записанным pass rate, от старых к новым. Quality score — доля успешных проверок запуска. Coverage — доля текущих неудалённых тест-кейсов проекта, получивших в этом запуске результат passed, failed или broken. Повторные результаты одного кейса учитываются один раз; skipped, untested и unknown не увеличивают покрытие. Если кейсов в проекте нет, покрытие равно 0 %. При добавлении или удалении кейсов исторические значения покрытия пересчитываются относительно текущего состава проекта.

У разделов живые счётчики: идущие запуски, активные тест-планы, общие шаги и датасеты, открытые дефекты. На нуле счётчик пропадает, а не показывает ноль.

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

Хлебная крошка в верхней панели работает переключателем проектов.

Поиск и переходы по проекту

⌘K / Ctrl+K открывает поиск проектов, тест-кейсов и запусков. Внутри проекта среди найденных кейсов и запусков первыми идут результаты текущего проекта. Поиск учитывает ваши права доступа. Переходы по разделам доступны в боковом меню.

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

Project Health

Отдельного экрана Project Health нет: для обзора проекта откройте Overview. Оценка от 0 до 100 и вклад пяти факторов доступны через GET /api/projects/:id/health и MCP get_project_health.

Test Coverage здесь характеризует размер тестовой базы, а не покрытие кода или требований. Оно отличается от доли выполненных кейсов на графике Quality Trend.

Удаление и восстановление проекта

Владелец проекта или администратор удаляет проект в настройках, подтвердив его название. Данные и файлы сохраняются 30 суток, но проект исчезает из рабочих списков и становится недоступен через API, MCP и ссылки скачивания.

Администратор может восстановить проект в Настройки ТМС → Удалённые проекты до истечения срока. Прежняя корзина остаётся корзиной, доступы и подключения сохраняются. Расписания планов, отчётов и оповещений нужно включить вручную; автоматическое завершение импортов — настроить заново.

После истечения срока или подтверждения «Удалить проект навсегда» начинается окончательная очистка; восстановление уже недоступно. При ошибке очистки администратор может повторить её. Исторические удаления без сохранённого состава данных восстановить нельзя: они доступны администратору только для окончательного удаления.

Активность и аудит

На Overview проекта есть лента последних событий, а полный след — на вкладке Audit Log: поиск текстом, фильтры по актору и действию, диапазон дат. Действие, сделанное токеном, пишется как «Имя Фамилия via token tp_…» — то есть видно и человека, и то, что это был скрипт, а строки одного человека выглядят одинаково независимо от способа входа.

Тест-кейсы и общие шаги

В Test Cases можно создавать сценарии, размещать их в деревьях папок, отправлять на ревью и выбирать для запуска.

Работа с папками и деревьями

Откройте проект → Test Cases. Доступны плоский список и именованные деревья папок. Кейс можно открыть в боковой панели или на отдельной странице.

Один кейс может находиться в нескольких деревьях, но только в одной папке каждого дерева. Перемещение внутри дерева меняет размещение, а не создаёт копию кейса.

Удаление папки убирает из неё размещения кейсов, а дочерние папки поднимает на уровень выше. Удаление дерева убирает его папки и размещения. Сами кейсы сохраняются в плоском списке и в других деревьях.

Создание и редактирование тест-кейса

1. В Test Cases нажмите New Test Case.
2. Укажите название, описание и предусловия, если эти поля включены в проекте.
3. Добавьте шаги: действие, ожидаемый результат, при необходимости подшаги и вложения. Можно подключить группу Shared Steps.
4. Заполните поля проекта и сохраните кейс. Незавершённый сценарий сохраняйте в Draft.

Новый кейс создаётся как Manual. Автоматизация связывается с результатами отдельно.

История версий позволяет сравнить сохранённые состояния кейса. Если другой автор уже изменил кейс, ваш текст остаётся в редакторе. Откройте Сравнить изменения: правки разных полей объединяются, а для конфликтующих выберите нужную версию. Примените выбор и сохраните кейс.

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

Статусы и обязательные поля

Набор статусов задаётся в Config → Project Entities → Test case statuses: можно добавить название и цвет или удалить статус из выбора. Уже назначенные значения остаются у кейсов. Системный Draft удалить нельзя. Таблица описывает исходные статусы проекта; пользовательские статусы не добавляют собственных правил ревью или проверки обязательных полей.

Проверки в таблице относятся к ручным кейсам. Сохранение метаданных существующего Auto-кейса не требует заполнения тех же обязательных полей.

Ревью тест-кейсов

Раздел Reviews доступен, когда ревью включено в Settings проекта.

1. Запросите ревью кейса, выберите ревьюера и при необходимости добавьте сообщение.
2. Проверяющий открывает ревью и выбирает Approve или Request changes. Комментарий при запросе правок может быть обязательным.
3. После правок автор отправляет кейс повторно через Resubmit.

В Reviews есть Inbox, Requested by me и Completed. Кто вправе принимать решение и можно ли одобрять собственный кейс, определяет политика проекта.

Статус кейса Review и запись ревью независимы. Перевод кейса в Review не заменяет запрос ревью. Одобрение также не переводит кейс в Active автоматически: измените статус отдельно.

Настройка Require approval before Ready, несмотря на название в UI, требует одобрения перед переходом в Active и запуском кейса. Пользовательский статус с именем Ready не заменяет это правило. При включённом Reset approval after edits изменение одобренного сценария требует нового ревью; при обязательном одобрении Active-кейс возвращается в Draft.

Ревью относится к отправленному снимку сценария, включая общие шаги и сведения о вложениях. Завершённые решения Approved и Changes Requested сохраняются в истории после правок. Открытый запрос, содержимое которого изменилось или который заменили новым, получает Stale. Повторная отправка создаёт отдельное ревью, сохраняя прежнее решение, автора и комментарий.

В Completed можно искать по имени и участникам, фильтровать по результату, автору запроса и датам отправки. История включает решения по удалённым кейсам и не очищается по возрасту. Завершённое решение удалить нельзя; открытый запрос может отозвать автор запроса, владелец проекта или администратор.

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

Массовые действия, копирование и перенос

Выделите кейсы галочками. В панели доступны Add metadata (план, владелец, тег, статус), Run, Export, клонирование, перенос в проект и Move to trash — с учётом ваших прав.

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

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

Clone test case в меню строки создаёт копию со статусом Draft и способом запуска Manual, без селектора автоматизации, версий и истории прогонов.

Move to project требует права записи в обоих проектах. Перед переносом проверьте различия: недостающие поля и тип можно добавить при наличии права настройки проекта либо исключить. Исключённые значения полей теряются. Общие шаги можно скопировать группами или записать в сценарий обычными шагами.

После переноса удаляются размещения в деревьях и членство в планах исходного проекта. Старые результаты запусков и ревью остаются в исходном проекте. Одобрение не переносится; обязательное ревью или незаполненные обязательные поля нового проекта могут вернуть Active-кейс в Draft.

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

Move to trash убирает кейс из рабочего списка. В Trash его можно восстановить или удалить безвозвратно; для окончательного удаления нужно отдельное разрешение.

Импортированные автотесты

У кейса типа Auto можно редактировать метаданные: название, статус, владельца, теги, описание и поля проекта. Сценарий и способ запуска вручную не меняются: шаги поступают из отчётов.

Карточка результата Allure Report показывает дерево шагов и вложения конкретного выполнения. Это отдельный просмотр результата, а не редактор тест-кейса.

Import test cases в уже загруженном Launch связывает результаты с тестовой базой. При выборе существующего Manual-кейса он становится Auto.

Каркас автотеста из ручного кейса

В карточке Manual-кейса нажмите Каркас автотеста (Test scaffold), выберите pytest / Python, Playwright / TypeScript или JUnit 5 / Java и скопируйте либо скачайте файл. Генерация не требует AI-модели и не меняет тип кейса.

Каркас сохраняет название, описание, предусловия, вложенность действий и ожидания; общие шаги разворачиваются в сценарий. В файл включён статический Allure ID кейса. Действия и проверки пока содержат падающие TODO: замените их реальным кодом и утверждениями, запустите тест и отправьте результаты через CLI. Файл с TODO не является готовым автотестом.

Через MCP доступен generate_test_scaffold с параметрами projectId, caseId и framework (pytest, playwright, junit5). Достаточно доступа на чтение. Для Auto-кейса или удалённого общего шага каркас недоступен; сначала исправьте исходный сценарий.

Связь автотеста по Allure ID

Укажите номер кейса TestSpot в статической аннотации адаптера Allure Report. Например, для TC-123 в pytest используйте @allure.id("123"). Метки ALLURE_ID и AS_ID содержат числовой номер кейса текущего проекта, без префикса TC-; UUID, historyId и ID из другой TMS для этого не подходят.

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

В CI-прогоне некорректный, неизвестный, удалённый или неоднозначный ID отклоняет пакет с ошибкой 400: при явном ID запасного поиска по селектору нет. При отдельном импорте ZIP или папки результатов неизвестный ID допускается: тест сопоставляется по селектору или создаётся при подтверждении. Поэтому первый импорт из другой TMS не требует заранее созданных кейсов. Исходные метки сохраняются, а повторная загрузка того же селектора использует существующий кейс. Некорректные и неоднозначные ID по-прежнему отклоняются. Без ID действует сопоставление по селектору. Для выборочного запуска после переименования обновите CLI и используйте адаптер с поддержкой ALLURE_TESTPLAN_PATH и ID на этапе сбора тестов.

Фильтры тест-кейсов

Откройте Filters и найдите поле по названию. Доступны статус, способ запуска, тип теста, включённые поля проекта и активные кастомные поля. Отключённые и архивные поля не предлагаются; при отключении поля его условие удаляется из фильтра.

Для списков выбирайте значение, для текста — «Равно» или «Содержит», для чисел и дат — точное значение или границы диапазона. У флажка доступны «Да» и «Нет». Даты создания и последнего запуска фильтруются по календарным дням UTC, включая выбранный день. Условия разных полей применяются совместно. Текстовые условия встроенных полей не учитывают регистр; кастомные текстовые поля учитывают.

Фильтр сохраняется в URL и применяется на сервере ко всему проекту, включая число результатов, страницы списка и действие «выбрать все подходящие».

Сохранённые фильтры. Владелец проекта и администратор TMS могут открыть панель Filters и нажать внутри «Сохранить фильтр», задать название и выбрать «Только для меня» или «Для всех в проекте». Личные фильтры доступны только автору, общие — участникам проекта, включая читателей. Сохраняются поиск и условия; при применении открывается первая страница, текущие сортировка и размер страницы сохраняются. Сохранённые фильтры хранятся на сервере. Удалять доступные сохранённые фильтры могут только владелец проекта и администратор TMS; чужие личные фильтры недоступны и им.

Shared Steps

В Shared Steps создайте группу повторяющихся шагов и подключите её в редакторе кейса. У группы есть название, шаги с ожидаемыми результатами, подшаги и вложения.

Кейс хранит ссылку на группу: изменение группы отражается в использующих её сценариях. Для независимого сценария записывайте шаги в самом кейсе.

Группу нельзя удалить, пока на неё ссылаются неудалённые кейсы. UI показывает Used in N cases. Сначала уберите ссылки из этих кейсов.

Тест-планы и датасеты

План отвечает на вопрос «что запускать» — набором кейсов или датасетом. Расписание, переменные прогона и выбор между ручным запуском и CI живут здесь же.

Создание тест-плана

1. Откройте Test Plans и форму нового плана.
2. Укажите название и выберите состав: тест-кейсы или датасеты.
3. В форме название ограничено 80 символами, описание — 500. Более длинные ранее сохранённые значения сохраняются при редактировании. Добавьте нужные кейсы или датасеты, задайте статус и нажмите Save Plan.

Один план содержит только один вид данных. После создания вид плана изменить нельзя. В карточке состав дополняется через Add cases или Add datasets. В выборе кейсов доступны поиск по имени, номеру и папке, папочные представления и меню Filters по исполнению, типу, статусу, приоритету, владельцу и тегам. Счётчик выбранных переключает показ только выбранных кейсов; смена фильтров сохраняет выбор, а «выбрать все» действует на текущие результаты поиска. Удаление элемента из плана не удаляет сам кейс или датасет.

Найти кейс в составе плана

В открытом плане из кейсов используйте поиск по названию или номеру и меню Filters. Фильтры учитывают поля, включённые в проекте; счётчик показывает число найденных кейсов относительно полного состава плана. Условие можно снять отдельно или очистить все фильтры.

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

Планы из кейсов

Отобранный набор тест-кейсов. Умеет:

• переменные прогона — пары «ключ → значение», передаваемые в CI;
• расписание — cron-выражение, например 0 3 * * * для ежедневного ночного прогона.

Планы из датасетов

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

Запускаются только через CI: строки датасета — входы для внешнего прогона, человеку там выполнять нечего, поэтому переключателя «вручную» у такого плана нет.

Статус плана и статусы строк

Статусы плана: Draft, Active, Archived. Вручную и по расписанию запускаются только планы Active.

У строк датасета те же три статуса. Для запуска берутся только Active, кроме исключённых из плана. При удалении датасета из плана его исключения сбрасываются: повторное добавление снова включает все активные строки.

Группировка и расписание

Group группирует планы в списке. Расписание задаётся cron-выражением и часовым поясом плана; при пустом поясе используется пояс сервера.

Для автоматического выполнения по расписанию выберите соединение GitLab или GitHub по умолчанию. Оно должно быть доступно проекту и настроено для запуска пайплайна; см. подключение CI. Без него план из кейсов создаёт ручной Launch, который нужно выполнить в интерфейсе. Плану из датасетов для расписания требуется CI-соединение.

Расписание запускает только Active-планы. Владелец проекта должен оставаться активным пользователем с правом записи.

Запуск плана

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

• переключатель Manual / CI (у плана датасетов — только CI);
• выбор соединения и ветки;
• переопределение переменных на один прогон — сохранённый план это не меняет.

Что именно TestSpot передаёт пайплайну, описано на странице «CLI и CI»: только идентификаторы проекта, запуска и плана — адрес стенда пайплайн задаёт сам.

Создание датасета и работа со строками

1. Включите Eval tests в настройках проекта и откройте Datasets.
2. Нажмите New Dataset, укажите название и нажмите Create.
3. Откройте датасет → Add item. Заполните данные строки и сохраните.

Input, Expected Output и Metadata принимают JSON-объекты. В строке также есть название, источник и статус. Полный JSON открывается по строке; отдельное поле можно отредактировать в его редакторе.

Поиск работает по ID или тексту полей. Условия фильтров применяются ко всему датасету, а не только к открытой странице. Выделенные строки можно массово удалить или перевести в Active, Draft или Archived.

Через Run можно отправить выделенные строки в CI без плана. Этот выбор включает Draft и Archived: ограничение «только Active» действует для запуска плана, а не для явно выделенных строк. Результат сохраняется в новом eval Launch.

При удалении датасета дочерние датасеты поднимаются на уровень выше.

Выполнение тестов на датасетах

Eval tests включает датасеты, планы из них и импорт eval-результатов. Расчёт выполняет ваш внешний runner; TestSpot передаёт выбранные данные и показывает полученные результаты.

Запуски

Список прогонов проекта: как запуск появляется, что означают его виды, как работает корзина и как импортировать готовый отчёт.

Создание и повторный запуск

Launch можно создать из Test Plans, действием Run по выбранным тест-кейсам, запуском выбранных строк Datasets, импортом отчёта или отправкой результатов из CI.

Каждый новый запуск из списка кейсов или плана создаёт отдельный Launch. Результаты предыдущего сохраняются.

Для повторной проверки падений откройте соответствующие кейсы в Test Cases, выделите их и нажмите Run. Отдельной команды Retry Failed в текущем UI нет.

Виды запусков и роль каждого

В API значения вида: manual, ci, allure, eval, load; allure показывается в UI как Imported.

Состав: automated, manual, mixed

Состав показывает способ выполнения строк, а не остаток работы:

• automated — Imported, eval и load, а также CI без ручной части;
• manual — Manual Launch или CI, где все строки выполняются вручную;
• mixed — CI с ручными и автоматизированными строками.

Состав не становится автоматическим после того, как человек поставил все вердикты. Сколько осталось выполнить, показывает прогресс.

Статусы запуска

Finish run завершает Launch и переводит все оставшиеся untested в skipped. Поэтому skipped может означать как осознанный пропуск, так и невыполненную к моменту завершения строку. Оба варианта исключены из pass rate.

Запись всех вердиктов сама не завершает Launch. Импорт отчёта создаёт уже завершённый Launch. Для нагрузочных Launch кнопки начала и завершения не применяются.

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

Средний pass rate и соответствующий фактор Project Health берут завершённые Launch. Другие показатели, например общее число Launch, могут учитывать незавершённые.

У eval-прогона свои показатели

Вместо обычных Passed / Failed / Broken / Unknown / Skipped и длительности он показывает: Pass rate, Total, Passed, Failed, Blocking, Safety, Linked, Unlinked.

Blocking и Safety приходят из самого отчёта — это его собственные счётчики блокирующих и связанных с безопасностью падений. Linked и Unlinked — сколько строк отчёта удалось сопоставить со строками датасета: несопоставленные не теряются и не роняют импорт, они просто помечаются как несвязанные.

Исполнитель и теги у самого запуска

Не только у кейсов: сам запуск может иметь исполнителя (включая явное «Unassigned») и цветные теги проекта. Оба ставятся массово через Add metadata и оба работают фильтрами в списке.

Дата под названием в списке — время создания запуска, независимо от его статуса.

Сравнение запусков

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

Сравнение работает для ручных, автоматических, смешанных и eval-запусков. Результаты связываются по history ID из Allure Report, строке датасета, идентификатору кейса или селектору с учётом параметров. Неоднозначные совпадения показаны отдельно. Новое падение — переход с passed на failed, broken, blocked или unknown; исправление — обратный переход. Добавленные и отсутствующие результаты, skipped и untested не считаются исправлениями. Раскройте строку, чтобы увидеть ошибки, длительность, параметры, вход и ответы датасета и оценки eval с обеих сторон.

Нагрузочный запуск сравнивается с другим нагрузочным: по транзакциям, количеству запросов, ошибкам, средней задержке, p95/p99 и пропускной способности. Неизвестные величины остаются пустыми, нестандартные перцентили не выдаются за p95/p99. Разный профиль нагрузки или окружение может объяснять изменение метрик, поэтому оно само по себе не объявляется регрессией.

«Саммари сравнения с ИИ» объясняет рассчитанные различия и ссылается на строки сравнения. Нужны завершённые запуски, право записи и подключённая модель для launchSummary; учитывается переключатель ИИ проекта. Без модели таблица работает полностью. В модель передаются общие метрики и до 60 изменённых строк с сокращёнными ошибками. Саммари формируется по запросу на языке интерфейса, не сохраняется между посещениями и сбрасывается при смене пары или обновлении сравнения.

Фильтры, чипы и порядок

Чипы Type над списком — это состав, а не колонка вида: Manual, Mixed, CI, Eval, Imported, Load. Первыми решают виды, которые отвечают за себя сами (eval, allure, load), остальное распределяет состав.

• Поиск — по имени, ветке, исполнителю, а также #84 или просто 84 по номеру запуска;
• фильтры — состав (чипы Type), статус отдельным набором чипов, исполнитель, теги проекта;
• системные теги — from-test-plan и scheduled обозначают запуск из плана и по расписанию. Назначаются автоматически; изменить их вручную нельзя;
• сортировка — по дате создания, имени или статусу; по умолчанию новые сверху: свежие запуски находятся в начале списка;
• меню View — порядок и набор видимых колонок.

Панель Filters использует тот же интерфейс, что и тест-кейсы: поиск по полям, выбор поля и значений, счётчики выбранных условий, Clear all и Done. Доступны тип, статус, источник запуска, теги и исполнитель. Условия сохраняются в URL.

Save filter находится внутри панели. Владелец проекта и администратор TMS могут сохранить условия только для себя или для всего проекта. Остальные участники могут применять общие фильтры через Saved filters. Личные фильтры видит только автор. Фильтры запусков хранятся отдельно от фильтров тест-кейсов. Применение возвращает на первую страницу, сохраняя текущую сортировку и размер страницы.

Загрузка отчёта и создание кейсов из результатов

1. Откройте Launches → Import.
2. Выберите Test results для Allure Report, Eval report для eval-JSON или Load report для нагрузочного отчёта. Последние два пункта зависят от функций проекта.
3. Выберите файл и выполните импорт. Успешная загрузка создаёт завершённый Launch.

Импорт требует разрешения на импорт запусков.

Import test cases — отдельное действие в уже загруженном Allure Report/CI Launch. Оно не подтверждает загрузку отчёта: результаты уже сохранены. Просмотрите сопоставления по Allure ID или селектору автоматизации, выберите подходящие Manual-кейсы или создание новых и подтвердите.

Выбранный Manual-кейс становится Auto. Обновление метаданных и сценария связанного кейса определяется политикой импорта проекта. Новые Auto-кейсы создаются в Active, а при обязательном ревью — в Draft.

Для пакета Allure Report действуют ограничения: до 5 000 результатов, до 2 000 файлов вложений и до 200 МиБ распакованного содержимого. CLI отправляет результаты частями, но его итоговый архив вложений проходит ту же проверку пакета.

Нагрузочные запуски

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

Таблица конечных точек сортируется по числу запросов и ошибок, длительности, перцентилям, пропускной способности и объёму переданных данных. Отсутствующее значение показывается тире; подпись перцентиля соответствует показанному числу.

Нагрузочный Launch можно переименовать, добавить теги и скопировать ссылку через меню строки.

Корзина

Кнопка с корзиной переключает вкладку в режим Trash, на значке — количество удалённого. Три действия есть и в строке, и как массовые над выборкой:

• Move to trash — убрать из списка;
• Restore — вернуть;
• Delete permanently — в два шага: первый клик спрашивает «удалить навсегда?», второй подтверждает.

Сведения о CI и автоматическое завершение

В шапке Launch показаны сохранённые сведения о пайплайне, ветке и коммите. Таблица результатов и разбор падений находятся ниже.

TestSpot сверяет незакрытые CI Launch с GitLab. Если пайплайн завершён и результатов не записывали последние 15 минут, Launch может завершиться автоматически. Оставшиеся untested станут skipped, причина появится в аудите.

Проверка выполняется раз в минуту для Launch старше трёх минут. Недоступный GitLab или неизвестный статус пайплайна не приводят к автозавершению. Для смешанного Launch новая запись результата откладывает закрытие ещё на 15 минут.

Сверка использует токен сохранённой CI-цели проекта. У старого запуска без ссылки на цель нужна единственная доступная GitLab-цель на хосте пайплайна. При нескольких подходящих целях автоматическая сверка не закрывает запуск. Если записанная цель удалена, её токен очищен или доступ отозван, токен другой цели не подставляется.

Результаты запуска

Таблица результатов, раздача ручной части прогона по людям, вложения и разбор падений по категориям.

Таблица результатов

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

Если автоматический отчёт не содержит шагов, карточка сообщает об этом явно. Для связанного кейса отдельно показаны его текущее описание и предусловия: это справочная информация, а не подтверждение выполнения сценария.

Во вкладке Logs / Логи показаны ошибка и трассировка, а также вложения stdout и stderr этого результата (в том числе с расширениями .txt и .log), если адаптер Allure включил их в отчёт. Текст загружается при открытии вкладки; файлы больше 512 КБ доступны для скачивания. Кнопка раскрытия открывает текст на весь экран; Escape возвращает к результату. Прокрутка над текстом остаётся внутри лога и не прокручивает страницу на его границах. Оригиналы остаются и во вкладке вложений. Общий лог CI job сюда не подмешивается.

Ручные вердикты — Pass, Fail, Skip. В отчётах также встречаются broken и unknown; untested означает отсутствие результата. Значения статусов.

Отметить одну строку

В строке результата стоит переключатель из трёх сегментов — Pass, Fail, Skip. Нажатие сразу записывает вердикт и отмечает, кто его поставил и когда. Тот же переключатель есть в подвале карточки кейса, если открыть строку целиком.

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

Ставить вердикты можно, только пока запуск в статусе running.

В карточке ручного результата можно отметить отдельный шаг и оставить комментарий к нему. Первый Fail на шаге отмечает предшествующие непроверенные шаги как Pass и сбрасывает результаты следующих шагов. Кейс получает Fail при наличии упавшего шага и Pass, когда пройдены все шаги. Общий Pass отмечает все шаги пройденными.

Назначение исполнителей

1. Откройте Launch в статусе draft или running.
2. Выделите строки ручной части и выберите исполнителя из команды проекта.

За одно действие обрабатывается до 500 строк. Пустое значение снимает назначение. Автоматические строки пропускаются. В завершённом Launch назначения изменить нельзя.

Назначение не ставит вердикт и не меняет того, кто фактически записал результат.

Массовая отметка

В идущем Launch нажмите All passed или All failed. Действие применяется к ручным строкам со статусом untested, входящим в текущий отфильтрованный список. Галочки выбора строк не задают область массовой отметки.

Уже записанные вердикты сохраняются, в том числе если их успели поставить после загрузки страницы. Массовой кнопки Skip нет; пропустить отдельную строку можно в её карточке или таблице.

Прогресс по исполнителям

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

Вложения

Скриншоты, логи, видео, трейсы — то, что приложил раннер или человек. Панель вложений одна и та же здесь, на тест-кейсах и на общих шагах.

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

• Rendered preview показывает HTML как документ, XML — как дерево с раскрываемыми узлами.
• Source code показывает исходный текст. Если XML не удалось разобрать, исходник доступен и вместо дерева.
• Кнопка раскрытия открывает просмотр на весь экран; Escape возвращает к вложению. Оригинал файла можно скачать.

HTML-просмотр не выполняет скрипты отчёта и не загружает внешние ресурсы. Поэтому интерактивные элементы и внешние картинки могут отсутствовать; для проверки содержимого переключитесь на исходник.

Если формат не поддерживает просмотр, скачайте файл и откройте его подходящей программой.

Разбор падений

Падения группируются по Failure Categories — упорядоченной таксономии проекта: побеждает первая подошедшая категория, поэтому порядок в настройках это приоритет. Настройка категорий и шаблонов.

Падение, которое человек поправил руками, остаётся поправленным — повторная классификация его не перезаписывает.

Группировка причин моделью

AI-группировка добавляет подгруппы внутри выбранной категории завершённого Launch. Нужны включённый ИИ и подходящее модельное соединение. Условия и ограничения.

Из падения — в дефект

Упавший результат можно превратить в новый дефект или прикрепить к существующему. Если у проекта подключена модель, рядом есть кнопка черновика: заголовок и описание напишет модель по контексту этого падения, а отправит человек. Пока человек не нажал «создать» — ничего не создано.

Дальше — на странице «Дефекты».

Дефекты

Локальная запись о проблеме — и единственное место в продукте, откуда создаётся новая задача в трекере.

Список

Адрес /defects. Важность: Critical, High, Medium, Low. Статус: открыт или закрыт. В списке есть поиск, чипы фильтров по важности и статусу, и кнопка быстрого закрытия в строке. Нажмите бейдж статуса перед названием, чтобы сразу переключить Open ↔ Closed без перехода в карточку. Изменение доступно пользователям с правом записи; при ошибке статус сохраняет прежнее значение, а список показывает сообщение.

Карточка дефекта

• описание свободным текстом;
• шаги воспроизведения — нумерованный список, разбирается из простого текстового формата вида 1. действие → expected: ...;
• обсуждение — ветка комментариев;
• важность и исполнитель правятся на месте;
• карточка связи с задачей в трекере;
• списки Linked launches и Linked test cases — только на просмотр.

Что происходит при закрытии

Закрытие ставит дату разрешения дефекта, переоткрытие снимает её. Оба действия создают события для правил оповещений.

Статусы результатов Launch при этом не меняются. Для проверки исправления выполните связанные кейсы повторно.

Задача в трекере

1. Подключите трекер в Integrations проекта.
2. В карточке дефекта откройте создание задачи, выберите цель и заполните поля.
3. При доступной модели можно использовать Draft with AI. Проверьте текст и подтвердите создание.

Создаётся отдельная задача во внешнем трекере со связью с локальным дефектом.

Панель в Jira

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

Панель доступна для Jira Cloud и Jira Data Center. Каждый пользователь подключает свой аккаунт TestSpot через подтверждение Approve.

Установка — на странице «Интеграции».

Релизы

Запись о версии: что выпускаем, когда, на каком окружении, какими прогонами это подтверждено и проходит ли оно quality gate.

Из чего состоит релиз

• версия или номер сборки;
• целевая дата — выбирается тем же контролом даты, что везде в продукте;
• имя окружения;
• ветка и хэш коммита;
• набор прикреплённых запусков;
• решение — Go или No-go. Ставится само при переводе статуса в Ready или Blocked.

Запуски выбираются в постраничном списке с поиском, и он помнит выбор, сделанный на страницах, с которых вы уже ушли, — и прямо об этом говорит: «N selected launches are not on this page, and stay attached». Иначе прикрепление двадцати прогонов превращалось бы в гадание.

Сводка и quality gate

Сводка учитывает все прикреплённые Launch, включая незавершённые. Блокеры = failed + broken + unknown. Quality gate проходит, когда прикреплён хотя бы один Launch, блокеров нет и все прикреплённые Launch имеют завершённый допустимый статус (completed или passed).

Число незавершённых Launch показано отдельно. Флаки и пропуски сами по себе не блокируют gate.

Покрытие — доля уникальных неудалённых кейсов текущего проекта, связанных с результатами прикреплённых Launch, относительно всех неудалённых кейсов проекта. Повтор одного кейса в нескольких запусках учитывается один раз. Статус кейса, в том числе пользовательский, на участие в покрытии не влияет.

Несвязанные результаты Allure Report и AI Eval, удалённые и перенесённые в другой проект кейсы не увеличивают покрытие, но их результаты остаются в статистике и pass rate. При изменении тестовой базы показатель старого релиза пересчитывается; без кейсов он равен 0 %.

Pass rate рассчитывается по суммарным результатам, а не усреднением процентов Launch. Если учтённых результатов нет, релиз показывает 0 %; список Launch в таком случае показывает тире.

Статусы

Статус ставит человек, прямо в строке и без открытия карточки. Автоматического перехода по результату quality gate нет: вердикт вычисляется и показывается рядом, но решение о статусе остаётся за человеком.

Фильтры

Поиск, чипы статусов, чипы окружений, меню сортировки и вида — устроены так же, как на Launches.

Аналитика и отчёты

Собственный дашборд проекта из виджетов, шесть шаблонов отчётов с расписанием и доставкой, и правила оповещений.

Analytics — дашборд, который собирают сами

У каждого пользователя своя панель для каждого проекта.

1. Нажмите Add widget / Добавить виджет и выберите виджет в каталоге.
2. Выберите метрику или представление. Задайте название, размер, тип графика, период и число строк — доступные настройки зависят от метрики.
3. При необходимости ограничьте данные в Выборке данных и проверьте предпросмотр.

Условия выборки применяются совместно. Название теста или запуска ищется по части текста, владелец и ветка — по точному совпадению. Доступны только фильтры выбранной метрики.

Templates / Шаблоны предлагают наборы «Качество релиза», «Автоматизация и скорость» и «Дефекты и ответственность». Шаблон и Reset / Сбросить заменяют раскладку только в черновике. В режиме настройки виджеты можно дублировать, удалять и перемещать перетаскиванием или стрелками.

Нажмите Save dashboard / Сохранить панель, чтобы сохранить изменения в аккаунте, или Cancel / Отмена, чтобы вернуться к сохранённой раскладке. При ошибке сохранения черновик остаётся доступным для повторной попытки. Лимит одной панели — 40 виджетов.

Общий период временно переопределяет периоды временных метрик; «Из настроек виджетов» возвращает сохранённые значения. Метрики состава тестовой базы, владельцев и текущих дефектов показывают текущее состояние проекта. Временные срезы строятся по дате создания записи, дни считаются в UTC.

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

• Кольцо автоматизации — доля Auto-кейсов среди неудалённых кейсов выбранной области.
• Тренд автоматизации — ежедневные снимки состава тестов. История начинается с первого наблюдения; дни без снимков остаются пустыми. Текущий день обновляется по мере наблюдений.
• Карта покрытия — выбранное именованное дерево: площадь ячейки соответствует числу тестов, цвет — доле автоматизации. Кейсы без размещения в этом дереве показаны отдельно.

«Проблемные тесты» позволяет выбрать низкую успешность, длительность, нестабильность или число падений. Успешность считается как доля passed среди passed, failed и broken в завершённых запусках. Текстовый блок хранит обычный текст; HTML в нём не выполняется.

Настройка оповещений

1. В Alerts создайте правило или выберите шаблон: падения регрессии, критические дефекты, еженедельная сводка, затянувшиеся запуски.
2. Выберите событие и условия. Для запусков можно указать точную ветку и пару «параметр окружения — значение»; пустые фильтры охватывают все запуски. Правило плана учитывает только запуски выбранных планов.
3. Выберите каналы Telegram/Slack проекта и сохраните правило. Проверить условие оценивает текущую метрику или подходящий запуск без отправки сообщения. Проверить доставку отправляет тестовое уведомление и показывает результат каждого канала.

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

Условие длительности завершённого запуска оценивается после его окончания. Для ещё выполняющегося запуска используйте событие «Когда запуск затянулся»: оно проверяет время от начала запуска и не повторяет уведомление при каждой проверке.

Дайджест отправляется ежедневно, еженедельно или по произвольному cron в выбранном часовом поясе; ближайшая отправка показана в правиле. При выборе времени сервера используется часовой пояс установки. Отправка происходит в течение пяти минут после назначенного времени.

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

История доступна за последние 30 дней, с выбором периода и переходом к источнику события. Совпадающие правила вызывают предупреждение, но их можно сохранить для разных каналов. Импорт нагрузочного отчёта не вызывает оповещение о завершении Launch.

Уведомления в самом приложении

Помимо мессенджеров есть колокольчик в шапке — третий канал, независимый от Telegram и Slack. В нём последние 30 событий и число непрочитанных; можно отметить одно или все прочитанными.

Уведомления относятся к проекту или адресованы лично вам:

Назначение строк Launch уведомляет другого выбранного исполнителя; назначение себе и снятие назначения такого уведомления не создают.

Инсайты и флаки

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

Сканирование проекта

Откройте Insights → Scan project. Сканирование анализирует кейсы, Launch, дефекты, планы и ревью. Можно уйти со страницы и вернуться: интерфейс подхватит текущее сканирование.

Между ручными сканированиями требуется две минуты; TMS Admin это ограничение не касается. Запуск, не завершившийся за пять минут, может быть признан зависшим и заменён новым.

Фоновая проверка выполняется каждые 15 минут. Повторный скан проекта — не раньше чем через 6 часов при новых завершённых Launch либо через 24 часа без новой активности. Поэтому находки могут появиться без нажатия кнопки.

Анализ ограничен выборкой: до 20 завершённых Launch за 30 дней, 5 000 результатов, 2 000 кейсов, 500 дефектов, 200 планов и 500 ревью. Отсутствие находок не подтверждает отсутствие проблем за пределами этой выборки.

Правила и AI-анализ

Встроенные правила выявляют просадку pass rate, частые падения, нестабильность, рост длительности, залежавшиеся кейсы и дефекты, задержки ревью и отсутствие запусков.

Модель может уточнить текст найденных проблем и добавить свои выводы. Приоритет её новых находок не выше High. Если модель недоступна или выключена, результаты правил сохраняются.

Условия появления находок

Примеры условий срабатывания:

• Просадка pass rate: среднее последних пяти Launch ниже предыдущих пяти минимум на 10 процентных пунктов.
• Постоянные падения: не меньше пяти результатов, доля failed/broken от 60 %; от 90 % — Critical.
• Новая нестабильность: среди последних четырёх результатов не меньше 30 % имеют retries или flaky, среди предыдущих четырёх — меньше 10 %.
• Залежавшийся кейс: активный кейс без запусков старше 60 дней; находка требует не меньше трёх таких кейсов.
• Залежавшийся черновик: Draft старше 90 дней; также не меньше трёх.

Находки имеют приоритет Critical, High, Medium или Low. Большое число однотипных проблем объединяется в сводные карточки.

Разбор находок

Фильтруйте находки по приоритету и статусу: Open, Resolved, Dismissed. Dismiss отклоняет находку: следующие сканы не открывают её снова, пока вы её не вернёте.

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

Flaky & Failed

Откройте Flaky & Failed в проекте, чтобы найти проблемные тесты, проверить причину падения и передать её в работу. Раздел анализирует результаты за последние 30 дней.

• Failing Now — последний результат теста failed или broken. Сначала показаны тесты с более длинной серией падений. Если все учтённые запуски провалены и признаков нестабильности нет, тест отмечен как постоянно падающий (нужно хотя бы два запуска).
• Flaky — тест помечен как flaky, прошёл после повторной попытки или не меньше двух раз сменил успешный результат на падение либо наоборот. Например, passed → failed → passed — признак нестабильности. Такой тест может одновременно находиться в Failing Now.
• Recovered — последний результат успешный, раньше были падения, а признаков нестабильности нет. Одно падение, за которым следует успешный запуск, само по себе не делает тест flaky.

Разные ветки и наборы параметров рассматриваются отдельно: проблема в одном варианте теста не означает, что остальные тоже падают.

Как читать показатели

Падения или нестабильность — доля запусков с результатом failed или broken, признаком flaky или повторными попытками. Один запуск учитывается один раз, даже если у него несколько признаков проблемы. Падений подряд — длина текущей серии падений; Повторов — суммарное число повторных попыток.

Оценка риска доступна от пяти учтённых запусков: High — от 50 % проблемных запусков, Medium — от 20 %, Low — меньше 20 %. При меньшем числе запусков показано «Мало данных». Процент описывает историю результатов, а не вероятность следующего падения.

Как разобрать проблему

1. Выберите вкладку и найдите тест по названию, ошибке, ответственному, ветке или параметрам.
2. Раскройте тест: проверьте причину падения и последние результаты. Откройте Последний результат или Последнее падение, чтобы изучить детали выполнения. Если причины падений различаются, они показаны отдельно: у каждой есть число повторений и ссылки на соответствующие результаты. Причины группируются по тексту ошибки; показатели теста учитывают все его запуски.
3. Назначьте Ответственного за тест, если нужно передать разбор коллеге. Это меняет владельца тест-кейса. Если связанного кейса нет, сначала свяжите его в результате запуска.
4. Нажмите Связать или создать дефект: выберите существующий дефект или проверьте и сохраните новый. Он связывается с последним падением, а если падения нет — с последним результатом.

Назначение ответственного и работа с дефектами требуют права на изменение проекта. С правом просмотра можно изучать результаты и переходить к связанным тест-кейсам и дефектам.

Известные проблемы

Если причина уже известна и исправление отложено, раскройте тест, найдите нужную причину падения и нажмите рядом с ней Игнорировать проблему. Укажите пояснение и подтвердите перемещение. Эта причина исчезнет из рабочих вкладок у всей команды и появится во вкладке Игнорируемые, где сохраняются причина, автор и дата решения.

Игнорирование относится к выбранной причине в конкретной ветке и наборе параметров. Повторения этой ошибки остаются игнорируемыми до возврата в работу. Другие причины, в том числе новые, остаются в рабочих вкладках. Поэтому тест может одновременно находиться в рабочей вкладке и в «Игнорируемых» с разными причинами. Результаты запусков и связанные дефекты сохраняются; общая статистика прохождения не меняется.

Когда будете готовы заняться проблемой, откройте её во вкладке Игнорируемые и нажмите Вернуть в работу. Тест снова появится в подходящей рабочей вкладке, если его текущие результаты соответствуют её условиям. Игнорируемые проблемы остаются доступны и после выхода результатов за 30-дневное окно: в таком случае показаны данные, сохранённые при игнорировании. Эти действия требуют права на изменение проекта.

Какие результаты учитываются

Учитываются passed, failed и broken, в том числе уже полученные результаты идущих запусков. Черновики и удалённые запуски, untested и skipped исключены. Для каждого варианта теста в одном запуске учитывается один итоговый результат; история показывает до десяти последних результатов.

При большом объёме данных анализ ограничен 10 000 последних результатов. Если достигнут лимит, раздел предупреждает, что показатели могут быть неполными. Пустой список означает отсутствие подходящих проблем в учтённых данных, но не подтверждает, что все тесты были выполнены и прошли.

Подключение модели

Модель подключается как соединение — так же, как GitLab или Jira: администратор держит учётные данные один раз и выдаёт их проектам. Ключ в проект не попадает.

Шаг администратора: соединение

1. В Admin → Connections → Models создайте соединение.
2. Укажите имя, протокол, адрес, API-ключ и идентификатор модели.
3. Выдайте соединение нужным проектам.

Поддержаны протоколы OpenAI-compatible, Anthropic и Gemini. Для OpenAI-compatible адрес обязателен. Для Anthropic по умолчанию используется https://api.anthropic.com, для Gemini — https://generativelanguage.googleapis.com. Идентификатор модели обязателен.

Шаг проекта: выбрать, чем пользоваться

Вкладка Integrations проекта, карточка Models. Проект не видит ни ключа, ни адреса — он выбирает из уже выданных ему учётных данных и создаёт свои записи:

• имя;
• какое выданное соединение использовать;
• переопределение слага модели — одна точка часто отдаёт несколько моделей, и какую взять, решает проект, а не администратор;
• отметка «по умолчанию»;
• привязка к конкретным функциям: launchSummary, insightScan, failureGrouping, issueDraft. Пустой список — запись общего назначения.

До 10 записей на проект.

Как выбирается запись, если их несколько

Для функции выбирается первая запись, явно назначенная ей. Если такой нет — общая запись с отметкой по умолчанию, иначе первая общая запись.

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

Проект без соединения

Подключите выданную проекту модель в Integrations → Models. Если подходящего соединения нет, новые сводки обычных Launch и другие запросы к модели недоступны. Сканер инсайтов продолжает работать по встроенным правилам.

Переключатель AI features в проекте

В Settings проекта включите AI features. Без доступного модельного соединения переключатель недоступен; перейдите в Integrations.

Выключение блокирует новые запросы к модели для проекта: сводки и сравнения Launch, группировку ошибок, AI-анализ инсайтов и черновики. Сохранённые ответы остаются доступными, а правила инсайтов продолжают работать.

Идентификатор модели

Идентификатор модели берётся из соединения администратора. В Integrations → Models его можно переопределить для записи проекта. Переменные окружения сервера не задают запасную модель.

Что делает ИИ

Модель может подготовить сводку Launch, сравнение запусков, группировку ошибок, инсайты и черновики. Доступность зависит от подключённого соединения и настроек проекта.

Сводка по запуску

На странице Launch откройте генерацию сводки. Для обычного запуска она описывает результаты и возможные причины падений. Для нагрузочного — дополняет диагноз, рассчитанный по метрикам.

Для обычного Launch без подходящего соединения показывается сообщение о необходимости подключить модель в Integrations. Для нагрузочного при отсутствии соединения доступен текст по метрикам. Выключенный флаг AI features и ошибка провайдера не равнозначны отсутствию соединения: они могут блокировать генерацию.

Сохранённая сводка не переводится при смене языка интерфейса; сформируйте её заново.

Сканер инсайтов

Правила работают всегда; модель только переформулирует худшие находки и может добавить несколько своих, ограниченных приоритетом High. Подробно — на странице «Инсайты и флаки».

Группировка причин падений

В завершённом Launch откройте категорию падений и запустите AI-группировку. Она добавляет подгруппы с названиями и объяснениями. При недостаточном числе различных ошибок запрос отклоняется; running и draft сначала нужно завершить.

Результат сохраняется. Regenerate формирует его заново. Без модели сохраняется обычное разбиение по категориям проекта.

Черновик дефекта или задачи

Draft with AI в форме дефекта или задачи подготавливает заголовок и описание по связанным данным. Проверьте текст и сохраните форму, чтобы создать запись.

Кнопка зависит от доступности модели и AI features проекта. Ошибка генерации показывается в форме; её можно заполнить вручную.

Встроенный ассистент

1. Откройте чат плавающей кнопкой.
2. Задайте вопрос о данных или использовании TestSpot. Внутри проекта текущая страница задаёт контекст; проверьте его в шапке чата. Вне проекта укажите, какой проект нужен.
3. Переходите по ссылкам ответа к кейсам, Launch, дефектам и разделам справки.

Инструменты ассистента читают данные с вашими правами. Для изменений он направляет в UI. Предложенный черновик дефекта становится записью только после нажатия кнопки создания человеком.

Ассистент не читает данные проекта с выключенным AI features для ответа модели. Глубокий режим увеличивает число обращений к данным и длину ответа, сохраняя выбранную модель. При обрыве ответа или ошибке интерфейс показывает причину; запрос можно повторить.

Администратор включает Assistant available to users и выбирает отдельное соединение в Settings → Connections. Без него кнопка чата недоступна. Это соединение используется для ассистента всего стенда, отдельно от моделей отдельных проектов.

Ассистент отвечает на языке сообщения. Генерации сводок, сравнений, группировок и черновиков используют язык интерфейса; сохранённые тексты автоматически не переводятся.

Работа без модели

Без обращений к модели работают правила инсайтов, метрики, отчёты, оповещения и категории падений. Формы дефектов и задач можно заполнить вручную.

Новые AI-сводки обычных Launch, AI-сравнения, подгруппы ошибок, черновики и ответы ассистента требуют доступной модели. У ассистента отдельное соединение и переключатель администратора.

MCP: агент как пользователь

TestSpot держит MCP-сервер на том же адресе, что и приложение. ИИ-агент подключается одной командой и работает с тест-кейсами, запусками и датасетами сам — теми же правами и с тем же аудитом, что человек.

Адрес и транспорт

Эндпоинт — POST /mcp, на том же хосте и порту, что веб-интерфейс и API. Ставить ничего не нужно: сервер уже там. Транспорт — Streamable HTTP, без состояния на сервере.

Аутентификация

Передайте персональный API-токен в заголовке Authorization: Bearer. Для чтения достаточно scope read, для изменений нужен write и право записи в проекте.

Действия выполняются от имени владельца токена и записываются в аудит проекта. Выпуск токена.

Подключение клиента

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

Claude Code

claude mcp add --transport http testpilot https://tms.example.com/mcp \
  --header "Authorization: Bearer tp_…"

Если правите ~/.claude.json руками, обязательно укажите "type": "http" — без него запись читается как сломанный stdio-сервер.

Cursor

{
  "mcpServers": {
    "testpilot": {
      "url": "https://tms.example.com/mcp",
      "headers": { "Authorization": "Bearer tp_…" }
    }
  }
}

Codex

[mcp_servers.testpilot]
url = "https://tms.example.com/mcp"

[mcp_servers.testpilot.http_headers]
Authorization = "Bearer tp_…"

Что умеет агент

Инструменты позволяют читать данные проектов и выполнять перечисленные ниже изменения. Сначала получите нужные идентификаторы инструментами чтения; для записи используйте UUID из ответа.

Чтение

whoami, list_projects, get_project_overview, get_project_health, list_test_cases, get_test_case, list_shared_steps, list_case_runs, list_case_comments, list_defect_comments, list_folders, list_folder_trees, list_custom_fields, list_test_types, list_test_case_statuses, list_launches, get_launch, get_launch_case, compare_launches, list_attachments, read_attachment, list_datasets, list_dataset_items, list_defects, search, run_analytics_query, search_docs, read_docs_section.

search_docs ищет по документации, read_docs_section читает раздел по адресу страница~якорь. Адрес можно скопировать из ссылки на раздел. Эти инструменты доступны и при выключенных AI features проекта.

Этот же список — инструменты встроенного ассистента: он вызывает их тем же способом и с доступом спрашивающего. Записывающие инструменты ниже ему не даются.

get_launch_case читает выбранный результат по номеру кейса или строки запуска; ссылки на доказательства открывают результат и нужный шаг. compare_launches сравнивает два запуска по тем же правилам, что интерфейс: новые падения, исправления и повторяющиеся проблемы.

list_attachments находит файлы результата, read_attachment читает текстовые логи и изображения PNG/JPEG/WebP до 2 МБ. Длинный текст читается частями; архивы и видео нужно открыть в интерфейсе. Для анализа изображения подключённая модель должна поддерживать зрение.

Встроенный ассистент также предлагает редактируемые черновики нового ручного кейса и плана перепроверки. Сохранение происходит только после вашего подтверждения и с вашими правами. Исходный кейс не меняется, план сохраняется в статусе «Черновик» и не запускает тесты автоматически.

Запись

Нужен токен со scope write: create_test_case, update_test_case, import_test_cases, create_defect, update_defect, create_folder, update_folder, set_case_placement, create_folder_tree, update_folder_tree, add_case_comment, add_defect_comment, create_launch, set_launch_case_result, finish_launch, create_dataset, update_dataset, create_dataset_item, update_dataset_item.

Постраничность у списков — page и limit, по умолчанию 20, максимум 100. У list_case_runs свои значения: 5 по умолчанию, максимум 50.

Особенности работы инструментов

Перед изменениями прочитайте текущее состояние и учитывайте правила замены полей и завершения Launch.

Агенту передаётся рекомендация писать новые описания кратко: цель и границы проверки, 2–4 предложения, ориентир до 600 символов. Для подробного описания попросите об этом явно. Текст не обрезается автоматически; правило не требует сокращать существующие записи или импорт.

Для новых значений сервер проверяет отдельные пределы: описание кейса и плана, предусловия и общий ожидаемый результат — до 10 000 символов на поле; действие и ожидаемый результат шага, в том числе вложенного или общего, — до 2 000; комментарий — до 2 000. Превышение отклоняет всю запись. При импорте такой кейс отмечается как отклонённая строка с причиной. Текст не обрезается.

Создания и редактирования тест-планов через внешние MCP-инструменты нет: агент может подготовить черновик для UI. create_launch создаёт запись запуска, не заменяет тест-план и сам не запускает CI или Eval.

list_test_case_statuses возвращает настроенные статусы кейсов, включая ещё не использованные. Используйте их для фильтра и изменения статуса; результаты выполнения вроде passed и failed — другое поле.

list_launches отдаёт старые сначала

Порядок по умолчанию — по дате создания по возрастанию. Это не совпадает со списком в интерфейсе (там новые сверху). Чтобы получить свежие прогоны первыми, укажите: sort: "created", dir: "desc".

Папки: переименование и размещение

update_folder и update_folder_tree переименовывают папку и дерево. Для размещения кейса используйте set_case_placement с treeId и folderId. folderId в создании или обновлении кейса не задаёт размещение.

Удаление папок и деревьев через MCP не предоставлено; используйте UI.

Шаги затираются целиком

steps в update_test_case заменяет весь список, а не дополняет. Отдельная ловушка — общие шаги: шаг может быть только ссылкой (sharedStepGroupId) с пустым текстом действия. Прочитали кейс, не заметили ссылку, записали шаги обратно — кейс молча отвязался от группы. Прежде чем писать, посмотрите list_shared_steps.

linked*-массивы у дефекта заменяются так же, целиком.

Пишущие инструменты кейса сохраняют вложенные subSteps и их ожидаемые результаты до пяти уровней. Неизвестные поля MCP отклоняет вместо молчаливого удаления.

Для изменения кейса через MCP нужен expectedRevision из прочитанного editRevision. Если другой редактор уже изменил кейс, сервер вернёт 409 без сохранения. Прочитайте свежую версию и перенесите в неё свою правку; не отправляйте старый снимок с новой версией.

Кастомные поля ведут себя иначе, чем шаги

• customFields сливаются по ключу — в отличие от шагов;
• неизвестный, архивный или выключенный ключ — это 400, а не тихое игнорирование;
• null — единственная универсальная «очистка»: пустая строка чистит текст, список и дату, но для числа и галочки она недопустима.

Импортированные автотесты правятся не полностью

У кейса, приехавшего из отчёта, update_test_case отклоняет steps и type с кодом 409: этими полями владеет следующий импорт. Всё остальное — имя, владелец, статус, теги, тип теста, приоритет, важность, риск, ревьюер — правится обычным образом.

Ревью может не пустить кейс в Active

При обязательном одобрении переход в Active без него даёт 409. Изменение содержимого сбрасывает одобрение только при включённом Reset approval after edits. Смена только статуса или ревьюера его не сбрасывает.

Ручной прогон нужно закрыть

Порядок: create_launch → set_launch_case_result → finish_launch.

Результат можно поставить только в running Launch. Запись последнего вердикта сама не завершает Launch. finish_launch завершает его и переводит оставшиеся untested в skipped.

Незавершённые Launch видны в списках и части метрик, но не входят в средний pass rate завершённых Launch.

Датасеты закрыты выключателем проекта

Записи в датасеты отвечают 403, если в проекте выключена функция Eval tests — даже с токеном на запись. Код тот же, что у отказа по scope, различает только текст. Чтение датасетов этим выключателем не закрыто.

Комментарий всегда от владельца токена

Автором комментария становится владелец токена. Указать другого автора нельзя.

Фильтры в списках строгие

Несколько значений передаются одним параметром через запятую; повторить ключ можно — значения объединятся так же, как через запятую, а дубликаты отбросятся. Значения словарных фильтров сверяются точно: опечатка даёт ноль строк, а не ошибку. Значений в одном фильтре не больше 50.

Коды ошибок

Импорт через агента

1. Вызовите import_test_cases с dryRun: true.
2. Проверьте предложенные соответствия, примеры кейсов и список decisions.
3. Повторите вызов с файлом, настройками, dryRun: false и идентификаторами согласованных решений в accepted.

Лимиты вызова: 20 000 кейсов и 400 000 символов содержимого. Большой файл передавайте в POST /api/projects/:projectId/test-cases/import как multipart. Форматы, сопоставление полей и ограничения.

CLI и CI

CLI запускает вашу команду тестов, отправляет результаты в формате Allure Report в TestSpot и завершает Launch. Команда plan получает селекторы тестов, выбранных для Launch.

Как это работает

Чтобы подключить автотесты в CI, настройте адаптер Allure Report, задайте URL TestSpot, токен и проект в окружении джобы и оберните команду тестов в run. Ниже — что происходит при таком запуске; готовые примеры GitLab и GitHub Actions показывают настройку пайплайна.

1. CLI использует Launch из TESTSPOT_LAUNCH_ID (или TESTPILOT_LAUNCH_ID). Если ID не задан, находит или создаёт CI Launch по контексту GitLab/GitHub; при локальном запуске создаёт новый.
2. Запускает команду после --. Вывод тестов остаётся в терминале или логе CI.
3. Во время тестов отправляет готовые *-result.json из каталога результатов.
4. После выхода команды повторно читает результаты, добавляет фикстуры из *-container.json и окружение из environment.properties, затем отправляет вложения ZIP-батчами.
5. После успешной финальной отправки завершает Launch, если не задан --no-finish. При ошибке отправки оставляет его открытым для повторной загрузки. Упавшие тесты сами по себе завершению не мешают.

При успешном завершении Launch получает статус completed, оставшиеся untested становятся skipped, включая ручные проверки. Завершённый Launch не принимает новые CI-результаты.

По умолчанию CLI возвращает код тестовой команды. Добавьте --strict, чтобы ошибка настройки или отправки в TestSpot давала код 1 при успешно прошедших тестах. При ненулевом коде тестов сохраняется их код.

Исполняемые файлы

Самостоятельные сборки CLI запускаются без установленного Node.js или Bun. Для Linux x64 — testspot_linux_amd64, Linux ARM64 — testspot_linux_arm64, macOS Intel — testspot_darwin_amd64, Apple Silicon — testspot_darwin_arm64, Windows x64 — testspot_windows_amd64.exe. Linux требует glibc; сборки macOS/Windows пока без цифровой подписи. На Linux/macOS выдайте файлу право исполнения через chmod +x.

Готовые файлы и SHA256SUMS публикуются в GitHub Releases TestSpot CLI. Совместимые файлы .mjs по-прежнему скачиваются с API стенда и требуют Node.js 20+.

Загрузка, выбор тестов и параллельные jobs

• ./testspot upload allure-results загружает готовый каталог; ошибка отправки возвращает код 1. Если в прогоне есть ручные кейсы, run и upload оставляют его открытым для их выполнения. После ручной части завершите прогон кнопкой Finish или командой finish.
• ./testspot doctor проверяет соединение, токен и чтение проекта. Для отправки нужны права записи.
• ./testspot plan --format allure --output-file testplan.json экспортирует план Allure Report.
• ./testspot run --select -- <команда> получает план выбранного запуска и передаёт ALLURE_TESTPLAN_PATH раннеру. Пустой план или ошибка запроса останавливают запуск. Адаптер должен поддерживать выборочное исполнение.
• --no-finish оставляет общий запуск открытым. Задайте одинаковый LAUNCH_ID всем шардам; после всех успешных загрузок отдельная зависимая job вызывает ./testspot finish.
• --output-file summary.json сохраняет ID, ссылку, статистику и признак ошибки репортинга. Ссылка использует адрес API: при внутреннем адресе раннера замените origin на браузерный.
• --help и --version работают без соединения.

Вложения используют новый эндпоинт /results/attachments/batch; старый сервер ответит 404. Повторы после частичного отказа хранилища не создают дубликатов. --ignore-passed-test-attachments исключает вложения успешных тестов, сохраняя фикстуры. --exclude-files принимает регулярное выражение JavaScript для путей вложений. --max-attachment-size по умолчанию 16 MiB: большие файлы пропускаются с предупреждением. --batch-size задаёт бюджет ZIP, по умолчанию 20 MiB, максимум 50 MiB. Файл вместе с необходимыми метаданными должен помещаться в один батч.

При ошибке финальной отправки запуск остаётся открытым. Сохраните каталог как CI-артефакт и повторите upload с прежним LAUNCH_ID. Каждый новый прогон должен писать в свежий каталог.

Токен

В API tokens → New token выпустите токен Read & write от аккаунта с правом записи в проект. Сохраните его в секретах CI.

CLI показывает ошибки репортинга в stderr. По умолчанию они не меняют код завершения тестов; для отказа джобы при неудачном репортинге используйте --strict.

Для общей CI-интеграции можно выделить отдельный аккаунт Writer: он занимает платное место. Деактивация владельца токена прекращает репортинг.

Установка

Для варианта .mjs ниже нужны Node.js 20 или новее, доступ к вашему TestSpot и API-токен. CLI поставляется одним файлом с зависимостями. Примеры shell рассчитаны на Bash; самостоятельная сборка не требует Node.js.

1. Задайте адрес TestSpot без /api и без завершающего слеша, публичный ID проекта из URL его страницы и токен.
2. Скачайте CLI со своего стенда.
3. Настройте адаптер Allure Report для runner на запись сырых JSON-результатов в allure-results.

export TESTSPOT_URL="https://tms.example.com"
export TESTSPOT_PROJECT="1234"
# В CI задайте TESTSPOT_TOKEN через хранилище секретов.
# Локально в Bash введите токен без отображения на экране:
read -rsp 'TestSpot API token: ' TESTSPOT_TOKEN
export TESTSPOT_TOKEN
printf '\n'

curl -fsS -H "Authorization: Bearer $TESTSPOT_TOKEN" \
  "$TESTSPOT_URL/api/downloads/testspot-cli" -o testspot.mjs

Файл скачивается из текущего развёртывания TestSpot. Сохраните его вместе с настройкой CI, если не хотите скачивать заново в каждой джобе; после обновления стенда скачайте обновлённый файл. Публикация в npm и установка через GitHub Releases в этой инструкции не используются.

Совместимые имена testpilot.mjs, /api/downloads/cli и переменные TESTPILOT_* продолжают работать. Ниже CI-примеры используют этот набор, поскольку TestSpot передаёт контекст запуска с префиксом TESTPILOT_.

Проверить подключение

В TESTSPOT_URL укажите конечный HTTPS-адрес TestSpot. CLI не следует HTTP-редиректам: если прокси переводит HTTP на HTTPS или меняет домен, задайте конечный адрес сразу.

Эти запросы проверяют токен и доступ к проекту, не создавая Launch. Успешное чтение ещё не подтверждает право записи.

curl -fsS -H "Authorization: Bearer $TESTSPOT_TOKEN" \
  "$TESTSPOT_URL/api/auth/me"
curl -fsS -H "Authorization: Bearer $TESTSPOT_TOKEN" \
  "$TESTSPOT_URL/api/projects/$TESTSPOT_PROJECT/overview"

Запустить тесты: run

node testspot.mjs run [--results <dir>] [--strict] -- <command…>

Для проекта с уже настроенным allure-playwright:

node testspot.mjs run --strict --results allure-results -- npx playwright test

Откройте Launches в указанном проекте и найдите созданный Launch. Результаты появляются во время работы тестов; фикстуры и вложения загружаются после выхода команды.

Runner должен записывать результаты прямо в указанный каталог: поиск JSON не проходит по вложенным папкам. Используйте отдельный чистый каталог для каждого прогона — CLI перечитывает все файлы, включая оставшиеся от предыдущих тестов. HTML-отчёт allure-report не подходит.

Для последовательности команд, перенаправлений и конвейеров в Linux/macOS запускайте shell явно, например node testspot.mjs run -- bash ./ci-tests.sh. CLI не настраивает адаптер Allure Report и не ограничивает набор тестов автоматически.

Полный список команд и флагов доступен через node testspot.mjs --help. Для выборочного исполнения используйте run --select с адаптером Allure Report, поддерживающим тест-план, либо настройте фильтр runner по результату plan.

Переменные окружения

Для каждого перечисленного имени поддерживается вариант TESTSPOT_*; он имеет приоритет над TESTPILOT_*, даже если задан пустым. Для новой настройки используйте один согласованный набор имён.

Повторная отправка результатов и повторный запуск

Повторная отправка одного результата в running CI Launch обновляет существующую строку. Завершённый Launch новые результаты не принимает.

Без явно заданного LAUNCH_ID CLI находит или создаёт Launch по идентификатору внешнего запуска:

• GitLab: CI_PROJECT_ID, CI_PIPELINE_ID, CI_JOB_ID;
• GitHub: репозиторий, run ID, attempt, GITHUB_JOB и TESTSPOT_JOB_KEY. Без JOB_KEY каждая команда создаёт отдельный запуск, включая matrix jobs. Для повторяемой идентичности задайте уникальный ключ на комбинацию матрицы.

Тот же набор значений возвращает тот же Launch. Изменение ID джобы или номера попытки создаёт другой Launch. Вне этих CI используется случайный идентификатор, поэтому следующий вызов создаёт новый Launch.

Если задан TESTSPOT_LAUNCH_ID или его совместимый вариант TESTPILOT_LAUNCH_ID, CLI отправляет результаты в указанный Launch. Для повторного выполнения завершённого прогона создайте новый.

Прогон плана из датасетов

Когда запускают план из датасетов (или выборку строк датасета), TestSpot добавляет в переменные пайплайна ещё две:

Отчёт возвращается своим запросом, в уже созданный запуск:

curl -fsS -X POST \
  "$TESTPILOT_URL/api/projects/$TESTPILOT_PROJECT/launches/import-eval" \
  -H "Authorization: Bearer $TESTPILOT_TOKEN" \
  -F "launchId=$TESTPILOT_LAUNCH_ID" \
  -F "file=@eval-report.json"

Поле launchId здесь и отличает «отчёт вернулся в свой прогон» от «кто-то загрузил отчёт» — во втором случае создаётся отдельный запуск.

Готовые сниппеты

GitLab

tests:
  stage: test
  image: node:20
  variables:
    TESTPILOT_URL: "https://tms.example.com"
    TESTPILOT_PROJECT: "1234"
    # TESTPILOT_TOKEN — переменная проекта или группы: Settings → CI/CD → Variables,
    # Masked + Protected, от аккаунта с правом записи в проект.
  script:
    - npm ci
    - npx playwright install --with-deps
    - curl -fsS -H "Authorization: Bearer $TESTPILOT_TOKEN"
        "$TESTPILOT_URL/api/downloads/cli" -o testpilot.mjs
    - node testpilot.mjs run --results allure-results -- npx playwright test
  artifacts:
    when: always            # именно на красном прогоне артефакт и нужен
    expire_in: 1 week
    paths: [allure-results]

GitHub Actions

name: tests
on: [push, pull_request]

jobs:
  playwright:
    runs-on: ubuntu-latest
    env:
      TESTPILOT_URL: "https://tms.example.com"
      TESTPILOT_PROJECT: "1234"
      # Секрет репозитория или организации: Settings → Secrets and variables → Actions.
      TESTPILOT_TOKEN: ${{ secrets.TESTPILOT_TOKEN }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx playwright install --with-deps
      - run: |
          curl -fsS -H "Authorization: Bearer $TESTPILOT_TOKEN" \
            "$TESTPILOT_URL/api/downloads/cli" -o testpilot.mjs
      - run: node testpilot.mjs run --results allure-results -- npx playwright test
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: allure-results
          path: allure-results
          retention-days: 7

Зачем сохранять allure-results артефактом. Это тот самый прогон, на который потом смотрят, — и запасной путь, если отправка в TestSpot не прошла. Сохранять нужно и на красном прогоне: именно там артефакт и нужен.

Получение выбранных автотестов: plan

node testspot.mjs plan выводит селекторы автоматизированных кейсов выбранного Launch, по одному на строку. Нужны URL, токен, проект и TESTSPOT_LAUNCH_ID (либо совместимые переменные TESTPILOT_*).

Команда не переводит селектор в синтаксис runner. Сначала проверьте формат, который записывает ваш адаптер Allure Report. Перед запуском тестов проверьте код завершения команды и непустой результат: пустой набор аргументов у некоторых runner запускает весь набор тестов.

# Выполняйте в скрипте джобы. Файл содержит селекторы для вашего runner.
node testspot.mjs plan > selectors.txt || exit 1
if [ ! -s selectors.txt ]; then
  echo "В Launch нет селекторов для запуска" >&2
  exit 1
fi
# Преобразуйте selectors.txt в аргументы или фильтр вашего runner.

Ошибка конфигурации или запроса даёт stderr и код 1. В текстовом формате успешный ответ может содержать пустой список.

plan --format allure --output-file testplan.json сохраняет JSON-план для адаптера Allure Report; пустая выборка в этом формате даёт код 1. Без --output-file результат выводится в stdout.

plan не запускает тесты. Он возвращает сохранённые в Launch непустые селекторы, без фильтрации по результату; строки без селектора пропускаются. PLAN_ID не заменяет обязательный LAUNCH_ID. Команда не выбирает строки Datasets.

Коды выхода

Таймауты и повторы

• у обычного запроса таймаут 30 секунд, у ZIP-батча вложений — 120 секунд;
• создание Launch, проверка подключения, получение селекторов и отправка батчей результатов и вложений повторяются при сетевой ошибке, 429 и любом 5xx — три повтора с задержками 1, 2 и 4 секунды. На обычной 4xx повторов нет;
• CLI проверяет новые файлы каждые 2 секунды. Файл готов к отправке, когда его размер и время изменения не менялись между двумя проверками;
• за один запрос уходит не больше 100 файлов при стриминге и не больше 200 в сверочном проходе.

Батч вложений также повторяется при частичном отказе хранилища. Завершение Launch выполняется без автоматического повтора. Статус completed сам по себе не подтверждает полноту отчёта: Launch можно закрыть вручную, а фильтры вложений могут исключить файлы. Проверьте итоговую статистику и предупреждения CLI.

Что передаёт TestSpot, когда запускает пайплайн сама

Кнопка Run триггерит пайплайн и передаёт TESTPILOT_PROJECT и TESTPILOT_LAUNCH_ID — то есть какой прогон пополнять, и связь с Launch (плюс TESTPILOT_PLAN_ID, если запуск создан из тест-плана). Всё остальное — переменные вашего пайплайна. В GitLab контекст PROJECT, LAUNCH_ID и PLAN_ID также передаётся с префиксом TESTSPOT_, чтобы оба варианта CLI пополняли выбранный прогон.

Задайте TESTPILOT_URL в переменных CI: нужен адрес TestSpot, доступный с раннера. Он может отличаться от адреса, по которому вы открываете приложение в браузере.

Для запуска выбранных тестов используйте run --select с поддерживающим тест-планы адаптером Allure Report. Другой вариант — получить селекторы через plan и передать их фильтру runner. Сохраняйте переданный LAUNCH_ID: одна кнопка Run не меняет команду тестов в вашем CI.

В GitHub Actions объявите входы TESTPILOT_PROJECT, TESTPILOT_LAUNCH_ID и TESTPILOT_PLAN_ID в workflow_dispatch и перенесите их из inputs в окружение шага CLI. Пример выше с push/pull_request создаёт самостоятельные Launch.

Для обычных переменных приоритет идёт от значений соединения к плану и затем к изменению в форме запуска. Запуск по расписанию использует значения плана. Пустая строка переопределяет значение, не удаляя ключ. GitLab получает значения буквально: знаки $ не раскрывают другие переменные; многострочные поля сохраняют переносы строк.

Перед запуском тест-плана через CI под подключением показана компактная сводка ветки и параметров. При массовом запуске выбранных кейсов откройте вкладку CI: там находятся подключение, ветка, параметры и дополнительные переменные. Нажмите шестерёнку рядом со сводкой, чтобы открыть окно редактирования ветки и параметров. «Применить» сохраняет правки для запуска, «Отмена» или Escape отбрасывают черновик. Кнопка сброса рядом с шестерёнкой возвращает исходные значения. Правки действуют только для этого запуска. При выборе другого подключения разовые правки параметров сбрасываются; сохранённые настройки подключения и тест-плана не меняются.

Повторить выбранные результаты

В меню завершённого запуска выберите Re-run, отметьте статусы и нужные тесты. TestSpot запустит GitLab pipeline и обновит результаты в этом же запуске. Невыбранные строки сохранят результаты; прежние исходы повторённых тестов останутся в истории попыток. Если job не пришлёт новый результат, прежний исход сохранится.

Для rerun используйте актуальный CLI. Он получает идентификатор попытки из TESTSPOT_RERUN_ID (совместимое имя TESTPILOT_RERUN_ID), передаёт его серверу и автоматически включает выборку по тест-плану Allure Report, даже без флага --select. Runner должен поддерживать тест-план Allure Report; pytest с allure-pytest проверен. Варианты параметризованного теста могут исполняться вместе по одному selector, но обновятся только выбранные результаты. Запоздавшая job другой попытки будет отклонена.

Поле плана Default CI connection позволяет сохранить GitLab или GitHub: выбранный провайдер используется при открытии формы запуска и по расписанию. Выборочный rerun из меню запуска в этой версии поддерживает GitLab.

Не задавайте постоянный LAUNCH_ID в настройке всех jobs. Секреты храните в CI: значения форм TestSpot видны в Environment прогона. Маскирование GitLab скрывает секрет в логе job, но не в файлах Allure Report — не прикладывайте секреты в stdout, скриншотах и других артефактах.

Тесты в контейнере

CLI должен видеть каталог, куда пишет runner. Если CLI работает снаружи контейнера, смонтируйте этот каталог и запускайте контейнер без фонового режима: завершение команды должно означать завершение тестов.

Если CLI работает внутри контейнера, передайте ему URL, токен и проект, а для Launch из TestSpot — LAUNCH_ID. Для автоматического определения запуска GitLab/GitHub нужны также соответствующие переменные CI из раздела повторных запусков. Без них и без LAUNCH_ID каждый вызов создаёт новый Launch.

Если результаты не появились

--strict проверяет ошибки операций, а не полноту прогона. Нечитаемые JSON пропускаются при чтении; код 0 не доказывает, что выполнен весь ожидаемый набор. Сопоставьте состав и результаты Launch с выполненными тестами.

API и токены

Для скриптов и CI используйте персональный API-токен. Он действует с правами владельца, но не даёт доступа к администрированию стенда, управлению аккаунтом и токенами или действиям владельца проекта.

Выпустить токен

В интерфейсе: страница API tokens (/settings/tokens) — она личная, не админская. Поля: Name (по нему потом искать, чей это токен и зачем), Access — Read only или Read & write, и Expires — 30 дней, 90 дней, год или без срока.

Токен не умеет двух вещей независимо от доступа: управлять токенами и менять аккаунт. Отозванные скрыты из списка, но остаются на сервере для истории — под списком стоит строка «N revoked hidden».

Создать токен также можно через API с JWT браузерной сессии:

curl -X POST https://tms.example.com/api/auth/tokens \
  -H "Authorization: Bearer <JWT браузерной сессии>" \
  -H "Content-Type: application/json" \
  -d '{"name": "ci pipeline", "scope": "write"}'

Scope: read и write

Токен не расширяет права. Он действует от имени своего владельца: то, чего пользователь не может в интерфейсе, его токен тоже не может.

Как обращаться

curl -fsS -H "Authorization: Bearer $TESTPILOT_TOKEN" \
  https://tms.example.com/api/projects

Базовый путь — /api. Проект в путях адресуется своим публичным идентификатором — тем числом, которое видно в адресной строке на странице проекта.

Подключение ИИ-агента с этой же страницы

Под списком токенов — панель Connect an AI assistant: выбираете клиента (Claude Code, Cursor, Codex), и она собирает готовый конфиг или однострочную команду, подставив только что выпущенный токен. Что агент получает и какими правами — на странице «MCP».

OpenAPI и Swagger UI

На странице API tokens доступны ссылки Swagger UI и OpenAPI JSON. Справочник находится по адресу /api/docs/ вашего экземпляра TestSpot, машиночитаемое описание — /api/openapi.json. Ресурсы Swagger поставляются с приложением: внешнее подключение к интернету не требуется.

В Swagger нажмите Authorize и вставьте персональный токен без префикса Bearer. Затем выберите операцию и нажмите Try it out → Execute. Запрос выполняется на вашем экземпляре с правами владельца токена; операции записи и удаления изменяют реальные данные. После перезагрузки страницы токен нужно ввести заново.

Справочник описывает все 297 HTTP-операций приложения: проекты, кейсы и общие шаги, импорт/экспорт и массовые изменения, папки и деревья, планы, прогоны и CI rerun, датасеты, ревью, дефекты, релизы, настройки проекта, участников, параметры окружения, вложения, авторизацию, админку, аналитику, интеграции, уведомления, ассистента и MCP. У каждого метода указан способ авторизации. Для сессионных операций выберите sessionAuth и используйте JWT входа; персональный API-токен для них не подходит. Схемы ответов описывают известные поля и допускают дополнительные; настройки проекта и его права проверяются сервером. При загрузке Allure проверяйте счётчики accepted, created и updated: отдельные некорректные результаты могут быть пропущены.

Эндпоинты, которые обычно и нужны

Базовый путь — /api. Проект адресуется публичным идентификатором из адресной строки.

Приём результатов прогона

Тест-кейсы

Остальное

Имена метрик

Поддерживаемые значения metric:

• kpi: kpi.totalRuns, kpi.neverRun, kpi.unassignedCases, kpi.totalLaunches, kpi.avgPassRate, kpi.openDefects, kpi.flakyRate, kpi.avgDuration, kpi.testCaseCount, kpi.automationCoverage, kpi.healthScore.
• breakdown: breakdown.runsByStatus, breakdown.launchesByBranch, breakdown.testCasesByOwner, breakdown.launchesByStatus, breakdown.defectsBySeverity, breakdown.defectsByStatus, breakdown.testCasesByStatus, breakdown.testCasesByPriority, breakdown.testCasesByType.
• list: list.slowestTests, list.recentLaunches, list.topFlakyTests, list.topFailingTests, list.recentDefects.
• trend: trend.flaky, trend.defectsCreated, trend.casesCreated, trend.passFail, trend.launchVolume, trend.passRate, trend.duration.
• widget: widget.automation, widget.automationTrend, widget.coverageMap, widget.lastLaunch, widget.launchTrend, widget.lowSuccess.

Для временных метрик задайте range, например 30d; максимальное окно — 180 дней. Не все метрики используют период. Неизвестное имя даёт 404.

Ограничения частоты

По умолчанию действует лимит 500 запросов в минуту по предъявленному токену, а без токена — по адресу клиента. Отдельные маршруты заменяют этот лимит своим: вход — 120 запросов в минуту по адресу и 10 ошибок за 15 минут на аккаунт, приём результатов прогона — 6000 запросов в минуту. У дорогих операций лимиты строже.

Лимиты входа общие для всех backend-реплик через PostgreSQL и настраиваются оператором. Счётчики остальных API-лимитов локальны для каждой реплики; для них общий лимит задаётся на внешнем шлюзе. За nginx необходимо указать доверенные прокси, иначе попытки входа разных пользователей попадут в общий счётчик адреса nginx.

Превышение — это 429. CLI на него повторяет запрос с задержками 1, 2 и 4 секунды; свой скрипт должен учитывать заголовок Retry-After. При входе дождитесь указанного числа секунд: повторные попытки не продлевают блокировку.

Ротация и отзыв

• Токен отзывается на той же странице API tokens; отзыв действует сразу.
• Токены живут у пользователя, а не у проекта: отключение или удаление пользователя обрывает всё, что ходило его токенами. Для CI поэтому нужен отдельный сервисный аккаунт, а не личный аккаунт автоматизатора.
• Меняете токен в пайплайне — сначала выпустите новый, подставьте в секреты CI, убедитесь, что джоба отчитывается, и только потом отзывайте старый.

Интеграции

Администратор задаёт адреса внешних систем и выдаёт доступ проектам. Каждое подключение внутри проекта хранит собственный токен. Ключи AI-моделей остаются у администратора.

Две половины одной интеграции

Проект видит выданные ему соединения и ранее настроенные подключения. При отзыве доступа сохранённые настройки остаются видимыми.

Категории соединений: CI (GitLab, GitHub), Messengers (Telegram, Slack), Task trackers (Jira Cloud и Jira Server/DC), Models (отдельная страница).

CI: GitLab и GitHub

1. Администратор создаёт соединение GitLab или GitHub в Admin → Connections и выдаёт его проекту.
2. В Integrations проекта добавьте цель CI: для GitLab — проект и ветку; для GitHub — ссылку на репозиторий, файл workflow и ветку.
3. Введите токен этого подключения, нажмите Test и сохраните настройки. Проверка ничего не сохраняет и не запускает pipeline. Пустое поле при редактировании сохраняет прежний токен.

Remove удаляет подключение вместе с его токеном в TestSpot. Токены соседних подключений не меняются; отзыв токена у провайдера выполняется отдельно.

GitHub-репозиторий должен относиться к выбранному соединению. Поддерживаются github.com и GitHub Enterprise Server. Целей может быть несколько; отметка по умолчанию есть у GitLab.

Выберите CI в диалоге запуска плана, выбранных кейсов или строк датасета. TestSpot передаст идентификаторы и переменные запуска. URL платформы и токен для репортинга задаются в CI отдельно. Переменные запуска.

Для GitLab действует сверка незакрытых Launch с пайплайном. Для GitHub завершение репортинга должна выполнить джоба.

Мессенджеры: Telegram и Slack

1. Администратор создаёт соединение Telegram или Slack и выдаёт его проекту.
2. В Integrations проекта выберите соединение и укажите чат Telegram или канал Slack. Введите бот-токен этого подключения; для Telegram при необходимости задайте тему. Сохраните настройки. Проверка доставки отправляет тестовое сообщение в выбранный канал.
3. Выберите получившийся канал в правилах оповещений или настройте доставку отчётов.

Slack использует bot-токен, а не incoming webhook. Серверу нужен доступ к API выбранного мессенджера.

Трекер задач

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

Способ аутентификации

У соединения с трекером его нужно выбрать: API-токен, персональный токен (PAT) или логин с паролем. Для Jira Cloud обычно API-токен, для Server/DC — PAT; выбор не угадывается автоматически, поэтому это отдельное поле.

Живой статус соединения

Токен и логин задаются в подключении проекта. Test connection проверяет доступ, а успешная проверка не меняет токены других подключений.

Ещё у соединения есть свой выключатель на стороне администратора, независимый от выдачи проектам: выключенное соединение перестаёт проверяться и обслуживать кнопки, оставаясь настроенным.

Что можно связать с задачей

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

Панель в тикете Jira

Одна кодовая база и две цели установки.

Jira Data Center

1. Скачайте JAR или ZIP с инструкцией из GitHub Releases TestSpot Jira. Контрольные суммы файлов опубликованы в SHA256SUMS.
2. Загрузите JAR через Administration → Manage apps → Upload app.
3. На Jira задайте JVM-параметры testspot.panel.baseUrl и testspot.panel.secret, затем перезапустите Jira.
4. На TestSpot задайте совпадающий PANEL_CONTEXT_SECRET_DC, внешний адрес APP_BASE_URL и origin вашей Jira в JIRA_FRAME_ANCESTORS.
5. Откройте тикет и нажмите Connect TestSpot. Каждый пользователь подключает свою учётную запись.

Панель уже входит в образ фронтенда TestSpot и раздаётся по адресу /embed/jira/. Подробная инструкция по установке описывает настройки для Linux, Windows, Docker и Kubernetes.

Jira Cloud

1. Собрать и развернуть приложение Forge (forge deploy, затем forge install).
2. В манифесте разрешить исходящий доступ к вашему хосту и задать базовый адрес API TestSpot.
3. Положить секрет панели в переменные Forge — он должен совпадать с PANEL_CONTEXT_SECRET_CLOUD на сервере.

Комментарий в тикет по завершении прогона

Функция по умолчанию выключена. При включении TestSpot добавляет в тикет один комментарий на завершённый запуск.

Ошибка отправки комментария не мешает завершить запуск. Если комментарий не появился, проверьте доступность трекера и права подключения; администратор может найти причину в логах TestSpot.

Пользователи и доступ

Две независимые системы прав: роль аккаунта на весь стенд и роль в конкретном проекте. Аккаунтная роль viewer сильнее любой проектной.

Роли аккаунта

Объявления

В Admin → Announcements ТМС-администратор может опубликовать одно общее объявление с текстом и необязательной ссылкой. Оно видно всем вошедшим пользователям, независимо от доступа к проектам. Перед публикацией доступен предпросмотр; Unpublish снимает объявление у всех.

Закрытие объявления сохраняется для аккаунта. Каждая новая публикация заменяет предыдущую и снова показывается всем, в том числе тем, кто уже закрыл старое объявление.

Admin → Access

Два переключателя на весь стенд:

• Self-registration — человек может зарегистрироваться сам и получит роль Writer;
• Writers can create projects — администратор может создавать проекты всегда, независимо от этого переключателя.

Добавление пользователя: имя, email, пароль, роль. При создании и смене пароля минимум — 12 символов для Admin и 8 для Writer/Viewer. Новый пароль должен содержать заглавную и строчную буквы, цифру и спецсимвол, например ! или @. Кириллица поддерживается; пробел не считается спецсимволом. Это правило действует при создании, самостоятельной смене и сбросе пароля, включая создание первого администратора. Существующие пароли продолжают работать; повышение роли само по себе не проверяет длину прежнего пароля. Дальше в строке пользователя доступны:

• смена роли — для своей собственной строки выключена;
• Set a new password — единственный путь восстановления доступа: самостоятельного сброса по email в продукте нет. Свой пароль пользователь, уже вошедший в систему, меняет сам — в Profile;
• Deactivate / Activate — отключает или восстанавливает доступ. История действий аккаунта сохраняется.

Сессии и выход из аккаунта

Сессия продлевается автоматически, пока она действительна. Для завершения работы используйте выход в меню пользователя. Для CI и интеграций выпускайте отдельные API-токены.

Смена или сброс пароля отзывает прежние сессии на всех устройствах. При смене своего пароля текущий браузер получает новую сессию с прежним выбором «запомнить меня». После администраторского или CLI-сброса войдите заново. Сам сброс пароля не отзывает API-токены. Деактивация аккаунта отзывает их; после повторной активации для интеграций нужны новые токены.

Системный аудит

Системный аудит записывает входы и выходы, работу с сессиями и API-токенами, изменения административных настроек, отказы и ошибки. Аудит проекта находится отдельно в Audit Log.

Отдельного экрана системного журнала нет. Администратор читает его через GET /api/admin/audit?page=1&limit=100 с токеном браузерной сессии; персональный API-токен здесь не подходит. Новые события идут первыми.

События содержат пользователя, действие, цель, результат, HTTP-код, IP и идентификатор запроса. Срок хранения и сбор технических логов настраивает оператор установки.

Группы

В Admin → Access создайте группу, выберите роль Writer или Viewer и добавьте аккаунты. Группу можно добавить в проект сразу целиком.

Добавление группы выдаёт доступ один раз. Дальнейшее изменение состава или роли группы, а также её удаление не меняют уже созданное членство в проекте. Меняйте его на вкладке Access проекта.

Роль Manager группой не выдаётся. При добавлении пропускаются уже имеющиеся участники, неактивные аккаунты и владелец проекта; результат показывает число пропусков.

Роли в проекте

Вкладка Access проекта.

Разрешения менеджера

В Access владелец или TMS Admin задаёт общий набор разрешений для всех менеджеров проекта.

Название «удаление сущностей» не означает запрет всех удалений для Writer: удаление планов, дефектов, релизов и неиспользуемых общих шагов доступно с правом записи; удаление датасетов также требует включённой функции Eval tests.

Перемещение кейсов и Launch в корзину, восстановление и окончательное удаление имеют отдельные права. Политика ревью доступна владельцу и TMS Admin. Настройка полей, типов и категорий ошибок требует права настройки проекта.

Отказ в доступе

Для изменения данных нужны одновременно подходящий scope токена, если используется API-токен, роль аккаунта и право в проекте. Роль аккаунта Viewer запрещает изменение данных проекта даже владельцу проекта.

Разрешения менеджера применяются к конкретным действиям. Они не заменяют обычное право Writer редактировать контент. При отказе проверьте свою роль и настройки Access.

MCP использует права владельца токена и аудит проекта. API-токены не дают доступа к администрированию стенда и действиям уровня владельца проекта.

Лицензия и места

Лицензия определяет число платных мест и срок доступа к установленному продукту. Набор функций не зависит от плана.

Установка ключа

1. Откройте Admin → Settings → License.
2. Вставьте полученный ключ и сохраните.

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

Что считается местом

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

На новом стенде без установленного ключа доступно одно платное место. Истечение установленной лицензии или неверная подпись ограничивают доступ по отдельному правилу ниже.

Состояния

Лицензия действует до конца указанного дня по UTC.

Истечение лицензии и восстановление доступа

При истечении установленной лицензии или недействительной подписи доступ сохраняется только у самого раннего действующего администратора. Он должен открыть настройки ТМС → Лицензия и установить действительный ключ. Остальным блокируются вход, действующие сессии, API-токены, MCP и скачивание файлов. Роли и членство в проектах сохраняются; после установки ключа доступ возвращается автоматически. Ранее деактивированные аккаунты остаются отключёнными.

На время блокировки приостанавливаются расписания тест-планов, отчётов и оповещений, AI-инсайты и другие фоновые действия проекта. Уже запущенный внешний CI-пайплайн не отменяется. Очистка данных по сроку хранения продолжается. Администраторы получают уведомления за 10, 3 и 1 день до истечения, при истечении и ошибке подписи.

Когда мест не осталось

Создание нового admin или writer и повышение viewer'а до них отклоняется сервером с кодом 409 и тем же текстом правила, что показан в интерфейсе. Проверка стоит на сервере, а не только в форме.

Если несколько пользователей одновременно занимают последнее свободное место, успешно завершится только одна операция. Это относится к созданию аккаунта, самостоятельной регистрации, повышению роли и восстановлению отключённого аккаунта. Остальные операции получат отказ без изменения аккаунтов.

Перед добавлением пользователя проверьте число занятых и доступных мест над формой.

Настройки проекта

Группа Config в меню проекта: поля кейсов, типы тестов и теги, окружения, категории падений, политика ревью и три переключателя функций.

Settings

В Settings настраиваются функции проекта: Eval tests для датасетов, Load tests для нагрузочных отчётов, AI features для обращений к модели.

В блоке Test case review владелец или TMS Admin включает ревью, выбирает ревьюера по умолчанию, круг проверяющих и правила самоодобрения, комментариев и сброса одобрения.

Require approval before Ready требует одобрения перед Active и запуском кейса. При включённом Reset approval after edits изменение одобренного содержимого требует нового решения; при обязательном одобрении Active-кейс возвращается в Draft. Прежнее решение сохраняется в истории.

Сохранение без изменения содержимого и смена только статуса или ревьюера одобрение не сбрасывают. Выключенное ревью не принимает новые запросы и решения. Отзыв открытого запроса не возвращает прежнее одобрение. Работа с ревью.

Fields

В Fields задайте режим встроенного поля: Off, Optional или Required. Отключение скрывает поле, сохраняя данные. Description хранит цель и описание теста отдельно от предусловий и ожидаемого результата. Test plans нельзя сделать обязательным.

Кастомные поля бывают text, number, select, date и checkbox. В проекте — до 30 полей. Ключ после создания не меняется; подпись и порядок можно изменить.

Обязательность проверяется у ручных кейсов в Active и Review. Checkbox нельзя сделать обязательным. Число 0 считается заполненным значением.

Archive скрывает кастомное поле из заполнения и сохраняет собранные ответы. Удаления поля вместо архивации нет.

Project Entities

В Project Entities настраиваются Test Types, Tags и Test case statuses: названия и цвета. Правила статусов описаны в руководстве по кейсам.

Переименование типа обновляет его в кейсах и общих шагах. Переименование тега обновляет его в кейсах, общих шагах и Launch.

Environments

Именованные параметры прогона — например «Environment», «OS», «Browser» — каждый привязан к имени переменной CI. Параметр бывает:

• Dropdown — заранее собранный список вариантов, у каждого своё значение для CI;
• Free text — значение вводится руками при каждом запуске.

Настроенные параметры доступны в диалогах запуска плана и прогона.

Failure Categories

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

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

Политика импорта и автоматический импорт по таймеру

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

Автоматический импорт по таймеру применяет импорт кейсов к Allure Report/CI-запускам после заданного срока от создания запуска. Примеры: 4min, 2h, 3d; диапазон — от минуты до 365 дней. off или 0 отключает правило; по умолчанию оно выключено. Сохраните значение, чтобы применить настройку.

Проверка выполняется раз в минуту и охватывает уже существующие запуски, включая завершённые. Она связывает результаты по ID или селектору, создаёт недостающие Auto-кейсы и завершает запуск. Предложения связать ручной кейс только по совпадению названия требуют выбора человека: без явного выбора будет создан новый кейс. Правила ревью и обновления полей сохраняются. Это отдельная настройка от сверки статуса пайплайна GitLab.

Хранение артефактов

Настройка стенда, а не проекта: четыре правила в Admin → Settings → Storage, все по умолчанию выключены. Разбор — в развёртывании.

Self-hosted: обзор

Установка TestSpot на своей инфраструктуре: подготовка, настройка и повседневная эксплуатация.

Путь от подготовки до эксплуатации

1. Спланируйте архитектуру и ресурсы, подготовьте PostgreSQL и S3.
2. Настройте сеть и HTTPS, получите комплект и выполните установку Helm.
3. Проверьте вход, импорт результата, вложения и MCP. Подключите мониторинг и резервирование.
4. Для следующей версии следуйте процедуре обновления; при отказе начните с диагностики.

Способ установки

Для одного сервера доступен готовый Docker Compose-комплект с PostgreSQL/MinIO или внешними сервисами. DEB/RPM-пакетов пока нет.

Что предоставляет TestSpot

Chart, образы приложения, миграции, примеры конфигурации и инструкции. Кластер, TLS, БД, S3, доступы, резервирование и доступность инфраструктуры обслуживает владелец установки. Приложению не нужны Redis и RabbitMQ.

Получите согласованную версию комплекта и отдельный read-only доступ к GitLab Registry и Package Registry. Доступ к исходному репозиторию не требуется. Установите готовые образы в своей инфраструктуре.

Архитектура и ресурсы

Два контейнера приложения и две внешние зависимости: PostgreSQL и S3. Спланируйте ресурсы, сетевые пути и резервирование до установки.

Компоненты

Ingress ──▶ frontend (nginx:8080) ──/api──▶ backend (node:3001)
                  │                ──/mcp──▶
            статика SPA                       Postgres + S3

Ingress нужен один, на frontend: /api и /mcp он проксирует сам, поэтому интерфейс, CLI и MCP работают по одному адресу. Разносить их по отдельным правилам не надо — /mcp, не дошедший до backend, провалится в SPA, и клиент получит index.html, то есть сообщит, что сервер сломан, а не что он недоступен.

Используйте frontend и backend из одного релиза. При обновлении заменяйте оба образа вместе.

Документация поставляется вместе с приложением и доступна по /docs, в том числе в закрытом контуре. Отдельная установка не требуется.

Helm-чарт содержит настройки frontend, backend, ingress и проверок готовности. Если при установке не хватает обязательного параметра, Helm укажет его имя: заполните значение и повторите установку.

Требования и планирование

Проверенный профиль — Kubernetes 1.34.0, узлы Linux amd64 и PostgreSQL 16. Приложение не хранит файлы на локальном диске: постоянные тома нужны зависимостям, а не frontend/backend. Один backend и два frontend — исходный production-профиль, а не обещание высокой доступности всей системы.

Спланируйте число пользователей, объём и частоту импортов, размер вложений и срок хранения. Начальные лимиты backend — 1 CPU / 2Gi RAM; крупные ZIP-архивы требуют проверки памяти на реальных данных. PostgreSQL и S3 масштабируются и резервируются отдельно.

До установки подготовьте БД, бакет, DNS/TLS и маршруты. Решите, кто отвечает за обновления, резервирование, мониторинг и восстановление. Проверьте ёмкость дисков и доступность копий независимо от основного кластера.

Установка через Docker Compose

TestSpot на одном Linux-сервере: готовые образы, PostgreSQL и MinIO в комплекте либо ваши внешние сервисы.

Получить комплект и запустить

Понадобятся Linux amd64, Docker Engine, Compose v2.20+ или v5, OpenSSL и от 4 ГБ RAM для небольшой установки. Размер диска выбирайте по объёму БД, вложений и резервных копий. Для отказоустойчивости используйте Kubernetes и внешние сервисы.

Поставщик выдаёт Deploy Token с правами read_registry, read_package_registry и лицензию. GitLab-аккаунт и доступ к исходникам не нужны. Комплект 0.0.2 содержит закреплённые версии образов и полную инструкцию README.md.

read -r -p 'Deploy Token login: ' DEPLOY_USER
read -r -s -p 'Deploy Token secret: ' DEPLOY_TOKEN; echo
BASE=https://gitlab.com/api/v4/projects/86465706/packages/generic/testspot-compose/0.0.2
curl --fail --user "$DEPLOY_USER:$DEPLOY_TOKEN" -O "$BASE/testspot-0.0.2-compose.tar.gz"
curl --fail --user "$DEPLOY_USER:$DEPLOY_TOKEN" -O "$BASE/testspot-0.0.2-compose.tar.gz.sha256"
sha256sum -c testspot-0.0.2-compose.tar.gz.sha256
tar -xzf testspot-0.0.2-compose.tar.gz
cd testspot-compose
printf '%s' "$DEPLOY_TOKEN" | docker login registry.gitlab.com -u "$DEPLOY_USER" --password-stdin
unset DEPLOY_TOKEN
./init.sh

В созданном .env укажите ADMIN_EMAIL. Пароль первого администратора — в ADMIN_PASSWORD. Сохраните этот файл в защищённом хранилище: он содержит пароли и ключ шифрования интеграционных секретов. Повторный init.sh откажется заменять существующий файл.

docker compose config --quiet
docker compose pull
docker compose up -d --wait --wait-timeout 300
docker compose ps

Откройте http://localhost:8080, войдите под первым администратором и активируйте лицензию в разделе лицензирования админки. Создайте проект и загрузите вложение. Для удалённого сервера можно временно использовать ssh -L 8080:127.0.0.2:8080 user@server.

Миграции выполняются отдельным контейнером migrate. Его завершение с кодом 0 — успешный результат. Backend запускается после миграций, frontend — после готовности API.

Своя БД и S3

В .env выберите COMPOSE_FILE:

• compose.yaml:compose.postgres.yaml:compose.minio.yaml — все сервисы в комплекте.
• compose.yaml — свои PostgreSQL и S3.
• compose.yaml:compose.minio.yaml — своя БД, комплектный MinIO.
• compose.yaml:compose.postgres.yaml — комплектная БД, свой S3.

Для внешней БД задайте DATABASE_URL=postgresql://user:password@db.company:5432/testspot?sslmode=require. Нужна отдельная БД PostgreSQL 16 и пользователь с правами на миграции. Спецсимволы логина/пароля кодируются для URL.

Для S3 задайте MINIO_ENDPOINT без протокола и пути, MINIO_PORT, MINIO_USE_SSL, MINIO_ACCESS_KEY, MINIO_SECRET_KEY, MINIO_BUCKET и MINIO_REGION. Для готового бакета — MINIO_CREATE_BUCKET=false. Приложению нужны чтение, запись, удаление объектов и listing бакета.

localhost внутри контейнера означает сам контейнер. Используйте доступный DNS внешнего сервиса. Переключение настроек не переносит существующие данные: для этого нужен отдельный backup/restore.

Домен и HTTPS

По умолчанию веб-порт доступен только на 127.0.0.2; порты БД и MinIO не публикуются. Поставьте перед ним ваш nginx или балансировщик с TLS. В .env задайте APP_BASE_URL=https://testspot.company и COOKIE_SECURE=true, затем повторите docker compose up -d --wait.

Для прокси на том же хосте оставьте HTTP_BIND=127.0.0.2. Для внешнего балансировщика укажите внутренний IP сервера и ограничьте доступ firewall. Пример nginx есть в README комплекта. Не меняйте COMPOSE_PROJECT_NAME: от имени проекта зависят volumes установки.

Резервная копия и обновление

До обновления остановите запись и сохраните .env, БД, S3 и версии образов. Для комплектных сервисов:

docker compose stop frontend backend
mkdir -p backups
chmod 700 backups
umask 077
cp .env backups/installation.env
docker compose exec -T postgres pg_dump -U testspot -d testspot -Fc > backups/database.dump
docker compose stop minio
docker compose run --rm -T --no-deps storage-backup -C /data -czf - . > backups/minio-data.tar.gz
docker compose up -d --wait --wait-timeout 300

Файловая копия MinIO снимается с остановленного сервиса и восстанавливается той же версией. Для внешних БД/S3 используйте их средства backup. Держите копию вне сервера и проверяйте восстановление; пошаговый restore приведён в README комплекта.

Получите новый комплект и release notes. Сохраните свои секреты, имя проекта и volumes. Перенесите новые Compose-файлы и обновите BACKEND_IMAGE и FRONTEND_IMAGE вместе значениями нового комплекта. PostgreSQL/MinIO обновляются отдельно по правилам этих продуктов.

docker compose pull
docker compose stop frontend backend
docker compose run --rm migrate
# Продолжайте только после успешной миграции:
docker compose up -d --wait --wait-timeout 300

Проверьте вход, лицензию, проект и скачивание старого вложения. Обновление выполняет администратор сервера. Автоматического отката схемы БД нет: возврат прежних образов допустим только при совместимой схеме; иначе восстановите согласованный backup в отдельной установке и проверьте его до переключения пользователей.

Закрытый контур

На машине с доступом к registry скачайте выбранные сервисы через docker compose pull и сохраните образы:

docker compose config --images | sort -u > images.txt
docker save -o testspot-compose-images.tar $(cat images.txt)
sha256sum testspot-compose-images.tar > testspot-compose-images.tar.sha256

Перенесите архив, checksum и Compose-комплект. Проверьте checksum, выполните docker load -i testspot-compose-images.tar, создайте .env и запустите docker compose up -d --pull never --wait --wait-timeout 300. Kubernetes airgap-архив содержит только образы приложения; PostgreSQL/MinIO для Compose нужно переносить тоже.

При использовании Harbor/Nexus/Artifactory замените четыре переменные *_IMAGE ссылками на импортированные образы и выполните docker login своего registry. Во время работы приложению не требуется GitLab.

Диагностика и удаление

docker compose ps -a
docker compose logs --tail=200 migrate backend frontend
docker compose exec backend curl -f http://127.0.0.2:3001/ready

docker compose down удаляет контейнеры и сеть, сохраняя данные. docker compose down -v уничтожает данные комплектных БД и MinIO. Для временной остановки используйте docker compose stop. Объекты внешних БД/S3 удаляет их администратор.

Установка в Kubernetes

Последовательная установка через Helm: namespace, секреты, конфигурация, первый вход и проверка результата.

Установка в Kubernetes: с чего начать

Этот путь рассчитан на администратора своего кластера. Понадобятся kubectl, Helm 3 с поддержкой OCI, ingress-контроллер, DNS и TLS-сертификат. Проверенный профиль — Kubernetes 1.34.0, Linux amd64, PostgreSQL 16 и S3-совместимое хранилище. PostgreSQL и S3 разворачиваются отдельно от chart.

На backend начните с requests 200m CPU / 512Mi RAM и limits 1 CPU / 2Gi RAM; на каждую из двух frontend-реплик — 10m / 32Mi и 200m / 128Mi. Это стартовые значения, нагрузку и размер импортируемых архивов проверьте на своём стенде.

1. Получите у поставщика версию, chart, release-values.yaml, release notes, verification.json и доступ read-only к registry. Для закрытой сети нужен airgap-архив с доверенной контрольной суммой.
2. Создайте отдельные БД и бакет по требованиям к зависимостям. Выберите адрес TestSpot, например testspot.example.com, и направьте DNS на ingress.
3. Создайте namespace и секреты, заполните my-values.yaml, выполните установку и приёмку.

Получить поставку

Для версии 0.0.2 поставщик передаёт готовый chart, release-values.yaml, values.production.yaml, release notes, результаты проверки и индивидуальную лицензию. Для скачивания выдаются username и Deploy Token; доступ к Git-исходникам и собственный CI-runner не нужны.

helm registry login registry.gitlab.com
# Username: выданный username; Password: Deploy Token.
helm pull oci://registry.gitlab.com/testspot-group/testspot-project/charts/testspot --version 0.0.2

Авторизация Helm действует на вашей рабочей машине. Для скачивания образов узлами кластера оператор отдельно создаёт imagePullSecret с тем же доступом.

Скачать airgap-комплект

Поставщик может передать архив и SHA256 файлами. Для самостоятельного скачивания выполните команды в Bash на Linux или macOS. При каждом запросе пароля curl вводите Deploy Token.

read -r -p 'Выданный username: ' TESTSPOT_USER
TESTSPOT_PACKAGE='https://gitlab.com/api/v4/projects/86465706/packages/generic/testspot/0.0.2'
for file in testspot-0.0.2-airgap.tar.gz.sha256 testspot-0.0.2-airgap.tar.gz; do
  curl --fail --location --user "$TESTSPOT_USER" --output "$file" "$TESTSPOT_PACKAGE/$file" || break
done
sha256sum -c testspot-0.0.2-airgap.tar.gz.sha256
# На macOS: shasum -a 256 -c testspot-0.0.2-airgap.tar.gz.sha256
mkdir testspot-0.0.2
tar -xzf testspot-0.0.2-airgap.tar.gz -C testspot-0.0.2

Распаковывайте архив только после успешной проверки. Сравните сумму также с переданной поставщиком. Продолжите по инструкции закрытого контура. Страница GitLab Releases может быть недоступна с клиентским токеном: используйте выданные OCI/API-адреса. Архивы «Source code» для установки не нужны.

Активировать после установки

Войдите первым администратором, откройте Settings → License (/admin/settings/license), вставьте целиком выданную строку TS1.… и сохраните. Проверьте компанию, срок и число мест. Admin и Writer занимают места, включая первого администратора; Viewer бесплатен. До активации доступно одно платное место.

Лицензия задаёт срок и лимит мест; Deploy Token даёт доступ к скачиванию. Это разные ключи. Приватный ключ вендора на сервер заказчика не устанавливается. Для продления поставщик выдаёт новую TS1-строку.

Namespace и секреты

kubectl config current-context
kubectl create namespace testspot

Убедитесь, что выбран нужный кластер. В namespace testspot должны существовать:

Синхронизируйте секреты из менеджера секретов вашей платформы. Если его нет, подготовьте защищённый файл /secure/testspot.env с правами 0600: одна строка KEY=value на параметр, без кавычек. DATABASE_URL — строка вида postgresql://USER:PASSWORD@HOST:5432/testspot?schema=public; спецсимволы учётных данных должны быть URL-encoded. Не добавляйте файл в Git. JWT_SECRET и TOKEN_ENC_KEY сгенерируйте по инструкции и сохраните вместе с установкой.

kubectl -n testspot create secret generic testspot-env --from-env-file=/secure/testspot.env
kubectl -n testspot get secret testspot-env testspot-registry testspot-tls

Вторая команда показывает наличие и число ключей, не их значения. TLS Secret можно создать через cert-manager или из выданных PEM-файлов; registry Secret — из отдельного Docker config с read-only доступом:

kubectl -n testspot create secret tls testspot-tls \
  --cert=/secure/tls.crt --key=/secure/tls.key
kubectl -n testspot create secret generic testspot-registry \
  --type=kubernetes.io/dockerconfigjson \
  --from-file=.dockerconfigjson=/secure/registry-config.json

Если TLS или registry Secret создаётся вашей платформой, соответствующую команду пропустите. Пароли не передавайте аргументами команд. Первый администратор создаётся при старте, SMTP для этого не нужен.

Конфигурация: my-values.yaml

Сохраните пример ниже как my-values.yaml рядом с комплектом. Замените DNS-имя, S3 endpoint, бакет, регион и часовой пояс. Endpoint задаётся без https://. В app.trustProxy укажите реальные доверенные адреса nginx/ingress по инструкции. Секретные значения остаются в Secret.

Аннотации предназначены для ingress-nginx; для другого контроллера настройте его эквиваленты лимита загрузки и таймаутов. Образы и digest берутся из release-values.yaml той же версии.

# Apply AFTER release-values.yaml. Images/digests come from the release, not this example.
ingress:
  host: testspot.example.com
  className: nginx
  tls:
    enabled: true
    secretName: testspot-tls
  # Example for ingress-nginx only; adapt to the controller actually installed.
  annotations:
    nginx.ingress.kubernetes.io/proxy-body-size: "200m"
    nginx.ingress.kubernetes.io/proxy-read-timeout: "600"
    nginx.ingress.kubernetes.io/proxy-send-timeout: "600"
    nginx.ingress.kubernetes.io/proxy-buffering: "off"
    nginx.ingress.kubernetes.io/proxy-request-buffering: "off"
imagePullSecrets:
  - name: testspot-registry
secrets:
  existingSecret: testspot-env
  revision: "initial"
storage:
  endpoint: s3.example.com
  port: 443
  useSSL: true
  bucket: testspot
  region: us-east-1
  createBucket: false
app:
  timezone: UTC
  cookieSecure: true
  # Replace with the actual trusted nginx/ingress proxy addresses or CIDRs.
  trustProxy: ""
migrations:
  enabled: true
  activeDeadlineSeconds: 1800
backend:
  replicas: 1
  startupProbe:
    periodSeconds: 5
    failureThreshold: 120
    timeoutSeconds: 2
frontend:
  replicas: 2

Обычная установка использует HTTPS и cookieSecure: true. Для тестового HTTP-стенда одновременно выключите ingress.tls.enabled и app.cookieSecure. Не выключайте проверки готовности: migration Job имеет отдельный бюджет 30 минут, backend — около 10 минут на старт.

Установить и открыть TestSpot

Работайте из каталога полученного комплекта. Проверьте внешнюю контрольную сумму архива, распакуйте его в новый каталог, затем выполните sha256sum -c SHA256SUMS (на macOS — shasum -a 256 -c SHA256SUMS). Файлы testspot-0.0.2.tgz и release-values.yaml должны относиться к одной версии. Здесь 0.0.2 — пример версии комплекта.

Если chart выдан через OCI, авторизуйте Helm в указанном registry через helm registry login REGISTRY --username USER --password-stdin, подавая пароль из менеджера секретов, и скачайте helm pull oci://REGISTRY/GROUP/PROJECT/charts/testspot --version 0.0.2. Адрес, USER и версию возьмите из поставки; доступ Helm не заменяет imagePullSecret для узлов.

helm lint ./testspot-0.0.2.tgz -f ./release-values.yaml -f ./my-values.yaml
helm install testspot ./testspot-0.0.2.tgz -n testspot \
  -f ./release-values.yaml -f ./my-values.yaml --wait --timeout 35m
kubectl -n testspot rollout status deployment/testspot-backend --timeout=10m
kubectl -n testspot rollout status deployment/testspot-frontend --timeout=5m

Сначала выполняется migration Job, затем запускается backend и создаётся первый администратор. Успешная Job удаляется автоматически. Ожидаемый результат — Helm сообщает deployed, оба rollout завершаются успешно. Откройте свой HTTPS-адрес, войдите с ADMIN_EMAIL/ADMIN_PASSWORD, смените пароль и установите лицензионный ключ.

Следующий шаг — проверить реальные действия. При ошибке начните с таблицы диагностики.

Первый старт

Точка входа контейнера делает три вещи по порядку: накатывает миграции (если RUN_MIGRATIONS не выключен), при заданном ADMIN_EMAIL создаёт первого администратора и запускает сервер.

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

Дымовая проверка после установки

После установки и каждого обновления проверьте пользовательские действия:

1. войти, перезагрузить страницу и повторить после истечения access-сессии — TLS и обновление cookie;
2. импортировать архив Allure Report — API, база, миграции;
3. загрузить и скачать вложение, сравнить байты; после обновления открыть старый результат и старое вложение;
4. скачать сгенерированный отчёт — подписанная ссылка, доступная из браузера;
5. выпустить read API-токен и вызвать MCP whoami — он должен вернуть вашего пользователя;
6. если используете мессенджер — получить оповещение и проверить исходящий доступ.

Удаление установки

Сначала остановите отправителей CI, сделайте резервную копию БД/S3/секретов и отключите автоматическое восстановление релиза в GitOps. Команда helm uninstall testspot -n testspot удаляет ресурсы приложения, управляемые Helm. Внешние БД, бакет и заранее созданные Secret остаются у оператора.

Не удаляйте namespace, БД или бакет как способ исправить неудачное обновление. Удаление данных — отдельное решение с проверкой резервной копии и срока хранения. Сохраните TOKEN_ENC_KEY: без него восстановленная БД не расшифрует секреты подключений.

PostgreSQL

Отдельная база и пользователь приложения. Здесь хранятся кейсы, результаты, пользователи и история действий.

Требования к PostgreSQL

• версия 14 и новее;
• пользователь должен владеть схемой public: миграции выполняют DDL при старте, и урезанный пользователь без прав на DDL уронит контейнер в цикл перезапусков;
• расширения не нужны;
• pgbouncer в transaction-режиме требует ?pgbouncer=true в строке подключения;
• ориентир по ресурсам — 2 vCPU и 4 ГБ.

Подключение и проверка

Создайте базу testspot и отдельную роль средствами вашей платформы PostgreSQL. Роль должна владеть схемой и объектами приложения; superuser не требуется. Передайте строку подключения в DATABASE_URL внешнего Secret testspot-env. Пароли со спецсимволами в URL должны быть percent-encoded.

Разрешите доступ к порту БД только backend и migration Job. В сетевой политике учитывайте отдельный component=migration. TLS и доверенный CA для Prisma настраиваются в строке подключения согласно требованиям вашей БД; NODE_EXTRA_CA_CERTS относится к Node HTTPS и не заменяет эту настройку.

После установки проверьте успешную migration Job, readiness backend и создание проекта через UI. При /ready=503 проверьте DNS, маршрут, пароль, права и исчерпание пула. Для миграций предпочтительно прямое соединение с PostgreSQL; совместимость вашего пулера проверьте отдельно.

Обновление приложения не обновляет сервер PostgreSQL. Его версии, диски, резервные копии и доступность обслуживает владелец инфраструктуры. Перед изменением версии БД проверьте восстановление и приложение на отдельном стенде.

S3-совместимое хранилище

Бакет для вложений и отчётов. Настройте права и доступность хранилища из кластера и браузера.

Требования к S3

• бакет создаётся заранее (имя по умолчанию — testspot, переменная MINIO_BUCKET);
• права: GetObject, PutObject, DeleteObject, ListBucket под префиксом projects/;
• доступно и из пода, и из браузера пользователя: скачивание отчёта идёт по подписанной ссылке, которую открывает браузер напрямую. Вложения при этом стримятся через API — но отчёты нет, и это самая частая причина «у меня отчёт не скачивается».

Если Jira, GitLab, модель или S3 используют внутренний CA, оператор создаёт ConfigMap с PEM-bundle и указывает backend.trustedCa.configMapName и backend.trustedCa.key (по умолчанию ca-bundle.pem) в Helm. Backend монтирует его только для чтения и использует NODE_EXTRA_CA_CERTS, сохраняя проверку сертификатов и имени хоста. После замены CA требуется перезапуск backend. Это не устанавливает доверие в браузерах и не настраивает TLS PostgreSQL.

Настройки S3

Приложение не делает бакет публичным. Проверьте отдельно загрузку и скачивание вложения через API, затем скачивание отчёта по подписанной ссылке из браузера. Успешная readiness backend не доказывает доступность S3.

Не задавайте lifecycle-удаление активных объектов независимо от политики приложения: запись в БД останется, а файл исчезнет. Versioning, retention, шифрование и резервирование настраиваются владельцем бакета; проверьте их совместимость с удалением объектов приложением.

Сеть и HTTPS

Один HTTPS-адрес для интерфейса, API, CLI и MCP. Настройте ingress, доверенные прокси и внутренние сертификаты.

Сетевые требования

• TLS в проде: cookie обновления сессии помечена Secure, поэтому на голом HTTP браузер её молча выбрасывает и получается цикл с 401 при внешне рабочем входе. Стенду, который принципиально отдаётся по HTTP, флаг снимают явно — COOKIE_SECURE=false; других способов нет, и молчаливой деградации тоже;
• исходящий доступ нужен только необязательным функциям: openrouter.ai, api.telegram.org, slack.com, api.github.com, а для подключённой напрямую модели — её эндпоинт (api.anthropic.com, generativelanguage.googleapis.com либо свой OpenAI-совместимый адрес). Сама TMS без интернета работает полностью;
• для исходящего прокси задайте HTTPS_PROXY, HTTP_PROXY и NO_PROXY. В NO_PROXY перечислите адреса сервисов, доступных напрямую, например хранилища и внутреннего GitLab;

Адрес клиента за прокси

Задайте app.trustProxy в Helm или TRUST_PROXY на сервере: IP-адреса либо CIDR-сети доверенных nginx и ingress, через запятую. Например, 10.4.0.0/16,10.5.0.0/16 — только пример формата, замените его сетями своего кластера.

По умолчанию список пуст: сервер игнорирует X-Forwarded-For. За nginx это означает общий лимит входа для адреса nginx. Значения true, * и сети /0 запрещены. Ingress должен корректно формировать цепочку адресов, а backend должен быть закрыт от прямых обращений недоверенных клиентов.

После настройки проверьте через ingress два случая: разные адреса клиентов получают отдельные лимиты; добавление подложенного адреса в начало X-Forwarded-For не позволяет обойти лимит.

Что делает nginx

После настройки сети проверьте резервирование и восстановление базы и файлов на отдельном стенде.

DNS, TLS и ingress

Направьте DNS-имя на ingress-контроллер. В namespace приложения создайте TLS Secret и задайте ingress.host, ingress.className, ingress.tls.enabled: true и ingress.tls.secretName. Сертификат должен покрывать выбранное имя; браузеры и CLI должны доверять его издателю.

Разрешите браузерам и CI HTTPS к ingress, ingress — frontend:8080, frontend — backend:3001, backend и migration Job — PostgreSQL, backend — S3. Учтите DNS и доступ узлов к registry. Сам backend и метрики не должны быть доступны напрямую из внешней сети.

Для больших импортов согласуйте размер тела и таймауты по всей цепочке балансировщиков. В примере ingress-nginx стоят 200m и 600 секунд; другой контроллер требует своих параметров. HTTP 413 указывает на ограничение размера, 504 — на таймаут или недоступный upstream.

Конфигурация и секреты

Несекретные настройки — в Helm values; пароли и ключи — во внешнем Secret. Применяйте изменения через контролируемый rollout.

Секреты

JWT_SECRET=$(openssl rand -hex 32)
TOKEN_ENC_KEY=$(openssl rand -base64 32)   # ровно 32 байта до base64

Переменные окружения

CORS_ORIGIN задаёт разрешённые адреса интерфейса через запятую, включая схему и порт. Для них API разрешает GET, HEAD, POST, PUT, PATCH, DELETE и OPTIONS с передачей credentials. При ошибке CORS проверьте доступность API, совпадение origin и ответ OPTIONS: метод запроса должен присутствовать в Access-Control-Allow-Methods.

Рядом с сервером лежит server/.env.example с комментариями — но он не полон: переменных первого администратора, RUN_MIGRATIONS, LOG_LEVEL и DOWNLOADS_DIR в нём нет. Полный перечень по группам:

APP_BASE_URL используется как основа для ссылок в исходящих сообщениях Telegram и Slack, а не как адрес для раннера: почему адрес не передаётся в пайплайн.

Применить изменения

После синхронизации внешнего Secret увеличьте secrets.revision в values и выполните обычный Helm upgrade. Переменные уже работающего контейнера не меняются после сохранения Secret. Проверьте готовность новых Pod и доступ к зависимости, чей пароль был изменён.

Не генерируйте JWT_SECRET и TOKEN_ENC_KEY при каждом обновлении. Потеря JWT_SECRET завершит сессии, потеря TOKEN_ENC_KEY лишит доступа к сохранённым секретам интеграций. Планируйте ротацию ключа шифрования вместе с данными.

Вход и пользователи

Локальные учётные записи, создание первого администратора, сессии и защита входа.

Лимиты входа

Для команды из 60 человек за одним офисным IP предусмотрен бюджет 120 запросов входа в минуту. После 5 неверных паролей в пределах двухчасового окна аккаунт блокируется на полные 120 минут с последней ошибки, независимо от IP. Успешный вход не расходует бюджет ошибок и не сбрасывает предыдущие ошибки. Email сравнивается без учёта регистра; неизвестные аккаунты ограничиваются так же.

Задавайте положительные целые числа: до 1000000 попыток и до 86400 секунд. Ошибочные значения останавливают запуск. Для большой команды за NAT можно увеличить IP-бюджет, сохранив защиту аккаунта. Настройки и PostgreSQL должны быть общими для всех реплик; после изменения перезапустите их. LOGIN_ACCOUNT_WINDOW_SECONDS задаёт окно подсчёта ошибок и полную длительность блокировки после исчерпания лимита. При обновлении проверьте ранее заданные значения: явные настройки имеют приоритет над defaults.

При исчерпании бюджета вход отвечает 429 даже с верным паролем. Дождитесь срока из Retry-After: отклонённые во время блокировки запросы не продлевают её. Одновременные проверки временно занимают места в бюджете аккаунта; успех освобождает место. При аварии процесса оно освобождается по окончании окна. Недоступность хранилища лимитов даёт 503. Redis не требуется.

Перед обновлением backend примените миграцию 20260912152634_shared_login_rate_limits штатным prisma migrate deploy или через RUN_MIGRATIONS в контейнере. Общая защита действует после обновления всех реплик.

Первый администратор и команда

Перед первым стартом задайте ADMIN_EMAIL и ADMIN_PASSWORD в Secret. Инициализация создаёт администратора, если его ещё нет, и не перезаписывает существующий пароль. После входа смените начальный пароль и настройте лицензию; пользователей и роли ведите через администрирование пользователей.

Вход в TestSpot использует локальные учётные записи. Штатных настроек LDAP, OIDC или SAML в этой поставке нет. SMTP для создания первого администратора не требуется; подключение SMTP лендинга не является настройкой авторизации приложения.

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

Закрытый контур

Перенос готового комплекта во внутренний registry, доверие CA и установка без внешнего сайта документации.

Закрытый контур: перенос образов и внутренний CA

Перенесите airgap-архив и доверенную контрольную сумму в контур, проверьте архив и распакуйте его в новый каталог. На машине с Docker и Node 22 авторизуйте Docker во внутреннем registry. Команды выполняются из корня комплекта:

sha256sum -c SHA256SUMS
node tools/mirror.mjs . registry.corp.example/testspot /secure/mirror-values.json

Скрипт проверит комплект, загрузит и отправит оба образа, запишет их новые digest. Подготовьте testspot-registry для внутреннего registry. Каждый Kubernetes-узел должен доверять его CA; настройка CA в Node этого не заменяет. Для исходящих HTTPS-соединений backend к внутренним сервисам:

kubectl -n testspot create configmap testspot-corporate-ca \
  --from-file=ca-bundle.pem=/secure/corporate-ca.pem

backend:
  trustedCa:
    configMapName: testspot-corporate-ca
    key: ca-bundle.pem

Если внутренние сервисы используют публичный CA, ConfigMap и этот overlay не нужны. При необходимости добавьте proxy.https и proxy.noProxy для внутренних БД/S3/CI/Jira и адресов кластера. Значения proxy не требуются для работы самой TMS без интернета.

helm install testspot ./testspot-0.0.2.tgz -n testspot \
  -f ./release-values.yaml -f ./my-values.yaml \
  -f ./my-airgap.yaml -f /secure/mirror-values.json --wait --timeout 35m

Файл с digest внутреннего registry идёт последним. После установки выполните ту же приёмку; документация /docs доступна внутри frontend без внешнего сайта.

Обновление

Подготовьте резервную копию, примените миграции и проверьте старые данные после rollout.

Обновление

Обновление выполняет администратор Kubernetes через Helm. Кнопки обновления приложения в UI нет; новые версии автоматически не устанавливаются. Поставщик передаёт номер, release notes и артефакты.

Chart не устанавливает PostgreSQL или MinIO. Ваши БД и S3 остаются подключёнными через Secret и values. MinIO необязателен: можно использовать своё S3-совместимое хранилище.

Получить новую версию

kubectl config current-context
helm list -n testspot
helm history testspot -n testspot
helm registry login registry.gitlab.com
TARGET_VERSION=0.0.2  # пример: замените опубликованной целевой версией
helm pull oci://registry.gitlab.com/testspot-group/testspot-project/charts/testspot --version "$TARGET_VERSION"

Перед обновлением убедитесь, что поставщик опубликовал выбранную версию и выдал новую лицензию. Получите release-values.yaml, release notes и файлы проверки этой же версии либо новый airgap-комплект. Используйте новый каталог и проверьте резервную копию до запуска upgrade.

Готовый комплект релиза содержит Helm chart, два образа, их digest, примеры production/airgap и инструкции. Используйте одну версию комплекта для frontend и backend. Проверка verification.json относится к конкретным commit и образам, а не к произвольной сборке.

Для отдельного migration Job включите migrations.enabled и заранее создайте secrets.existingSecret. Job выполняется до rollout; при ошибке обновление останавливается. В прежнем режиме миграции выполняются при старте backend. Бюджет старта задают backend.startupProbe.periodSeconds и failureThreshold, по умолчанию около десяти минут.

После изменения внешнего Secret увеличьте secrets.revision и выполните upgrade: работающий Pod не перечитывает переменные окружения сам. Ключ шифрования TOKEN_ENC_KEY сохраняйте при обновлениях. Откат образа не отменяет миграции данных.

1. Прочитайте release notes целевой версии. Зафиксируйте текущую версию, digest, values и версии секретов. Сделайте и проверьте согласованную резервную копию.
2. Получите новый комплект в отдельный каталог, проверьте checksum и перенесите свой my-values.yaml. JWT_SECRET и TOKEN_ENC_KEY сохраните прежними. Проверьте изменения настроек в release notes.
3. Если миграция меняет смысл данных, согласуйте окно обслуживания: остановите отправителей CI и backend, приостановив GitOps/HPA. Pre-upgrade Job сама по себе не останавливает старые Pod.
4. Из каталога нового комплекта выполните команды ниже, задав TARGET_VERSION целевой версией.

helm lint "./testspot-${TARGET_VERSION}.tgz" -f ./release-values.yaml -f ./my-values.yaml
helm upgrade testspot "./testspot-${TARGET_VERSION}.tgz" -n testspot \
  --reset-values -f ./release-values.yaml -f ./my-values.yaml --wait --timeout 35m
kubectl -n testspot rollout status deployment/testspot-backend --timeout=10m
kubectl -n testspot rollout status deployment/testspot-frontend --timeout=5m

В my-values.yaml сохраните свои настройки, но уберите старые image tag/digest. Не переносите старый release-values.yaml и не применяйте --reuse-values. При --reset-values все ваши настройки передаются явно через файлы. Release name и namespace сохраняются; uninstall для обновления не нужен.

Лицензия хранится в БД и при обычном обновлении остаётся действовать в пределах своего срока. Если release notes сообщают о смене публичного ключа вендора, получите новую TS1-строку. После обновления проверьте компанию, срок и места в Settings → License.

В закрытом контуре запустите mirror.mjs из нового комплекта и получите новый mirror-values. Добавьте свои airgap и mirror-values последними, как при установке. После upgrade проверьте старый результат и вложение, новый импорт, вход и MCP по приёмке. Верните отправителей и автоматизацию после успешной проверки.

Если migration Job завершилась ошибкой, сначала сохраните её лог и выясните состояние БД. Helm останавливает rollout, но уже выполненные изменения данных не отменяются. helm rollback и --atomic не заменяют восстановление БД/S3. Не запускайте prisma migrate reset на рабочей базе.

У плана может быть собственный часовой пояс. Если он не задан, для расписания используются SCHEDULE_TIMEZONE, затем TZ сервера, затем UTC.

Завершение сервера при обновлении

По SIGTERM или SIGINT сервер прекращает запуск новых тиков планировщиков, ждёт завершения активных HTTP-запросов и отслеживаемых фоновых операций, затем отключается от БД. Завершающиеся HTTP-ответы закрывают keep-alive соединение.

Предельное ожидание — 25 секунд, в Helm время завершения пода — 30 секунд. Если запрос или задача зависли, процесс завершается с кодом 1. Это не гарантирует повтор прерванного задания: восстановление фоновых задач после аварии остаётся отдельной задачей.

Резервирование и восстановление

Согласованная копия PostgreSQL, S3 и ключей, расписание и проверка восстановления на независимом стенде.

Резервирование и восстановление

Владелец установки настраивает резервирование PostgreSQL, S3 и секретов. История Helm и копия только БД не восстанавливают вложения и зашифрованные токены. Храните вместе идентификатор снимка, версию приложения, digest и values; ключи JWT_SECRET/TOKEN_ENC_KEY резервируйте в менеджере секретов.

1. Согласуйте допустимую потерю данных (RPO), время восстановления (RTO), расписание и срок хранения. Ежедневная копия означает потенциальную потерю до суток. Хранилище копий должно быть независимо от основного.
2. Для согласованного снимка остановите отправителей CI, дождитесь активных запросов, приостановите GitOps/HPA, запишите число backend-реплик и уменьшите его до нуля. Дождитесь завершения Pod: так остановятся и schedulers.
3. Снимите дамп PostgreSQL и копию S3 средствами провайдера с сохранением ключей объектов и метаданных. Проверьте оба результата до возвращения записи. Живая реплика S3 сама по себе не является историческим backup.
4. Верните исходное число реплик и отправителей. Ошибка любой части означает, что снимок неуспешен; возврат сервиса и повтор копирования должны иметь ответственного.

Пример дампа с защищёнными PGSERVICE/PGPASSFILE, заранее настроенными оператором. Пароль не передаётся в командной строке:

umask 077
pg_dump --dbname="service=testspot-backup" --format=custom --file=database.dump
pg_restore --list database.dump > database.contents.txt

Периодически восстанавливайте существующий снимок в новую БД и новый бакет, с той же версией приложения и ключей. Заблокируйте обращения восстановленного стенда к production CI/Jira/мессенджерам до запуска, чтобы расписания не выполняли реальные действия. Проверьте вход, старые результаты и байты вложений, затем контрольный импорт. Измерьте фактические RPO/RTO; успех pg_restore не доказывает восстановление приложения.

Для алертов обновляйте testspot_backup_last_success_timestamp_seconds с service="testspot" только после проверки БД и S3. В комплекте есть monitoring/backup-alerts.yml и подробная процедура docs/backup-production.md.

Мониторинг

Готовность приложения, Prometheus, Grafana и поведение при отказах зависимостей.

Проверки живости

/health проверяет только работу процесса. /ready проверяет доступность базы и возвращает 503 при отказе: Kubernetes перестаёт направлять трафик на неготовую реплику.

Prometheus и Grafana

Задайте backend отдельный случайный секрет METRICS_TOKEN и перезапустите его. Тогда GET /metrics с заголовком Authorization: Bearer <токен> отдаёт метрики Prometheus: число запросов по HTTP-коду, время ответа, память, CPU и Node.js. Без токена endpoint выключен; неверный токен получает 401.

Prometheus собирает метрики напрямую с внутреннего адреса backend каждые 15 секунд. Штатный nginx этот путь не проксирует. При нескольких репликах собирайте каждую отдельно. В Grafana выберите Prometheus как источник данных. Конфигурация сбора находится в deploy/monitoring/prometheus.yml, инструкция и запросы — в docs/monitoring.md репозитория.

Метки используют шаблоны маршрутов без ID и параметров URL. Пробы и сбор метрик не входят в HTTP-статистику. Успешный сбор не подтверждает доступность базы или S3. Prometheus, Grafana, хранение данных и оповещения настраивает владелец установки.

Временные сбои зависимостей

При обрыве связи с PostgreSQL /ready отвечает 503; после возврата связи соединение восстанавливается без перезапуска. /health продолжает проверять только процесс.

S3-запрос ограничен 30 секундами до начала ответа; во время скачивания допускается не более 30 секунд без передачи данных. Недоступность хранилища при загрузке возвращает 503 с сообщением Object storage is unavailable; запись вложения создаётся после успешной записи файла. При обрыве уже начатого скачивания загрузите файл заново.

Вызовы CI и Jira имеют таймаут 15 секунд на попытку. Общий HTTP-клиент допускает три попытки с паузами 1 и 2 секунды — до примерно 48 секунд ожидания; проверка подключения Jira делает одну попытку. Неуспешный запрос к CI сам по себе не означает, что удалённый запуск не был создан.

Хранение и очистка

Правила хранения артефактов настраиваются администратором. Удаление объектов необратимо, поэтому сначала проверьте объём и резервирование.

Хранение артефактов

Admin → Settings → Storage. Четыре независимых правила, и все они по умолчанию выключены — то есть установка ничего не удаляет, пока администратор не решит иначе.

Окно задаётся словами: 90d, 6w, 12m, 2y. Выключается через 0, off, never, no, none или -. Максимум — 10 лет. На той же странице видно текущий объём хранилища с разбивкой по видам, то есть что именно затронет правило, видно до сохранения.

Если хранилище не позволило удалить файл, очистка повторит попытку при следующем проходе.

Диагностика

Найдите причину по симптому, состоянию Job и Pod, затем соберите нужные сведения для поддержки.

Диагностика установки и обновления

Начните с состояния Pod, Job и событий; команды предполагают namespace и имя релиза testspot.

kubectl -n testspot get pods,deploy,svc,ingress,jobs
kubectl -n testspot get events --sort-by=.lastTimestamp
kubectl -n testspot logs deployment/testspot-backend --since=15m
# Для неуспешной миграции (успешная Job удаляется):
kubectl -n testspot logs job/testspot-migrate

Для обращения в поддержку приложите версию/commit/digest, время, reqId и очищенный фрагмент лога. Не прикладывайте Secret, полный env, токены или backup. У перезапущенного Pod предыдущий лог доступен через kubectl -n testspot logs POD --previous.

Логи

Пишутся в stdout структурированным JSON, уровень задаётся LOG_LEVEL (по умолчанию info).

Заголовки авторизации, cookie и известные поля с секретами удаляются из логов или заменяются пометками. Параметры token, sig, access_token и key в URL скрываются.

Известные токены и пароли подключения скрываются и в сообщениях об ошибках CI, Jira и AI; код и причина отказа сохраняются. Автоматическая очистка не охватывает произвольный текст: перед отправкой лога в поддержку проверьте его содержимое.

Импорт и экспорт

Импорт переносит сценарии из CSV или JSON. Экспорт выгружает выбранные кейсы в CSV, JSON или PDF. Результаты запусков загружаются отдельно через Launches → Import.

Импорт тест-кейсов

Для переноса тест-кейсов используйте MCP или API импорта. В Test Cases нет формы загрузки CSV/JSON. Импорт результатов в формате Allure Report находится отдельно в Launches.

Сначала отправьте файл с dryRun: true, проверьте соответствия и вопросы, затем повторите запрос с согласованными параметрами и dryRun: false.

Форматы и структура файла

Поддерживаются CSV и JSON:

• CSV с одной строкой на кейс: шаги собраны в одной ячейке.
• CSV с одной строкой на шаг: повторяющийся caseKey объединяет строки в кейс.
• JSON-массив кейсов или массив внутри поддерживаемой структуры выгрузки.

Заголовки известных форматов распознаются автоматически; для остальных задайте mapping. Само название исходной TMS не гарантирует совместимость конкретной выгрузки — проверьте dryRun.

При обратном импорте JSON общие шаги записываются обычными шагами кейса: идентификаторы групп исходного проекта не создают связи в новом проекте.

Во что можно сопоставить колонку

Для ручного сопоставления доступны следующие поля:

Можно также сопоставить ключи кастомных полей проекта. Повторяющееся значение caseKey объединяет строки одного кейса в формате «строка на шаг».

Подстановка значений

Словарные поля переводятся в фиксированный словарь продукта. Подстановка задаётся по имени поля:

Например, задайте в valueMap соответствия: 1 → P0 для приоритета, Blocker → Critical для важности. Числовой приоритет требует явного сопоставления.

Прочие параметры импорта

Какие поля импорт не переносит

Даже из собственной выгрузки TestSpot эти колонки распознаются и игнорируются: номер кейса, внутренний идентификатор, даты создания и последнего прогона, признак автоматизации, полное имя, идентификатор Allure Report. И тип кейса: всё приезжает ручным, автоматическим кейс делает уже прогон, а не импорт.

Предпросмотр и запись

dryRun: true проверяет файл без записи: возвращает колонки, предложенные соответствия, проблемы и примеры кейсов. После проверки повторно передайте файл, настройки и решения с dryRun: false.

При проверке явно указывайте dryRun: true: без него запрос может записать данные. Для записи повторно отправьте файл и все параметры — предпросмотр их не сохраняет.

Лимиты: 20 000 кейсов, 8 000 000 символов файла, 200 символов в названии кейса; в отчёте показываются первые 100 проблем. У MCP лимит содержимого файла — 400 000 символов; большие файлы передавайте в multipart API.

Разрешение вопросов импорта

При записи нерешённые вопросы дают 409: неопознанные колонки с данными, значения без соответствия, кейсы без шагов, некорректные строки и дубликаты имён.

Исправьте mapping, задайте valueMap или явно подтвердите перечисленные вопросы через accepted. При согласованном пропуске проблемных строк импортируются только корректные кейсы; проверьте итоговые числа и список пропусков.

Дубликаты по умолчанию пропускаются. Для создания отдельных кейсов с повторяющимися именами задайте onDuplicate: create.

Пути папок: A > B, /A/B, A\B, до 10 уровней. При отсутствии дерева импорт создаёт Imported; если деревьев несколько, укажите нужное.

Экспорт тест-кейсов

1. В Test Cases выделите кейсы или откройте меню одного кейса.
2. Выберите Export и формат: CSV, JSON или PDF. За раз — до 500 кейсов.

Экспорт не является резервной копией проекта. История версий, результаты запусков, ревью и все размещения в деревьях в него не входят. Поле папки не восстанавливает структуру всех деревьев. При обратном импорте кейсы получают новые идентификаторы и способ запуска Manual.

Ограничение PDF: вложения, добавленные через текущий интерфейс тест-кейса, в PDF не включаются. Передавайте нужные файлы отдельно.

Импорт результатов прогона

Это другая операция и другой раздел — Launches → Import, три пункта: Test results (пакет Allure Report), Eval report, Load report. Ограничения архива и порядок описаны на странице «Запуски».

FAQ и поддержка

Решения частых проблем при работе с TestSpot, CI и установкой.

Работа в продукте

Где кнопка «создать запуск»?

Запустите план, выбранные кейсы в Test Cases или строки Datasets. Для готового отчёта используйте Launches → Import, для отправки из джобы — CLI. Создание и повторный запуск.

Почему pass rate показывает тире, а не 0 %?

Нет результатов passed, failed, broken или unknown. Если они есть, но среди них нет passed, показатель равен 0 %. Формула.

Идущий запуск показывает низкий процент — прогон правда плохой?

Низкий pass rate означает, что среди уже учтённых результатов мало passed. Это не процент выполнения плана. Пока Launch идёт, показатель может измениться; проверьте ошибки и число ещё не выполненных строк.

Не удаляется группа общих шагов

На неё ссылается хотя бы один тест-кейс — кнопка выключена и подписана «Used in N cases». Сначала уберите ссылки из кейсов.

Не вижу разделов Datasets или Reviews

Проверьте Settings проекта: для Datasets включите Eval tests, для Reviews — ревью. Если у вас нет права менять настройки, обратитесь к владельцу проекта.

Нужное поле кейса не показывается

Поля включает проект: Fields → режим Off / Optional / Required. Кастомное поле могли заархивировать — архивные не спрашиваются на новых кейсах, но старые ответы остаются видны.

CI и модель

Джоба пишет 401 или 403

• 401 — токен не тот, просрочен или отозван. Секрет виден только при создании, восстановить нельзя: выпустите новый.
• 403 на записи — у токена scope read. CLI пишет, ему нужен write.
• 403 на действии — прав не хватает самому владельцу токена: токен прав не расширяет.

Пайплайн зелёный, а результатов в TestSpot нет

Проверьте сообщения CLI в логе джобы: по умолчанию ошибки отправки в TestSpot не меняют успешный результат тестовой команды. Добавьте --strict, чтобы ошибка отправки завершала команду с кодом 1, если сами тесты прошли. Проверка отправки результатов.

Запуск висит незакрытым

Если пайплайн GitLab завершился, а результатов не прислал, TestSpot закрывает запуск сам и пишет причину. Семь статусов считаются живыми и не трогаются — список.

Джоба не может разрешить хост TestSpot

Проверьте TESTPILOT_URL в переменных CI и доступность указанного адреса с раннера. Он может отличаться от адреса приложения в браузере. Настройка адреса для CI.

Переключатель AI features выключен и не нажимается

Подключите модель в Integrations → Models. Если доступных соединений нет, попросите администратора выдать соединение проекту. Затем включите Settings → AI features. Подключение модели к проекту.

Не удаётся сформировать сводку Launch

Проверьте Integrations → Models и назначение модели для сводок, затем Settings → AI features. Наличие соединения для другой функции не гарантирует доступность сводки. Выбор модели.

Эксплуатация

Вложения открываются, а сгенерированный отчёт не скачивается

Вложения скачиваются через API, а сгенерированный отчёт — по подписанной ссылке в объектное хранилище. Проверьте, доступен ли адрес из ссылки в браузере пользователя, и запросите новую ссылку, если прежняя истекла.

После входа выкидывает обратно на форму, 401 по кругу

Проверьте протокол и cookie сессии. В production по умолчанию используется Secure-cookie, которая требует HTTPS. Для установки по HTTP оператор должен явно настроить COOKIE_SECURE=false. Если причина не в этом, проверьте ответы входа и обновления сессии в логах.

Контейнер backend перезапускается по кругу

Проверьте доступность PostgreSQL, строку DATABASE_URL и ошибку запуска в логах backend. При включённых миграциях учётной записи БД нужны права на изменение схемы.

Не вижу встроенного ассистента

Попросите администратора проверить Settings → Connections: включён ли Assistant available to users и выбрано ли соединение модели для ассистента. Настройка ассистента. Подключение внешних агентов через MCP работает независимо.

Группировка падений отвечает ошибкой

Завершите Launch: для running и draft группировка недоступна. Если различимых ошибок слишком мало, новая группировка также не создаётся (409). Проверьте AI features и соединение модели: 403 может означать выключенный ИИ, 503 — отсутствие модели, 429 — ограничение частоты, 502 — ошибку ответа или соединения.

Импорт отвечает 409 со списком вопросов

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

MCP-клиент подключается, но обрывается

Проверьте, что ингресс пропускает /mcp с выключенной буферизацией и большими таймаутами. И что в конфиге клиента указан тип http.

Не создаётся пользователь: 409 про места

Кончились платные места. Admin и Writer занимают по одному, Viewer бесплатен. Либо освободите место, либо поставьте лицензию на большее число. Подробно.

Ночной прогон уходит не в то время

Сначала проверьте часовой пояс самого плана. Если он не задан, используется SCHEDULE_TIMEZONE, затем TZ сервера, затем UTC.

Поддержка

Контакт поддержки стенда указан в Admin → Settings → General.

В обращении укажите адрес страницы, номер проекта и Launch или кейса, время события, ожидаемое и фактическое поведение. Для проблем CI приложите сообщения CLI из лога джобы.