> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Playtest

> XBOX 게임의 플레이테스트를 나열, 가져오기, 비교, 생성, 업데이트, 게시 및 삭제합니다.

플레이테스트를 사용하면 선택한 플레이어 그룹이 출시 전에 게임을 체험해 볼 수 있습니다. `playtest`
명령은 Partner Center에서 게임의 플레이테스트를 읽고, 생성, 업데이트, 게시 및 삭제합니다.
`create`, `update`, `publish`, `delete`는 변경하기 전에 묻습니다.

`create`, `update`, `publish`, `delete`는 실험적 기능입니다. 옵션과 출력이 변경되거나
제거될 수 있습니다. [실험적 명령](https://docs.xbox.com/ko/tools/xbox-cli/cli-command-lifecycle.md)을 참조하세요.

## 명령

| 명령 | 설명 |
| - | - |
| `playtest list` | 게임의 플레이테스트를 나열합니다. |
| `playtest get <playtest-id>` | 플레이테스트 하나의 세부 정보, 패키지, 이미지, 대상 그룹, `etag`를 가져옵니다. |
| `playtest diff <playtest-id>` | 플레이테스트를 마지막으로 게시된 버전 또는 다른 플레이테스트와 비교합니다. |
| `playtest create` | 비공개 초안 플레이테스트를 생성합니다(실험적). |
| `playtest update <playtest-id>` | 플레이테스트를 변경합니다. 게시된 플레이테스트는 초안으로 돌아갑니다(실험적). |
| `playtest publish <playtest-id>` | 플레이테스트를 게시하여 시작 날짜부터 대상 그룹에 제공하고, 예약되거나 라이브가 될 때까지 기다립니다(실험적). |
| `playtest delete <playtest-id>` | 플레이테스트를 삭제하고, 삭제될 때까지 기다립니다(실험적). |

## 인수 및 옵션

| 인수 또는 옵션 | 적용 대상 | 필수 | 설명 |
| - | - | - | - |
| `<playtest-id>` | `get`, `diff`, `update`, `publish`, `delete` | 예 | `list`에서 얻은 `playtestId`이며, 예를 들면 `11111111-2222-3333-4444-555555555555`입니다. |
| `--store-id <id>` | 모두 | 둘 중 하나 | 게임의 Store ID이며, 예를 들면 `9N0000000000`입니다. |
| `--xbox-title-id <id>` | 모두 | 둘 중 하나 | 게임의 PlayFab 타이틀 ID가 아닌 XBOX 타이틀 ID이며, 예를 들면 `1234ABCD`입니다. 일치하는 게임이 없거나 여러 개이면 오류에 대신 전달할 Store ID가 나열됩니다. |
| `--compare-to <playtest-id>` | `diff` | 아니요 | 마지막으로 게시된 버전 대신 비교할 다른 플레이테스트입니다. |
| `--name <name>` | `create`, `update` | `create` | 플레이어에게 표시되는 플레이테스트 이름입니다. 비워 둘 수 없습니다. |
| `--description <text>` | `create`, `update` | 아니요 | 짧은 설명입니다. `update`에서 `""`를 지정하면 지워집니다. |
| `--long-description <text>` | `create`, `update` | 아니요 | 긴 설명입니다. `update`에서 `""`를 지정하면 지워집니다. |
| `--start <date>` | `create`, `update` | `create` | 플레이테스트가 시작되는 시점입니다. [날짜](#dates)를 참조하세요. |
| `--end <date>` | `create`, `update` | `create` | 플레이테스트가 끝나는 시점입니다. `--start` 이후여야 합니다. |
| `--audience-id <id>` | `create`, `update` | 아니요 | 참여할 수 있는 대상 그룹이며 [`audience list`](https://docs.xbox.com/ko/tools/xbox-cli/commands/audience)에서 얻습니다. 더 추가하려면 반복합니다. [대상 그룹 선택](#choosing-audiences)을 참조하세요. |
| `--pc-package-id <id>` | `create`, `update` | 아니요 | 플레이어가 받는 PC 패키지입니다. [패키지](#packages)를 참조하세요. |
| `--console-package-id <id>` | `create`, `update` | 아니요 | 플레이어가 받는 콘솔 패키지입니다. [패키지](#packages)를 참조하세요. |
| `--idempotency-key <key>` | `create` | 아니요 | 새 GUID 대신 사용할 1\~50자의 인쇄 가능한 ASCII 문자입니다. [플레이테스트 생성](#creating-a-playtest)을 참조하세요. |
| `--if-match <etag>` | `update` | 아니요 | 플레이테스트에 `playtest get`에서 얻은 이 `etag`가 여전히 있는 경우에만 업데이트합니다. [플레이테스트 업데이트](#updating-a-playtest)를 참조하세요. |
| `--no-wait` | `publish`, `delete` | 아니요 | 게시 또는 삭제가 큐에 추가되는 즉시 반환합니다. `--timeout`과 함께 사용할 수 없습니다. |
| `--timeout <duration>` | `publish`, `delete` | 아니요 | 기다릴 시간이며 `90s`, `10m`, `2h`처럼 지정합니다. 기본값은 `5m`이고 최대 `7d`입니다. |
| `--confirm` (`--yes`, `-y`) | `create`, `update`, `publish`, `delete` | 아니요 | 확인 프롬프트를 건너뜁니다. 이 옵션이 없고 터미널도 없으면 명령은 변경을 거부합니다. |
| `--seller-id <id>` | 모두 | 저장되지 않은 경우 | Partner Center 판매자 ID입니다. [컨텍스트](https://docs.xbox.com/ko/tools/xbox-cli/commands/context.md)를 참조하세요. |
| `--base-url <url>` | 모두 | 아니요 | 요청의 기본 URL이며, `XboxPartner:BaseUrl` 구성 키를 재정의합니다. |
| `--output <format>` | 모두 | 아니요 | `json`(기본값), `json-compact` 또는 `table`. `create`, `update`, `publish`, `delete`는 `table`을 거부합니다. |

## 예제

플레이테스트를 나열하고, 하나를 가져오고, 두 플레이테스트를 비교합니다.

```bash theme={null}
xbox playtest list --store-id 9N0000000000
xbox playtest list --xbox-title-id 1234ABCD --output table
xbox playtest get 11111111-2222-3333-4444-555555555555 --store-id 9N0000000000
xbox playtest diff 11111111-2222-3333-4444-555555555555 --store-id 9N0000000000 --compare-to 22222222-3333-4444-5555-666666666666 --output table
```

대상 그룹에 대한 플레이테스트를 생성합니다.

```bash theme={null}
xbox playtest create --store-id 9N0000000000 --name "Nod Arena alpha" --start 2026-11-01 --end 2026-11-15 --audience-id 1152921504606846976
```

플레이테스트의 종료 날짜를 변경합니다.

```bash theme={null}
xbox playtest update 11111111-2222-3333-4444-555555555555 --store-id 9N0000000000 --end 2026-11-30
```

플레이테스트를 게시합니다.

```bash theme={null}
xbox playtest publish 11111111-2222-3333-4444-555555555555 --store-id 9N0000000000
```

플레이테스트를 삭제합니다.

```bash theme={null}
xbox playtest delete 11111111-2222-3333-4444-555555555555 --store-id 9N0000000000
```

## 플레이테스트 읽기

`playtest list`는 `playtests` 배열을 씁니다. 테이블에는 `PLAYTEST ID`, `NAME`, `STATUS`,
`TYPE`, `START`, `END` 열이 있습니다. 일부 발췌:

```json theme={null}
{ "playtests": [ { "playtestId": "11111111-2222-3333-4444-555555555555", "name": "Alpha", "status": "Live", "type": "Private" } ] }
```

`playtest get`은 서비스가 반환한 그대로 플레이테스트를 씁니다. `etag`는
`update --if-match`에 전달할 버전이고, `audiences.audienceIds`는 참여할 수 있는 대상 그룹을
나열합니다. 테이블에는 `FIELD` 및 `VALUE` 행이 있습니다.

`playtest diff`는 `hasDiffData`, `current`, `compared`를 씁니다. `hasDiffData`가 `false`이면
비교할 것이 없으며 `compared`는 생략됩니다. 테이블에는 다른 필드만 `FIELD`, `CURRENT`,
`COMPARED` 열로 표시됩니다. 이미지는 비교하지 않습니다.

## 플레이테스트 생성

```bash theme={null}
xbox playtest create --store-id 9N0000000000 --name "Nod Arena alpha" --start 2026-11-01 --end 2026-11-15
```

`playtest create`는 비공개 초안 플레이테스트를 만들고 `playtest get`과 같은 방식으로 씁니다.
다시 실행하면 플레이테스트가 하나 더 생성됩니다. 원하지 않는 플레이테스트는
[`playtest delete`](#deleting-a-playtest)로 제거하세요.

각 생성 요청은 멱등성 키를 보내며, `--idempotency-key`를 전달하지 않으면 새 GUID를 사용합니다.
키를 반복하는 생성 요청은 그 키로 생성된 플레이테스트를 반환하며, 다른 옵션이 달라도
무시합니다.

시간 초과 후처럼 결과를 알 수 없으면 명령은 `3`으로 종료하고, 같은 키로 다시 시도하는 명령을
출력합니다.

```bash theme={null}
xbox playtest create --store-id 9N0000000000 --name "Nod Arena alpha" --start 2026-11-01 --end 2026-11-15 --idempotency-key 11111111-2222-3333-4444-555555555555
```

다시 시도하면 첫 번째 요청이 플레이테스트를 생성한 경우 그 플레이테스트를 반환하고, 그렇지
않으면 생성합니다. 옵션에 줄 바꿈이 있으면 키만 출력되므로, 같은 명령을
`--idempotency-key`와 그 키로 실행하세요. 종료 날짜가 지났다는 등의 이유로 다시 시도가
거부되면, 새 키로 플레이테스트를 생성하기 전에 `playtest list`를 확인하세요.

## 패키지

플레이테스트에는 PC 패키지 하나와 콘솔 패키지 하나를 포함할 수 있습니다.
[`xbox package list`](https://docs.xbox.com/ko/tools/xbox-cli/commands/package#listing-packages)에서 플레이테스트에 사용할 준비가 된 패키지를 선택하고,
해당 플랫폼의 옵션에 그 `id`를 전달하세요.

```bash theme={null}
xbox playtest create --store-id 9N0000000000 --name "Nod Arena alpha" --start 2026-11-01 --end 2026-11-15 --pc-package-id 11111111-2222-3333-4444-555555555555
```

`update`에서 생략한 패키지 옵션은 기존 패키지를 유지하고, 새 ID는 패키지를 대체하며, `""`는
패키지를 제거합니다.

```bash theme={null}
xbox playtest update 11111111-2222-3333-4444-555555555555 --store-id 9N0000000000 --pc-package-id 22222222-3333-4444-5555-666666666666 --console-package-id ""
```

## 플레이테스트 업데이트

> [!WARNING]
>
> Partner Center에서 편집할 때와 마찬가지로, 업데이트하면 게시된 플레이테스트가 초안으로
> 돌아갑니다. 플레이어가 사용할 수 있게 하려면 `playtest publish`로 다시 게시하세요.

```bash theme={null}
xbox playtest update 11111111-2222-3333-4444-555555555555 --store-id 9N0000000000 --end 2026-11-30
```

`playtest update`는 전달한 옵션만 변경하며, 옵션이 하나 이상 필요합니다. 업데이트된
플레이테스트를 `playtest get`과 같은 방식으로 씁니다. Partner Center에서 구성한 게임 아트는
유지되며, 플레이테스트에 연결된 그 밖의 아트는 자리 표시자로 대체됩니다.

다른 사람의 변경 내용을 덮어쓰지 않으려면 `playtest get`에서 얻은 `etag`를 `--if-match`에
전달하세요. 값을 감싸는 큰따옴표는 선택 사항이며, `*`, 약한(`W/`) etag, etag 목록은
거부됩니다.

```bash theme={null}
xbox playtest update 11111111-2222-3333-4444-555555555555 --store-id 9N0000000000 --end 2026-11-30 --if-match 0x8DD1234ABCD5678
```

결과를 알 수 없으면 명령은 `3`으로 종료합니다. 다시 시도하기 전에 `playtest get`으로
플레이테스트를 확인하세요.

## 대상 그룹 선택

대상 그룹은 판매자가 Partner Center에서 관리하는 테스터 같은 플레이어 그룹입니다.
[`audience list`](https://docs.xbox.com/ko/tools/xbox-cli/commands/audience)에서 얻은 `id`를 `--audience-id`에 전달하고, 더 추가하려면 반복하세요.

```bash theme={null}
xbox playtest create --store-id 9N0000000000 --name "Nod Arena alpha" --start 2026-11-01 --end 2026-11-15 --audience-id 1152921504606846976 --audience-id 1152921504606846977
```

`--audience-id`가 없으면 `create`는 대상 그룹이 없는 플레이테스트를 만들고, `update`는 기존
대상 그룹을 유지합니다. `update`에서는 전달한 ID가 플레이테스트의 모든 대상 그룹을
대체합니다. 모든 대상 그룹을 제거하려면 `""`만 전달하세요.

```bash theme={null}
xbox playtest update 11111111-2222-3333-4444-555555555555 --store-id 9N0000000000 --audience-id ""
```

`""`는 대상 그룹 ID와 함께 사용할 수 없으며, `create`는 이를 거부합니다. 플레이테스트를
게시하려면 대상 그룹이 하나 이상 있어야 합니다.

## 플레이테스트 게시

게임이 XBOX 서비스를 사용하는 경우 게시하기 전에 해당 구성과 엠바고를 설정하세요.
[플레이테스트에서 XBOX 서비스 사용](https://docs.xbox.com/ko/tools/xbox-cli/xbox-services-in-a-playtest.md)을 참조하세요.

```bash theme={null}
xbox playtest publish 11111111-2222-3333-4444-555555555555 --store-id 9N0000000000
```

게시하면 시작 날짜부터 대상 그룹에 플레이테스트가 제공됩니다. 명령은 처음 읽은 버전을
게시하며, 그사이에 플레이테스트가 변경되면 게시가 `412`로 실패하고 아무것도 변경되지 않습니다.

확인을 요청하기 전에 명령은 엠바고 날짜가 플레이테스트 종료 날짜 이후인지와 같은 게임의
XBOX 서비스 설정을 검사하고, 검토할 항목을 stderr에 나열합니다. 이 검사는 권고일 뿐이며,
`--confirm`을 사용하면 묻지 않고 게시합니다.

그런 다음 서비스가 자체 검사를 실행합니다. 검사 중 하나가 게시를 차단하면 아무것도 큐에
추가되지 않으며, 명령은 각 검사를 stderr에 나열하고 `1`로 종료합니다. 오류를 수정하고 다시
게시하세요. 연령 등급 누락으로 차단된 플레이테스트는 Partner Center에서 연령 등급 설문을
완료해야 합니다.

게시가 큐에 추가되면 명령은 플레이테스트가 `Scheduled`, `Live` 또는 `PublishFailed`가 될
때까지 기다린 다음 `playtest get`과 같은 방식으로 씁니다. Ctrl+C를 누르면 대기는 멈추지만
게시는 계속됩니다. `--no-wait`를 사용하면 게시가 큐에 추가되는 즉시 `publishJobId`와
`warnings`(있는 경우)를 씁니다. 이후 `playtest get`으로 추적하세요.

| 종료 코드 | 의미 |
| - | - |
| `0` | 플레이테스트가 `Scheduled` 또는 `Live`입니다. `--no-wait`를 사용한 경우 게시가 큐에 추가되었습니다. |
| `1` | 검사에 의해 차단되었거나 플레이테스트가 변경되는 등의 이유로 게시되지 않았습니다. |
| `2` | 게시가 실패했습니다. 플레이테스트가 `PublishFailed`입니다. |
| `3` | 요청이 전송되었지만 결과를 알 수 없습니다. 다시 게시하기 전에 `playtest get`으로 플레이테스트를 확인하세요. |
| `4` | 게시가 큐에 추가되었지만 완료되기 전에 대기가 끝났습니다. `playtest get`으로 확인하세요. |

## 플레이테스트 삭제

```bash theme={null}
xbox playtest delete 11111111-2222-3333-4444-555555555555 --store-id 9N0000000000
```

`playtest delete`는 처음 읽은 버전의 플레이테스트를 삭제합니다. 플레이테스트가 `Deleted`가
되거나 없어질 때까지 기다린 다음, `status`가 포함된 서비스의 응답을 씁니다. Ctrl+C를 누르면
대기는 멈추지만 삭제는 계속됩니다. `--no-wait`를 사용하면 삭제가 큐에 추가되는 즉시 응답을
씁니다. `412` 후에는 삭제가 이미 큐에 추가되었을 수 있으므로, 1분 정도 기다렸다가 다시
삭제하기 전에 `playtest get`으로 확인하세요.

| 종료 코드 | 의미 |
| - | - |
| `0` | 삭제되었습니다. `--no-wait`를 사용한 경우 삭제가 큐에 추가되었습니다. |
| `1` | 플레이테스트가 변경되었거나 상태가 삭제를 허용하지 않는 등의 이유로 삭제되지 않았습니다. |
| `3` | 요청이 전송되었지만 결과를 알 수 없습니다. 다시 삭제하기 전에 `playtest get`으로 플레이테스트를 확인하세요. |
| `4` | 삭제가 큐에 추가되었지만 대기가 끝나기 전에 플레이테스트가 `Deleted`가 되지 않았습니다. `playtest get`으로 확인하세요. |

## 날짜

`--start`와 `--end`는 `2026-11-01T09:00:00-07:00` 또는 `2026-11-01T16:00:00Z`와 같은
ISO 8601 날짜 및 시간을 허용합니다. 시간이 없는 날짜는 UTC 자정을 의미하고, 오프셋이 없는
시간은 UTC입니다. 업데이트에서 날짜를 하나만 전달하면 서비스가 그 날짜를 플레이테스트의
다른 날짜와 비교하여 검사합니다.

## 오류

위의 종료 코드 표에서 달리 명시하지 않는 한, 실패는 stderr로 출력되고 `1`로 종료합니다.
`create`와 `update`는 결과를 알 수 없으면 `3`으로 종료합니다. 서비스가 반환하는 실패에는 HTTP
상태가 포함되며, `--verbose`를 사용하면 서비스의 응답이 추가됩니다. 응답의 `code` 필드는
다음과 같습니다.

| 상태 | `code` | 의미 |
| - | - | - |
| 400 | `invalid_playtest_request` | `create` 또는 `update`가 종료 시점이 시작 시점 이후가 아닌 경우처럼 잘못된 요청을 보냈습니다. |
| 400 | `playtest_audience_not_found` | `--audience-id`가 판매자의 대상 그룹이 아닙니다. 메시지에 확인용 `audience list` 명령이 표시됩니다. |
| 400 | `playtest_package_not_found` | 게임에 해당 ID의 패키지가 없습니다. |
| 400 | `playtest_package_ambiguous` | 패키지 ID가 둘 이상의 패키지 세트와 일치하지만 그중 게임의 Main 분기에 있는 것이 없거나, 둘 이상의 마켓 그룹과 일치하지만 그중 `default`인 것이 없습니다. |
| 400 | `playtest_package_platform_mismatch` | `--pc-package-id`에 콘솔 패키지를 지정한 경우처럼 패키지가 옵션의 플랫폼과 일치하지 않습니다. `xbox package list`로 패키지의 플랫폼을 확인하세요. |
| 400 | `playtest_request_rejected` | Partner Center가 요청을 거부했습니다. 예를 들어 종료 날짜가 과거이거나 아직 플레이테스트에 사용할 수 없는 패키지로 `create` 또는 `update`를 실행했거나, 삭제된 플레이테스트를 `publish`한 경우입니다. |
| 403 | `audience_permission_denied` | 판매자에 대한 Partner Center의 고객 그룹 읽기 권한 없이 `--audience-id`를 전달했습니다. 아무것도 변경되지 않았습니다. Partner Center 계정 관리자에게 액세스 권한을 요청하세요. |
| 403 | `package_permission_denied` | `list`, `get`, `diff`에서는 Developer 역할에 포함된 게임에 대한 패키지 읽기 권한이 없습니다. 그 밖의 명령에서는 게임의 플레이테스트를 변경할 권한이 없습니다. Partner Center 계정 관리자에게 액세스 권한을 요청하세요. |
| 403 | `playtest_not_enabled` | 게임과 판매자에 대해 Playtest가 활성화되지 않았거나, 서비스가 지금 확인할 수 없습니다. 활성화되어 있어야 한다면 나중에 다시 시도하세요. |
| 404 | `playtest_not_found` | 게임에 해당 ID 또는 `--compare-to` ID의 플레이테스트가 없습니다. 메시지에 확인용 `playtest list` 명령이 표시됩니다. |
| 404 | `game_not_found` | 판매자에게 해당 Store ID의 게임이 없습니다. `--store-id`와 `--seller-id`를 확인하세요. |
| 409 | `playtest_not_editable` | 게시 중일 때처럼 플레이테스트의 상태가 지금은 `update`를 허용하지 않습니다. `playtest get`으로 확인하세요. |
| 409 | `playtest_ended` | 플레이테스트가 종료되었는데 `update`가 `--end`를 전달하지 않았습니다. 변경 내용과 함께 미래의 `--end`를 전달하세요. |
| 409 | `playtest_not_publishable` | 플레이테스트의 상태가 `publish`를 허용하지 않거나, 읽은 이후에 변경되었습니다. `playtest get`으로 확인하세요. |
| 409 | `playtest_not_deletable` | 플레이테스트의 상태가 `delete`를 허용하지 않습니다. `playtest get`으로 확인하세요. |
| 412 | `playtest_precondition_failed` | 읽은 이후에 플레이테스트가 변경되었습니다. `update`의 경우 `playtest get`을 실행하여 변경 내용이 여전히 적용되는지 확인하고, 새 `etag`로 다시 시도하세요. `publish`와 `delete`의 경우 플레이테스트를 확인하고 다시 시도하세요. |
| 422 | `playtest_publish_blocked` | 서비스의 게시 검사가 실패하여 아무것도 큐에 추가되지 않았습니다. 명령이 각 검사를 나열합니다. |

그 밖의 실패에 대해서는 명령이 서비스의 메시지를 표시합니다. 429는 요청을 너무 많이 보냈다는
뜻입니다. 다시 시도하기 전에 메시지에 표시된 시간만큼 기다리세요.


## Related topics

- [Playtest 사용](https://docs.xbox.com/ko/publishing/game-publishing/concepts/playtest-preview.md)
- [Playtest 개요](https://docs.xbox.com/ko/publishing/game-publishing/concepts/playtest.md)
- [사전 릴리스 테스트 옵션](https://docs.xbox.com/ko/publishing/game-publishing/publishing-processes/managed-creators/publishing-processes-prerelease.md)
- [샌드박스](https://docs.xbox.com/ko/publishing/game-publishing/concepts/sandboxes.md)
- [XBOX Insider Program 플라이팅 FAQ](https://docs.xbox.com/ko/publishing/game-publishing/publishing-processes/managed-creators/publishing-processes-xbox-flighting-faq.md)
