CSV와 JSON으로 파라미터화된 API 테스트 실행 방법

로그인 테스트를 작성했고, 테스트는 통과했습니다. 그때 팀원 중 한 명이 당연한 질문을 던집니다. 잠긴 계정, 인증되지 않은 이메일, 후행 공백이 있는 비밀번호, 언젠가 누군가가 필드에 붙여넣을 SQL 인젝션 문자열에 대해서도 통과할까요? 이제 선택의 순간입니다. 테스트를 다섯 번 복사하고 각 복사본에서 한 값을 변경하거나, 동일한 테스트에 여러 행의 입력을 제공하여 모두 실행되도록 하는 방법을 찾거나.

복사-붙여넣기 방식은 대부분의 테스트 스위트가 망가지는 방식입니다. 거의 동일한 다섯 개의 테스트는 1년이 지나면서 서로 멀어집니다. 하나는 새로운 단언을 추가하고, 다른 것들은 추가하지 않습니다. 필드 이름 변경으로 인해 네 개가 조용히 깨집니다. 결국 하나였어야 할 다섯 가지를 유지 관리하게 됩니다. 매개변수화된 테스트는 이 문제를 근본적으로 해결합니다. 테스트를 한 번 작성한 다음, 입력 및 예상 출력 테이블을 가리키고 모든 것을 실행합니다. 하나의 시나리오, 수백 개의 케이스, 편집할 수 있는 한 곳.

button

매개변수화된 테스트의 실제 의미

때때로 데이터 기반 테스트라고도 불리는 매개변수화된 테스트는 테스트의 로직과 테스트가 실행되는 데이터를 분리합니다. 로직은 단계의 순서입니다: 요청을 보내고, 상태 코드를 확인하고, 응답의 필드를 검증합니다. 데이터는 해당 로직을 실행하려는 입력 및 예상 결과의 집합입니다.

할인 코드 엔드포인트에 대한 단일 테스트 시나리오를 상상해 보세요. 로직은 항상 동일합니다. 코드를 포함하여 POST /api/orders를 보내고, 응답에 대해 단언(assert)합니다. 데이터는 각 케이스마다 변경됩니다:

code	order_total	expected_status	expected_discount
WELCOME10	100	200	10
WELCOME10	5	422	0
EXPIRED	100	410	0
(empty)	100	400	0
FAKE123	100	404	0

다섯 개의 행, 다섯 가지 개별 동작, 하나의 테스트. 러너는 행을 반복합니다. 각 통과 시 열 값을 변수에 바인딩하고, 요청을 실행하고, 해당 행의 예상 결과에 대해 단언을 확인합니다. 만료된 코드가 410 대신 200을 반환하여 3번 행이 실패하면, 한 행을 가리키는 하나의 명확한 실패를 얻게 됩니다. 어떤 복사본이 깨졌는지 파악하기 위해 다섯 개의 개별 테스트 파일을 찾아다닐 필요가 없습니다.

이 패턴은 가장자리(edge)에서 가장 중요합니다. 정상 경로(happy-path) 커버리지는 작성하기 쉽고 오전 2시에 당신을 호출하는 버그를 거의 잡지 못합니다. 버그는 경계 사례(boundary cases)에 있습니다: 빈 문자열, 음수, 유니코드 이름, 만료된 토큰, 제한을 1센트 초과하는 값. 매개변수화를 통해 경계 사례를 추가하는 것은 스프레드시트에 행을 추가하는 것만큼 저렴해집니다.

별도의 데이터 파일이 하드코딩된 값보다 나은 이유

각 사례를 테스트에 직접 하드코딩할 수 있습니다. 대부분의 사람들이 그렇게 시작합니다. 문제는 나중에 나타납니다.

