DEV Community

Cover image for Trae에서 Apidog CLI 사용법
Rihpig
Rihpig

Posted on • Originally published at apidog.com

Trae에서 Apidog CLI 사용법

Trae는 루프입니다. Trae의 Builder 에이전트는 저장소를 읽고, 파일을 편집하고, 터미널 명령을 실행한 뒤 출력을 기반으로 다음 작업을 결정합니다. API 테스트도 이 루프에 포함할 수 있습니다. GUI에서만 실행하던 Apidog 테스트 시나리오를 CLI로 실행하면, Builder는 유닛 테스트처럼 결과와 종료 코드를 읽고 실패한 경우 코드를 수정할 수 있습니다.

지금 Apidog를 사용해 보세요

해결책은 프로젝트 규칙 파일 하나입니다. Apidog CLI는 apidog-cli npm 패키지로 제공되며, Apidog에서 만든 테스트 시나리오를 터미널에서 직접 실행합니다. CLI를 설치하고 Trae가 실행 규칙을 읽도록 설정하면, Builder는 apidog run을 실행하고 종료 코드가 0이 아니면 테스트 실패로 처리할 수 있습니다.

아직 CLI를 설치하지 않았다면 먼저 설치하세요. AI 코딩 에이전트로 Apidog CLI를 설치하는 방법에서 npm 설치, 인증, 첫 실행 과정을 확인할 수 있습니다. 이 글은 다음 조건을 가정합니다.

apidog --version
Enter fullscreen mode Exit fullscreen mode

위 명령이 버전 번호를 출력하고, Apidog 계정 인증이 완료되어 있어야 합니다.

이 글에서 다루는 Trae

Trae는 ByteDance의 AI IDE이며, VS Code를 기반으로 합니다. Builder 에이전트 모드에서는 파일 편집과 터미널 명령 실행을 수행할 수 있습니다. 제품 상세 정보는 Trae 공식 사이트에서 확인할 수 있습니다.

이 글은 GitHub의 독립형 trae-agent 연구 프로젝트가 아니라 데스크톱 IDE의 Trae를 다룹니다. Trae를 열었을 때 편집기 옆에 채팅 패널이 있고 에이전트를 Builder로 전환할 수 있다면 대상 환경입니다.

Trae Builder 에이전트 화면

이 구분이 중요한 이유는 Trae가 프로젝트 규칙 파일을 통해 에이전트의 작업 방식을 학습하기 때문입니다. 채팅에서 한 번만 “테스트를 실행해”라고 요청하는 대신, 규칙 파일에 API 테스트 명령과 실패 처리 기준을 저장하면 Builder가 반복적으로 참조할 수 있습니다.

도구와 무관한 CLI 사용법이 필요하다면 완전한 Apidog CLI 가이드를 참고하세요.

단계 1: 프로젝트 규칙 파일 추가

Trae는 Builder가 작업을 시작하기 전에 규칙 파일을 읽습니다. Trae 규칙 문서에 따르면 프로젝트 수준 규칙 파일은 저장소 루트의 다음 경로에 둡니다.

.trae/rules/project_rules.md
Enter fullscreen mode Exit fullscreen mode

프로젝트 전체에 적용되는 사용자 수준 user_rules.md도 있지만, 이 워크플로우에는 리포지토리 안의 project_rules.md 하나면 충분합니다.

파일을 생성하고 아래 내용을 추가하세요. <scenario_id>와 <env_id>는 실제 Apidog 시나리오 및 환경 ID로 교체합니다.

## API testing with the Apidog CLI

When you change code that touches an API endpoint, verify it by running the
Apidog test scenario, not just the unit tests.

Command:
  apidog run -t <scenario_id> -e <env_id> -r cli

Rules:
- `apidog run` exits 0 when every assertion passes and non-zero on any failure.
  Treat a non-zero exit code as a failing test, even if the summary looks fine.
- This machine is already authenticated via `apidog login`. Never add an
  --access-token flag and never put a token in this file.
- If a flag is unknown, run `apidog run --help` and use the exact flag from there.
Enter fullscreen mode Exit fullscreen mode

이 파일에 명령을 저장하는 이유는 단순합니다.

  • 채팅에 입력한 시나리오 ID는 세션이 끝나면 사라질 수 있습니다.
  • project_rules.md의 시나리오 ID는 이후 모든 Builder 실행에서 재사용됩니다.
  • 팀원이 같은 저장소를 열어도 동일한 테스트 규칙을 참고할 수 있습니다.

Trae는 하위 디렉터리의 .trae/rules/ 폴더도 읽을 수 있으므로, 모노리포에서는 각 서비스 디렉터리별로 규칙을 둘 수 있습니다.

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

명령과 ID를 추측하지 마세요. Apidog에서 테스트 시나리오를 열고 CI/CD 탭으로 이동한 뒤, 생성된 apidog run 명령을 복사하세요.

