TestTrout

Тестовый ассистент для приложений, созданных ИИ.

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

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

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

Проблема

Кодинг-агенты быстро выпускают код. Они также тихо всё ломают, а в приложениях, которые они создают — Lovable, v0, Bolt, собственный React на Vercel — почти никогда нет тестов. Поэтому цикл заканчивается фразой «выглядит нормально» от того, кто только что написал код.

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

Related MCP server: Lastest

Запуск

pip install testtrout
trout up

Это запускает всё: хранилище, фоновый воркер и интерфейс на localhost:7411. Никакого Docker, демонов и баз данных для установки — хранилище на SQLite в ~/.testtrout, а воркер работает в том же процессе.

Затем привяжите репозиторий через интерфейс или терминал:

trout link ~/code/my-app          # a folder you already have
trout link --github owner/name    # cloned with your GitHub token

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

Две вещи делают это безопасным и полезным:

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

Неполный набор даёт неполный набор тестов. Имея только URL, вы можете зондировать и запускать API-тесты; добавьте анонимный ключ и второй аккаунт — и станут возможны тесты авторизации. Каждая заблокированная возможность называет единственную следующую вещь, которая ей нужна, а не «настройте как следует».

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

Или оставайтесь в своём кодинг-агенте

Приложение — один из способов входа, но не единственный. Всё, что оно умеет, доступно в виде типизированных MCP-инструментов и CLI-команд, так что тем, кто не хочет покидать свой редактор, и не придётся:

pip install 'testtrout[mcp]'
trout mcp /path/to/your/project

Направьте своего агента на навык в .claude/skills/ или скажите ему:

Используй MCP-сервер TestTrout. Просканируй репозиторий, покажи, что не покрыто тестами, отсортировав по важности, составь тесты для пяти лучших и запусти их.

Тринадцать инструментов, привязанных к одному проекту, чтобы агент не мог действовать не с тем репозиторием:

Плюс trout://surfaces, trout://intent, trout://config, trout://scenarios в качестве ресурсов, чтобы объёмное состояние никогда не вытесняло контекстное окно агента.

Что он понимает

trout scan полностью детерминирован — без модели, без сети, безопасен для только что склонированного репозитория. В типичном приложении на Supabase он находит:

Он также сообщает, когда таблица записывается из браузерного кода без row-level security — то есть доступна для записи всем через анонимный ключ. Обычно это становится новостью.

Почему тестам можно доверять

Он строит базовую линию, а не догадки по каждому PR. Тест, выведенный из только что изменённого кода, по построению утверждает, что новое поведение корректно — он не может поймать регрессию. TestTrout сначала сертифицирует набор тестов против работающего деплоя, поэтому сбой что-то значит.

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

critical  authorization  A user cannot read another user's rows in payments   100
  · critical surface
  · policy: exists (select 1 from orders o where o.id = payments.order_id …)

Каждое утверждение несёт своё происхождение. derived — из политики, observed — в реальном браузере, или inferred — моделью, и одно лишь inferred никогда ничего не блокирует.

Сбой классифицируется до того, как о нём сообщается. Только assertion_failure — сигнал продукта. Сбои аутентификации, недоступные базы данных и заблокированные сторонние вызовы относятся к обвязке, и неубедительный прогон никогда не повышается до успешного.

Всё из терминала

trout scan          # understand the code
trout init          # connect a deployment
trout gaps          # what's missing, ranked, with reasons
trout run           # execute, with evidence behind every result

Каждая команда поддерживает --json. Полное руководство в docs/setup.md.

Как это хранится

Ваш набор тестов остаётся в репозитории, в коммитах и доступен для ревью:

.trout/scenarios/*.yaml    what each test asserts, in plain language
.trout/config.yaml         deployments and env: references, never secrets
tests/trout/               generated Playwright and Vitest files

История прогонов, покрытие с течением времени и очередь заданий хранятся в SQLite в ~/.testtrout. Такое разделение неслучайно: набор тестов должен лежать рядом с кодом, где его может проверить pull request, а вопросы, на которые файлы ответить не могут — становится ли тест более флакающим, растёт ли покрытие — должны лежать в базе данных.

Необязательное веб-представление

trout web

Покрытие с первого взгляда, ранжированный список пробелов, ревью сценариев, история прогонов с доказательствами, живой журнал. Те же файлы .trout/, что и в CLI — без базы данных, без хостинга, только loopback. Полностью опционально; CLI и MCP самодостаточны.

Безопасность

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

• Продакшн по умолчанию доступен только для чтения. Изменяющие запросы блокируются на сетевом уровне, если точка входа явно не помечена как disposable. Защита находится ниже навигации, потому что «просто загрузка страницы — это чтение» — ложь: многие такие приложения пишут при монтировании. Ни один агент и ни один клик в вебе не может изменить эту настройку.

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

• Секреты не попадают в коммитимые файлы. .trout/config.yaml содержит только ссылки env:. Значения живут в .env, исключённом из git.

• Ничего не хостится. Ничего не покидает вашу машину, кроме вызовов выбранного вами провайдера моделей. Никакой телеметрии.

Провайдеры моделей

Anthropic, OpenAI или Kimi — или любая OpenAI-совместимая конечная точка через base_url.

model:
  provider: anthropic
  api_key: env:ANTHROPIC_API_KEY

Анализ никогда не вызывает модель, поэтому trout scan, trout gaps и trout run работают вообще без ключа.

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

React + Vite (Lovable, v0, Bolt) и Next.js App Router, на TypeScript, с Supabase, задеплоенные где угодно, доступном по HTTP. Аутентификация через Supabase, Clerk или NextAuth.

Осознанно узкий. Глубина на одном стеке лучше поверхностного покрытия многих — а эти кодовые базы достаточно регулярны, чтобы статический анализ был на них по-настоящему точен. Другие стеки — в одном адаптере: см. docs/adapters.md.

Дорожная карта

Участие

Добавление фреймворка, провайдера аутентификации или тест-раннера означает реализацию одного протокола и регистрацию точки входа — без форка. См. CONTRIBUTING.md и docs/adapters.md.

Полный набор тестов запускается офлайн без API-ключа. Это осознанное решение, и его стоит сохранить.

Лицензия

Apache 2.0