데이터가 테스트 내에 있으면 비엔지니어는 사례를 기여할 수 없습니다. 당신의 QA 리드는 이 엔드포인트를 이전에 깨뜨렸던 15가지 까다로운 입력을 알고 있지만, 코드를 편집하고 풀 리퀘스트를 열지 않고는 추가할 수 없습니다. 데이터가 CSV에 있으면 스프레드시트를 편집하고 커밋합니다. 장벽이 거의 0으로 떨어집니다.

별도의 파일은 또한 테스트 시나리오를 읽기 쉽게 유지합니다. 외부 파일을 반복하는 테스트는 짧습니다: 하나의 요청, 소수의 단언, 끝. 30개의 인라인 사례가 있는 테스트는 아무도 건드리고 싶지 않은 반복의 벽입니다. 그리고 프로그램적으로 사례를 생성해야 할 때, 예를 들어 프로덕션 로그에서 가져온 수천 개의 행을 생성해야 할 때, 파일만이 유일한 합리적인 선택입니다. 수천 개의 사례를 테스트 본문에 붙여넣을 수는 없습니다.

선택하는 형식은 데이터의 모양에 따라 달라집니다. 평면적이고 표 형식의 사례는 CSV에 적합합니다. 중첩되거나 구조화된 페이로드(payload)는 JSON에 적합합니다. 둘 다 Apidog의 러너에서 일급 입력이므로, 선택은 도구의 한계가 아니라 데이터에 관한 것입니다.

데이터 파일 설정하기

표 형식의 사례에는 CSV로 시작하세요. 헤더 행은 변수 이름을 지정하고, 아래의 모든 행은 하나의 반복입니다. 다음은 할인 코드 테이블을 실제 파일인 discount-cases.csv로 나타낸 것입니다:

code,order_total,expected_status,expected_discount
WELCOME10,100,200,10
WELCOME10,5,422,0
EXPIRED,100,410,0
,100,400,0
FAKE123,100,404,0

각 열 헤더는 테스트 내에서 참조하는 변수가 됩니다. 요청 본문에는 {{code}}와 {{order_total}}을 작성하고, 단언에서는 {{expected_status}}와 {{expected_discount}}를 비교합니다. 러너는 행별로 바인딩을 수행합니다.

입력이 중첩되어 있을 때는 JSON을 사용하세요. 각 반복당 하나의 객체로 구성된 객체 배열을 사용하면, 각 사례가 열로 평면화하기에는 어색한 구조화된 데이터를 전달할 수 있습니다. 다음은 페이로드에 중첩된 필드가 있는 사용자 생성 엔드포인트에 대한 user-cases.json입니다:

[
  {
    "scenario": "valid full profile",
    "user": {
      "email": "ada@example.com",
      "roles": ["admin", "billing"],
      "profile": { "country": "US", "timezone": "America/New_York" }
    },
    "expected_status": 201
  },
  {
    "scenario": "missing email",
    "user": {
      "email": "",
      "roles": ["viewer"],
      "profile": { "country": "GB", "timezone": "Europe/London" }
    },
    "expected_status": 400
  },
  {
    "scenario": "unknown role",
    "user": {
      "email": "grace@example.com",
      "roles": ["wizard"],
      "profile": { "country": "CA", "timezone": "America/Toronto" }
    },
    "expected_status": 422
  }
]

테스트 내에서는 동일한 {{user}}, {{expected_status}} 구문으로 구조화된 값을 참조하며, Apidog는 각 객체의 필드를 반복에 전달합니다. scenario 열은 자신을 위한 레이블입니다. 보고서에 표시되므로 실패한 반복은 "반복 3" 대신 "알 수 없는 역할"로 표시됩니다.

몇 가지 규칙을 따르면 데이터 파일로 인한 문제를 피할 수 있습니다:

파일당 하나의 관심사를 유지하세요. 할인 코드 파일과 사용자 생성 파일은 두 개의 파일이며, 열이 혼합된 하나의 파일이 아닙니다.
예상 결과는 테스트가 아닌 데이터에 넣으세요. 핵심은 2번 행은 422를 예상하고 1번 행은 200을 예상한다는 것입니다. 예상 결과가 하드코딩되어 있으면 각 사례당 하나의 테스트로 돌아가는 것입니다.
CSV에서 쉼표가 있는 모든 것을 따옴표로 묶거나, 해당 파일을 JSON으로 전환하세요. 쉼표가 포함된 자유 텍스트 필드는 CSV에서 흔히 발생하는 문제입니다.
이 파일들을 저장소의 다른 테스트 설정 옆에 저장하여 테스트 대상 코드와 함께 버전 관리되도록 하세요.

Apidog에서 매개변수화된 시나리오 구축하기

Apidog 앱에서 다른 시나리오와 마찬가지로 테스트 시나리오를 한 번 구축하세요. 엔드포인트에 요청을 추가하세요. 본문에서 리터럴 값을 변수 참조(예: {{code}}, {{order_total}} 등)로 바꿉니다. 이는 데이터 파일의 열입니다.

그런 다음 동일한 파일에서 읽는 단언을 추가합니다. 할인 예제의 경우, 응답 상태가 {{expected_status}}와 같고 JSON 본문의 할인 필드가 {{expected_discount}}와 같다고 단언합니다. 입력과 예상 출력이 모두 행에서 오기 때문에 동일한 단언 로직이 모든 사례를 올바르게 검증합니다. 이전에 Apidog에서 단언을 작성한 적이 없다면, API 단언: 실용 가이드에서 패턴을 다루고, JSON 응답에서 단언을 설정하고 변수를 추출하는 방법에서 JSONPath 측면을 자세히 보여줍니다.

데이터를 연결하려면 테스트 시나리오의 실행 설정을 열고 CSV 또는 JSON 파일을 반복 데이터 소스로 첨부하세요. Apidog는 파일을 읽고, 행을 세고, 각 행의 열을 일치하는 변수에 바인딩하면서 각 행당 한 번 시나리오를 실행합니다. 앱 내에서 실행하면 반복별 분석을 얻을 수 있습니다: 어떤 행이 통과했는지, 어떤 행이 실패했는지, 그리고 각 실패한 단언에 대한 실제 값 대 예상 값.

이것은 또한 매개변수화가 스위트의 나머지 부분과 결합되는 지점입니다. 매개변수화된 시나리오는 여전히 시나리오이므로, 여러 시나리오를 테스트 스위트로 그룹화하고 전체 세트를 하나의 작업으로 실행할 수 있습니다. 데이터 기반 루프는 단일 엔드포인트 내의 폭을 처리하고, 테스트 스위트는 엔드포인트 간의 커버리지를 처리합니다.

명령줄에서 실행하기

앱은 구축하고 디버그하는 곳입니다. CI는 테스트가 제 몫을 하는 곳으로, 아무도 버튼을 클릭하지 않고 모든 풀 리퀘스트에서 실행됩니다. 이러한 인계를 위해 Apidog CLI가 존재합니다. 앱에서 구축한 시나리오를 동일한 반복 데이터로 터미널에서 헤드리스로 실행합니다.

CLI는 npm 패키지로 제공됩니다. 전역으로 설치하세요:

npm install -g apidog-cli

실행 파일은 apidog이므로 모든 명령은 apidog run으로 시작합니다. 기본 실행은 ID로 시나리오를 가리키고 ID로 환경을 가리킵니다:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli

데이터 파일에서 해당 시나리오를 실행하려면 반복 데이터 플래그를 추가하세요. JSON 또는 CSV 파일의 경로를 허용합니다:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 \
  -d ./discount-cases.csv -r cli,junit --out-dir ./test-reports

