GitHub Copilot에서 Apidog CLI 사용법

GitHub Copilot의 에이전트 모드는 파일을 편집하고, 터미널 명령을 실행하고, 출력을 읽은 뒤 다음 작업을 결정하는 루프를 반복합니다. API 테스트도 이 루프에 넣을 수 있습니다. Apidog에서 만든 테스트 시나리오를 apidog-cli로 실행하도록 설정하면, Copilot은 단위 테스트처럼 API 테스트를 실행하고 종료 코드를 기준으로 수정 작업을 계속할 수 있습니다.

지금 Apidog 사용해 보기

해결책은 간단합니다. Apidog에서 만든 테스트 시나리오를 터미널에서 실행하는 npm 패키지 apidog-cli를 설치하고, Copilot에 실행 규칙을 알려주면 됩니다. 이후 에이전트 모드는 apidog run을 실행하고, 실패한 종료 코드와 테스트 출력을 읽어 코드를 수정하는 편집-테스트-수정 루프에 API 테스트를 포함합니다.

먼저 CLI를 설치하고 인증을 완료하십시오. apidog --version이 버전 번호를 출력하고 apidog login이 완료된 상태를 기준으로 진행합니다.

어떤 Copilot을 대상으로 하나요?

이 글은 VS Code의 GitHub Copilot 에이전트 모드를 대상으로 합니다.

VS Code에서 Copilot Chat을 열고 모드 드롭다운을 에이전트로 바꾸면, Copilot은 다음 작업을 반복할 수 있습니다.

1. 여러 파일 편집
2. 터미널 명령 제안 및 실행
3. 명령 출력 분석
4. 실패 원인에 따라 코드 수정
5. 테스트 재실행

명령 실행 전에는 Copilot이 실행할 명령을 보여주고 승인을 요청합니다. 이 지점에서 apidog run을 승인하면 됩니다.

관련 인터페이스도 구분해 두는 것이 좋습니다.

• Copilot 코딩 에이전트: GitHub 이슈를 할당하면 GitHub Actions에서 비동기적으로 실행되고 풀 리퀘스트를 생성합니다.
• Copilot CLI: 별도 터미널 클라이언트입니다.
• VS Code 에이전트 모드: 편집기에서 코드 작성과 테스트 실행을 가장 밀접하게 연결합니다.

아래의 저장소 지침 파일은 에이전트 모드뿐 아니라 동일한 지침을 읽는 Copilot 코딩 에이전트에도 적용할 수 있습니다. 에이전트 기능의 변화는 GitHub Copilot의 새로운 코딩 에이전트에서 확인할 수 있습니다.

1단계: Copilot 지침 파일에 Apidog 규칙 추가

저장소 루트에 다음 파일을 만드십시오.

.github/copilot-instructions.md

Copilot은 이 파일을 저장소 사용자 지정 지침으로 읽습니다. GitHub 문서의 저장소 사용자 지정 지침에 따르면 에이전트 모드, Copilot Chat, 코드 검토, 코딩 에이전트가 이 파일을 자동으로 로드합니다.

CLAUDE.md 또는 AGENTS.md처럼 프로젝트 규칙을 선언하는 Markdown 파일로 생각하면 됩니다.

파일에 다음 내용을 추가하십시오.

## Apidog CLI를 사용한 API 테스트

API 엔드포인트를 변경할 때, 작업을 완료했다고 선언하기 전에 Apidog CLI로 확인하십시오. 다음을 실행하십시오:

    apidog run -t 812345 -e 671234 -r cli

- `apidog run`은 모든 어설션이 통과하면 0으로 종료하고, 실패가 있으면 0이 아닌 값으로 종료합니다.
  요약 텍스트가 괜찮아 보여도 0이 아닌 종료는 실패한 테스트로 간주하십시오.
- 머신은 이미 `apidog login`을 통해 인증되었습니다. `--access-token` 플래그를 추가하지 마십시오.
  그리고 이 파일에 토큰을 절대 넣지 마십시오.
