테스트 생성 (Open API)

이 섹션은 프로젝트 내 Test Suite 실행을 통해 테스트를 생성하는 방법을 설명합니다.
단일 Test Suite 실행 API와 복수 Test Suite 실행 API를 모두 다룹니다.

단일 Test Suite 실행 #

지정한 프로젝트에서 Test Suite 실행 요청을 보냅니다.

엔드포인트 #

[POST] /openapi/v3/projects/{pid}/test-suite-runs

인증 (Authorization) #

이 API를 호출하려면 username과 access_key를 조합한 Basic Auth 인증이 필요합니다.

key	type	required	default	description
auth	(username, access_key)	Y	–	암호화된 로그인 정보. API 호출 시 반드시 필요
username	str	Y	–	Ptero 로그인 ID
access_key	str	Y	–	Access Key (비밀번호 아님). 발급 위치: Ptero › 우측 상단 아이콘 › Edit Profile › Access Key

Note
username:access_key 문자열을 base64 인코딩하여 Authorization 헤더에 포함해야 합니다.

경로 파라미터 (Path Parameter) #

API 호출 시 반드시 프로젝트 ID를 경로에 포함해야 합니다.

key	type	required	default	description
pid	int	Y	–	프로젝트 아이디

요청 바디 (Body) #

Content-Type: multipart/form-data

테스트 실행 시 Test Suite와 앱 정보를 본문에 전달해야 합니다.

- test_suite_id: int
- device: str | None 
- os: "ANDROID" | "iOS"
- source_type: "app_id" | "file" | None
- app_file: bytes | None
- app_download_url: str | None
- app_id: str | None

