test-trust

AI 코딩 에이전트(Claude Code, Codex, OpenHands, Cursor 또는 로컬 모델 — MCP, Model Context Protocol을 통한 에이전트 비종속)에게 변경 사항을 커버하는 테스트가 어떤 것인지뿐만 아니라, 해당 테스트가 실제로 그곳의 회귀(regression)를 잡아낼 수 있는지 신뢰할 수 있는지를 알려줍니다.

"CI가 초록불이다"와 "이 변경은 안전하다"는 오늘날 모든 에이전트가 동일한 것으로 취급합니다. 하지만 그렇지 않습니다. 함수를 커버하는 테스트가 있다는 것과, 그 함수가 고장났을 때 실제로 실패할 테스트가 있다는 것은 다릅니다 — 과도한 목(mock) 테스트, 새 출력을 그저 다시 기록하는 스냅샷 테스트, 그리고 단언(assertion)이 없는 테스트는 모두 아무것도 잡지 못하면서 초록불을 보여줍니다.

방법

1. 뮤테이션 테스팅(성숙한 기존 엔진을 래핑하며, 재구현이 아님 — Python용 mutmut, JS/TS용 StrykerJS, Go용 gremlins, Rust용 cargo-mutants): 변경된 코드에 의도적으로 작은 버그를 주입하고, 커버하는 테스트가 실제로 실패하는지 확인합니다. 뮤테이션별 테스트 선택은 각 엔진 자체의 커버리지 데이터에서 오며, 여기서 재구현하지 않습니다 — mutmut과 Stryker(지원되는 러너(jest/mocha/vitest)가 있는 경우)는 각 뮤테이션을 커버하는 특정 테스트만 선택합니다. gremlins와 cargo-mutants는 커버리지가 0인 뮤테이션은 건너뛰지만, 커버리지가 있는 모든 뮤테이션에 대해 관련 전체 테스트 스위트를 다시 실행합니다 — 더 거칠고(대형 저장소에서는 더 느리지만) 여전히 올바른 메커니즘입니다.

2. Diff 스코핑(당사의 방식): git diff의 변경된 라인을 각 언어 자체 파싱을 통해 둘러싼 함수에 매핑하여, 뮤테이션 실행과 신뢰 점수 모두 실제 변경된 부분에만 범위가 지정되며 전체 파일/저장소가 아닙니다.

3. 퓨전(새로운 부분, 다른 곳에서는 구축되지 않음 — 검증됨): 위의 것을 결합하여 변경된 함수별 하나의 신뢰 점수로 만들고, 에이전트가 초록색 테스트 실행을 안전성의 증거로 취급하기 전에 호출할 수 있는 MCP 도구로 노출합니다.

examples/weak-test-fixture/(Python), examples/weak-test-fixture-js/(JS), examples/weak-test-fixture-go/(Go), examples/weak-test-fixture-rust/(Rust), examples/plug-and-play-fixture/(구성 전혀 없음), examples/multi-file-fixture-js/(형제 모듈을 임포트하는 함수 — 뮤테이션 스코딩이 교차 파일 임포트를 깨지 않음을 증명)를 참조하세요. 오늘은 통과하지만 실제 버그는 잡지 못하는 테스트로 커버된 함수의 실제 작동 데모입니다.

Related MCP server: sumo-qa

실제 저장소로 검증, 픽스처만이 아님

위의 모든 픽스처는 장난감입니다. 개념을 신뢰하기 전에, 이 도구는 또한 네 가지 언어 모두의 실제 외부, 수정되지 않은 저장소에 대해 제로 구성으로 실행되었습니다: psf/requests(Python, 37개 실제 함수 점수화, 예: resolve_proxies가 신뢰 0.0으로 올바르게 플래그 — 실제로 이를 참조하는 테스트가 0개), kind-of(JS, 주간 다운로드 약 5천만, 36개 테스트가 모두 통과함에도 isArray와 isRegexp 플래그), dustin/go-humanize(Go), 그리고 chronotope/humantime(Rust, 실제 다중 모듈 crate — 뮤테이션 스코딩이 우리 자체 픽스처뿐만 아니라 실제 교차 모듈 코드에서도 깨지지 않음을 확인). 이 과정에서 네 개 중 세 개에서 실제 버그를 발견하고 수정했습니다 — 실패한 뮤테이션 실행이 잘못된 100% 신뢰 점수로 조용히 보고된 것, 그리고 한 파일에 스코프된 요청이 실제 전체 패키지를 조용히 뮤테이션한 스케일링 버그를 포함합니다. Rust의 실제 저장소 검사는 새 버그를 표면화하지 않았으며, 이는 cargo-mutants -f가 네 가지 중 가장 깨끗하고 가장 직접적으로 지원되는 스코핑 메커니즘임과 일치합니다. 전체 설명은 docs/architecture.md를 참조하세요.

이 도구가 래핑하는 외부 도구(사용하는 언어당 한 번 설치)

• Python: mutmut — 이 프로젝트의 의존성으로 자동 설치됩니다.

• JS/TS: @stryker-mutator/core — 첫 사용 시 npx를 통해 자동으로 가져옵니다.

• Go: gremlins — go install github.com/go-gremlins/gremlins/cmd/gremlins@latest

• Rust: cargo-mutants — cargo install cargo-mutants

사용해 보기