- "알 수 없는 옵션" 오류가 발생하면 `apidog run --help`를 실행하고
  실제 플래그를 사용하십시오. 추측하지 마십시오.

다음 단계에서 실제 Apidog 테스트 시나리오 ID와 환경 ID로 -t, -e 값을 교체합니다.

채팅 메시지에 시나리오 ID를 일회성으로 입력하지 말고 지침 파일에 저장하십시오. 채팅 컨텍스트는 세션 종료 후 사라질 수 있지만, .github/copilot-instructions.md의 규칙은 다음 대상에 계속 적용됩니다.

• 모든 팀원
• 모든 Copilot 에이전트 모드 세션
• 이후 Copilot 코딩 에이전트가 생성하는 풀 리퀘스트

특정 경로에만 규칙을 적용해야 한다면 .github/instructions/NAME.instructions.md 형식의 경로별 지침을 사용할 수 있습니다. 이 경우에는 저장소 전체 지침 파일 하나로 충분합니다.

2단계: Apidog에서 실행 명령 가져오기

apidog run 명령을 직접 추측해서 작성하지 마십시오. Apidog의 CI/CD 탭에서 생성된 명령을 사용하십시오.

예시는 다음과 같습니다.

apidog run -t 812345 -e 671234 -r cli

생성된 실제 명령의 -t와 -e 값을 .github/copilot-instructions.md에 붙여넣으십시오.

Copilot의 기억이나 추측보다 Apidog CI/CD 탭에서 생성된 명령을 신뢰해야 합니다. 지침 파일의 값과 Apidog에서 생성한 값이 다르면 Apidog의 명령을 우선하십시오.

전체 옵션과 리포터 목록은 apidog run 명령 참조를 확인하십시오.

3단계: 에이전트 모드에서 테스트 실행하기

VS Code에서 다음 순서로 실행합니다.

1. Copilot Chat 열기
2. 모드 드롭다운에서 에이전트 선택
3. API에 영향을 주는 코드 변경 요청
4. 또는 다음처럼 직접 요청

Apidog API 테스트 시나리오를 실행하고 결과를 알려줘.

에이전트 모드는 시작할 때 .github/copilot-instructions.md를 로드합니다. 따라서 Copilot은 테스트 실행에 사용할 apidog run 명령을 이미 알고 있어야 합니다.

Copilot이 명령 실행을 제안하면 실제 명령을 확인한 뒤 승인하십시오.

apidog run -t 812345 -e 671234 -r cli

-r cli 리포터는 통합 터미널에 요청별 결과, 어설션 결과, 요약을 출력합니다.

여기서 확인할 항목은 두 가지입니다.

• apidog run 명령이 실제로 실행되었는지
• Copilot이 출력과 종료 코드를 읽고 결과를 보고하는지

한 번 명령을 승인하면 VS Code는 작업 공간에서 해당 명령에 대한 선택을 기억할 수 있습니다. 스테이징 환경에 대해 읽기 전용으로 실행하는 테스트 시나리오라면, 반복 실행을 허용할 작업 공간 명령으로 적합합니다.

4단계: Copilot에서 테스트 보고서 읽기

테스트가 실패하면 -r cli 출력에서 다음 정보를 확인할 수 있습니다.

• 실패한 요청
• 실패한 어설션
• 기대값과 실제값
• 상태 코드 불일치
• 누락된 필드
• 잘못된 응답 값

Copilot은 이 출력을 다음 수정 반복의 입력으로 사용할 수 있습니다. 예를 들어 결제 응답에서 필수 필드가 누락되어 실패했다면, 에이전트는 실패한 필드를 확인한 뒤 핸들러 또는 응답 스키마 관련 코드를 수정하고 테스트를 다시 실행할 수 있습니다.

HTML 보고서도 함께 생성하려면 리포터를 추가하십시오.