key	type	required	default	description
test_suite_id	int	Y	–	실행할 Test Suite ID
device	str \| None	N	“random_device”	실행할 디바이스. “random_device”는 사용 가능한 디바이스 중 무작위 선택
os	“ANDROID” \| “iOS”	Y	–	기기의 OS 플랫폼. 대소문자 구분
source_type	“app_id” \| “file” \| None	N	–	프로젝트에 등록된 앱 ID 또는 파일 지정
app_file	bytes \| None	N	–	앱 파일. – Android: apk, apks, xapk – iOS: ipa 확장자만 허용
app_download_url	str \| None	N	–	앱 다운로드 URL (http://, https:// 필수)
app_id	str \| None	N	–	테스트 대상 앱의 APP ID. – Android: package name – iOS: bundle ID

제한 조건

source_type, app_file, app_download_url, app_id 중 1개만 전달 가능
2개 이상 전달하면 value error 발생

Request Curl 예시 #

프로젝트에 지정된 앱 실행 #

source_type, random_device

curl -X POST "https://api.apptest.ai/openapi/v3/projects/123/test-suite-runs" \
 -H "Authorization: Basic $(echo -n 'johndoe:1q2w3e4r' | base64)" \   # curl auth 기본 포맷, base64 인코딩 필수
 -F "test_suite_id=112233" \                                          # device 미입력 시 random_device 자동 적용
 -F "os=iOS" \                                                        # i는 소문자, OS는 대문자
 -F "source_type=app_id"                                              # 프로젝트에 일치하는 앱이 없으면 테스트 생성 실패

앱 파일 업로드 + 특정 디바이스 지정 #

app_file, target_device

curl -X POST "https://api.apptest.ai/openapi/v3/projects/123/test-suite-runs" \
 -H "Authorization: Basic $(echo -n 'johndoe:1q2w3e4r' | base64)" \   # curl auth 기본 포맷, base64 인코딩 필수
 -F "test_suite_id=112233" \
 -F "device=SAMSUNG GALAXY NOTE8 / ANDROID 9" \
 -F "os=ANDROID" \                                                    # 반드시 대문자
 -F "app_file=@/upload/your/file/path.apk"                            # 확장자: apk, apks, xapk, ipa

앱 ID + 랜덤 디바이스 지정 #

app_id, random_device

curl -X POST "https://api.apptest.ai/openapi/v3/projects/123/test-suite-runs" \
 -H "Authorization: Basic $(echo -n 'johndoe:1q2w3e4r' | base64)" \   # curl auth 기본 포맷, base64 인코딩 필수
 -F "test_suite_id=112233" \
 -F "device=random_device" \                                         # device 값을 전달하지 않아도 random_device로 지정됨
 -F "os=ANDROID" \                                                   # 반드시 대문자
 -F "app_id=com.android.chrome"

Output #

content-type: application/json

성공 응답 #

{
  "error_code": 0,
  "reason": "",
  "result": "success",
  "data": {
    "session_id": 123456,
    "test_suite_run_id": 789012,
    "test_run_count": 5
  }
}

session_id: 해당 테스트 실행 API 호출 식별자. 이후 진행 상태/결과 조회 시 사용
test_suite_run_id: Test Suite 실행 결과 식별자. Test Suite 단위 결과 조회 시 사용
test_run_count: 해당 Test Suite로 생성된 개별 test_run 개수

오류 응답 #

error_code	reason	설명
401	Could not verify your access level	가입되어 있지 않거나 잘못된 유저 정보
V001	Invalid value	잘못된 요청 값 (예: test_suite_id에 문자열 전달)
N001	Just one application is allowed	앱 지정 필드를 2개 이상 전달
V003	Invalid project ID	존재하지 않는 프로젝트
A002	Access denied for project	해당 프로젝트 접근 권한 없음
V008	Invalid test suite ID	존재하지 않는 Test Suite
M001	Invalid app file : System app file can not be tested	시스템 앱 파일 전달
M002	app file info extraction error	앱 파일 메타데이터 추출 실패
M003	invalid app file extension	지원하지 않는 앱 파일 확장자
A006	Too many tests in account	계정 테스트 생성 한도 초과 (data.allowed_test_creation_count 포함)
V004	Invalid scenario ID	존재하지 않는 시나리오 (data.invalid_scn_ids)
S006	Scenario file is Invalid or corrupted while getting test data	시나리오 파일 없음/손상 (data.not_exist_scns_file 제공)
M006	Device info does not exist	디바이스 정보 없음 또는 리스트 미조회
M007	Project settings app info is Empty	프로젝트에 source_type과 일치하는 앱이 없음
M008	Invalid app id	app_id가 비어있거나 100자 초과
A007	The service is currently under system maintenance.	서비스 점검 중
E0001	Internal Server Error	서버 내부 오류

예시 1: 인증 실패 #

잘못된 사용자 정보이거나 Access Key가 올바르지 않아 발생한 오류입니다.

{
  "response": "Could not verify your access level for that URL.",
  "status": 401,
  "headers": { "WWW-Authenticate": "Basic realm=\"Access key Required\"" }
}

예시 2: V001 오류 #

정수값(int)을 요구하는 test_suite_id 필드에 문자열을 전달했을 때 발생한 오류입니다.

{
  "data": [],
  "detail": {
    "errors": [
      {
        "input": "abc",
        "loc": ["test_suite_id"],
        "msg": "Input should be a valid integer, unable to parse string as an integer",
        "type": "int_parsing",
        "url": "https://errors.pydantic.dev/2.7/v/int_parsing"
      }
    ]
  },
  "errorCode": "V001",
  "error_code": "V001",
  "reason": "Invalid value",
  "result": "fail"
}

복수 Test Suite 실행 #

지정한 프로젝트에서 여러 Test Suite 실행 요청을 한 번에 보냅니다.

전달받은 test_suite_ids 배열에 포함된 순서대로 테스트를 생성합니다.
test_suite_ids를 생략하면, 프로젝트 내 모든 Test Suite을 이름 순으로 정렬해 실행합니다.

주의: test_suite_ids를 생략할 경우, 해당 프로젝트에 등록된 모든 Test Suite이 실행됩니다.

엔드포인트 #

[POST] /openapi/v3/projects/{pid}/multi-test-suite-runs

인증 (Authorization) #

이 API를 호출하려면 username과 access_key를 조합한 Basic Auth 인증이 필요합니다.

key	type	required	default	description
auth	(username, access_key)	Y	–	암호화된 로그인 정보. API 호출 시 반드시 필요
username	str	Y	–	Ptero 로그인 ID
access_key	str	Y	–	Access Key (비밀번호 아님) 발급 위치: Ptero › 우측 상단 아이콘 › Edit Profile › Access Key

Note
username:access_key 문자열을 base64 인코딩하여 Authorization 헤더에 포함해야 합니다.

경로 파라미터 (Path Parameter) #

API 호출 시 반드시 프로젝트 ID를 경로에 포함해야 합니다.

key	type	required	default	description
pid	int	Y	–	프로젝트 아이디

요청 바디 (Body) #

Content-Type: multipart/form-data

테스트 실행 시 Test Suite와 앱 정보를 본문에 전달해야 합니다.

- test_suite_id: int
- device: str | None
- os: "ANDROID" | "iOS"
- source_type: "app_id" | "file" | None
- app_file: bytes | None
- app_download_url: str | None
- app_id: str | None

key	type	required	default	description
test_suite_ids	list[int]	N	–	실행할 Test Suite ID 목록. 배열 순서대로 실행됨. 생략 시 프로젝트 내 모든 Test Suite을 이름 순으로 정렬해 실행
device	str \| None	N	“random_device”	실행할 디바이스. 미지정 시 사용 가능한 디바이스 중 무작위 선택
os	“ANDROID” \| “iOS”	Y	–	디바이스 OS 플랫폼. 대소문자 구분
source_type	“app_id” \| “file” \| None	N	–	프로젝트에 등록된 앱 ID 또는 파일 지정
app_file	bytes \| None	N	–	앱 파일 – Android: apk, apks, xapk – iOS: ipa 확장자만 허용
app_download_url	str \| None	N	–	앱 다운로드 URL. http://, https:// 필수
app_id	str \| None	N	–	테스트 대상 앱의 APP ID. – Android: package name – iOS: bundle ID

제한 조건

app_id, app_file, app_download_url, source_type 중 1개만 전달 가능
2개 이상 전달 시 value error 발생

Request Curl 예시 #

모든 Test Suite 실행 #

test_suite_ids 미전달, source_type, random_device

curl -X POST "https://api.apptest.ai/openapi/v3/projects/123/multi-test-suite-runs" \
 -H "Authorization: Basic $(echo -n 'johndoe:1q2w3e4r' | base64)" \   # curl auth 기본 포맷, base64 반드시 포함
 -F "os=iOS" \                                                        # i는 소문자, OS는 대문자
 -F "source_type=app_id"                                              # 프로젝트에 os, source_type과 일치하는 앱이 없으면 테스트 생성 실패

test_suite_ids 미전달 시: 프로젝트 내의 모든 Test Suite을 이름 순으로 실행
device 미전달 시: 자동으로 random_device 지정

지정한 Test Suite 배열 실행 #

test_suite_ids 전달, app_file, target_device

curl -X POST "https://api.apptest.ai/openapi/v3/projects/123/multi-test-suite-runs" \
 -H "Authorization: Basic $(echo -n 'johndoe:1q2w3e4r' | base64)" \   # curl auth 기본 포맷, base64 인코딩 필수
 -F "test_suite_ids=[112233, 445566, 778899]" \
 -F "device=SAMSUNG GALAXY NOTE8 / ANDROID 9" \
 -F "os=ANDROID" \                                                    # 반드시 대문자
 -F "app_file=@/upload/your/file/path.apk"                            # 확장자: apk, apks, xapk, ipa

test_suite_ids 전달 시: 배열에 지정된 순서대로 테스트 실행
device 지정 시: 해당 디바이스에서 실행
app_file 사용 시: 업로드한 앱 파일 기반으로 실행

모든 Test Suite 실행 #

test_suite_ids 미전달, app_id, random_device

curl -X POST "https://api.apptest.ai/openapi/v3/projects/123/multi-test-suite-runs" \
 -H "Authorization: Basic $(echo -n 'johndoe:1q2w3e4r' | base64)" \   # curl auth 기본 포맷, base64 인코딩 필수
 -F "device=random_device" \                                         # device 미지정 시 자동으로 random_device 적용
 -F "os=ANDROID" \                                                   # 반드시 대문자
 -F "app_id=com.android.chrome"

test_suite_ids 미전달 시: 프로젝트 내의 모든 Test Suite을 이름 순으로 실행
device=random_device: 무작위 사용 가능한 디바이스에서 실행
app_id: 프로젝트에 등록된 앱 ID 기반 실행

Output #

content-type: application/json

성공 응답 #

{
  "error_code": 0,
  "reason": "",
  "result": "success",
  "data": {
    "session_id": 123456,
    "test_suite_runs": [
      {
        "test_suite_run_id": 11111,
        "test_run_count": 5
      },
      {
        "test_suite_run_id": 22222,
        "test_run_count": 3
      }
    ],
    "total_test_run_count": 8
  }
}

session_id: 테스트 실행 API 호출 식별자. 이후 실행 상태/결과 조회 시 사용
test_suite_runs: 각 Test Suite 실행 결과 목록. test_suite_run_id와 test_run_count를 포함
total_test_run_count: 전체 실행 요청으로 생성된 test_run 총 개수

Note
session_id는 복수 Test Suite 실행 결과를 식별하기 위한 값입니다.
자세한 내용은 [API 문서 > 테스트 결과 조회 (Open API)] 를 참고해 주세요.

오류 응답 #

error_code	reason	description
401	Could not verify your access level	가입되어 있지 않거나 잘못된 유저 정보
V001	Invalid value	잘못된 요청 값 (예: test_suite_ids에 문자열 전달)
V003	Invalid project ID	존재하지 않는 프로젝트
A002	Access denied for project	프로젝트 접근 권한 없음
C007	test suite does not exist in project	해당 프로젝트에 Test Suite이 하나도 존재하지 않음
M001	Invalid app file : System app file can not be tested	시스템 앱 파일 전달
M002	app file info extraction error	앱 파일 메타데이터 추출 실패
M003	invalid app file extension	지원하지 않는 앱 파일 확장자
A006	Too many tests in account	계정 테스트 생성 한도 초과 (data.allowed_test_creation_count 포함)
V004	Invalid scenario ID	존재하지 않는 시나리오 (data.invalid_scn_ids)
S006	Scenario file is Invalid or corrupted while getting test data	시나리오 파일 없음/손상 (data.not_exist_scns_file 제공)
M006	Device info does not exist	디바이스 정보 없음 또는 리스트 미조회
M007	Project settings app info is Empty	프로젝트에 source_type과 일치하는 앱이 없음
M008	Invalid app id	app_id가 비어있거나 100자 초과
A007	The service is currently under system maintenance.	서비스 점검 중
E0001	Internal Server Error	서버 내부 오류

오류 응답 형식은 단일 Test Suite 실행 API의 오류 응답 예시를 참고해 주세요.

Updated on 2025/09/19

Overview

Getting Started

Ptero 사용 가이드

Stego 사용 가이드

시나리오 파일 관리

API 문서

추가 활용 가이드

테스트 생성 (Open API)

단일 Test Suite 실행 #

엔드포인트 #

인증 (Authorization) #

경로 파라미터 (Path Parameter) #

요청 바디 (Body) #

Request Curl 예시 #

프로젝트에 지정된 앱 실행 #

앱 파일 업로드 + 특정 디바이스 지정 #

앱 ID + 랜덤 디바이스 지정 #

Output #

성공 응답 #

오류 응답 #

예시 1: 인증 실패 #

예시 2: V001 오류 #

복수 Test Suite 실행 #

엔드포인트 #

인증 (Authorization) #

경로 파라미터 (Path Parameter) #

요청 바디 (Body) #

Request Curl 예시 #

모든 Test Suite 실행 #

지정한 Test Suite 배열 실행 #

모든 Test Suite 실행 #

Output #

성공 응답 #

오류 응답 #