BugTrail

Сервис для передачи багов от тестировщиков разработчикам: заметки на элементах страницы со скриншотами и аннотациями, запись алгоритма воспроизведения, веб-панель с неугадываемыми ссылками для Jira.

Состав

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

npm install          # workspaces: shared, ui, web, extension
make dev             # postgres + API в docker, панель на http://localhost:5173

API: http://localhost:8001 (healthcheck: /api/healthz). Миграции применяются при старте контейнера; вручную — make migrate.

Расширение

make ext             # сборка в packages/extension/dist/{chrome,firefox}
                     # + zip-архивы в packages/web/public/ext (страница /download)

Пользователям расширение раздаётся через страницу панели /download (пункт меню «Расширение»): архивы для Chrome и Firefox + инструкция по установке и настройке.

Установка (dev):

• Chrome/Chromium: chrome://extensions → Developer mode → Load unpacked → packages/extension/dist/chrome
• Firefox: about:debugging#/runtime/this-firefox → Load Temporary Add-on → packages/extension/dist/firefox/manifest.json

Затем: иконка расширения → Settings (или Alt+Shift+B → контекстное меню настроек не используется, страница настроек открывается из chrome://extensions → Details → Extension options): указать URL сервера, войти (email/пароль), выбрать проект по умолчанию.

Управление:

• Alt+Shift+B — пикер элемента: клик по элементу → скриншот → аннотации (перо/стрелка/прямоугольник/текст) → комментарий → Submit.
• Alt+Shift+R — старт/стоп записи: клики, ввод (с дебаунсом 250 мс), переходы по URL; скриншоты ключевых шагов прикладываются автоматически. Кнопка Note в рекордер-баре открывает тот же пикер для заметки на элемент.

Пароли не сохраняются: маскирование ввода дублируется на сервере.

Почему /assets

kit.css из gnexus-ui-kit ссылается на шрифты абсолютными путями /assets/.... Веб-панель копирует ассеты кита в свой dist/assets (dev-миддлварь + vite-plugin-static-copy). Расширение раздаёт их как web_accessible_resources и переписывает пути на chrome-extension://.../assets/... при загрузке стилей в shadow root (constructable stylesheets — CSS хост-страницы и её CSP не затрагиваются).

E2E-проверка расширения

make ext-test (нужен поднятый make dev) — headless Chromium грузит собранное расширение, проходит сценарий «пикер → заметка» и «рекордер: клики + ввод», проверяет репорты через API.

Прод

Стек прод-версии — docker-compose.prod.yml: caddy (статика панели + reverse-proxy /api), API-сервер, Postgres 16. Миграции применяются при старте контейнера сервера автоматически.

Первый перенос на сервер

git clone <repo> && cd live-testing-tool
npm ci
make prod            # сборка панели + up -d --build

Панель и API на одном origin: http://<host>:8081 (caddy: статика + /api → server). Для сборки zip-архивов расширения (страница /download) на сервере должен быть установлен zip (apt install zip и т.п.). Первый зарегистрированный через панель аккаунт — обычный пользователь; проекты создаёт каждый сам, публичные ссылки выдаются на проект и репорт.

Настройки (.env рядом с compose-файлом)

Домен + автоматический HTTPS (caddy сам выпустит сертификат). Релизный адрес — https://bugtrail.gnexus.space:

# .env
SITE_ADDRESS=bugtrail.gnexus.space
HTTP_PORT=80
HTTPS_PORT=443

(образец — deploy/.env.example)

Для расширения в настройках указать URL сервера = адрес панели (https://bugtrail.example.com), войти и выбрать проект по умолчанию.

Обновление

git pull
make prod            # пересоберёт панель и контейнеры, накатит миграции

Данные живут в volume postgres_data (БД) и каталоге ./data (файлы скриншотов/видео) — их достаточно для бэкапа: docker compose -f docker-compose.prod.yml exec postgres pg_dump -U ltt ltt > dump.sql плюс копия ./data.

Ссылки и доступ

• PK — UUIDv7; публичные ссылки — случайные 128-битные токены (/p/<token>, /r/<token>).
• Токен = авторизация: страницы проекта и репорта открываются без логина.
• Ротация токена: кнопка в панели (POST .../share/rotate).
• Превью ссылок (Telegram, Jira): /p/* и /r/* проксируются caddy на API, который подставляет в SPA-шелл og-метатеги — заголовок, описание, дата создания, скриншот/видео репорта.

Структура

server/app/routers/   auth, projects, reports, uploads
packages/web/src/     pages (Login, Register, Projects, Project, Report, Settings), i18n
packages/ui/src/      AnnotationEditor, ScreenshotViewer, ElementContext, EnvironmentInfo
packages/extension/src/  background (SW: сеть, captureVisibleTab, буфер рекордера),
                         content (shadow-DOM оверлей: PickerLayer, NoteComposer, RecorderBar),
                         options (сервер, логин, проект по умолчанию)