파일을 받는 엔드포인트를 구축했습니다. 사용자가 프로필 사진을 POST /avatars로 업로드하거나, 앱에서 서명된 PDF를 POST /documents로 푸시합니다. 머릿속에서는 이 라우트가 작동합니다. 이제 HTTP를 통해 실제로 작동한다는 것을 증명해야 합니다. 실제 파일을 선택하고, 양식 필드에 첨부하고, 요청을 보내고, 응답을 확인해야 합니다.
이것이 많은 API 도구들이 까다로워지는 부분입니다. 파일 업로드에는 JSON이 아닌 multipart/form-data가 사용되므로, 단순히 본문을 붙여넣고 전송 버튼을 누를 수 없습니다. 파일 필드를 이해하는 요청 빌더와 나중에 테스트가 실행될 때 파일을 찾을 수 있는 테스트 러너가 필요합니다. Apidog은 이 두 가지를 모두 처리하며, 이 가이드는 전체 과정을 안내합니다. 단일 업로드 전송, JSON과 함께 파일 전송, 응답 확인, 그리고 아무도 경고하지 않는 솔직한 부분, 즉 러너(Runner)나 CLI에서 해당 업로드 단계가 헤드리스로 실행될 때 파일을 찾지 못할 경우 발생하는 상황까지 다룹니다. 형식 자체에 대한 배경 지식이 먼저 필요하다면, API의 파일 업로드 입문서에서 멀티파트 요청 구조를 다룹니다. 브라우저 측면에서는 FormData에 대한 MDN 참조 문서가 좋은 보조 자료입니다.
multipart/form-data란 무엇이며, 왜 파일 업로드에 필요한가요?
API 요청 본문은 여러 형태를 가질 수 있습니다. Apidog의 요청 본문(Body) 섹션에서는 form-data, x-www-form-urlencoded, JSON, XML, raw, 또는 binary를 선택할 수 있습니다. 대부분의 경우 JSON을 사용하지만, 파일 업로드는 예외입니다.
form-data 본문 유형은 Content-Type: multipart/form-data 헤더에 매핑됩니다. 이것은 다른 데이터와 함께 파일을 업로드하기 위해 만들어진 형식입니다. 하나의 덩어리(blob) 대신, 본문은 각기 고유한 이름과 콘텐츠를 가진 여러 부분(part)으로 나뉩니다. 한 부분은 캡션과 같은 일반 문자열일 수 있고, 다른 부분은 이미지의 원시 바이트일 수 있습니다. 이것이 사진 업로드와 그 메타데이터가 동일한 요청으로 전송될 수 있는 이유입니다.
가장 유사한 것은 x-www-form-urlencoded입니다. 편집기에서는 본문에 전송되는 키-값 쌍으로 유사하게 보이지만, 파일이 없는 간단한 양식에 사용됩니다. 엔드포인트가 파일을 받는다면, form-data가 원하는 형식입니다. 모든 필드가 짧은 스칼라 값이고 바이트가 관련되지 않은 경우에만 x-www-form-urlencoded를 사용하세요.
form-data에서 Apidog은 각 매개변수를 키-값 쌍으로 보여주며, 모든 매개변수는 유형(문자열, 정수, 파일 등)을 가집니다. 이 매개변수별 유형이 핵심입니다. 필드를 file로 설정하면 Apidog은 그 값을 텍스트로 보내는 대신 첨부할 파일로 처리합니다.
단일 파일 업로드 전송 및 응답 확인
POST /avatars를 테스트한다고 가정해 봅시다. 이 엔드포인트는 이미지를 포함하는 avatar 필드 하나를 받고, 저장된 URL이 포함된 JSON을 반환합니다. 다음은 전체 과정입니다.
1. 본문(Body) 섹션을 열고 form-data를 선택합니다. 엔드포인트 또는 새 요청에서 메서드를 POST로 설정하고 URL을 아바타 라우트로 설정합니다. 본문(Body) 탭을 열고 form-data 본문 유형을 선택합니다. Apidog은 자동으로 Content-Type: multipart/form-data를 설정합니다.
2. 파일 매개변수를 추가하고 유형을 파일로 설정합니다. 키가 avatar인 매개변수를 추가합니다. 키 옆에 있는 유형 선택기를 사용하여 유형을 string에서 file로 변경합니다. 값 셀은 텍스트 상자 대신 파일 선택기로 바뀝니다.
3. 업로드를 클릭하고 로컬 파일을 선택합니다. avatar 행에서 업로드(Upload)를 클릭하고 컴퓨터에서 이미지(예: jane-profile.png)를 선택합니다. Apidog은 해당 파일의 경로를 기록합니다.
4. 요청을 보냅니다. 전송(Send)을 클릭합니다. Apidog은 저장된 로컬 경로에서 파일을 읽고, 멀티파트 본문을 구축하여 전송합니다. 미리 알아둘 가치가 있는 점: Apidog은 요청에 파일을 보내지만 파일을 클라우드에 저장하지는 않습니다. 바이트가 아닌 로컬 경로만 저장합니다. 이 세부 사항은 나중에 중요하므로 기억해 두세요.
성공적인 호출은 다음과 유사한 응답을 반환합니다.
{
"id": "usr_8842",
"avatarUrl": "https://cdn.example.com/avatars/usr_8842.png",
"sizeBytes": 48210,
"contentType": "image/png"
}
5. 응답을 확인(Assert)합니다. 200을 반환하는 전송만으로는 통과 테스트가 아닙니다. 실제 검사가 되도록 확인(Assertion)을 추가하세요. Apidog에서는 엔드포인트 또는 시나리오 단계에서 요청 후 확인으로 추가합니다. 간단히 말해, 상태와 본문에 사용 가능한 URL이 포함되어 있는지 확인해야 합니다.
status code == 200
$.avatarUrl exists
$.contentType == "image/png"
이것들은 Apidog의 확인 UI에 직접 매핑됩니다. 상태 코드에 대한 확인 하나, JSONPath $.avatarUrl이 존재하는지에 대한 확인 하나, $.contentType에 대한 확인 하나입니다. 확인에 익숙하지 않다면, API 확인 가이드에서 전체 연산자 세트와 JSONPath가 필드를 대상으로 하는 방법을 보여줍니다.
도구 외부에서 빠른 현실 확인을 위해, curl에서 동일한 업로드는 다음과 같습니다.
curl -X POST https://api.example.com/avatars \
-F "avatar=@jane-profile.png"
-F 플래그는 curl이 멀티파트 부분을 구축하는 방법이며, @는 파일 내용을 읽도록 지시합니다. Apidog의 form-data 파일 매개변수는 플래그 대신 선택기를 사용하여 동일한 작업을 수행합니다.
파일과 JSON 함께 전송
실제 엔드포인트는 단순히 파일만 받는 경우가 거의 없습니다. POST /documents는 파일 외에 제목, 카테고리, 태그 배열과 같은 메타데이터를 원할 수 있습니다. 한 번의 멀티파트 요청으로 이 작업을 수행하는 두 가지 깔끔한 방법이 있습니다.
간단한 경우는 스칼라 필드입니다. 파일 필드 옆에 더 많은 form-data 매개변수를 추가하고 string 또는 integer로 둡니다. title 문자열, category 문자열, 유형이 file로 설정된 file입니다. 이 세 가지 모두 동일한 요청으로 전송됩니다.
중첩된 객체나 배열과 같이 메타데이터가 구조화된 경우, 문자열 부분 안에 JSON으로 보냅니다. metadata라는 이름의 form-data 매개변수를 추가하고, 유형을 string으로 유지한 다음, JSON을 값에 직접 붙여넣습니다.
{
"title": "Q3 Invoice",
"category": "billing",
"tags": ["invoice", "2026", "paid"]
}
따라서 요청은 두 부분으로 구성됩니다. q3-invoice.pdf를 담는 file(유형 file)과 해당 JSON을 담는 metadata(유형 string)입니다. 서버는 한 부분에서 파일을 읽고 다른 부분에서 JSON을 파싱합니다. 많은 공용 API는 이와 똑같은 방식으로 업로드를 받습니다. Stripe 파일 업로드 문서는 파일 부분과 일반 필드를 짝짓는 실제 멀티파트 엔드포인트의 좋은 예입니다. 이 패턴은 Postman 사용자에게도 충분히 흔합니다. 마이그레이션 중이라면 Postman에서 파일 및 JSON 데이터 업로드 방법에 대한 가이드가 Apidog의 form-data 필드에 깔끔하게 매핑됩니다.
하나 이상의 파일을 첨부해야 하나요? 유형이 file인 다른 매개변수를 추가합니다. 기본 파일과 썸네일을 받는 POST /documents는 각각 자체 업로드(Upload) 버튼이 있는 file 및 thumbnail 두 개의 파일 행을 가집니다. 특별한 다중 파일 모드는 없습니다. 엔드포인트가 예상하는 모든 부분을 다룰 때까지 파일 유형 매개변수를 추가하기만 하면 됩니다.
요청을 반복 가능한 테스트 시나리오로 만들기
단일 전송은 엔드포인트가 한 번 작동한다는 것을 증명합니다. 회귀를 잡으려면 주문형 또는 스케줄에 따라 실행되는 저장된 테스트 시나리오 안에 업로드가 있어야 합니다. 아바타를 업로드하고, 반환된 id를 캡처한 다음, GET /users/{id}를 호출하고 아바타 URL이 지속되었는지 확인하는 단계를 연결하세요.
단일 요청을 구축했던 방식과 동일하게 구축한 다음, 시나리오의 한 단계로 저장하세요. Apidog으로 테스트 시나리오 작성 방법 가이드에서는 단계 연결 및 단계 간 값 전달에 대해 다룹니다. 업로드가 시나리오에 포함되면, 배포할 때마다 스테이징 환경에서 실행하거나, API 테스트 시나리오의 조건부 로직을 사용하여 조건부 분기를 추가하거나, 예약된 API 테스트로 타이머를 설정할 수 있습니다.
위의 모든 것은 파일을 가지고 있기 때문에 사용자 머신에서 잘 실행됩니다. 이 가정이 바로 다음 단계에서 문제가 되는 부분입니다.
함정: 다른 곳에서 실행되는 업로드
여기가 순조로운 길에서는 숨겨진 부분입니다. Apidog은 파일 자체가 아닌 파일 경로를 저장합니다. 사용자 노트북에서는 경로가 항상 실제 파일로 해석되기 때문에 보이지 않습니다. 하지만 동일한 단계가 다른 머신에서 실행되는 순간, 경로는 아무것도 가리키지 않습니다.
두 가지 상황에서 이 문제에 직면하게 될 것입니다.
팀 협업. 팀원이 POST /avatars 요청을 열 때, 그들은 파일 매개변수와 사용자가 선택한 경로(예: /Users/jane/pics/jane-profile.png)를 봅니다. 그들은 요청을 볼 수 있지만, 그 파일이 그들의 디스크가 아닌 사용자 디스크에 있기 때문에 보낼 수 없습니다. 경로는 그것을 선택한 머신에 로컬하게 존재합니다.
러너(Runner) 및 CLI 실행. 이것은 자동화에서 문제가 되는 부분입니다. 업로드 시나리오가 로컬에서는 통과하지만, 러너(Runner)에서 예약하거나 CLI에서 실행하면 파일 업로드 단계가 실패합니다. 확인(Assertion)에 문제가 있는 것은 아닙니다. 러너는 사용자 노트북이 저장한 경로에 있는 파일을 찾을 수 없을 뿐입니다. 그 경로는 러너의 호스트에 존재하지 않기 때문입니다.
해결책은 원인에서 파생됩니다. 파일은 전송을 수행하는 머신에 존재해야 하며, 단계의 경로는 해당 파일을 가리켜야 합니다.
러너(Runner)의 경우: 러너는 볼륨에 마운트된 호스트 디렉터리에서 파일을 읽습니다. 배포할 때 -v 플래그를 사용하여 마운트를 설정합니다. 업로드할 파일을 마운트된 호스트 디렉터리에 복사합니다. 그런 다음 시나리오에서 파일 업로드 단계의 단계 세부 정보를 열고 오른쪽 상단 모서리에 있는 일괄 편집(Batch Edit) 버튼을 클릭한 다음, 파일 필드의 값을 러너 디렉터리 내부 경로로 바꿉니다. 예를 들어:
/opt/runner/jane-profile.png
CLI의 경우: 형태는 동일합니다. CLI 머신에 파일을 넣은 다음, 단계에서 일괄 편집(Batch Edit)을 사용하여 해당 위치의 경로를 가리키도록 합니다. 예를 들어:
/opt/apidog/runner/jane-profile.png
하드코딩보다 더 깔끔하게: 변수 사용. 단계에 리터럴 경로를 고정하는 대신, 값을 변수로 바꾸고 환경별로 실제 파일 경로로 변수 값을 설정하세요. 그러면 동일한 시나리오가 노트북, 러너, CI에서 매번 단계를 편집할 필요 없이 실행됩니다. 변수를 로컬에서는 /Users/jane/pics/jane-profile.png로, 러너에서는 /opt/runner/jane-profile.png로 지정하면, 단계 자체는 변경되지 않습니다.
명확히 언급할 가치가 있는 한 가지 전제 조건: 러너는 배포 시 -v 플래그로 마운트한 디렉터리 아래에 있는 호스트 파일만 접근합니다. 파일이 해당 마운트 아래에 없으면 어떤 경로로도 찾을 수 없습니다. 이것은 계획의 한계가 아니라 배포 설정 세부 사항입니다. Apidog 파일 업로드 요청 문서는 정식 버전을 원한다면 마운트 및 일괄 편집 단계를 자세히 설명합니다.
Apidog CLI로 워크플로 자동화
업로드 시나리오를 저장하면 CI에서 헤드리스로 실행할 수 있습니다. CLI를 설치하고 인증하세요.
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
그런 다음 환경을 지정하여 저장된 시나리오를 ID로 실행합니다.
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
여기서 -t는 테스트 시나리오 ID, -e는 환경 ID, -r은 리포터(여러 개를 사용하려면 cli, html, junit를 쉼표로 구분하여 사용)입니다. CLI는 클라우드 프로젝트에서 저장된 시나리오를 실행하고 종료 코드로 성공/실패를 보고하여 파이프라인을 제어할 수 있도록 합니다. 설정 세부 정보는 Apidog CLI 설치 가이드에 있습니다.
솔직한 주의사항 한 가지, 이것은 지난 섹션과 동일합니다. 파일 업로드 단계가 있는 시나리오는 CLI 머신에 파일이 존재해야 하며, 단계의 경로는 해당 파일을 가리켜야 합니다. 파일을 러너에 넣은 다음, 실행하기 전에 일괄 편집(Batch Edit)을 통해 경로를 지정하거나(또는 변수를 사용)해야 합니다. 그렇지 않으면 시나리오의 나머지 부분은 괜찮더라도 업로드 단계가 파일을 찾지 못해 실패합니다. 행별 입력 전달을 포함한 더 완전한 CI 설정은 Apidog CLI를 사용한 데이터 기반 테스트를 참조하세요.
자주 묻는 질문
동료가 내 파일 업로드 요청을 보낼 수 없는 이유는 무엇인가요? Apidog은 파일 자체가 아닌 로컬 파일 경로를 저장하며, 파일을 클라우드에 업로드하지 않습니다. 동료는 요청과 사용자가 선택한 경로를 볼 수 있지만, 그 경로는 그들의 디스크가 아닌 사용자 디스크에 있는 파일로 해석됩니다. 동료가 자신의 머신에 파일 사본을 넣고 필드가 자신의 경로를 가리키도록 해야 합니다. 예약된 테스트와 러너(Runner) 작업이 실행되는 곳에 파일이 준비되어 있어야 하는 이유도 같은 메커니즘으로 설명됩니다.
동일한 요청에서 파일과 함께 JSON을 보내려면 어떻게 해야 하나요? 본문 유형을 form-data로 유지합니다. 유형이 file인 파일 필드를 추가한 다음, 유형이 string인 다른 매개변수를 추가하고 JSON을 해당 값에 붙여넣습니다. 서버는 하나의 멀티파트 요청에서 두 부분을 모두 받습니다. 파일은 한 부분에, JSON 문자열은 다른 부분에 있습니다. 이것은 업로드에 메타데이터를 첨부하는 표준적인 방법입니다.
러너(Runner)에서 파일에 어떤 경로를 사용해야 하나요? 배포 시 -v 플래그로 러너의 볼륨에 마운트한 호스트 디렉터리 내부 경로를 사용합니다. 예를 들어 /opt/runner/yourfile.jpg입니다. 파일을 해당 마운트된 디렉터리에 복사한 다음, 단계를 열고 일괄 편집(Batch Edit)을 클릭하고 필드의 값을 해당 경로로 설정합니다. CLI의 경우 /opt/apidog/runner/yourfile.jpg와 유사합니다.
파일 크기 제한이나 허용되는 파일 유형 목록이 있나요? Apidog의 업로드 동작은 요청이 어떻게 구성되고 파일이 어디에서 읽히는지에 관한 것입니다. 크기 및 유형에 대한 실제 제한은 테스트 중인 API에서 비롯되므로, 서버 자체의 유효성 검사 규칙을 확인하고 과도하거나 거부된 파일에 대해 반환되는 응답에 대해 확인(assertion)을 작성하세요.
업로드 시 form-data 또는 x-www-form-urlencoded 중 무엇을 사용해야 하나요? form-data를 사용하세요. 이것은 multipart/form-data에 매핑되며 파일을 전송하기 위해 구축되었습니다. x-www-form-urlencoded는 파일이 없는 짧은 스칼라 필드의 간단한 양식에 사용되므로 이미지나 PDF를 전송할 수 없습니다.
마무리
파일 업로드 테스트는 두 가지로 요약됩니다. 멀티파트 요청을 올바르게 구축하는 것과, 테스트가 실행되는 모든 곳에서 파일에 접근할 수 있도록 하는 것입니다. Apidog에서는 본문(Body)을 form-data로 설정하고, 필드 유형을 file로 변경하고, 업로드(Upload)를 클릭하고, JSON을 문자열 부분으로 추가한 다음, 전송하고 확인(assert)합니다. 동일한 시나리오를 러너(Runner) 또는 CLI로 옮길 때는 해당 머신에 파일을 준비하고 일괄 편집(Batch Edit) 또는 변수를 사용하여 경로를 재지정하면 자동화된 실행이 로컬 실행과 동일하게 작동합니다.
자신의 엔드포인트에 대해 시도해보고 싶으신가요? Apidog을 다운로드하고, 업로드 라우트에 form-data 요청을 보낸 다음, 응답이 돌아오는 것을 확인하세요. 시작은 무료이며, 신용카드 정보가 필요 없습니다.