Antigravity는 에이전트가 파일을 편집하고, 터미널 명령을 실행하고, 출력을 읽고, 다음 작업을 결정하는 루프입니다. 그렇다면 API 테스트는 왜 이 루프 밖에 있을까요? GUI에서 수동으로 실행해야 하는 테스트는 에이전트의 검증 흐름에 포함되지 않습니다.
해결 방법은 간단합니다. Apidog에서 만든 테스트 시나리오를 apidog-cli로 터미널에서 실행하고, Antigravity 규칙 파일에 그 명령을 등록하면 됩니다. 그러면 에이전트는 유닛 테스트와 마찬가지로 API 테스트를 실행하고 종료 코드를 기준으로 다음 작업을 결정할 수 있습니다.
먼저 CLI가 설치되고 인증되어 있어야 합니다.
apidog --version
위 명령이 버전을 출력하고 apidog login 인증이 완료된 상태를 기준으로 설명합니다. 설치와 첫 실행 과정은 AI 코딩 에이전트로 Apidog CLI를 설치하는 방법을 참고하세요.
Antigravity와 규칙 파일
Antigravity는 2025년 말에 출시된 Gemini 3 기반 Google 에이전트 개발 플랫폼입니다. Agent Manager를 통해 작업을 계획하고, 리포지토리 파일을 편집하고, 터미널과 브라우저에서 명령을 실행합니다.
Antigravity는 프로젝트 규칙을 읽어 에이전트 작업 방식에 반영합니다. 즉, 채팅에서 한 번만 “테스트를 실행해 달라”고 요청하는 대신 규칙 파일에 테스트 명령을 기록하면 이후 작업에서도 일관되게 사용할 수 있습니다.
자세한 개요는 Google Antigravity가 무엇이며 어떻게 사용하는지를 참고하세요.
1단계: Apidog CLI 규칙 파일 만들기
Antigravity는 작업 공간 루트의 .agents/ 디렉터리를 인식합니다. Google의 Antigravity 자율 개발자 파이프라인 코드랩에서는 작업 공간 규칙을 .agents/rules/에 배치하는 방식을 보여 줍니다.
프로젝트에 다음 파일을 만드세요.
.agents/rules/apidog.md
이미 루트에 AGENTS.md가 있다면 별도 파일을 만들지 않고 그 파일에 규칙을 추가해도 됩니다. 이는 Codex가 Apidog CLI를 위해 읽는 방식과도 동일합니다.
apidog.md에 다음 규칙을 추가합니다.
## Apidog CLI를 사용한 API 테스트
- API를 테스트하려면 GUI를 클릭하지 말고 Apidog 시나리오를 실행하십시오.
- 명령어: apidog run -t <scenario_id> -e <env_id> -r cli
- 종료 코드 0은 모든 어설션이 통과했음을 의미합니다. 0이 아닌 값은 실패를 의미합니다. 보고서를 열고 코드를 수정하십시오.
- 머신은 이미 `apidog login`을 통해 인증되었습니다. 절대로 --access-token 플래그를 추가하거나 이 파일에 토큰을 넣지 마십시오.
이 규칙을 채팅이 아니라 파일에 저장해야 하는 이유는 세션 지속성입니다. 채팅에서 언급한 시나리오 ID나 실행 지침은 세션 종료 후 사라질 수 있지만, 규칙 파일은 팀원과 이후 Antigravity 실행에서 계속 사용할 수 있습니다.
2단계: Apidog에서 실제 실행 명령 복사하기
시나리오 ID와 환경 ID를 직접 추측하지 마세요.
- Apidog에서 테스트 시나리오를 엽니다.
- CI/CD 탭으로 이동합니다.
- 생성된 명령을 복사합니다.
예시는 다음과 같습니다.
apidog run -t 123456 -e 789012 -r cli
각 옵션의 역할은 다음과 같습니다.
-
-t: 테스트 시나리오 ID -
-e: 환경 ID -
-r cli: 터미널 인라인 출력 리포터
복사한 실제 명령을 .agents/rules/apidog.md에 붙여 넣으세요. 옵션 전체 목록은 apidog run 명령 참조에서 확인할 수 있습니다.
3단계: 에이전트에게 API 테스트 실행 요청하기
규칙 파일을 추가한 뒤 Antigravity에서 작업을 시작합니다. 에이전트는 시작 시 규칙을 로드하므로 Apidog CLI 명령을 이미 알고 있어야 합니다.
다음처럼 요청하세요.
Apidog 테스트 시나리오를 실행하고 종료 코드를 알려주세요.
에이전트는 규칙 파일의 apidog run 명령을 자체 터미널에서 실행해야 합니다.
명령 실행 전에 승인이 필요한지는 Antigravity의 보안 프리셋에 따라 달라집니다. Google의 Antigravity 시작 코드랩에 설명된 것처럼, 설정에 따라 터미널 명령이나 파일 접근 전에 검토 요청이 표시될 수 있습니다.
스테이징 환경을 대상으로 하는 읽기 전용 테스트 시나리오라면 apidog run 실행 요청을 검토 후 승인할 수 있습니다. 자동 실행을 허용한 환경이라면 에이전트는 중단 없이 명령을 실행하고 결과를 보고합니다.
중요한 점은 에이전트의 요약만 받지 않는 것입니다. 실행 명령, 원시 출력, 종료 코드를 함께 확인하세요.
4단계: 터미널 보고서 읽기
실행이 실패했다면 -r cli 출력에서 원인을 확인할 수 있습니다. 일반적으로 다음 정보를 확인할 수 있습니다.
- 실행된 요청
- 각 어설션의 통과 또는 실패 여부
- 예상 값과 실제 값
- 실패한 상태 코드
- 누락되었거나 잘못된 응답 필드
에이전트가 API 핸들러를 수정해야 한다면 이 출력이 수정 방향을 제공할 수 있습니다.
브라우저에서 열거나 팀원에게 공유할 보고서도 필요하다면 HTML 리포터를 함께 사용하세요.
apidog run -t 123456 -e 789012 -r cli,html
html 리포터는 ./apidog-reports에 자체 포함 HTML 파일을 작성합니다. 에이전트가 다음 작업을 결정할 수 있도록 인라인 출력을 유지하려면 cli도 함께 지정하세요.
JUnit 형식의 CI 대시보드 연동을 포함한 리포터 옵션은 전체 Apidog CLI 가이드와 Apidog CLI 테스트 보고서 읽는 방법을 참고하세요.
에이전트 루프에 API 테스트 넣기
규칙 파일에 명령을 등록하면 에이전트의 작업 흐름은 다음과 같이 바뀝니다.
- API 핸들러 또는 관련 코드를 수정합니다.
-
apidog run으로 스테이징 환경의 시나리오를 실행합니다. - 종료 코드를 확인합니다.
- 종료 코드가
0이면 다음 작업으로 진행합니다. - 종료 코드가
0이 아니면 실패한 어설션을 읽습니다. - 상태 코드, 누락 필드, 잘못된 값 등을 수정합니다.
- 다시 테스트를 실행합니다.
즉, API 테스트가 유닛 테스트와 동일한 편집-테스트-수정 루프에 포함됩니다.
이 방식은 위임과 검증을 분리합니다. Antigravity는 명령을 실행하고 결과를 읽으며, 개발자는 Apidog에서 시나리오를 시각적으로 관리하고 실행 결과를 필요할 때 점검합니다. 더 넓은 워크플로우는 AI 에이전트를 사용하여 API 테스트를 수행하는 방법과 Apidog AI 테스트 하니스에서 확인할 수 있습니다.
Antigravity가 실제로 CLI를 실행했는지 확인하기
에이전트의 “테스트 통과” 요약만 신뢰하지 말고 다음 세 가지를 확인하세요.
1. 실제 명령 실행 여부
Antigravity 터미널에서 다음과 같은 명령이 실제로 실행되었는지 확인합니다.
apidog run ...
명령과 그 아래의 원시 출력이 보이지 않는다면 에이전트가 실행하지 않고 요약만 했을 수 있습니다. 이 경우 다시 실행하도록 요청하고 원시 출력을 보여 달라고 하세요.
2. 종료 코드
직접 다음과 같이 물어볼 수 있습니다.
그 apidog run 명령의 종료 코드는 무엇이었습니까?
apidog run은 모든 어설션이 통과하면 0으로 종료하고, 실패가 있으면 0이 아닌 값으로 종료합니다.
에이전트의 설명이 “통과”라고 해도 종료 코드가 0이 아니면 실패로 처리해야 합니다.
3. 시나리오와 환경 ID
“시나리오를 찾을 수 없음” 오류가 발생하면 에이전트가 ID를 잘못 기억했거나 임의로 사용했을 수 있습니다.
다음을 다시 확인하세요.
- Apidog CI/CD 탭에서 생성한 명령
-
.agents/rules/apidog.md의-t값 -
.agents/rules/apidog.md의-e값
규칙 파일에는 Apidog에서 생성된 실제 명령을 기록하는 것이 중요합니다.
선택 사항: Apidog MCP 서버 연결
대부분의 경우 규칙 파일에서 apidog run을 실행하는 것만으로 충분합니다. 에이전트가 구현 중 API 사양까지 참조해야 한다면 MCP 서버를 연결할 수 있습니다.
Antigravity는 Model Context Protocol(MCP)을 지원합니다. Google의 시작 코드랩에 따르면 MCP 서버는 다음 파일에 구성합니다.
$HOME/.gemini/config/mcp_config.json
mcpServers 객체에 command, args, env를 포함하는 서버 항목을 추가한 뒤 Antigravity 설정에서 MCP를 새로 고칩니다.
Apidog MCP 서버를 연결하면 에이전트는 MCP를 통해 API 사양을 읽을 수 있습니다.
역할은 분리됩니다.
- Apidog CLI: 테스트 시나리오 실행
- Apidog MCP 서버: API 사양 제공
자주 발생하는 문제
규칙 파일을 무시하는 경우
에이전트가 일반 명령을 실행하거나 아무 명령도 실행하지 않는다면 규칙이 로드되지 않았을 수 있습니다.
다음을 확인하세요.
- 파일 이름이 올바른지
-
.agents/rules/아래에 파일이 있는지 - 작업 공간 루트가 올바른지
- 새 작업을 시작해 규칙을 다시 로드했는지
--access-token을 추가하는 경우
에이전트가 --access-token을 추가하려 한다면 공개 예제의 인증 방식을 추측했을 수 있습니다.
이미 apidog login으로 인증했다면 토큰을 규칙 파일이나 프롬프트에 넣지 마세요. 규칙 파일에 토큰을 사용하지 말라는 지침을 명확히 추가하세요.
인증 방식은 Apidog CLI 인증을 참고하세요.
존재하지 않는 플래그를 사용하는 경우
“알 수 없는 옵션” 오류는 설치된 CLI 버전에 없는 옵션을 에이전트가 추측했음을 의미합니다.
다음 명령으로 설치된 버전의 옵션을 확인하세요.
apidog run --help
출력에 표시되는 정확한 옵션만 규칙 파일과 실행 명령에 사용하세요.
실패한 실행을 통과로 보고하는 경우
가장 중요한 기준은 종료 코드입니다.
- 종료 코드
0: 통과 - 종료 코드
0이 아님: 실패
에이전트의 자연어 요약과 종료 코드가 다르면 종료 코드를 우선하세요.
일상적인 에이전트 작업을 테스트 루프로 전환하기
설정은 간단합니다.
-
설치 가이드에 따라
apidog-cli를 설치합니다. -
apidog login으로 인증합니다. - Apidog에서 테스트 시나리오를 만들고 CI/CD 명령을 복사합니다.
- Antigravity 규칙 파일에
apidog run명령을 추가합니다. - 에이전트가 API 변경 후 명령과 종료 코드를 확인하도록 요청합니다.
이제 깨진 엔드포인트는 배포 후가 아니라 에이전트가 변경을 수행하는 동안 발견될 수 있습니다.
GUI의 테스트는 사람이 클릭할 때 실행됩니다. 반면 규칙 파일에 기록한 한 줄의 명령은 Antigravity가 작업 흐름에서 필요하다고 판단할 때 실행할 수 있습니다.
Apidog에서 시나리오를 만들고, 그 apidog run 명령을 규칙 파일에 추가해 보세요. 이후 에이전트 없이 CI 파이프라인에서 같은 명령을 실행하려면 GitHub Actions의 Apidog CLI에서 시크릿, 리포터, 종료 코드 게이팅 설정을 확인할 수 있습니다.
Top comments (0)