부록 A · 테스트 실행과 디버깅¶

Java 개발자가 IntelliJ에서 하던 것들 — 테스트 하나만 돌리기, 브레이크포인트 걸고 스텝 실행 — 을 이 프로젝트에서 그대로 하는 방법입니다.

테스트 실행 (pytest = JUnit)¶

모든 명령은 agent/ 폴더에서 실행합니다.

하고 싶은 것	명령	IntelliJ 였다면
전체 테스트	`uv run pytest -q`	프로젝트 우클릭 → Run All Tests
파일 하나	`uv run pytest tests/test_graph.py`	테스트 클래스 실행
테스트 하나	`uv run pytest tests/test_graph.py::test_clarify`	`@Test` 메서드 하나 실행
이름으로 골라서	`uv run pytest -k "hallucin"`	패턴 매칭 실행
첫 실패에서 멈춤	`uv run pytest -x`	—
직전 실패한 것만 재실행	`uv run pytest --lf`	실패 테스트 재실행
상세 출력	`uv run pytest -v`	—
`print()` 출력 보기	`uv run pytest -s`	(pytest 는 기본으로 stdout 을 숨김)

assert 가 실패하면 pytest 가 양쪽 값을 자동으로 펼쳐서 보여줍니다 — assertEquals(expected, actual) 같은 전용 메서드가 필요 없는 이유입니다.

디버깅 방법 3가지¶

방법 1 — IDE 브레이크포인트 (가장 익숙한 방식)¶

저장소에 VS Code 설정이 포함되어 있습니다 (.vscode/launch.json). 전제: Python 확장(ms-python) 설치.

서버 디버깅: 줄번호 왼쪽 클릭으로 브레이크포인트 → F5 → "prepay-agent 서버 (디버그)" 선택 → curl 이나 WAS 로 요청을 쏘면 해당 줄에서 멈춤. 변수 확인·스텝 오버(F10)·스텝 인투(F11) 전부 IntelliJ 와 같은 감각입니다.
테스트 디버깅: 좌측 플라스크(🧪) 아이콘의 테스트 탐색기에서 개별 테스트 옆 벌레 아이콘 클릭 → 브레이크포인트에서 멈춤. (또는 F5 → "pytest 전체 (디버그)")
Run(▶) vs Debug(🐞): IntelliJ 와 동일 — Run 은 브레이크포인트를 무시하고 빠르게 실행(통과 확인용), Debug 는 디버거를 붙여 브레이크포인트에서 멈춤(원인 조사용). Debug 의 브레이크포인트는 테스트 코드뿐 아니라 테스트가 호출하는 앱 코드(예: nodes.py 의 validate)에도 걸립니다 — 그래프 디버깅의 핵심 패턴.
주의: 디버거에서는 자동 리로드가 꺼져 있어야 브레이크포인트가 잡힙니다(리로더가 자식 프로세스를 만들기 때문). launch.json 이 APP_RELOAD=false 를 강제하므로 F5 로 띄우면 신경 쓸 것이 없습니다.
PyCharm(= Python 계의 IntelliJ, 같은 JetBrains 제품) 사용자는 설정 없이 우클릭 → Debug 로 동일하게 됩니다.

방법 2 — `breakpoint()` 한 줄 (Java 에 없는 물건)¶

멈추고 싶은 코드 줄에 직접 breakpoint() 를 적으면, 터미널 실행 중 그 지점에서 대화형 디버거(pdb)로 진입합니다:

async def validate(self, state: AgentState) -> dict:
    decision = state["decision"]
    breakpoint()          # ← 여기서 멈춰서 터미널이 디버거 프롬프트로 바뀜
    missing = find_missing_ids(...)

pdb 프롬프트에서 쓰는 명령 (IntelliJ 단축키 대응):

pdb	의미	IntelliJ
`p state["decision"]`	표현식 출력	Evaluate Expression
`pp state`	보기 좋게 출력	—
`n`	다음 줄	Step Over (F8)
`s`	함수 안으로	Step Into (F7)
`c`	계속 실행	Resume (F9)
`w`	콜스택	Frames 패널
`q`	중단	Stop

pytest 실행 중에도 그대로 동작합니다 (pytest 가 알아서 출력 캡처를 풀어줍니다). 커밋 전에 지우는 것만 잊지 마세요.

방법 3 — `pytest --pdb` (실패 지점 사후 부검)¶

uv run pytest --pdb

테스트가 실패하는 순간 그 지점의 디버거로 떨어집니다. 브레이크포인트를 미리 걸 필요 없이, "왜 깨졌지?"를 실패한 자리에서 변수 들여다보며 확인할 수 있습니다.

API 요청 보내기 — curl 말고 편한 방법 2가지¶

① FastAPI 내장 Swagger UI (설치 0, GUI) — 서버를 켜고 브라우저에서 http://localhost:8800/docs를 열면, 스프링의 springdoc(Swagger)처럼 자동 생성된 대화형 API 문서가 나옵니다. "Try it out" 버튼으로 요청 본문을 편집해 바로 쏠 수 있고, DTO 스키마도 표로 보입니다. FastAPI가 Pydantic 모델에서 자동으로 만들어주는 것이라 별도 설정이 없습니다.

② REST Client 확장 + agent/requests.http (팀 공유용) — VS Code 확장 "REST Client"(humao.rest-client)를 설치하면, 저장소에 커밋된 agent/requests.http 파일의 각 요청 위에 Send Request 링크가 생깁니다. 클릭하면 옆 창에 응답이 뜹니다. Postman과 달리 요청 모음이 저장소에 커밋되므로 팀 전체가 같은 시나리오를 공유하고, fixture JSON 파일을 본문으로 참조(< ./tests/fixtures/...)해서 중복도 없습니다.

Postman 스타일의 GUI 패널을 꼭 원하면 Thunder Client 확장(rangav.vscode-thunder-client)도 있습니다 — 다만 요청 모음의 팀 공유 관점에서는 ①·②를 권장합니다.

개발 포트는 8800 (501 주의)

이 개발 서버의 8000 포트는 다른 프로젝트의 정적 서버가 쓰고 있어서, 그쪽에 POST 를 보내면 501 Not Implemented 가 옵니다. 이 프로젝트는 8800 포트로 통일 — launch.json, requests.http, 실습서 예시 모두 8800 기준입니다.

확장 프로그램 정리 — 뭐가 내장이고 뭐가 확장인가¶

것	정체
좌측 플라스크(🧪) Testing 탭	VS Code 내장 — 단, 내용물을 채우는 건 언어별 확장. Python 테스트가 보이려면 Python 확장 필요
Python 확장 (ms-python.python)	pytest 탐색·실행, 디버거(launch.json 의 `"type": "debugpy"`), 자동완성 제공
REST Client (humao.rest-client)	`.http` 파일 실행

저장소의 .vscode/extensions.json에 위 2개를 권장 목록으로 넣어두었으므로, 처음 여는 팀원에게 VS Code가 설치를 자동으로 제안합니다.

상황별 추천¶

상황	추천
그래프 노드 로직이 이상함	IDE에서 해당 테스트를 벌레 아이콘으로 디버그 (방법 1)
서버로 실제 요청을 받았을 때의 흐름 추적	F5 서버 디버그 + curl (방법 1)
IDE 없이 서버 터미널에서 빠르게	`breakpoint()` 한 줄 (방법 2)
테스트가 갑자기 깨졌는데 원인 불명	`uv run pytest --lf --pdb` (방법 3)
값 하나만 슬쩍 보고 싶음	`print()` + `pytest -s` — 부끄러워할 것 없음, 다들 씁니다