> For the complete documentation index, see [llms.txt](https://developers-apps-in-toss.toss.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers-apps-in-toss.toss.im/guide/operation/toss.md).

# 미니앱 테스트하기

앱 번들(.ait) 파일을 업로드하고 생성된 테스트용 앱스킴으로 토스 앱에서 최종 테스트를 할 수 있어요.

### 콘솔에서 테스트하기

콘솔에서 테스트하는 방법은 [가이드](https://developers-apps-in-toss.toss.im/guide/operation/console-workspace#undefined-10)를 참고해주세요.

### CI/CD 명령어 사용하기

콘솔에 접속하지 않고 CLI로 앱 번들을 업로드할 수 있어요.

CI/CD 명령어로 자동 업로드하려면 SDK v1.4.0 이상이 필요해요. 이전 버전을 쓰고 있다면 먼저 SDK를 업그레이드해 주세요.

먼저 콘솔에서 API 키를 발급해 주세요. 전체 앱 또는 특정 앱 단위로 접근 권한을 설정할 수 있어요.

> 접속 경로: 워크스페이스 선택 → 왼쪽 메뉴에서 '키'

<figure><img src="https://3177177630-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8pQgXiR5QAzduV54W8Om%2Fuploads%2FTRGlSNFN10sqdcSQ4APK%2F%E1%84%8F%E1%85%B5%2065.png?alt=media&#x26;token=4683c816-1797-43e2-aafb-6a303e0a5b6f" alt=""><figcaption></figcaption></figure>

<figure><img src="https://3177177630-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8pQgXiR5QAzduV54W8Om%2Fuploads%2FjOJeYrLClNjd8ioFdl20%2Fimage.png?alt=media&#x26;token=51ed417b-f10d-41ae-b047-8e3ca33c54ef" alt=""><figcaption></figcaption></figure>

아래 명령어를 실행해 앱 번들을 업로드하세요. 정상적으로 업로드되면 테스트용 앱스킴을 확인할 수 있어요.

```
npx ait deploy --api-key {API 키}
```

API 키를 등록해 두면 반복해서 입력하지 않아도 돼요.

```
npx ait token add
npx ait deploy
```

`-m` 옵션으로 번들을 업로드할 때 메모를 함께 남길 수 있어요.

```
npx ait deploy -m "출시메모"
```

필요에 따라 아래 명령어를 사용해 보세요.

| 명령어                                               | 용도                                      |
| ------------------------------------------------- | --------------------------------------- |
| npx ait token --help                              | 도움말 보기                                  |
| npx ait token add \[워크스페이스명] \[API 키]             | 토큰 등록하기                                 |
| npx ait token remove \[워크스페이스명]                   | 등록된 토큰 삭제하기                             |
| npx ait deploy \[워크스페이스명] \[API 키]                | 번들 업로드하기                                |
| npx ait deploy \[워크스페이스명] \[API 키] --timeout \[초] | 배포 상태 확인 최대 대기 시간 설정하기 (10초 이상 300초 이하) |

***

### 기능 테스트하기

`intoss://` 스킴은 앱이 정식 출시된 뒤에만 접근할 수 있어요. 출시 전 기능 테스트는 업로드할 때 생성된 테스트 스킴(QR 코드)으로 해야 해요.

#### QR 코드에서 deploymentId 확인하기

앱 번들을 업로드할 때마다 새로운 `deploymentId`가 발급돼요. 테스트 스킴에서 `_deploymentId`는 필수 파라미터예요.

```
intoss-private://appsintoss?_deploymentId=0198c000-68c3-7d2b-0000-2c00000005ec
```

#### 스킴에 path·query 적용해 테스트하기

하위 path를 적용한 경우:

```
intoss-private://appsintoss/path/pathpath?_deploymentId=0198c000-68c3-7d2b-0000-2c00000005ec
```

쿼리 파라미터를 적용한 경우 (queryParams는 반드시 URL 인코딩해야 해요):

```
intoss-private://appsintoss?_deploymentId=0198c000-68c3-7d2b-0000-2c00000005ec&queryParams=%7B%22categoryKey%22%3A%22
```

***

### 웹 디버그 툴즈로 문제 확인하기 <a href="#debug" id="debug"></a>

로컬 브라우저나 샌드박스 앱에서 정상 동작했더라도, 토스 앱 환경에서는 문제가 발생할 수 있어요.\
웹 디버그 툴즈를 사용하면 실제 토스 앱에서 실행 중인 미니앱의 로그, 네트워크 요청, 페이지 구조를 확인할 수 있어요.

웹 디버그 툴즈는 앱 번들을 업로드한 뒤 QR 코드나 테스트 스킴(`intoss-private://`)으로 실행한 미니앱에서 사용할 수 있어요.

<figure><img src="https://3177177630-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8pQgXiR5QAzduV54W8Om%2Fuploads%2F1xOLhIktlPHeGBasADz3%2Fimage.png?alt=media&#x26;token=41dc25d5-4cc0-4eee-9fe7-63f873943118" alt="" width="563"><figcaption></figcaption></figure>

#### 왜 필요한가요?

토스 앱 WebView는 로컬 브라우저나 샌드박스 앱과 실행 환경이 달라요.\
그래서 로컬에서는 발견하기 어려운 문제를 토스 앱 테스트 환경에서 직접 확인해야 할 때가 있어요.

예를 들어 아래와 같은 상황에서 웹 디버그 툴즈를 사용할 수 있어요.

* 토스 앱에서만 흰 화면이 보여요.
* API 요청이 실패하거나 응답을 확인하기 어려워요.
* 특정 기기에서 화면이 다르게 보여요.
* 개발 중 남긴 `console.log` 값을 실제 테스트 환경에서 확인하고 싶어요.

#### 사용 방법

확인하고 싶은 값이나 실행 흐름이 있다면 먼저 코드에 로그를 남겨 주세요.

```js
console.log('userId', userId);
console.warn('retry request', retryCount);
console.error('payment failed', error);
```

로그를 추가한 뒤 앱 번들을 다시 생성하고 콘솔에 업로드하세요. \
업로드가 끝나면 QR 코드나 테스트 스킴(`intoss-private://`)으로 토스 앱에서 미니앱을 실행해 주세요.

미니앱 화면 오른쪽 위 내비게이션바에서 더보기 버튼을 누르고 **웹 디버그 툴즈**를 선택하세요. \
웹 디버그 툴즈가 열리면 `Log` 탭에서 콘솔 로그를 확인할 수 있어요. API 요청과 응답을 확인하려면 `Network` 탭을 확인해 주세요.

<figure><img src="https://3177177630-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8pQgXiR5QAzduV54W8Om%2Fuploads%2F7XevqP8EBZphEK5vlYL2%2Fimage.png?alt=media&#x26;token=71014182-b5f6-4760-86b7-9cc30ee1ae8b" alt="" width="563"><figcaption></figcaption></figure>

#### 확인할 수 있는 정보

| 탭       | 확인할 수 있는 정보                                            |
| ------- | ------------------------------------------------------ |
| Log     | `console.log`, `console.warn`, `console.error`로 출력한 로그 |
| System  | WebView 실행 환경 정보                                       |
| Network | API 요청과 응답, 실패한 네트워크 요청                                |
| Element | 화면의 페이지 구조                                             |

***

### 자주 묻는 질문

<details>

<summary>iOS에서 흰 화면이 보여요.</summary>

샌드박스에서는 정상 동작하는데 토스 앱에서 흰 화면이 보인다면, 아래 항목을 순서대로 점검해 보세요.

1. **Sentry로 오류 감지·모니터링하기** — 런타임 에러가 났는데 바로 확인되지 않는 경우가 있어요. Sentry로 에러를 수집해서, 실제 사용자 환경에서 생기는 오류를 추적해 보세요. [Sentry 설정 가이드](https://developers-apps-in-toss.toss.im/ai-vibe-coding/integration/sentry#id-1.-sentry)
2. **메모리·리소스 사용량 점검하기** — 토스 앱에서는 메모리 제약 때문에 앱이 제대로 렌더링되지 못하고 흰 화면이 보일 수 있어요.
   * 이미지·폰트 등 리소스 용량을 줄여 빌드 파일을 최적화하세요.
   * 분할 로딩 구조를 적용해, 처음에는 꼭 필요한 파일만 불러오고 나머지 리소스는 순차적으로 불러오도록 구성해 보세요.
   * 불필요한 객체 생성이나 메모리 누수가 없는지 점검하세요.

</details>

<details>

<summary>토스 앱에서 통신이 되지 않아요.</summary>

* **CORS 설정 확인** — 미니앱에서 서버와 통신하려면, 서버의 CORS 허용 Origin에 미니앱 Origin을 추가해야 해요. 허용해야 하는 Origin은 SDK 버전과 적용일에 따라 달라요.

{% hint style="info" %}
**SDK 3.x Origin 변경 안내**

SDK 3.1.1 번들부터, SDK 2.x에서 사용하던 Origin으로 서비스돼요.\
외부 서버와 통신하는 경우, 서버의 CORS 허용 Origin에 아래 Origin을 추가해 주세요.

* `https://<appName>.apps.tossmini.com` : 실제 서비스 환경
* `https://<appName>.private-apps.tossmini.com` : 콘솔 QR 테스트 환경
  {% endhint %}

SDK 3.0.0 \~ 3.1.1 미만

* `https://<appName>.web.tossmini.com` : 실제 서비스 환경
* `https://<appName>.private-web.tossmini.com` : 콘솔 QR 테스트 환경

\
SDK 1.x \~ 2.x

* `https://<appName>.apps.tossmini.com` : 실제 서비스 환경
* `https://<appName>.private-apps.tossmini.com` : 콘솔 QR 테스트 환경
* **App Transport Security(ATS) 설정 확인** — 샌드박스에서는 HTTP 요청이 허용되지만, 라이브 환경에서는 HTTPS만 허용돼요. HTTP 기반 API는 토스 앱에서 차단돼요.
* **iOS 서드파티 쿠키 차단 정책 확인** — iOS·iPadOS 13.4 이상에서는 서드파티 쿠키가 완전히 차단돼요. 쿠키 기반 로그인 대신 토큰 기반 인증 방식을 적용하세요.

</details>

<details>

<summary>토스앱에서 미니앱이 열리지 않아요.</summary>

토스앱 하위 버전에서 오류가 발생할 수 있어요 최신 버전의 토스앱에서 테스트를 진행해 주세요.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers-apps-in-toss.toss.im/guide/operation/toss.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.