apidog run -t 812345 -e 671234 -r cli,html

html 리포터는 ./apidog-reports에 자가 포함형 보고서 파일을 생성합니다. 다만 Copilot이 다음 단계를 판단하려면 터미널 출력이 필요하므로 cli 리포터는 유지하십시오.

JUnit 출력과 CI 대시보드 분석을 포함한 리포터 사용법은 다음 문서를 참고하십시오.

• 완전한 Apidog CLI 가이드
• Apidog CLI 테스트 보고서 읽는 방법

Copilot의 편집-테스트-수정 루프에 API 테스트 넣기

핵심은 매번 “테스트를 실행해”라고 요청하는 것이 아닙니다. 지침 파일에 규칙을 작성하면, Copilot은 API 변경 작업의 완료 조건으로 테스트 실행을 고려할 수 있습니다.

예를 들어 에이전트 모드가 결제 응답을 만드는 핸들러를 수정한다고 가정해 보겠습니다.

1. Copilot이 핸들러 코드 수정
2. 스테이징 환경 대상 Apidog 시나리오 실행
3. 종료 코드와 어설션 결과 확인
4. 성공이면 다음 작업 진행
5. 실패면 상태 코드, 누락 필드, 잘못된 값 확인
6. 코드 수정 후 시나리오 재실행

이렇게 하면 API 테스트가 단위 테스트와 같은 편집-테스트-수정 루프에 포함됩니다.

에이전트에게 실행을 위임하되 결과를 검증하는 방식이 중요합니다. 테스트 시나리오는 Apidog에서 시각적으로 관리하고, 에이전트가 실제 종료 코드를 기준으로 판단하는지 수시로 확인하십시오.

더 넓은 활용 패턴은 다음 문서에서 확인할 수 있습니다.

• API 테스트에 AI 에이전트를 사용하는 방법
• Apidog AI 테스트 하네스

Copilot이 실제로 CLI를 실행했는지 확인하기

에이전트가 실제로 실행하지 않은 테스트를 성공으로 요약할 수 있습니다. 다음 세 가지를 순서대로 확인하십시오.

1. 터미널에 실제 명령과 출력이 있는지 확인

에이전트 모드는 실행한 명령과 출력을 터미널에 표시합니다.

다음과 같은 실제 명령이 보이는지 확인하십시오.

apidog run -t 812345 -e 671234 -r cli

명령과 원시 출력이 없는데 Copilot이 “테스트가 통과했다”고 말한다면, 실제 실행 결과가 아닐 수 있습니다. 다시 실행하고 원시 출력을 보여달라고 요청하십시오.

2. 종료 코드 확인

다음처럼 직접 질문할 수 있습니다.

What was the exit code of that apidog run command?

apidog run은 다음 규칙을 따릅니다.

• 모든 어설션 통과: 종료 코드 0
• 하나 이상의 어설션 실패: 0이 아닌 종료 코드

Copilot의 자연어 요약과 종료 코드가 다르면 종료 코드를 우선하십시오.

3. 실제 시나리오 ID와 환경 ID 확인

다음과 같은 오류가 발생하면 ID가 잘못되었을 수 있습니다.

시나리오를 찾을 수 없음

이 경우 다음을 다시 비교하십시오.

• .github/copilot-instructions.md의 -t, -e 값
• Apidog CI/CD 탭에서 생성된 실행 명령

Copilot이 ID를 추측하거나 잘못 기억할 수 있으므로 Apidog에서 생성한 명령을 기준으로 수정하십시오.

선택 사항: Apidog MCP 서버 연결

지침 파일과 apidog run만으로도 대부분의 테스트 자동화 흐름을 구성할 수 있습니다. API 사양을 에이전트의 컨텍스트로 제공하려면 Apidog MCP 서버도 연결할 수 있습니다.

VS Code 에이전트 모드는 GitHub의 MCP로 Copilot 확장 문서에 따라 저장소 루트의 다음 파일에서 MCP 서버를 읽습니다.