아직 PyPI에 게시되지 않음. 아래의 모든 명령은 이 저장소의 로컬 클론을 가정하며, 그 안에서 실행합니다(외부에서 uv run --directory <path> ... — 아래의 에이전트 임베딩 예제와 같이). 게시되면, 그 모든 것은 일반 pip install test-trust / uvx test-trust로 축소되며 어디서든 실행 가능합니다 — 클론 없음, 기억할 경로 없음, uv run --directory 없음. 그 단일 변경이 "설정이 있는 작동"과 "실제로 채택하기 쉬운" 사이의 마지막 단계입니다. 도구의 동작 방식은 전혀 변하지 않으며, 얻는 방법만 변합니다.

Python 3.11+ 및 uv가 필요합니다. 언어별 뮤테이션 엔진(위 참조)은 실제로 사용하는 언어에만 필요합니다 — 아래 Python 예시는 uv sync 외에 아무것도 필요하지 않습니다.

uv sync
uv run test-trust check examples/plug-and-play-fixture inventory.py

설정 파일 없이, 수동 뮤테이션 테스트 실행 없이 — 이 단일 명령은 언어를 자동 감지하고, 구성을 자동 작성하고, 저장소의 실제 테스트 명령을 사용하여 해당 파일에 스코프된 뮤테이션 테스트를 자동 실행하고, 신뢰 점수를 출력합니다.

다른 파일이나 저장소에 대해 실행하려면:

uv run test-trust check <path-to-repo> <source-file> [--changed-file F] [--base-ref REF] [--threshold T]

임계값 변경(기본 0.5) — 적절히 테스트된 것으로 간주하는 기준. 높이면(예: 0.8) 거의 완전한 뮤테이션 커버리지에 미치지 못하는 모든 것을 플래그합니다. 낮추면 최악의 공백만 플래그합니다. 동일한 매개변수, 세 가지 표면:

• CLI: --threshold 0.8, 위에 표시된 대로.

• MCP 도구: threshold는 get_test_trust 인수입니다. 예: get_test_trust(repo_path=..., source_file=..., threshold=0.8). 이걸 직접 호출하지 않습니다 — 에이전트가 호출합니다 — 따라서 설정한다는 것은 에이전트에게(프롬프트에서, 또는 CLAUDE.md의 상시 지시로: "get_test_trust를 threshold=0.8로 호출") 지시하는 것을 의미합니다. 설정하지 않으면 0.5를 사용합니다.

• GitHub Action: 워크플로 파일의 low-trust-threshold 입력:

  - uses: ./.github/actions/test-trust-pr
    with:
      github-token: ${{ secrets.GITHUB_TOKEN }}
      low-trust-threshold: "0.8"

에이전트에 임베드

일회성 설정, 프로젝트별이 아닌 전역으로 등록 — repo_path가 시작 시 고정이 아니라 모든 호출에서 매개변수이므로, 하나의 등록이 설정된 프로젝트뿐만 아니라 이후 여는 모든 프로젝트에 서비스합니다. Claude Code의 경우 ~/.claude.json(프로젝트의 .mcp.json이 아닌 사용자 수준)에 추가:

{
  "mcpServers": {
    "test-trust": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/test-trust", "test-trust", "mcp"]
    }
  }
}

동일한 command/args 형태는 Codex, Cursor 또는 다른 MCP 클라이언트에서도 작동합니다 — 해당 내용과 PyPI에 게시된 후 변경되는 사항(uvx test-trust mcp, 로컬 경로 전혀 불필요)은 docs/embedding.md를 참조하세요.

그 후에는 일상적으로 보이지 않습니다: 에이전트가 파일 읽기 또는 bash 도구를 호출하는 것과 같은 방식으로 작업 중간에 get_test_trust를 직접 호출합니다 — 직접 호출하지 않습니다.

또는 에이전트 없이 모든 PR에서 실행

.github/actions/test-trust-pr은 PR의 모든 변경된 지원 파일을 점수화하고 하나의 코멘을 게시(또는 이후 푸시에서 업데이트)합니다 — 기존 테스트가 실제로 그곳의 회귀를 잡지 못하는 함수를 플래그합니다. AI 에이전트를 사용하는지 여부와 관계없이 코드 리뷰를 하는 모든 팀에 유용합니다. .github/workflows/test-trust.yml이 작동 예시이며, 실제 저장소의 실제 커밋에 대해 종단 간(디프 감지, 점수화, "모두 정상" 및 "플래그됨" 코멘트 렌더링 모두) 검증되었습니다 — 실제 GitHub API 호출 자체만 테스트되지 않았습니다. 실제 PR이 필요하기 때문입니다.

개발

uv sync
uv run pytest tests/            # this project's own unit test suite
uv run test-trust check <repo> <file>   # exercise it against real code

tests/는 결정적 로직(디프 스코핑, 신뢰 점수 집계, 언어 자동 감지, 각 뮤테이션 엔진의 보고서 어댑터)을 제작된 픽스처로 커버합니다 — 빠르고, 외부 뮤테이션 테스트 도구가 필요 없으며, 이 스위트가 실제로 CI(.github/workflows/ci.yml)에서 실행됩니다. 위의 실제 저장소 검증을 대체하지는 않습니다 — 그것은 개발 중에 수동으로 일회성으로 수행한 작업(실제 외부 클론, 실제 엔진 설치)이며, CI가 모든 푸시에서 다시 실행하는 것이 아닙니다. 나중에 자동화할 가치가 있습니다. 아직은 아닙니다.

MIT 라이선스.