docs(10_Wiki): 위키 전체 재구성 — Topic_* 폴더를 4개 카테고리로 통합 + 대규모 중복 제거
Topic_Agent/Topic_Blog/Topics/Topics_Biz/Topics_Meeting/Topics_Rag의 마크다운 지식 문서를 Topic_General/Topic_Programming/Topic_Graphic/Topic_Business 4개 카테고리로 재분류. - 중복 제거: frontmatter의 status:duplicate/merged + duplicate_of/redirect_to 필드로 자기 자신을 중복으로 선언한 리다이렉트 stub 1032개 제거, 완전 동일 내용 파일 472개 제거, 동일 파일명·다른 내용 충돌 시 더 큰(완전한) 버전만 유지(162개 제거) — 총 1639개 중복 제거. - 분류: 폴더 단위로 명확한 항목(AI_and_ML/Coding/Architecture 등 → Programming, Comfyui/Visual_Effects → Graphic, Topics_Biz/Topics_Meeting/사업 등 → Business, Poetic_Blog_Writing/창의성/Game_Design 등 → General)은 폴더 우선순위로, 나머지 혼재 폴더(Topic_Agent/Topic_Blog/Topics 루트/Thinking & Reasoning/Other/UI_UX_Assets)는 title/tags 키워드 스코어링으로 파일 단위 분류(불명확한 경우 General로 폴백). 원본 폴더명은 "From_*" 서브폴더로 보존해 추적 가능성 유지. - 최종 배치: Programming 2784 / General 1608 / Graphic 285 / Business 249 = 4926개 문서. - 에이전트 운영 상태(.astra/.agent/.obsidian/sessions/memory/_company/docs/lessons/_shared/src)는 지식 콘텐츠가 아니므로 재분류 대상에서 제외하고 원위치 유지. - Topics/Topic_email(상위 보호 폴더 Topic_email과 파일명 100% 중복) 삭제 — 보호 폴더 자체는 미변경. - 완전히 비게 된 Topic_Agent/Topic_Blog/Topics_Biz/Topics_Rag 폴더 제거.
This commit is contained in:
Antigravity Agent
@@ -0,0 +1,106 @@
|
||||
---
|
||||
id: testing-contract-testing
|
||||
title: Contract Testing — 서비스 간 약속 검증
|
||||
category: Coding
|
||||
status: draft
|
||||
source_trust_level: B
|
||||
verification_status: conceptual
|
||||
created_at: 2026-05-09
|
||||
updated_at: 2026-05-09
|
||||
tags: [testing, contract-test, pact, microservices, vibe-coding]
|
||||
tech_stack: { language: "TypeScript / Pact", applicable_to: ["Backend microservices"] }
|
||||
applied_in: []
|
||||
aliases: [consumer-driven contract, Pact, schema test]
|
||||
---
|
||||
|
||||
# Contract Testing
|
||||
|
||||
> 마이크로서비스 환경에서 E2E 테스트는 비싸고 느리다. **각 서비스가 "다른 서비스와의 약속(contract)" 만 검증** = consumer-driven contract. 약속 깨면 즉시 파이프라인 fail.
|
||||
|
||||
## 📖 핵심 개념
|
||||
- Consumer 가 "이 형식의 응답을 기대한다" 라는 contract 작성.
|
||||
- Provider 는 그 contract 를 받아 자기 코드가 약속을 지키는지 검증.
|
||||
- 양쪽이 contract 를 통해 통신, E2E 환경 안 띄움.
|
||||
|
||||
## 💻 코드 패턴 (Pact)
|
||||
|
||||
### Consumer 측 (Frontend / 다른 서비스)
|
||||
```ts
|
||||
import { PactV3, MatchersV3 } from '@pact-foundation/pact';
|
||||
const { like, eachLike, integer } = MatchersV3;
|
||||
|
||||
const provider = new PactV3({ consumer: 'web-app', provider: 'user-service', port: 1234 });
|
||||
|
||||
test('GET /users/:id', async () => {
|
||||
await provider
|
||||
.given('user 1 exists')
|
||||
.uponReceiving('a request for user 1')
|
||||
.withRequest({ method: 'GET', path: '/users/1' })
|
||||
.willRespondWith({
|
||||
status: 200,
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: like({
|
||||
id: integer(1),
|
||||
email: like('a@a.com'),
|
||||
roles: eachLike('admin'),
|
||||
}),
|
||||
});
|
||||
|
||||
await provider.executeTest(async (mock) => {
|
||||
const res = await fetch(`${mock.url}/users/1`).then(r => r.json());
|
||||
expect(res.id).toBe(1);
|
||||
});
|
||||
});
|
||||
```
|
||||
실행 결과 = `pacts/web-app-user-service.json` 파일.
|
||||
|
||||
### Provider 측 검증
|
||||
```ts
|
||||
import { Verifier } from '@pact-foundation/pact';
|
||||
|
||||
test('user-service satisfies web-app contract', async () => {
|
||||
const v = new Verifier({
|
||||
provider: 'user-service',
|
||||
providerBaseUrl: 'http://localhost:3000',
|
||||
pactUrls: ['./pacts/web-app-user-service.json'], // 또는 Pact Broker
|
||||
stateHandlers: {
|
||||
'user 1 exists': async () => {
|
||||
await db.users.upsert({ id: 1, email: 'a@a.com' });
|
||||
},
|
||||
},
|
||||
});
|
||||
await v.verifyProvider();
|
||||
});
|
||||
```
|
||||
|
||||
### Pact Broker — 중앙 저장
|
||||
- consumer CI: pact 파일 publish.
|
||||
- provider CI: 최신 pact 받아 검증.
|
||||
- can-i-deploy 명령으로 안전한 deploy 확인.
|
||||
|
||||
## 🤔 의사결정 기준
|
||||
| 상황 | 권장 |
|
||||
|---|---|
|
||||
| 마이크로서비스 다수 (>3개) | Pact 도입 |
|
||||
| 단일 서비스 + DB | unit + integration 만 충분 |
|
||||
| Public API (외부 사용자) | OpenAPI 스키마 + 검증 |
|
||||
| GraphQL | schema introspection + breaking change detector |
|
||||
| gRPC | proto 가 자체 contract |
|
||||
| Frontend ↔ Backend | Pact 또는 OpenAPI generator (zod, ts-rest) |
|
||||
|
||||
## ❌ 안티패턴
|
||||
- **contract 안에 정확한 값 (literal) 만 명시**: 실 응답이 약간만 달라도 fail. matcher 사용 (like / eachLike / regex).
|
||||
- **provider state handler 없음**: contract 가 "user 1 exists" 가정 — handler 없으면 검증 못 함.
|
||||
- **breaking change 없이 contract 갱신**: 옛 consumer 가 깨짐. semantic versioning + can-i-deploy.
|
||||
- **pact 만 있고 unit/integration test 없음**: pact 는 약속만, 비즈니스 로직 안 검증.
|
||||
- **양쪽 모두 mock**: contract 가 양쪽에서 거짓말이면 의미 없음. provider 는 진짜 코드 검증.
|
||||
- **contract test 가 가짜 데이터 fixture 의존**: stateHandlers 로 진짜 상태 만들어야.
|
||||
|
||||
## 🤖 LLM 활용 힌트
|
||||
- consumer 측: matcher 사용 (literal X).
|
||||
- provider 측: stateHandler 로 진짜 DB 상태.
|
||||
- Pact Broker + can-i-deploy 가 deploy gate.
|
||||
|
||||
## 🔗 관련 문서
|
||||
- [[Testing_Test_Pyramid]]
|
||||
- [[Testing_Mocking_Boundaries]]
|
||||
Reference in New Issue
Block a user