-d 플래그(긴 형식 --iteration-data)는 명령줄에서 매개변수화된 실행의 핵심입니다. Apidog는 파일을 읽고, 각 행당 한 번 시나리오를 실행하며, 각 반복을 보고합니다. discount-cases.csv를 user-cases.json으로 바꾸면 동일한 플래그가 JSON 배열을 처리합니다. 러너는 파일에서 형식을 감지합니다. 액세스 토큰을 비밀번호처럼 취급하고 커밋된 파일이 아닌 CI 비밀 저장소에 저장하세요. 이것이 모든 예제가 리터럴 값 대신 $APIDOG_ACCESS_TOKEN을 참조하는 이유입니다.

몇 가지 플래그는 매개변수화된 실행과 자연스럽게 짝을 이룹니다:

-d, --iteration-data <path>는 실행을 CSV 또는 JSON 파일로 가리킵니다. 이것이 단일 통과 실행을 데이터 기반 실행으로 전환하는 것입니다.
-n, --iteration-count <n>은 시나리오를 고정된 횟수만큼 실행합니다. 데이터 파일을 제공하면 행 수가 일반적으로 반복을 주도하므로, 주로 부하 테스트와 같이 데이터 없이 반복하는 경우에 -n을 사용합니다.
-r, --reporters <list>는 출력 형식을 선택합니다. 읽기 쉬운 빌드 로그 출력을 위해서는 cli를 사용하고, CI 대시보드가 반복당 합격/실패 트리로 구문 분석하는 XML을 내보내려면 junit를 사용합니다.
--out-dir <path>는 보고서가 저장될 위치를 설정하여 빌드 아티팩트로 보관할 수 있도록 합니다.

설치된 버전의 권위 있고 최신 플래그 목록을 보려면 apidog run --help를 실행하세요. CLI는 모든 옵션을 짧은 형식과 긴 형식으로 출력합니다.

CI에 매개변수화된 실행 연결

매개변수화된 테스트에 투자하는 이유는 자동으로 성과를 내기 때문입니다. 다음은 CLI를 설치하고 모든 풀 리퀘스트에서 CSV 기반 시나리오를 실행하는 GitHub Actions 작업입니다:

name: API tests
on: [pull_request]

jobs:
  api-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Install Apidog CLI
        run: npm install -g apidog-cli
      - name: Run parameterized API tests
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
        run: |
          apidog run --access-token $APIDOG_ACCESS_TOKEN \
            -t 605067 -e 1629989 \
            -d ./tests/discount-cases.csv \
            -r cli,junit --out-dir ./test-reports
      - name: Upload report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: api-test-report
          path: ./test-reports

토큰은 저장소 설정에 한 번 설정된 secrets.APIDOG_ACCESS_TOKEN에서 가져옵니다. junit 리포터는 대부분의 CI 대시보드가 반복별 결과 트리로 변환하는 XML을 작성하므로, 실패한 행은 로그 텍스트의 벽이 아닌 명명된 실패 테스트로 표시됩니다. 업로드 단계의 if: always()는 실행이 실패하더라도 보고서를 유지한다는 의미이며, 바로 이때 보고서가 필요합니다. Actions 측면에 대한 더 자세한 내용은 GitHub Actions에서 API 테스트를 자동화하는 방법을 참조하세요.

동일한 시나리오와 동일한 데이터 파일이 모든 CI 시스템에서 실행됩니다. GitLab CI, Jenkins, CircleCI 등은 모두 동일한 세 가지 단계로 귀결됩니다: Node 및 CLI 설치, 토큰을 환경 변수로 노출, -d와 함께 apidog run 호출. 플랫폼별 테스트 재작성은 필요 없습니다.

매개변수화된 테스트 접근 방식 비교

Apidog만이 데이터 기반 API 테스트를 실행하는 유일한 방법은 아닙니다. 적절한 것을 선택할 수 있도록 전반적인 상황을 아는 것이 중요합니다.