생성된 명령에는 다음 값이 이미 포함됩니다.

  • -t 뒤의 실제 시나리오 ID
  • -e 뒤의 환경 ID
  • 필요한 리포터 또는 기타 플래그

복사한 명령을 .trae/rules/project_rules.md에 붙여넣고 플레이스홀더를 실제 값으로 바꾸세요.

apidog run -t 실제_시나리오_ID -e 실제_환경_ID -r cli
Enter fullscreen mode Exit fullscreen mode

각 플래그와 지원 옵션은 apidog run 명령 참조에서 확인할 수 있습니다.

단계 3: Builder에게 테스트 실행시키기

규칙 파일을 저장한 뒤 Trae에서 에이전트를 Builder로 전환하세요. Builder는 초기화할 때 project_rules.md를 읽으므로, API에 영향을 주는 변경 사항을 만들거나 직접 테스트 실행을 요청할 수 있습니다.

예를 들어 다음과 같이 입력합니다.

Run the Apidog test scenario and tell me the exit code.
Enter fullscreen mode Exit fullscreen mode

Builder는 규칙 파일에 정의된 apidog run 명령을 제안합니다. Trae의 승인 모델에서는 에이전트가 셸 명령을 실행하기 전에 실행 버튼을 표시하므로, 명령을 검토한 뒤 승인해야 합니다.

실행이 끝나면 Builder는 다음 정보를 읽을 수 있습니다.

  • 요청별 실행 결과
  • 어설션 통과 및 실패 내역
  • 요약 결과
  • 프로세스 종료 코드

-r cli 리포터를 사용하면 이러한 정보가 Trae 터미널에 바로 출력됩니다.

단계 4: Trae에서 실패 보고서 읽기

실행이 실패하면 -r cli 출력에서 실패 원인을 확인할 수 있습니다. 일반적으로 다음 정보가 표시됩니다.

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

Builder가 실패 원인을 읽고 수정 작업을 시도할 수 있도록, 규칙 파일에는 반드시 0이 아닌 종료 코드를 테스트 실패로 처리한다는 조건을 포함하세요.

브라우저에서 열거나 팀원에게 전달할 HTML 보고서가 필요하면 html 리포터를 추가합니다.

apidog run -t <scenario_id> -e <env_id> -r cli,html
Enter fullscreen mode Exit fullscreen mode

html 리포터는 ./apidog-reports에 자체 포함형 파일을 생성합니다. Builder가 터미널 출력을 계속 읽을 수 있도록 cli 리포터는 유지하세요.

JSON, JUnit 등 CI 시스템에서 파싱할 수 있는 형식은 Apidog CLI 테스트 보고서 가이드에서 확인할 수 있습니다.

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

핵심은 사람이 매번 테스트 실행을 요청하지 않아도 Builder가 규칙에 따라 시나리오를 실행하도록 만드는 것입니다.

예를 들어 Builder가 결제 응답을 생성하는 핸들러를 수정한다고 가정해 보겠습니다. 규칙 파일이 있다면 작업 흐름은 다음과 같이 바뀝니다.

  1. Builder가 API 핸들러 코드를 수정합니다.
  2. Apidog 시나리오를 스테이징 환경에서 실행합니다.
  3. 종료 코드와 실패한 어설션을 읽습니다.
  4. 종료 코드가 0이면 다음 작업으로 진행합니다.
  5. 종료 코드가 0이 아니면 상태 코드, 누락 필드, 잘못된 값 등을 확인합니다.
  6. 코드를 수정하고 시나리오를 다시 실행합니다.

즉, API 테스트가 유닛 테스트와 같은 편집-테스트-수정 루프에 포함됩니다.

이 패턴은 위임과 검증을 분리합니다.

  • Builder는 명령을 실행하고 결과를 해석합니다.
  • 개발자는 Apidog에서 시나리오를 시각적으로 관리합니다.
  • 종료 코드는 에이전트의 설명보다 우선하는 검증 기준이 됩니다.

더 넓은 패턴은 API 테스트에 AI 에이전트를 사용하는 방법과 Apidog AI 테스트 하네스에서 확인할 수 있습니다.

Trae가 실제로 CLI를 실행했는지 확인하기

에이전트가 실제로 실행하지 않은 테스트를 성공으로 요약할 수 있으므로, 다음 세 가지를 확인하세요.

1. 터미널에서 실제 명령 확인

Trae 터미널에서 Builder가 실행한 명령을 찾습니다.

apidog run ...
Enter fullscreen mode Exit fullscreen mode

명령과 그 아래 출력이 실제로 있어야 합니다. Builder가 “테스트를 실행했다”고 말하지만 터미널에 명령이 없다면, 원시 출력을 보여 달라고 요청하고 다시 실행하세요.

2. 종료 코드 확인

Builder에게 명시적으로 종료 코드를 요청할 수 있습니다.

What was the exit code of that apidog run command?
Enter fullscreen mode Exit fullscreen mode

apidog run은 모든 어설션이 통과하면 0으로 종료하며, 하나라도 실패하면 0이 아닌 값으로 종료합니다.

