Windsurf의 Cascade 에이전트는 루프를 실행합니다. 파일을 편집하고, 터미널 명령을 실행하고, 출력을 읽고, 다음에 무엇을 할지 결정합니다. 그렇다면 API 테스트는 왜 이 루프에 포함되지 않을까요? API 테스트는 GUI 뒤의 Apidog에 있으며 누군가 클릭할 때까지 기다립니다. Cascade는 API 테스트를 전혀 건드리지 않습니다.
해결책은 하나의 구성 블록입니다. Apidog CLI는 Apidog에서 구축한 테스트 시나리오를 터미널에서 직접 실행하는 npm 패키지인 apidog-cli입니다. CLI가 설치되고 Cascade가 CLI의 존재를 알게 되면, Windsurf는 유닛 테스트를 실행하는 것과 동일한 방식으로 Apidog 시나리오를 실행합니다. 즉, 명령을 실행하고, 종료 코드를 읽고, 결과가 빨간색이면 코드를 수정합니다.
CLI를 아직 설치하지 않았다면 먼저 설치하십시오. AI 코딩 에이전트로 Apidog CLI를 설치하는 방법은 npm 설치, 인증 및 첫 실행을 에이전트가 입력하는 방식으로 안내합니다. 이 문서는 apidog --version이 숫자를 출력하고 Apidog 계정이 인증된 상태를 가정합니다.
여기서 다루는 Windsurf
Windsurf는 Codeium의 에이전트 기반 IDE이며, 내장 에이전트는 Cascade라고 합니다. Cascade는 로컬에서 실행되며, 리포지토리를 읽고, 파일을 편집하고, 통합 터미널에서 셸 명령을 실행하며, 자동 실행 설정에 따라 승인을 요청합니다. 이것은 브라우저 확장이나 자동 완성 플러그인이 아닌 편집기와 그 에이전트입니다.
아직 설정하지 않았다면 Windsurf 다운로드 및 설치 방법부터 시작하십시오. 프로젝트에서 Cascade를 열면 자체 규칙 메커니즘을 통해 Apidog CLI에 대해 알려줄 수 있으며, 이를 통해 일회성 "내 테스트 실행"이 Cascade가 스스로 찾는 것으로 바뀝니다.
단계 1: .windsurf/rules에 Apidog 규칙 추가
Cascade는 작업을 시작하기 전에 Markdown 파일에서 프로젝트 규칙을 읽습니다. 리포지토리 루트의 .windsurf/rules/ 디렉토리에 파일당 하나의 규칙으로 저장하십시오. Windsurf는 여전히 워크스페이스 루트의 레거시 단일 파일 .windsurfrules와 모든 프로젝트에 적용되는 전역 ~/.codeium/windsurf/memories/global_rules.md를 읽지만, 프로젝트별 지침의 경우 .windsurf/rules/ 디렉토리가 올바른 위치입니다. 이는 Windsurf의 규칙 및 메모리 참조에 문서화되어 있습니다.
다음과 같은 블록으로 .windsurf/rules/apidog.md를 생성하십시오.
# Apidog API tests
This project has Apidog test scenarios. Run them with the Apidog CLI:
apidog run -t <scenario_id> -e <env_id> -r cli
Rules:
- Use the exact command above; do not invent flags. Run `apidog run --help` if unsure.
- `apidog run` exits 0 when every assertion passes, non-zero when any fails.
Treat exit 0 as pass and non-zero as fail. Report the real exit code.
- The machine is already authenticated via `apidog login`. Never add an
access token to the command or commit one to this file.
- After you change code that touches the API, run the scenario and act on the result.
채팅 메시지 대신 규칙 파일인 이유는 무엇일까요? 채팅에 입력된 시나리오 ID는 세션이 끝나면 사라집니다. .windsurf/rules/apidog.md에 있는 시나리오 ID는 지금부터 모든 팀원과 모든 Cascade 세션에 존재합니다. 이는 지속되며, Git에 버전이 지정되고, Cascade는 시작 시 자동으로 컨텍스트에 로드합니다.
단계 2: Apidog에서 명령 가져오기
해당 블록의 <scenario_id> 및 <env_id>는 추측하는 플레이스홀더가 아닙니다. Apidog가 정확한 명령을 생성해 줍니다.
Apidog에서 테스트 시나리오를 열고, CI/CD 탭으로 이동하여 미리 준비된 apidog run 명령을 복사하십시오. 여기에는 이미 올바른 시나리오 ID, 환경 ID 및 리포터 플래그가 채워져 있습니다. 해당 명령을 .windsurf/rules/apidog.md에 예시 줄 대신 붙여넣으십시오. 이제 규칙은 템플릿이 아닌 프로젝트에 대해 실제로 작동하는 명령을 포함합니다.
해당 명령의 전체 구조와 허용하는 모든 플래그에 대한 자세한 내용은 apidog run 명령 참조를 참조하십시오.
단계 3: Cascade가 테스트를 실행하도록 하기
규칙이 적용되면 리포지토리에서 Cascade를 엽니다. 시작할 때 .windsurf/rules/apidog.md를 로드하므로 CLI의 존재를 이미 알고 있습니다. API를 건드리는 변경을 하거나 단순히 확인을 실행하도록 요청하십시오.
Run the Apidog scenario and tell me the exit code.
Cascade는 규칙에서 apidog run 명령을 실행합니다. 프롬프트 없이 실행되는지 여부는 자동 실행 설정에 따라 달라집니다. Windsurf는 네 가지 수준을 제공합니다: 비활성화됨 (모든 명령에 승인 필요), 허용 목록 전용 (허용 목록과 일치하는 명령만 자동 실행), 자동 (프리미엄 모델 판단), 및 터보 (비허용 명령을 제외한 모든 것이 자동 실행). 터보 모드에서는 일반 apidog run이 자동으로 실행되며, 더 엄격한 모드에서는 Cascade가 일시 중지하고 먼저 요청합니다.
모든 것을 완화하지 않고 apidog run이 자동 실행되기를 원한다면 허용 목록에 추가하십시오. 설정은 windsurf.cascadeCommandsAllowList이며, 명령 팔레트의 '설정 열기'에서 접근할 수 있습니다. apidog를 추가하면 Cascade는 묻지 않고 명령을 실행합니다. 일치하는 비허용 목록 설정은 windsurf.cascadeCommandsDenyList이며, 명령이 둘 다와 일치할 경우 비허용 목록이 우선합니다. 둘 다 Windsurf의 터미널 문서에 설명되어 있습니다. 스테이징에 대한 읽기 전용 시나리오는 허용 목록 항목이 만들어진 안전하고 작업 공간 내의 명령 유형입니다.
단계 4: Windsurf 내에서 보고서 읽기
실행이 빨간색으로 표시되면 보고서에 답이 있습니다. -r cli 리포터는 Cascade 터미널에 단계별 결과와 요약을 직접 출력합니다. 각 요청, 각 어설션, 그리고 어떤 것이 예상 값과 실제 값으로 실패했는지 보여줍니다. 실패한 어설션은 정확한 필드 또는 상태 코드를 명시하며, 이는 Cascade가 다음 단계에서 수정 사항을 찾는 데 일반적으로 충분합니다.
브라우저에서 열거나 팀원에게 전달할 수 있는 보고서를 원하면 HTML 리포터를 추가하십시오.
apidog run -t <scenario_id> -e <env_id> -r cli,html
html 리포터는 ./apidog-reports에 자체 포함된 파일을 작성합니다. Cascade가 다음 단계를 결정하기 위해 읽는 인라인 출력을 여전히 얻을 수 있도록 목록에 cli를 유지하십시오. JUnit 형식 CI 대시보드가 파싱하는 것을 포함한 모든 리포터에 대해서는 완전한 Apidog CLI 가이드 및 Apidog CLI 테스트 보고서 읽는 방법을 참조하십시오.
Windsurf 자체 루프 내에서 테스트
핵심은 당신이 요청을 멈추고 Cascade가 규칙에 따라 스스로 시나리오를 실행할 때 발생하는 일입니다.
체크아웃 응답을 구축하는 핸들러를 편집하는 Cascade를 상상해 보십시오. 루프가 변경됩니다. 코드를 편집한 다음, 성공을 선언하는 대신, 스테이징에 대해 Apidog 시나리오를 실행하고, 종료 코드를 읽고, 그에 따라 조치합니다. 녹색이면 다음으로 넘어갑니다. 빨간색이면 보고서를 열고, 어떤 어설션이 실패했는지(상태 코드, 누락된 필드, 잘못된 값) 읽고, 수정을 시도하고, 다시 실행합니다. API 테스트는 Cascade가 이미 유닛 테스트를 실행하는 동일한 편집-테스트-수정 루프의 일부가 됩니다. 당신은 하나의 규칙을 작성했고 Cascade는 명령을 이미 작동하는 방식에 통합했습니다.
이것은 모든 에이전트 워크플로우를 안전하게 만드는 위임-검증 모델입니다. Cascade는 명령을 실행하고 결과를 읽습니다. 당신은 Apidog에서 시나리오를 시각적으로 계속 작성하고 에이전트가 종료 코드를 정직하게 읽는지 스팟 확인합니다. 더 넓은 패턴에 대해서는 API 테스트에 AI 에이전트를 사용하는 방법 및 Apidog AI 테스트 하네스를 참조하십시오.
Cascade가 실제로 CLI를 실행하는지 확인
에이전트는 얻지 못한 성공을 보고하며, Cascade도 예외는 아닙니다. 문제를 파악하는 빈도 순으로 세 가지 확인 사항이 있습니다.
첫째, 명령이 실행되었는지 확인하십시오. Cascade는 터미널에 실행되는 명령과 그 출력을 인라인으로 표시합니다. 실제 apidog run ... 줄과 그 아래의 결과를 찾으십시오. Cascade가 테스트를 실행했다고 말했지만 명령이 보이지 않으면, 실제로 하지 않은 일을 요약한 것입니다. 다시 실행하고 원시 출력을 보여달라고 요청하십시오.
둘째, 중요한 종료 코드를 확인하십시오. 직접 물어보십시오.
What was the exit code of that apidog run command?
apidog run은 모든 어설션이 통과하면 0으로 종료하고, 실패하면 0이 아닌 값으로 종료합니다. 이 단일 동작을 통해 Cascade 또는 파이프라인은 실행을 깔끔한 게이트로 처리할 수 있습니다. Cascade의 설명이 "테스트 통과"라고 말하지만 종료 코드가 0이 아니면 종료 코드가 맞습니다.
셋째, 실제 시나리오를 사용했는지 확인하십시오. 실행이 "시나리오를 찾을 수 없음"으로 실패하면 Cascade가 ID를 만들거나 잘못 기억했을 수 있습니다. 규칙 파일 및 Apidog의 CI/CD 탭에서 생성된 명령과 -t 및 -e 값을 다시 확인하십시오. .windsurf/rules/apidog.md의 ID가 진실입니다.
선택 사항: Apidog MCP 서버 연결
규칙에서 apidog run을 실행하는 것은 필요한 대부분을 충족합니다. 한 단계 더 나아가 MCP 서버를 연결하십시오.
Cascade는 모델 컨텍스트 프로토콜을 지원합니다. Windsurf는 ~/.codeium/windsurf/mcp_config.json에서 서버 목록을 읽으며, 직접 편집하거나 Cascade MCP 패널을 통해 관리할 수 있습니다. 형식은 Windsurf의 MCP 참조에 문서화되어 있으며, Windsurf에서 MCP 서버를 설정하는 방법은 패널을 안내합니다. Apidog MCP 서버는 MCP를 통해 API 사양을 노출하므로, Cascade는 코드를 작성하는 동안 스키마를 읽을 수 있으며, 나중에 읽는 것이 아닙니다. 작업 분할이 깔끔합니다. CLI는 테스트를 실행하고, MCP는 에이전트에 사양을 제공합니다.
Windsurf가 잘못된 경우
설정 중에 몇 가지 오류가 자주 발생합니다.
규칙을 무시합니다. Cascade가 일반 명령을 실행하거나 전혀 실행하지 않으면 규칙이 로드되지 않을 수 있습니다. 파일이 리포지토리 루트의 .windsurf/rules/에 있고 .md 확장자를 가지고 있는지 확인하십시오. 각 규칙 파일은 12,000자로 제한되므로 Apidog 블록을 짧게 유지하십시오. Cascade를 다시 시작하면 새로 읽습니다.
어쨌든 액세스 토큰을 전달합니다. Cascade가 명령에 액세스 토큰을 추가하려고 하면 공개 예시에서 추측하는 것입니다. 머신이 apidog login을 통해 인증되었으므로 규칙은 이미 그렇게 하지 말라고 지시합니다. 해당 줄을 강화하고, 커밋되는 규칙 파일에 실제 토큰을 절대 넣지 마십시오. 인증이 실제로 작동하는 방식에 대해서는 Apidog CLI 인증 가이드를 참조하십시오.
플래그를 발명합니다. "알 수 없는 옵션" 오류는 Cascade가 설치된 버전에는 없는 플래그를 추측했음을 의미합니다. apidog run --help를 실행하고 거기에서 정확한 플래그를 복사하도록 지시하십시오. 이 플래그는 설치된 버전에 대해 항상 올바릅니다.
실패한 실행에서 통과를 보고합니다. 가장 비용이 많이 드는 것이며, 종료 코드 규칙이 규칙 파일과 검증 단계 모두에 있는 이유입니다. 요약과 종료 코드가 일치하지 않으면 종료 코드가 우선합니다.
일상적인 에이전트에서 테스트된 루프로
이것이 설정입니다. 설치 가이드에 따라 apidog-cli를 한 번 설치하고, 리포지토리의 .windsurf/rules/ 디렉토리에 짧은 Apidog 규칙을 추가하면 Cascade는 코드를 편집하는 데 이미 사용하는 동일한 루프 내에서 API 테스트를 실행하고 결과를 읽는 방법을 알게 됩니다. 깨진 엔드포인트는 배포된 후가 아니라 Cascade가 변경 작업을 진행하는 동안 파악됩니다.
GUI 뒤의 테스트는 사람이 클릭할 때 실행됩니다. 한 줄짜리 명령은 Cascade가 결정할 때마다 실행됩니다. 당신은 Apidog에서 시나리오를 시각적으로 계속 구축하고, 에이전트는 당신이 보지 않는 곳에서 시나리오를 실행합니다. 로컬에서 작동하면 파이프라인에서 동일한 명령을 실행하려면 GitHub Actions의 Apidog CLI에서 비밀, 리포터 및 종료 코드 게이팅을 다룹니다. Apidog를 다운로드하고, 하나의 시나리오를 구축하고, 해당 apidog run 명령을 Windsurf 규칙에 삽입하고, Cascade가 다음 변경 시 이를 수행하는 것을 지켜보십시오.