Postman과 그 러너도 데이터 파일을 지원합니다. Postman의 컬렉션 러너(Collection Runner) 또는 Newman 명령줄 도구를 사용하면 CSV 또는 JSON 파일을 첨부하고 요청에서 {{column}} 변수를 참조할 수 있으며, 이 패턴과 매우 유사합니다. 이는 유능한 접근 방식이며 문서화가 잘 되어 있습니다. 단점은 테스트 로직이 JavaScript 사전 요청 및 테스트 스크립트에 존재하므로, 단언이 증가할수록 더 많은 코드를 유지 관리해야 한다는 것입니다. 특히 명령줄 러너를 고려하고 있다면, Postman CLI vs Newman에서 차이점을 분석합니다.

@pytest.mark.parametrize가 있는 pytest, JUnit의 @ParameterizedTest 또는 REST Assured와 같은 코드 우선 프레임워크는 완전한 프로그래밍 언어 제어를 제공합니다. 이는 테스트 로직이 복잡한 설정, 사용자 정의 데이터 생성, 기존 테스트 코드베이스와의 긴밀한 결합과 같이 진정으로 코드를 필요로 할 때 적절한 선택입니다. 단점은 모든 사례가 코드에 존재하므로 비엔지니어가 기여할 수 없고, HTTP 플러밍을 직접 유지 관리해야 한다는 것입니다.

Apidog의 관점은 시나리오가 시각적이고 데이터가 외부적이라는 것입니다. 따라서 로직은 읽기 쉽고, 스프레드시트를 편집할 수 있는 모든 사람에게 사례가 열려 있으며, 동일한 시나리오는 CI에서 여전히 헤드리스로 실행됩니다. CSV 및 JSON 데이터 기반 실행을 위한 도구를 특별히 선택하는 경우, CSV 또는 JSON을 사용한 데이터 기반 API 테스트를 위한 도구의 비교에서 장단점을 더 깊이 파고듭니다. 이들 중 틀린 것은 없습니다. 누가 사례를 작성하고 각 사례에 얼마나 많은 사용자 정의 로직이 필요한지에 따라 접근 방식을 일치시키세요.

확장 가능한 실용적인 워크플로

다음은 팀의 루틴의 일부가 되었을 때의 모습입니다.

좁게 시작하세요. 이전에 문제를 일으켰던 엔드포인트 하나를 선택하세요. Apidog에서 요청에 변수 참조를, 단언에 예상 결과를 포함하는 단일 시나리오를 작성하세요. 정상 경로, 알려진 실패, 경계 사례의 세 행으로 CSV를 구축하세요. 세 가지 반복 모두 예상대로 작동할 때까지 앱에서 실행하세요.

그런 다음 테스트가 아닌 데이터를 확장하세요. 버그 보고서가 들어올 때마다, 버그를 유발한 입력을 올바른 예상 출력과 함께 새 행으로 추가하세요. 버그는 영구적인 회귀 사례가 되고, 새 테스트를 작성하는 대신 파일에 한 줄을 추가했을 뿐입니다. 몇 달 동안 파일은 엔드포인트가 실제로 직면하는 실제 세상의 문제점을 축적합니다.

마지막으로, 자동화하세요. apidog run -d 명령을 CI에 넣으면 전체 테이블이 모든 풀 리퀘스트에서 실행됩니다. 이제 만료된 코드 경로를 깨뜨리는 변경 사항은 푸시되는 순간 빌드를 실패시키고, 손상된 행을 직접 가리키는 명명된 반복이 표시됩니다.

복합적인 이점은 유지 관리입니다. 엔드포인트의 응답 형태가 변경될 때, 단언을 한 번 수정하면 모든 사례에 수정 사항이 적용됩니다. 50개의 추가 사례가 필요할 때, 50개의 행을 추가합니다. 테스트 로직은 커버리지가 얼마나 넓어지든 상관없이 단일하고 작고 읽기 쉬운 상태를 유지합니다.

자주 묻는 질문

