Trae는 루프입니다. Trae의 빌더 에이전트는 저장소를 읽고, 파일을 편집하고, 터미널에서 명령을 실행하고, 출력을 읽어 다음에 무엇을 할지 결정합니다. 그렇다면 왜 API 테스트는 이 루프에 포함되지 않을까요? API 테스트는 GUI 뒤의 Apidog에 놓여 있으며, 누군가 클릭을 기억할 때만 실행됩니다. 에이전트는 절대 건드리지 않습니다.
해결책은 하나의 설정 블록입니다. Apidog CLI는 `apidog-cli`라는 npm 패키지로, Apidog에서 구축한 테스트 시나리오를 터미널에서 직접 실행합니다. CLI가 설치되고 Trae가 그것의 존재를 알게 되면, 빌더는 유닛 테스트를 실행하는 것과 동일한 방식으로 Apidog 시나리오를 실행합니다: 명령을 실행하고, 종료 코드를 읽고, 빨간색(실패)이면 코드를 수정합니다.
아직 CLI를 설치하지 않았다면, 먼저 설치하십시오. AI 코딩 에이전트로 Apidog CLI를 설치하는 방법 문서에는 npm 설치, 인증, 그리고 에이전트가 직접 입력하는 첫 실행 과정이 자세히 설명되어 있습니다. 이 글은 `apidog --version` 명령이 숫자를 출력하고 Apidog 계정이 인증되었다고 가정합니다.
이 글이 다루는 Trae
Trae는 ByteDance의 AI IDE로, VS Code를 기반으로 하며 Builder라는 에이전트 모드를 통해 파일을 편집하고 터미널 명령을 스스로 실행합니다. 제품 상세 정보는 Trae 공식 사이트에서 읽을 수 있습니다. 이 글은 GitHub의 독립형 `trae-agent` 연구 프로젝트가 아닌 데스크톱 IDE에 관한 것입니다. Trae를 열었을 때 편집기 옆에 채팅 패널이 보이고 에이전트를 Builder로 전환할 수 있다면 제대로 오신 겁니다.
이러한 구분은 중요합니다. Trae는 프로젝트 규칙을 학습하는 자체적인 방식을 가지고 있으며, 이 메커니즘이 일회성 "내 테스트 실행"을 빌더가 스스로 수행하는 작업으로 바꿉니다. 이 메커니즘은 프로젝트 규칙 파일입니다. 이 워크플로우의 도구 비종속적 버전을 먼저 원한다면, 완전한 Apidog CLI 가이드에서 CLI 자체에 대해 다룹니다.
단계 1: 프로젝트 규칙 파일 추가
Trae는 빌더가 작업을 시작하기 전에 규칙 파일을 읽습니다. 프로젝트 수준 파일은 Trae의 규칙 문서에 따라 저장소 루트의 `.trae/rules/project_rules.md`에 위치합니다. 에이전트는 초기화 중에 이 규칙들을 로드하고, 코드를 생성 및 편집하는 동안 이 규칙들을 참조합니다. 모든 프로젝트에 적용되는 사용자 수준의 `user_rules.md`도 있지만, 이 워크플로우에서는 리포지토리 루트에 하나의 프로젝트 파일이면 충분합니다.
`.trae/rules/project_rules.md` 파일을 생성하고 CLI 이름, 정확한 시나리오 명령, 그리고 빌더가 정직하게 작동하도록 하는 규칙을 담은 짧은 블록을 추가하세요:
## 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.
이것이 바로 채팅에서 언급하는 대신 CLI를 `project_rules.md`에 작성하는 이유입니다. 채팅 패널에 입력된 시나리오 ID는 세션이 끝나면 사라집니다. `.trae/rules/project_rules.md`에 있는 시나리오 ID는 이제부터 모든 팀원과 모든 빌더 실행을 위해 존재합니다. Trae는 하위 디렉터리의 `.trae/rules/` 폴더도 읽으므로, 모노리포는 각 서비스 옆에 서비스별 규칙을 유지할 수 있습니다.
단계 2: Apidog에서 명령 가져오기
명령을 추측할 필요가 없습니다. Apidog에서 테스트 시나리오를 열고 CI/CD 탭으로 이동하여 생성된 `apidog run` 라인을 복사하십시오. 이 라인에는 이미 `-t` 뒤에 실제 시나리오 ID가, `-e` 뒤에 환경 ID가 포함되어 있으므로, 수동으로 ID를 만드는 대신 Apidog이 유효하다고 아는 명령을 붙여넣는 것입니다.
해당 정확한 ID를 `.trae/rules/project_rules.md` 블록에 붙여넣어 `` 및 `` 플레이스홀더를 대체하십시오. 모든 플래그 세트와 각 플래그의 기능에 대해서는 apidog run 명령 참조를 참조하십시오.
단계 3: 빌더에게 테스트 실행시키기
블록이 준비되면, Trae의 에이전트를 Builder로 전환하고 저장소에서 시작하십시오. 빌더는 초기화 시 `project_rules.md`를 로드하므로, 이미 CLI가 존재한다는 것을 알고 있습니다. API에 영향을 주는 변경 사항을 만들거나, 단순히 확인을 실행하도록 요청하십시오:
Run the Apidog test scenario and tell me the exit code.
빌더는 규칙 파일에서 `apidog run` 명령을 실행합니다. 여기서 Trae의 승인 모델이 중요합니다: 에이전트가 셸 명령을 실행하려고 할 때, 명령을 권장하고 실행 버튼을 표시하며, 당신이 클릭해야만 Trae 터미널에서 명령이 실행됩니다. 일단 실행되면, 빌더는 자동으로 출력을 읽고 분석합니다. 따라서 `apidog run`을 한 번 승인하면, 에이전트가 거기서부터 결과를 가져옵니다.
`-r cli` 리포터는 터미널에 단계별 결과와 요약을 바로 출력하며, 빌더는 실행되는 각 요청과 어설션을 읽습니다. 당신은 실행이 진행되고 빌더가 요약과 종료 코드를 모두 보고하는 것을 보게 될 것입니다.
단계 4: Trae 내에서 보고서 읽기
실행이 실패하면(빨간색이 되면), 보고서에 답이 있습니다. `-r cli`를 사용하면 빌더는 Trae 터미널에서 읽기 쉬운 상세 분석을 얻습니다: 각 요청, 각 어설션, 그리고 예상 값과 실제 값을 비교하여 어떤 것이 실패했는지. 실패한 어설션은 정확한 필드 또는 상태 코드를 명시하며, 이는 빌더가 수정 사항을 찾는 데 일반적으로 충분합니다.
브라우저에서 열거나 팀원에게 전달할 수 있는 보고서를 원한다면 HTML 리포터를 추가하십시오:
apidog run -t <scenario_id> -e <env_id> -r cli,html
`html` 리포터는 `./apidog-reports`에 자체 포함된 파일을 작성합니다. 빌더가 다음 단계를 결정하기 위해 읽는 인라인 출력을 계속 받을 수 있도록 `cli`를 목록에 유지하십시오. CI 대시보드가 파싱하는 JSON 및 JUnit 형식을 포함한 모든 리포터에 대해서는 Apidog CLI 테스트 보고서 가이드를 참조하십시오.
자체 루프 내에서 Trae 테스트
핵심은 당신이 요청을 멈췄을 때 `project_rules.md`가 지시했기 때문에 빌더가 스스로 시나리오를 실행할 때 어떤 일이 일어나는가 하는 것입니다.
빌더가 결제 응답을 생성하는 핸들러를 편집하는 상황을 상상해 보십시오. 빌더의 루프가 바뀝니다: 코드를 편집한 다음, 성공을 선언하는 대신 스테이징 환경에 대해 Apidog 시나리오를 실행하고, 종료 코드를 읽고, 그에 따라 조치합니다. 성공(초록색)이면 다음 단계로 진행합니다. 실패(빨간색)이면 보고서를 열어 어떤 어설션이 실패했는지(상태 코드, 누락된 필드, 잘못된 값) 읽고, 수정을 시도한 다음 다시 실행합니다. API 테스트는 빌더가 이미 유닛 테스트를 실행하는 것과 동일한 편집-테스트-수정 루프의 일부가 됩니다. 당신은 하나의 지시를 작성했고 빌더는 이 명령을 기존의 작동 방식에 통합했습니다.
이것은 모든 에이전트 워크플로우를 안전하게 만드는 위임-검증 모델입니다. 빌더는 명령을 실행하고 결과를 읽습니다. 당신은 Apidog에서 시각적으로 시나리오를 계속 작성하고 에이전트가 종료 코드를 정직하게 읽는지 점검합니다. 더 넓은 패턴에 대해서는 API 테스트에 AI 에이전트를 사용하는 방법 및 Apidog AI 테스트 하네스를 참조하십시오.
Trae가 실제로 CLI를 실행하는지 확인
에이전트는 얻지 못한 성공을 보고하는 경우가 있으며, 빌더도 예외는 아닙니다. 문제 발생 빈도에 따라 세 가지 확인 사항이 있습니다.
첫째, 명령이 실제로 실행되었는지 확인하십시오. Trae는 빌더가 실행한 명령과 그 출력을 터미널에 보여줍니다. 문자 그대로 `apidog run` 라인과 그 아래 결과를 찾으십시오. 빌더가 테스트를 실행했다고 말했지만 명령이 보이지 않는다면, 빌더는 실행하지 않은 것을 요약한 것입니다. 다시 실행하고 원시 출력을 보여달라고 요청하십시오.
둘째, 종료 코드를 확인하십시오:
What was the exit code of that apidog run command?
`apidog run`은 모든 어설션이 통과하면 0으로 종료하고, 무엇이든 실패하면 0이 아닌 값으로 종료합니다. 이 단일 동작은 빌더 또는 파이프라인이 실행을 깨끗한 게이트로 처리할 수 있게 합니다. 빌더의 설명이 "테스트 통과"라고 하지만 종료 코드가 0이 아니라면, 종료 코드가 맞습니다.
셋째, 실제 시나리오를 사용했는지 확인하십시오. 실행이 "시나리오를 찾을 수 없음"으로 실패하면, 빌더가 ID를 만들었거나 잘못 기억했을 수 있습니다. `project_rules.md`의 `-t` 및 `-e` 값과 Apidog이 CI/CD 탭에서 생성한 명령을 다시 확인하십시오. 규칙 파일의 ID가 진실입니다.
선택 사항: Apidog MCP 서버 연결
`project_rules.md`에서 `apidog run`을 실행하는 것은 대부분의 필요한 기능을 포함합니다. MCP 서버를 연결하면 한 단계 더 나아갈 수 있습니다. Trae 에이전트는 MCP 클라이언트 역할을 하므로, 빌더는 MCP 서버가 노출하는 도구를 호출할 수 있습니다.
MCP 서버를 추가하려면 Trae 설정에서 MCP 탭으로 이동하여 마켓플레이스에서 서버를 선택하거나, Trae의 MCP 서버 추가 가이드에 따라 수동 추가를 선택하고 서버의 `command`, `args`, `env`를 포함하는 JSON 블록을 붙여넣으십시오. Apidog MCP 서버는 MCP를 통해 API 사양을 노출하므로, 빌더는 코드를 작성하는 동안 스키마를 읽을 수 있으며, 단순히 나중에 읽는 것이 아닙니다. 작업 분담은 명확합니다: CLI는 테스트를 실행하고, MCP는 에이전트에게 사양을 제공합니다.
Trae가 잘못될 때
설정 중에 몇 가지 오류가 자주 나타납니다.
규칙 파일을 무시합니다. 빌더가 일반적인 명령을 실행하거나 아무것도 실행하지 않는다면 파일이 로드되지 않는 것일 수 있습니다. 저장소 루트의 `.trae/rules/project_rules.md`에 파일이 있는지, 폴더 이름이 `rule`이 아닌 `rules`인지 확인하십시오. 세션을 다시 시작하면 규칙을 새로 읽게 됩니다.
어쨌든 액세스 토큰을 전달합니다. 빌더가 `--access-token`을 추가하려고 한다면, 공개 예제를 통해 추측하는 것입니다. 이 머신은 `apidog login`을 통해 이미 인증되었으므로, 블록은 이미 그렇게 하지 말라고 지시하고 있습니다. 해당 줄을 강조하고, 절대로 실제 토큰을 `project_rules.md`에 넣지 마십시오. CLI가 대화형 사용 및 CI에서 자격 증명을 처리하는 방법에 대해서는 Apidog CLI 인증을 참조하십시오.
플래그를 만들어냅니다. "알 수 없는 옵션" 오류는 빌더가 현재 버전에 없는 플래그를 추측했다는 의미입니다. `apidog run --help`를 실행하도록 지시하고 거기서 정확한 플래그를 복사하여 사용하십시오. 이는 설치된 버전에 항상 올바른 플래그입니다.
실패한 실행을 성공으로 보고합니다. 가장 큰 비용이 드는 문제이며, 종료 코드 규칙이 `project_rules.md`에 있고 검증 단계에 포함된 이유입니다. 요약과 종료 코드가 일치하지 않을 때는 종료 코드가 우선합니다.
일상적인 에이전트에서 테스트된 루프로
이것이 설정 방법입니다. 설치 가이드에 따라 `apidog-cli`를 한 번 설치하고, `.trae/rules/project_rules.md`에 짧은 Apidog 블록을 추가하면, 빌더는 코드를 편집하는 데 이미 사용하는 동일한 루프 내에서 API 테스트를 실행하고 결과를 읽는 방법을 알게 됩니다. 손상된 엔드포인트는 빌더가 변경 사항을 작업하는 동안에 잡히며, 배포된 후가 아닙니다.
GUI 뒤의 테스트는 사람이 클릭할 때 실행됩니다. 한 줄짜리 명령은 빌더가 결정할 때마다 실행됩니다. 당신은 Apidog에서 시각적으로 시나리오를 계속 구축하고, 당신의 에이전트는 당신이 보고 있지 않은 곳에서 시나리오를 실행합니다. Apidog를 다운로드하고, 하나의 시나리오를 구축하고, 해당 `apidog run` 명령을 `.trae/rules/project_rules.md`에 추가한 다음, 빌더가 다음 변경 사항에서 이를 어떻게 인식하는지 지켜보십시오. 에이전트 없이 동일한 시나리오를 실행할 준비가 되면, GitHub Actions의 Apidog CLI에서 CI를 위한 비밀, 리포터, 그리고 종료 코드 게이팅을 다룹니다.