Cursor의 에이전트는 이미 파일을 편집하고, 터미널을 실행하고, 출력을 읽고, 오류를 수정합니다. 다음 단계는 API 테스트를 이 루프에 포함시키는 것입니다. Cursor가 실제 Apidog 시나리오를 실행하고, 통과 또는 실패 여부를 읽고, 계속 진행하도록 하세요. 이를 가능하게 하는 핵심 요소는 Cursor가 호출할 수 있는 명령줄 러너입니다.
그 러너는 `apidog-cli`라는 npm 패키지인 Apidog CLI입니다. Apidog에서 시각적으로 구축한 테스트 시나리오를 터미널에서 실행하고, Cursor가 처리할 수 있는 상태 코드를 반환하며 종료합니다. 이 가이드는 Cursor 관련 절반을 다룹니다: Cursor에게 워크플로우를 가르치는 규칙 파일, 테스트를 실행하는 프롬프트, 실행이 편집-테스트-수정 루프에 어떻게 통합되는지, 그리고 코딩 중에 Cursor에게 API 사양을 제공하는 선택적 MCP 서버입니다.
아직 CLI가 설치되지 않았다면, Cursor가 설치 및 인증을 진행하는 AI 코딩 에이전트로 Apidog CLI를 설치하는 방법부터 시작하세요. `apidog --version`이 숫자를 출력하면 다시 돌아오십시오. 또한 하나 이상의 저장된 테스트 시나리오가 있는 Apidog 계정이 필요합니다. 계정이 없다면 Apidog를 다운로드하세요.
“Cursor에서 CLI 사용”의 의미
Cursor용 Apidog 플러그인은 없으며, 필요하지도 않습니다. Cursor의 에이전트는 이미 프로젝트 터미널에서 셸 명령을 실행합니다. 따라서 Cursor에서 Apidog CLI를 사용하는 것은 다음 세 가지를 의미합니다:
- 프로젝트 규칙으로 Cursor에게 워크플로우를 한 번 가르칩니다. 그래서 명령, 플래그, 그리고 종료 코드가 진실의 원천임을 알게 합니다.
- 에이전트가 단위 테스트를 실행하는 것처럼, `apidog run`을 루프의 일반적인 단계로 실행하도록 합니다.
- 선택적으로 Apidog MCP 서버를 연결합니다. 그래서 Cursor가 해당 테스트가 확인하는 코드를 작성하는 동안 API 사양을 읽을 수 있도록 합니다.
이 규칙은 "터미널을 열고 입력"하는 일반적인 가이드 대신 Cursor에 특화된 기능을 제공합니다.
1단계: 프로젝트 규칙 추가
Cursor는 저장소 루트의 `.cursor/rules` 디렉토리에서 프로젝트 규칙을 읽습니다. 각 규칙은 작은 프론트매터 블록이 있는 `.mdc` 파일이며, 코드와 함께 버전 관리되어 전체 팀이 동일한 동작을 얻을 수 있습니다.
두 가지 방법으로 만들 수 있습니다: 채팅에서 `/create-rule`을 입력하고 원하는 것을 설명하거나, `Cursor 설정 > 규칙, 명령`을 열고 `+ 규칙 추가`를 클릭합니다. 어떤 방법이든 `.cursor/rules` 아래에 파일이 생성됩니다.
이것을 `.cursor/rules/apidog-cli.mdc`로 저장하세요:
---
description: 터미널에서 Apidog API 테스트를 실행하는 방법
alwaysApply: false
---
# Apidog API 테스트 실행
이 프로젝트에는 Apidog에 API 테스트 시나리오가 있습니다.
전역으로 설치되어 이미 인증된 apidog-cli로 실행합니다.
- 명령은 `apidog run`입니다. 바이너리는 `apidog`입니다.
- ID로 단일 시나리오 실행: `apidog run -t <scenarioId> -e <environmentId> -n 1 -r cli`
- `-t`는 테스트 시나리오 ID, `-e`는 환경 ID입니다.
- `-n 1`은 한 번 실행합니다. `-r cli`는 읽기 쉬운 보고서를 터미널에 출력합니다.
- `--access-token`을 전달하지 마세요. 인증은 이전 `apidog login`으로 처리됩니다.
- 종료 코드가 진실의 원천입니다: `0`은 모든 단언이 통과했음을 의미하고,
0이 아닌 값은 실패를 의미합니다. 요약뿐만 아니라 종료 코드를 보고하세요.
- 플래그를 모르는 경우 `apidog run --help`를 실행하고 거기서 정확한 플래그를 사용하세요.
절대 플래그 이름을 추측하지 마세요.
- 엔드포인트를 건드리는 코드를 변경한 후에는, 관련 시나리오를 실행하고
변경 사항이 작동한다고 주장하기 전에 결과를 읽으세요.
프론트매터가 중요합니다. `description`과 `alwaysApply: false`는 이를 '스마트하게 적용'하는 규칙으로 만듭니다. Cursor는 모든 대화에서 컨텍스트를 소모하는 대신, 채팅이 테스트 실행에 관한 것일 때 이 규칙을 가져옵니다. `alwaysApply: true`로 설정하면 항상 범위 내에 유지됩니다. 특정 파일 형식에 범위를 지정하려면 설명을 삭제하고 `globs` 줄을 추가하면, 일치하는 파일이 열릴 때 Cursor가 자동으로 연결합니다.
내용이 실제 작업을 수행합니다. 명령의 형태를 고정하고, 인증 소스를 지정하며, 에이전트의 정직성을 유지하는 핵심 원칙(종료 코드가 내용보다 우선)을 명시합니다. 에이전트가 실패 보고서를 읽고 "괜찮아 보입니다"라고 말하는 경우가 있습니다. 이 규칙을 한 번 작성해두면 수동으로 잡을 필요가 없습니다.
2단계: Apidog에서 명령 가져오기
에이전트에게 어떤 것을 실행하도록 요청하기 전에, 알려진 올바른 명령을 얻으세요. Cursor가 ID를 추측하게 하지 마세요.
Apidog에서 테스트 시나리오를 열고, CI/CD 탭으로 전환한 다음, 명령줄 옵션을 선택합니다. Apidog는 시나리오 ID, 환경 ID, 그리고 액세스 토큰이 이미 채워진 완전한 `apidog run` 명령을 구축합니다:
apidog run --access-token YOUR_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r cli
`605067`은 테스트 시나리오 ID이고 `1629989`는 환경 ID입니다. 사용자 환경에서는 다를 것입니다. 설치 시 CLI를 인증했으므로 `--access-token` 부분을 삭제하고 ID만 유지하세요. 이것이 규칙이 Cursor에게 사용하도록 지시한 명령입니다.
3단계: 에이전트가 테스트를 실행하도록 하기
Cursor의 에이전트(인라인 편집이 아닌 터미널 명령을 실행하는 채팅 모드)를 엽니다. 규칙이 설정되면 프롬프트는 짧습니다:
내 Apidog 테스트 시나리오를 실행하고 전체 출력을 보여주고 종료 코드를 알려줘.
Cursor는 명령을 제안하고, 승인하면 통합 터미널에서 실행합니다:
apidog run -t 605067 -e 1629989 -n 1 -r cli
기본적으로 Cursor는 터미널 명령을 실행하기 전에 물어보므로, 실행하려는 것을 정확히 볼 수 있습니다. 승인하면 에이전트가 시나리오를 실행한 다음, 실행 결과와 요약을 읽어줍니다.
확인 사항: 요약이 아닌 종료 코드를 확인하세요. `apidog run`은 모든 단언이 통과하면 `0`으로 종료하고, 하나라도 실패하면 0이 아닌 값으로 종료합니다. 이러한 동작이 CI와 에이전트의 게이트 역할을 하는 전체 이유입니다. Cursor가 "테스트 통과"라고 말했지만 종료 코드가 0이 아니었다면, 그것은 틀린 것입니다. 코드를 믿으세요. 이것이 1단계 규칙이 방지하는 정확한 오류입니다.
다른 보고서 형식이나 더 많은 반복을 원하면, 에이전트가 `apidog run --help`를 실행하여 설치된 버전에 대한 실제 플래그 목록을 읽도록 하세요. 전체 Apidog CLI 가이드는 `html`, `json`, `junit` 리포터 및 데이터 기반 반복을 포함한 모든 플래그를 문서화합니다.
4단계: Cursor 내에서 보고서 읽기
`-r cli` 리포터는 Cursor가 이미 읽는 터미널에 결과를 출력하므로 에이전트 작업에 적합합니다. 에이전트는 사용자와 동일한 줄을 봅니다: 어떤 시나리오가 실행되었는지, 각 요청, 각 단언, 그리고 최종 통과 또는 실패 횟수입니다.
실행이 실패하면, 보고서는 실패한 단언, 예상 값, 그리고 엔드포인트가 반환한 값을 명시합니다. 이 텍스트가 에이전트의 컨텍스트에 있으므로 동일한 채팅에서 후속 조치를 취할 수 있습니다:
시나리오가 실패했습니다. 보고서에서 실패한 단언을 읽고, 해당 필드를 생성하는 핸들러를 찾아서 수정안을 제안하세요. 그런 다음 시나리오를 다시 실행하고 새로운 종료 코드를 보여주세요.
이제 테스트가 루프의 일부입니다. Cursor는 핸들러를 편집하고, `apidog run`을 다시 실행하고, 새로운 종료 코드를 읽고, 계속 진행하거나 다시 시도합니다. API 검사는 Cursor가 단위 테스트에 사용하는 것과 동일한 편집-테스트-수정 주기 내에서 이루어지며, 단지 실제 엔드포인트를 대상으로 실행된다는 점이 다릅니다. 더 넓은 패턴에 대해서는, API 테스트를 위한 AI 에이전트 사용 방법에서 적합한 부분과 적합하지 않은 부분을 다룹니다.
선택 사항: Apidog MCP 서버 연결
CLI는 Cursor가 테스트를 **실행**하도록 합니다. Apidog MCP 서버는 Cursor가 코드를 작성하는 동안 API 사양을 **읽을** 수 있도록 합니다. 두 가지가 결합됩니다: MCP 서버는 Cursor에게 스키마를 제공하여 계약에 맞는 코드를 생성하도록 하고, CLI는 실제 시나리오에 대해 해당 코드를 검증합니다.
Cursor는 JSON 설정을 통해 MCP 서버를 지원합니다. 프로젝트 범위의 서버는 저장소 루트의 `.cursor/mcp.json`에, 전역 서버는 `~/.cursor/mcp.json`에 배치합니다. 구조는 이름으로 키가 지정된 `mcpServers` 객체이며, 각 객체는 `command`, `args` 배열, 그리고 선택적 `env` 값을 가집니다:
{
"mcpServers": {
"apidog": {
"command": "npx",
"args": ["-y", "apidog-mcp-server@latest", "--project=YOUR_PROJECT_ID"],
"env": {
"APIDOG_ACCESS_TOKEN": "YOUR_ACCESS_TOKEN"
}
}
}
}
두 가지 주의사항. MCP는 일부 설치에서 토글 뒤에 숨겨져 있으므로, Cursor 설정을 열고 Model Context Protocol 섹션을 찾아 Apidog 서버가 활성화되어 있는지 확인하세요. 그리고 `.cursor/mcp.json`을 커밋하는 경우, 토큰을 하드코딩하지 말고 환경 변수를 참조하세요. 프로젝트 ID와 토큰을 얻는 방법을 포함한 전체 설정은 Apidog MCP 서버 가이드를 참조하세요. 수동으로 연결하는 대신 패키지화되고 재사용 가능한 워크플로우를 원한다면, Claude Skills 가이드와 함께 Apidog CLI에서 스킬 기반 버전을 보여줍니다.
로컬 루프에서 CI로
Cursor가 로컬에서 시나리오를 실행하고 종료 코드를 처리한 후, 파이프라인이 사용할 정확한 명령을 검증했습니다. CI로의 전환은 작습니다: 동일한 `apidog run` 명령을 사용하되, 토큰은 저장된 로그인 대신 마스킹된 비밀로 전달됩니다. Cursor는 규칙에서 명령을 알고 있으므로, 단계 작성을 요청할 수도 있습니다:
해당 단계의 메커니즘(비밀, 리포터, 종료 코드 게이팅)은 GitHub Actions의 Apidog CLI에 있습니다. 동일한 명령이 이제 터미널, Cursor의 에이전트 루프, CI 세 곳에서 실행되며, 모두 동일한 종료 코드를 신뢰합니다.
일반적인 문제
규칙이 적용되지 않습니다. `description`과 `alwaysApply: false`를 사용하면, Cursor는 채팅이 관련 있다고 판단할 때만 규칙을 로드합니다. 테스트 세션이 규칙을 선택하지 않는다면, 채팅에서 `@apidog-cli`를 언급하거나 `alwaysApply: true`로 전환하세요.
에이전트가 명령을 실행할 수 없습니다. 명령을 실행하는 대신 제안만 한다면, 에이전트 모드가 아닌 편집 모드에 있거나 승인 프롬프트를 놓쳤을 가능성이 큽니다. 에이전트 채팅에 있는지 확인하고 Cursor가 요청할 때 승인하세요. 터미널 실행이 완전히 실패한다면, 일반적으로 설치 가이드에서 다루는 `apidog: command not found` PATH 문제일 것입니다.
`apidog whoami`가 인증되지 않았음을 보여줍니다. 로그인은 Cursor가 아닌 사용자 머신에 저장됩니다. Apidog에서 새 토큰을 사용하여 직접 `apidog login --with-token`을 실행한 다음, 에이전트에게 `apidog whoami`로 확인하도록 요청하세요. 토큰은 채팅에 포함하지 마세요.
플래그를 지어냅니다. "알 수 없는 옵션" 오류로 실행이 실패하면, 에이전트가 사용자 버전에 존재하지 않는 플래그를 추측한 것입니다. `apidog run --help`를 실행하게 하고 정확한 플래그를 복사하세요.
마무리
Cursor 설정은 하나의 파일과 하나의 습관입니다: 명령, 인증 소스, 종료 코드 규칙을 고정하는 `.cursor/rules/apidog-cli.mdc` 규칙과, 에이전트가 `apidog run`을 실행하도록 하고 직접 종료 코드를 확인하는 습관입니다. Apidog MCP 서버를 추가하면 Cursor가 코드를 작성하는 동안 사양을 읽을 수도 있습니다.
계속해서 Apidog에서 시나리오를 시각적으로 작성하면 됩니다. Cursor는 단지 시나리오를 실행할 뿐입니다. 여기에서, 동일한 명령을 GitHub Actions의 Apidog CLI를 사용하여 파이프라인으로 연결하거나, 전체 Apidog CLI 가이드에서 전체 플래그 참조를 읽으십시오.