매개변수화된 테스트와 데이터 기반 테스트의 차이점은 무엇인가요? 둘 다 동일한 아이디어를 설명하며, 사람들은 이 용어들을 서로 바꿔가며 사용합니다. 둘 다 테스트 외부에서 제공되는 다양한 입력과 예상 출력으로 하나의 테스트를 반복적으로 실행하는 것을 의미합니다. "매개변수화된(Parameterized)"는 매개변수 바인딩 메커니즘에 중점을 두고, "데이터 기반(data-driven)"은 외부 데이터 소스에 중점을 둡니다. 실제로 이들은 동의어로 간주하세요.

데이터 파일에 CSV를 사용해야 하나요, JSON을 사용해야 하나요? 데이터 형태에 맞는 형식을 사용하세요. 모든 행에 동일한 간단한 열이 있는 평면적이고 표 형식의 사례는 CSV에 적합하며, CSV는 비엔지니어가 스프레드시트에서 편집하기 더 쉽습니다. 배열과 하위 객체가 있는 요청 본문과 같은 중첩되거나 구조화된 페이로드는 JSON에 적합합니다. Apidog는 둘 다 반복 데이터로 읽으므로, 왜곡 없이 사례를 나타내는 것을 선택하세요.

수백 번의 반복이 파이프라인 속도를 늦출까요? 각 행은 시나리오의 한 번 실행이므로, 총 시간은 행 수 곱하기 요청당 지연 시간으로 조정됩니다. 대부분의 API 테스트의 경우 몇 분이 아니라 몇 초입니다. 대규모 데이터 세트가 빌드를 늘어뜨리는 경우, 분할하세요: 모든 풀 리퀘스트에서 빠른 스모크 테스트 하위 집합을 실행하고, 야간 또는 사전 릴리스 작업에서 전체 테이블을 실행하세요. 동일한 시나리오와 파일이 둘 다에 사용되며, 데이터 하위 집합만 변경됩니다.

데이터 파일 및 테스트 구성에서 비밀 정보를 제외하는 방법은 무엇인가요? 자격 증명은 데이터 파일에서 완전히 제외하세요. 토큰과 비밀번호는 환경 변수 또는 CI 시스템의 비밀 저장소에 속하며, $APIDOG_ACCESS_TOKEN 등과 같이 참조됩니다. 데이터 파일은 테스트 입력과 예상 결과를 포함해야 하며, 인증 자료는 포함하지 않아야 합니다. 리포지토리를 읽을 수 있는 모든 사람이 CSV를 읽을 수 있으므로, 그렇게 취급하세요.

동일한 매개변수화된 시나리오를 스테이징 및 프로덕션에 대해 실행할 수 있나요? 예. 시나리오와 데이터 파일은 고정된 상태로 유지하고, -e 플래그로 환경을 전환하세요. 동일한 시나리오 ID와 동일한 데이터를 사용하여 풀 리퀘스트 검사를 스테이징에 연결하고, 배포 후 스모크 테스트를 프로덕션에 연결하되, 환경 ID만 다르게 하세요. 이것이 환경과 데이터가 별도의 입력인 전체 이유입니다.

마무리하며

매개변수화된 API 테스트는 커버리지를 복사-붙여넣기 작업에서 데이터 입력 작업으로 전환합니다. 테스트를 한 번 작성하고, 각 사례를 CSV 또는 JSON 파일의 행으로 설명하고, 러너가 나머지를 처리하도록 합니다. 로직은 작고 읽기 쉬우며, 사례는 팀의 모든 사람에게 열려 있고, CI는 모든 변경 사항에 대해 전체 테이블을 실행합니다.

Apidog는 작성을 위한 시각적 시나리오 빌더, 데이터를 위한 외부 CSV 및 JSON 파일, 그리고 모든 CI 시스템에서 헤드리스 실행을 위한 apidog run -d 명령을 제공합니다. 하나의 시나리오를 구축하고, 증가하는 사례 테이블에 연결하면, 누군가가 행을 추가할 때마다 테스트 커버리지가 넓어집니다. Apidog를 다운로드하고 다음 불안정한 일회성 테스트를 확장 가능한 매개변수화된 시나리오로 전환하세요.

button