TestTrout

AI 기반 앱을 위한 테스트 어시스턴트.

앱으로 실행하거나 MCP를 통해 코딩 에이전트에 넘겨주세요. 어느 쪽이든 앱에 없던 테스트를 작성하고, 언제 깨지는지 알려줍니다.

송어는 지표종입니다. 깨끗하고 산소가 풍부한 물에서만 살기 때문에, 개울에서 송어를 발견하면 직접 테스트하지 않아도 물이 건강하다는 것을 알 수 있습니다.

좋은 테스트 스위트도 바로 그런 것입니다. 잔일이 아니라 한눈에 읽을 수 있는 신호입니다.

문제점

코딩 에이전트는 빠르게 출시합니다. 하지만 조용히 문제를 일으키기도 하고, 에이전트가 만든 앱(Lovable, v0, Bolt, Vercel에서 직접 작성한 React)에는 테스트가 거의 없습니다. 그래서 루프는 방금 코드를 작성한 대상의 *"괜찮아 보인다"*는 말로 끝나버립니다.

TestTrout는 그 루프를 닫습니다. 저장소를 읽고, 실행 중인 배포에 연결하고, 무엇이 테스트되지 않았고 어떤 순서로 중요한지 파악하고, 실제 테스트를 작성하고 실행한 뒤 실제로 조치를 취할 수 있는 결과를 보고합니다.

Related MCP server: Lastest

시작하기

pip install testtrout
trout up

그러면 모든 것이 시작됩니다: 스토리지, 백그라운드 워커, 그리고 localhost:7411의 인터페이스. Docker, 데몬, 설치할 데이터베이스가 없습니다. 스토리지는 ~/.testtrout의 SQLite이고, 워커는 프로세스 안에서 실행됩니다.

그런 다음 인터페이스나 터미널에서 저장소를 연결하세요:

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

로컬 폴더를 연결해도 폴더는 절대 수정되지 않습니다. 스캔이 자동으로 시작되며, Setup 탭에 배포, Supabase, 테스트 계정, 모델 제공자 등 모든 설정이 있습니다.

이를 안전하고 유용하게 만드는 두 가지가 있습니다:

앱에 필요한 자격 증명을 알려줍니다. 소스를 읽어 어떤 변수에 접근하는지, 각 변수가 무엇을 위한 것인지, 해당 변수가 나타나는 줄을 발견합니다. 코드가 이미 명시한 것을 다시 유추하지 않습니다.

일부만 제공하면 일부 테스트 스위트가 만들어집니다. URL만 있으면 API 테스트를 프로브하고 실행할 수 있습니다. anon 키와 두 번째 계정을 추가하면 인가 테스트가 가능해집니다. 차단된 각 기능은 필요한 다음 한 가지를 정확히 말하며, 절대 "제대로 구성하세요"라고 하지 않습니다.

비밀 값은 gitignore된 .env에 기록됩니다. 커밋된 구성에는 env:NAME 참조만 들어 있고, 구성 필드에 입력된 실제 비밀 값은 거부됩니다.

또는 코딩 에이전트에 머물기

앱은 하나의 진입 방법이지 유일한 방법이 아닙니다. 앱이 하는 모든 일은 타입이 지정된 MCP 도구와 CLI 명령으로 제공되므로, 에디터를 떠나고 싶지 않은 사람은 떠날 필요가 없습니다:

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

.claude/skills/에 있는 스킬을 에이전트에 지정하거나, 에이전트에게 이렇게 말하세요:

TestTrout MCP 서버를 사용하세요. 저장소를 스캔하고, 중요도 순으로 테스트되지 않은 것을 보여주고, 상위 5개에 대한 테스트 초안을 작성한 다음 실행하세요.

열세 개의 도구는 하나의 프로젝트에 바인딩되어 있으므로 에이전트가 잘못된 저장소에서 작업할 수 없습니다:

게다가 trout://surfaces, trout://intent, trout://config, trout://scenarios가 리소스로 제공되므로, 대량 상태가 에이전트의 컨텍스트 창을 밀어내지 않습니다.

무엇을 이해하는가

trout scan은 완전히 결정적입니다. 모델도 네트워크도 없으며, 방금 클론한 저장소에서도 안전합니다. 일반적인 Supabase 앱에서는 다음을 찾습니다:

또한 브라우저 코드에서 행 수준 보안(row-level security) 없이 테이블이 쓰이는 경우를 알려줍니다. 즉, anon 키를 통해 누구나 쓸 수 있다는 뜻입니다. 이는 대개 처음 알게 되는 사실입니다.

테스트를 신뢰할 수 있는 이유

PR별 추측이 아니라 기준선을 만듭니다. 방금 변경한 코드에서 파생된 테스트는 새 동작이 구조적으로 올바르다고 단언하므로 회귀(regression)를 잡을 수 없습니다. 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

실행 기록, 시간 경과에 따른 커버리지, 작업 큐는 ~/.testtrout 아래의 SQLite에 저장됩니다. 이렇게 나눈 것은 의도적입니다. 스위트는 코드 옆에 있어야 풀 리퀘스트가 검토할 수 있고, 파일이 답할 수 없는 질문(이 테스트가 점점 더 불안정해지는가, 커버리지가 올라가는가)은 데이터베이스에 속합니다.

선택적 웹 뷰

trout web

한눈에 보는 커버리지, 순위가 매겨진 갭 목록, 시나리오 검토, 증거가 포함된 실행 기록, 실시간 로그. CLI와 동일한 .trout/ 파일을 사용합니다. 데이터베이스 없음, 호스팅 없음, 루프백 전용입니다. 전적으로 선택 사항이며, CLI와 MCP는 그 자체로 완전합니다.

안전

이 도구는 데이터베이스 자격 증명이 필요하고 배포를 구동할 수 있으므로, 보장 사항은 문서가 아닌 코드로 강제됩니다:

• 프로덕션은 기본적으로 읽기 전용입니다. 엔트리포인트가 명시적으로 disposable로 표시되지 않는 한, 변형(mutating) 요청은 네트워크 계층에서 차단됩니다. 이 가드는 내비게이션 아래 계층에 위치합니다. "페이지를 로드하는 것만으로는 읽기 전용"이라는 말은 거짓이기 때문입니다. 이 앱들 중 상당수는 마운트될 때 쓰기를 수행합니다. 어떤 에이전트도, 어떤 웹 클릭도 이 설정을 변경할 수 없습니다.

• 서드파티는 가로채입니다. 테스트 실행은 카드를 결제하거나 고객에게 이메일을 보낼 수 없습니다. 일치하지 않는 아웃바운드 요청은 분명하게 실패합니다. 조용히 아무것도 일치시키지 못하는 목(mock)은 아무것도 테스트하지 않으면서 스위트가 초록불을 보고하는 방식입니다.

• 비밀 값은 커밋된 파일에 남지 않습니다. .trout/config.yaml에는 env: 참조만 들어 있습니다. 값은 gitignore된 .env에 저장됩니다.

• 호스팅되는 것은 없습니다. 선택한 모델 제공자에 대한 호출 외에는 아무것도 머신 밖으로 나가지 않습니다. 텔레메트리도 없습니다.

모델 제공자

Anthropic, OpenAI 또는 Kimi — 혹은 base_url을 통한 모든 OpenAI 호환 엔드포인트.

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