TestTrout

AI가 만든 앱을 위한 테스트 어시스턴트.

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

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

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

문제

코딩 에이전트는 빠르게 결과물을 만듭니다. 하지만 조용히 무언가를 깨뜨리기도 하고, 에이전트가 만든 앱들 — Lovable, v0, Bolt, Vercel에 직접 만든 React — 에는 거의 항상 테스트가 없습니다. 그래서 루프는 방금 코드를 작성한 대상이 *"저는 괜찮아 보이는데요"*라고 말하는 것으로 끝납니다.

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

Related MCP server: Lastest

실행하기

pip install testtrout
trout up

스토리지, 워커, 그리고 localhost:7411의 인터페이스. Docker도, 데몬도, 설치할 데이터베이스도 없습니다 — SQLite는 ~/.testtrout 아래에, 워커는 프로세스 내부에 있습니다. 어떤 종류의 API 키도 필요 없습니다. 여기서 모델을 호출하는 것은 없습니다.

작동 방식

프로젝트를 추가하세요 — 이 머신의 폴더와, 배포된 URL입니다.

trout add ~/code/my-app --url https://my-app.vercel.app

그 다음 네 단계, 그리고 네 개의 명령어가 있습니다:

trout look     # read the code, ask the deployment, work out what is testable
trout facts    # what I still need from you — all optional
trout build    # write the baseline and prove it
trout run      # re-run it and report what changed

베이스라인은 오늘 배포가 하는 일입니다. TestTrout은 그것을 기록하고 계속 그렇게 동작하는지 검증합니다. 현재 동작이 올바른지는 알지 못합니다 — 아무도 알려주지 않았기 때문입니다 — 그리고 절대 묻지 않습니다. 동작이 무엇인지는 알고, 그 동작이 바뀌는 날을 감지합니다.

이 단 하나의 규칙이 인터뷰도, 승인 대기열도, 제품에 대한 질문 목록도 없는 이유입니다. 묻는 것은 스스로 발견할 수 없는 구체적인 값뿐입니다:

모든 항목은 몇 초 안에 답할 수 있고, 모두 선택 사항이며, 각각 무엇을 가능하게 하는지 설명합니다. URL 하나만 주고 나머지는 주지 않으면, 로그아웃 상태에서 로드되는 모든 페이지를 얻습니다 — 대부분의 앱에서 이미 유용한 스위트입니다.

파악한 모든 것은 사이드바의 아티팩트로 보관됩니다 — 프로젝트 맵, 폼, 테스트 계획, 베이스라인 스위트 — 그래서 중요한 것이 채팅 스크롤백의 세 화면 위에 묻히지 않습니다.

아니면 코딩 에이전트에 머물기

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

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

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

TestTrout MCP 서버를 사용하세요. 저장소를 살펴보고, 나에게 아직 무엇이 필요한지 알려준 다음, 베이스라인을 만들고 실행하세요.

하나의 프로젝트에 바인딩된 일곱 개의 도구로, 에이전트가 잘못된 저장소에서 작업할 수 없습니다:

추가로 trout://map, trout://facts, trout://plan, trout://config, trout://scenarios를 리소스로 제공하므로, 대량 상태가 에이전트의 컨텍스트 창을 가득 채우지 않습니다.

무엇을 이해하는가

trout look은 네트워크 접근 없이 코드를 읽으므로, 방금 클론한 저장소에서도 안전합니다. 일반적인 Supabase 앱에서 다음을 찾아냅니다:

또한 행 수준 보안 없이 브라우저 코드에서 테이블에 쓰는 경우를 알려줍니다 — 즉 anon 키를 통해 전 세계에서 쓸 수 있다는 뜻입니다. 그것은 대개 새로운 소식입니다.

데이터베이스를 절대 요구하지 않습니다

테스트는 사용자가 앱에 접근하는 방식과 동일하게 접근합니다: 엔드포인트에 대한 HTTP, 그리고 인터페이스에 대한 실제 브라우저. 로그인은 trout look이 한 번 찾아내는 자체 로그인 폼을 통해 진행되므로, 테스트는 추측 대신 알려진 폼을 재생합니다.

