peira (피라) · AI 네이티브 API 테스팅
당신의테스트 계획이컴파일됩니다.실행은 결정론적 러너가 합니다.
인텐트 컴파일러, 결정론적 러너, 실패 트리아지, 증거 원장을 하나의 CLI로 제공합니다. peira compile 과 peira run 을 어떤 REST API에든 겨누세요.
API 키 불필요 · 가입 불필요 · 런타임 LLM 호출 0 · MIT
run-start · the loop
동작 원리
AI-네이티브 테스팅은 예전 테스팅에 모델을 덧붙인 것이 아닙니다 — 역할 분담 자체가 달라집니다. 약속 하나가 루프 전체를 지나는 과정을, 산출물까지 함께 따라가 보세요.
당신이 쓰는 것
## Cancelling a shipped order Cancelling an order that has already shipped is refused with 409, and the order stays SHIPPED.
…작성 표면은 이것이 전부입니다 — 태깅은 에이전트가 처리합니다.
당신이 얻는 것
- 실행 가능하고 검토 가능한 케이스 — 레퍼런스 베드에서 16개 섹션이 26개 케이스가 되었습니다
- 모든 인바리언트 섹션마다 실행할 때마다 새로 생성되는 시드 기반 프로브 5개
- 필요할 때마다 다시 만드는 Given/When/Then 문서와 시각적 HTML 실행 리포트
- 이 섹션이 실행을 거듭하며 applied를 쌓아 가는 신뢰 원장
약속을 서술합니다 — 평범한 문장으로
당신의 일은 문장을 쓰는 것뿐입니다. 태그는 기계적인 작업입니다: 에이전트가 붙여 주고(드롭인 에이전트 지침에 들어 있습니다), peira adopt가 기존 문서에 붙여 주며, 태그가 없어도 동작합니다 — id는 제목에서 파생되기 때문입니다. 태그는 문장을 고쳐 써도 계보가 살아남게 할 뿐입니다.
사람 · 태그는 에이전트가intent/orders.md
## Cancelling a shipped order ← 당신 <!-- peira: id=order-cancel-shipped kind=ac --> ← 에이전트 Cancelling an order that has already shipped ← 당신 is refused with 409, and the order stays SHIPPED.
사람이 테스트 코드를 손으로 씁니다
사람은 인텐트를 씁니다 — 평범한 마크다운, 섹션 하나에 약속 하나
테스트 코드가 명세에서 소리 없이 멀어집니다
모든 케이스는 출처가 된 인텐트를 기록합니다 — 그 문장이 바뀌면 표시되어 재컴파일됩니다
sleep과 재시도, 그리고 미덥지 않은 green
시드 기반의 결정론적 판정 — 어떤 실패든 그대로 재현됩니다
빨간 빌드는 원인부터 뒤져야 하는 일거리입니다
실패가 bug | drift | flake로 분류되어 증거와 함께 돌아옵니다
peira render
읽을 수 있는 산출물
케이스는 부분 일치 의미론을 가진 JSON입니다. 명령 하나면 같은 케이스가 Given/When/Then이 되거나 — 실패마다 관찰된 요청/응답 로그가 붙은 완전한 시각적 HTML 실행 리포트가 됩니다.
GivenPOST /orders as alice — captures orderId ← body.id
WhenGET /orders/status?id=$orderId, polling until { status: "CONFIRMED" }
Thenthe response is 200, and the body matches { id: $orderId, status: "CONFIRMED" }
Finallyevery captured job is drained to a terminal state
From intent status-visibility @ ae5ab7a63816 — when the section's text changes, this case is flagged stale and recompiled.
--seed 42
시드 기반 테스트 데이터
시드는 그 실행의 재생 번호입니다. 모든 “랜덤” 값은 hash(seed, case id, key)입니다 — 순수 함수이고, 저장되는 것은 없습니다. 같은 시드, 같은 서비스 상태 → 같은 판정. 어떤 실패든 그대로 재현됩니다.
peira triage
실패 트리아지
인프라 오류는 모델이 보기 전에 걸러집니다 — 닿지 않는 환경을 제품 버그로 오독하는 일이 구조적으로 불가능합니다. 남은 것은 케이스가 아니라 인텐트 문장을 기준으로 판단됩니다.
서비스가 약속을 어겼습니다
관찰된 동작이 인텐트의 요구와 모순됩니다. 기대와 관찰이 담긴 finding으로 돌아오며, 그대로 등록할 수 있습니다.
약속이 움직였습니다
케이스의 표현은 위반되었지만 인텐트의 실제 요구는 여전히 유효합니다. 가장 작은 인텐트 수준 diff로 돌아오고 — 승인하거나 거절하는 것은 당신입니다.
증거가 부족합니다
비결정성을 시사하는 실패 양상입니다. 재실행 처방으로 돌아오며 — 시드가 함께 오므로 재현은 정확합니다.
case-verdict → applied | contradicted
증거 원장
판단이 끝난 실행은 peira evidence로 기록하고, 현황은 peira trust로 읽습니다. 통과한 섹션은 applied를 남기고 — 트리아지된 버그도 마찬가지입니다. 위반을 잡아내는 제 몫을 했기 때문입니다. 판단이 끝난 drift는 사유가 그대로 인용된 채 contradicted를 남기고, 판단되지 않은 잡음은 아무것도 남기지 않습니다.
| section | applied | contradicted | runs | last applied |
|---|---|---|---|---|
| plan#parallel-request-queueing | 3 | 0 | 3 | 2026-08-29 |
| plan#robustness | 3 | 0 | 3 | 2026-08-29 |
| plan#get-status | 2 | 1 | 2 | 2026-08-29 |
| plan#post-submit | 2 | 1 | 2 | 2026-08-29 |
real rows — peira’s own committed ledger, 3 recorded runs
evidence · docs/findings/
지표
Peira(피라)의 베드는 어떤 서비스를 테스트 픽스처로 재구현한 것입니다. 함께 들어 있는 27개의 손으로 쓴 명세는 원본으로, 그 서비스를 위해 수년 전에 작성된 것입니다.
런타임 LLM 호출
0
CI에 API 키도, 세션도 필요 없습니다 — 머지를 막는 것은 종료 코드입니다
레거시 명세 재표현
27/27
원래의 손으로 쓴 스위트를 request, capture, expect로 재표현했습니다 — 별도 코드로 빠진 적 0회, sleep 0
드러난 불일치
3
레거시 테스트 계획을 그대로 컴파일하자 인텐트와 구현의 간극이 드러났습니다 — 그중 하나는 아무도 테스트한 적이 없었습니다
외부 API, 첫 시도
5/5
공개된 서드파티 API를 대상으로 컴파일했습니다; 베드 설정은 URL 한 줄이었습니다
트리아지 일치율
87.9%
미리 심어 둔 33개 동작 변화에 대한 bug/drift 판정; 스키마 거부와 인젝션은 0건
도구 자체의 테스트
316
실제로 배포되는 컴파일 산출물을 대상으로 실행 — 엄격한 TypeScript, CI는 Linux와 Windows
첫 판정까지
57ms
부팅, 전체 스위트 로드와 검증, 실제 요청 발행, 결과 보고까지 — 트랜스파일 파이프라인도, JVM도, 브라우저도 없습니다
케이스당 도구 오버헤드
0.17ms
주장이 아니라 측정값입니다 (npm run bench) — 기다리게 되는 것은 러너가 아니라 당신의 서비스입니다
run-end · 0 error
시작하기
마크다운 파일 하나와 URL 하나면 시작할 수 있습니다. 첫 실행은 증거를 남기고, 세 번째 실행부터 신뢰가 쌓이기 시작합니다.
API 키 불필요 · 가입 불필요 · 런타임 LLM 호출 0 · MIT
문서 읽기 — 시작하기, CLI 레퍼런스, 케이스 해부