Builder의 요약이 “통과”라고 해도 종료 코드가 0이 아니라면 해당 실행은 실패입니다. 종료 코드를 최종 기준으로 사용하세요.

3. 실제 시나리오 ID 확인

다음과 같은 오류가 발생하면 시나리오 또는 환경 ID가 잘못되었을 수 있습니다.

Scenario not found
Enter fullscreen mode Exit fullscreen mode

이 경우 다음 값을 다시 비교하세요.

  • .trae/rules/project_rules.md의 -t 값
  • .trae/rules/project_rules.md의 -e 값
  • Apidog의 CI/CD 탭에서 생성한 원본 명령

규칙 파일의 값은 Apidog에서 복사한 검증된 명령과 일치해야 합니다.

선택 사항: Apidog MCP 서버 연결

project_rules.md에서 apidog run을 실행하는 방식만으로도 대부분의 테스트 워크플로우를 구성할 수 있습니다. MCP 서버를 연결하면 Builder가 테스트 실행뿐 아니라 API 사양을 읽는 데도 도움을 받을 수 있습니다.

Trae는 MCP 클라이언트 역할을 합니다. MCP 서버를 추가하려면 Trae 설정의 MCP 탭에서 마켓플레이스 서버를 선택하거나, Trae MCP 서버 추가 가이드에 따라 수동 설정을 추가하세요. 수동 설정에는 보통 서버의 command, args, env가 포함된 JSON 블록을 입력합니다.

Apidog MCP 서버는 MCP를 통해 API 사양을 노출합니다. 역할을 분리하면 다음과 같습니다.

  • Apidog CLI: 테스트 시나리오 실행과 종료 코드 반환
  • Apidog MCP 서버: Builder가 구현 중 API 스키마와 사양을 읽도록 지원

Trae 설정에서 자주 발생하는 문제

규칙 파일을 무시하는 경우

Builder가 일반적인 명령을 실행하거나 아무 명령도 실행하지 않는다면 규칙 파일이 로드되지 않았을 수 있습니다.

다음을 확인하세요.

<repository-root>/.trae/rules/project_rules.md
Enter fullscreen mode Exit fullscreen mode

특히 폴더 이름이 rule이 아니라 rules인지 확인하세요. 파일을 수정한 뒤에는 Trae 세션을 다시 시작해 규칙을 다시 읽도록 할 수 있습니다.

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

Builder가 --access-token을 추가하려 한다면 공개 예제를 바탕으로 플래그를 추측한 것일 수 있습니다. 이미 apidog login으로 인증했다면 토큰을 규칙 파일에 넣지 마세요.

다음 규칙을 유지하세요.

Never add an --access-token flag and never put a token in this file.
Enter fullscreen mode Exit fullscreen mode

대화형 환경과 CI 환경의 인증 방식은 Apidog CLI 인증에서 확인할 수 있습니다.

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

Unknown option 오류는 설치된 CLI 버전에 없는 플래그를 Builder가 추측했다는 의미입니다.

먼저 설치된 버전의 도움말을 확인하세요.

apidog run --help
Enter fullscreen mode Exit fullscreen mode

그 출력에 있는 정확한 플래그만 사용하도록 Builder에 지시하세요.

실패한 실행을 성공으로 보고하는 경우

가장 중요한 문제입니다. 요약 문구와 종료 코드가 다르면 종료 코드가 우선합니다.

exit code 0     → 성공
exit code != 0  → 실패
Enter fullscreen mode Exit fullscreen mode

이 기준을 project_rules.md에 명시하고, Builder에게 항상 종료 코드도 보고하도록 요청하세요.

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

설정은 간단합니다.

  1. 설치 가이드에 따라 apidog-cli를 설치합니다.
  2. Apidog에서 테스트 시나리오의 apidog run 명령을 복사합니다.
  3. .trae/rules/project_rules.md에 명령과 종료 코드 규칙을 추가합니다.
  4. Builder가 API 관련 변경 후 해당 명령을 실행하도록 합니다.
  5. 터미널 출력과 종료 코드로 결과를 검증합니다.

이렇게 하면 손상된 엔드포인트를 배포 이후가 아니라 Builder가 변경 사항을 작업하는 동안 발견할 수 있습니다.

GUI 뒤의 테스트는 사람이 클릭할 때만 실행됩니다. 반면 규칙 파일에 정의된 한 줄의 CLI 명령은 Builder의 작업 루프에 포함될 수 있습니다. Apidog에서 시나리오를 관리하고, 그 실행 명령을 Trae 프로젝트 규칙에 연결하세요.

Apidog 다운로드 후 시나리오 하나를 만들고 apidog run 명령을 .trae/rules/project_rules.md에 추가해 보세요. 에이전트 없이 같은 시나리오를 CI에서 실행하려면 GitHub Actions의 Apidog CLI에서 비밀 관리, 리포터, 종료 코드 게이팅 방법을 확인할 수 있습니다.

Top comments (0)