.vscode/mcp.json

Apidog MCP 서버는 MCP를 통해 API 사양을 제공합니다. 이를 연결하면 Copilot은 코드를 작성하는 동안 API 스키마를 읽을 수 있습니다.

역할은 분명합니다.

• Apidog CLI: 테스트 실행과 종료 코드 반환
• Apidog MCP 서버: API 사양과 스키마 컨텍스트 제공

GitHub Actions에서 Copilot 코딩 에이전트를 실행하는 경우 MCP 설정 위치는 다릅니다. 클라우드 에이전트 설정은 저장소 설정의 Copilot 섹션에서 JSON으로 추가하고, 시크릿은 COPILOT_MCP_ 접두사를 가진 Actions 시크릿으로 저장합니다. .vscode/mcp.json은 VS Code 편집기 내 에이전트 모드용 설정입니다.

Copilot이 잘못 동작할 때 해결 방법

지침 파일을 무시하는 경우

Copilot이 일반 명령을 실행하거나 테스트를 실행하지 않는다면 다음을 확인하십시오.

• 파일 이름이 정확히 .github/copilot-instructions.md인지
• 파일이 저장소 루트의 .github 디렉터리에 있는지
• VS Code 설정에서 사용자 지정 지침이 활성화되어 있는지

경로가 다르면 Copilot은 파일을 읽지 않습니다.

--access-token을 추가하려는 경우

Copilot이 --access-token을 추가하려 한다면 공개 예시를 바탕으로 플래그를 추측한 것일 수 있습니다.

이미 apidog login으로 인증했다면 지침 파일에 다음 규칙을 유지하십시오.

`--access-token` 플래그를 추가하지 마십시오.
이 파일에 토큰을 절대 넣지 마십시오.

인증 방식은 Apidog CLI 인증에서 확인할 수 있습니다.

존재하지 않는 플래그를 사용하는 경우

다음 오류는 설치된 CLI 버전에 없는 옵션을 사용했다는 의미입니다.

알 수 없는 옵션

추측으로 수정하지 말고 다음 명령을 실행하십시오.

apidog run --help

출력된 도움말에서 실제 지원되는 플래그를 복사해 사용하십시오.

실패한 테스트를 성공으로 보고하는 경우

가장 중요한 기준은 종료 코드입니다.

• 요약이 성공이라고 말해도 종료 코드가 0이 아니면 실패입니다.
• 지침 파일에도 종료 코드 규칙을 명시하십시오.
• 중요한 변경에서는 터미널의 원시 출력을 직접 확인하십시오.

일상적인 에이전트 작업을 테스트된 루프로 전환하기

구성은 간단합니다.

1. 설치 가이드에 따라 apidog-cli 설치
2. apidog login으로 인증
3. Apidog에서 테스트 시나리오와 환경에 대한 apidog run 명령 생성
4. .github/copilot-instructions.md에 실행 규칙 추가
5. VS Code 에이전트 모드에서 API 변경 작업 수행
6. Copilot이 실행한 명령, 출력, 종료 코드 확인

이제 Copilot은 코드를 편집하는 루프 안에서 API 테스트를 실행하고 결과를 읽을 수 있습니다. 문제 있는 엔드포인트를 배포 후에 발견하는 대신, 변경 작업 중에 발견할 수 있습니다.

테스트 시나리오는 계속 Apidog에서 시각적으로 관리하고, Copilot은 apidog run 명령으로 반복 실행하게 하십시오. Apidog 다운로드 후 시나리오 하나를 만든 뒤, 생성된 명령을 .github/copilot-instructions.md에 추가하면 바로 시작할 수 있습니다.

Copilot 없이 CI 파이프라인에서 같은 명령을 실행하려면 GitHub Actions의 Apidog CLI를 참고하십시오. 시크릿 설정, 리포터 구성, 종료 코드 기반 게이팅을 다룹니다.