그래서 필요한 것은 URL 하나와 테스트 계정 두 개뿐입니다. anon 키도, service role도, 프로젝트 자격 증명도 없습니다 — 대부분의 팀이 테스트 도구에 주기를 합리적으로 거부할 만한 것은 아무것도 없습니다.

인가도 여전히 다루어지며, 어쩌면 더 잘 다루어집니다: 두 개의 일반 계정으로 로그인했을 때, 한쪽이 볼 수 있는 것은 다른 쪽이 볼 수 없어야 합니다. 이것은 정책 그리고 그 위에 애플리케이션이 쌓아올린 모든 것을 검증합니다 — 실제 사용자가 마주하는 것과 동일합니다.

테스트를 신뢰할 만한 이유

PR별 추측이 아니라 베이스라인을 만듭니다. 방금 변경한 코드에서 파생된 테스트는 구성상 새 동작이 올바르다고 단언합니다 — 회귀를 잡을 수 없습니다. TestTrout은 먼저 작동 중인 배포에 대해 스위트를 인증하므로, 실패는 의미를 갖습니다.

어디에도 모델이 없습니다. 스캔에도, 계획에도, 테스트 작성에도 없습니다. 모든 단언은 배포가 실제로 한 일에 기반하므로, 같은 입력은 항상 같은 스위트를 만들고 설정할 API 키가 없는 이유입니다.

모든 단언은 출처를 지닙니다. 그리고 베이스라인에서는 항상 observed입니다 — 증거는 생성된 파일에 기록됩니다:

// observed: the page title when /orders was loaded
await expect(page).toHaveTitle('Orders');
// observed: seen on /orders at baseline
await expect(page.getByTestId('orders-table')).toBeVisible();

GET만 보냅니다. 엔드포인트 테스트는 엔드포인트가 선언하는 메서드와 관계없이 프로브가 만든 요청을 재생하므로, 프로덕션에 지정해도 그곳에서 아무것도 변경할 수 없습니다.

실패는 보고되기 전에 분류됩니다. assertion_failure만 제품 신호입니다. 인증 실패, 도달할 수 없는 데이터베이스, 차단된 서드파티 호출은 하네스에 관한 것이며, 불확정 실행이 절대 통과로 승격되지 않습니다.

터미널에서 모든 것

trout add ~/code/my-app --url https://my-app.vercel.app
trout look          # read the code, ask the deployment
trout facts         # what I still need — all optional
trout build         # write the baseline and prove it
trout run           # re-run it; a failure means behaviour changed

모든 명령어는 --json을 지원합니다. 전체 워크스루는 docs/setup.md에 있습니다.

저장 방식

테스트 스위트는 저장소에 남아 커밋되고 검토 가능합니다:

.trout/scenarios/*.yaml    what each test asserts, in plain language
.trout/facts.yaml          what was asked for — never a secret value
.trout/plan.yaml           what can be tested, and what is waiting
.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로 표시되지 않는 한 변경 요청은 네트워크 계층에서 차단됩니다. 가드는 내비게이션 아래에 있습니다. "페이지를 로드하는 것만으로는 읽기 전용"이라는 말이 거짓이기 때문입니다 — 이런 앱 중 상당수는 마운트 시에 쓰기를 수행합니다. 어떤 에이전트도, 어떤 웹 클릭도 그 설정을 변경할 수 없습니다.

• 서드파티는 가로채집니다. 테스트 실행은 카드를 청구하거나 고객에게 이메일을 보낼 수 없습니다. 일치하지 않는 아웃바운드 요청은 크게 실패합니다; 조용히 아무것도 일치하지 않는 목은 스위트가 아무것도 테스트하지 않으면서 초록색을 보고하는 방식입니다.

• 비밀은 커밋된 파일 밖에 유지됩니다. .trout/config.yaml은 env: 참조만 보관합니다. 값은 gitignore된 .env에 있습니다.

• 호스팅되는 것도, 머신을 떠나는 것도 없습니다. 호출할 모델도, 만들 계정도 없습니다. 텔레메트리도 없습니다.

지원 스택

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