> ## 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

> Liste, obtenha, compare, crie, atualize, publique e exclua os playtests de um jogo do XBOX.

Um playtest permite que um grupo escolhido de jogadores experimente um jogo antes do lançamento. Os comandos `playtest` leem
os playtests de um jogo no Partner Center e os criam, atualizam, publicam e excluem. `create`,
`update`, `publish` e `delete` pedem confirmação antes de fazer uma alteração.

`create`, `update`, `publish` e `delete` são Experimentais: suas opções e sua saída podem mudar
ou ser removidas. Consulte [Comandos experimentais](https://docs.xbox.com/pt-BR/tools/xbox-cli/cli-command-lifecycle.md).

## Comandos

| Comando | Descrição |
| - | - |
| `playtest list` | Lista os playtests de um jogo. |
| `playtest get <playtest-id>` | Obtém um playtest: seus detalhes, pacotes, imagens, públicos e `etag`. |
| `playtest diff <playtest-id>` | Compara um playtest com sua última versão publicada ou com outro playtest. |
| `playtest create` | Cria um playtest privado em rascunho (Experimental). |
| `playtest update <playtest-id>` | Altera um playtest. Um playtest publicado volta para rascunho (Experimental). |
| `playtest publish <playtest-id>` | Publica um playtest, o que o oferece aos seus públicos a partir da data de início, e aguarda até que ele esteja agendado ou ativo (Experimental). |
| `playtest delete <playtest-id>` | Exclui um playtest e aguarda até que ele seja excluído (Experimental). |

## Argumentos e opções

| Argumento ou opção | Aplica-se a | Obrigatório | Descrição |
| - | - | - | - |
| `<playtest-id>` | `get`, `diff`, `update`, `publish`, `delete` | Sim | Uma `playtestId` de `list`, como `11111111-2222-3333-4444-555555555555`. |
| `--store-id <id>` | todos | Uma das duas | A ID da Store do jogo, como `9N0000000000`. |
| `--xbox-title-id <id>` | todos | Uma das duas | A ID de título do XBOX do jogo, e não sua ID de título do PlayFab, como `1234ABCD`. Se ela não corresponder a nenhum jogo ou corresponder a vários, o erro lista as IDs da Store a serem passadas em vez disso. |
| `--compare-to <playtest-id>` | `diff` | Não | Outro playtest com o qual comparar, em vez da última versão publicada. |
| `--name <name>` | `create`, `update` | `create` | O nome do playtest, mostrado aos jogadores. Não pode ficar em branco. |
| `--description <text>` | `create`, `update` | Não | Descrição curta. Em `update`, `""` a limpa. |
| `--long-description <text>` | `create`, `update` | Não | Descrição longa. Em `update`, `""` a limpa. |
| `--start <date>` | `create`, `update` | `create` | Quando o playtest começa. Consulte [Datas](#dates). |
| `--end <date>` | `create`, `update` | `create` | Quando o playtest termina. Deve ser posterior a `--start`. |
| `--audience-id <id>` | `create`, `update` | Não | Um público que pode participar, de [`audience list`](https://docs.xbox.com/pt-BR/tools/xbox-cli/commands/audience). Repita para adicionar mais. Consulte [Escolher públicos](#choosing-audiences). |
| `--pc-package-id <id>` | `create`, `update` | Não | O pacote para PC que os jogadores recebem. Consulte [Pacotes](#packages). |
| `--console-package-id <id>` | `create`, `update` | Não | O pacote para console que os jogadores recebem. Consulte [Pacotes](#packages). |
| `--idempotency-key <key>` | `create` | Não | De 1 a 50 caracteres ASCII imprimíveis, em vez de um novo GUID. Consulte [Criar um playtest](#creating-a-playtest). |
| `--if-match <etag>` | `update` | Não | Atualiza somente se o playtest ainda tiver esta `etag` de `playtest get`. Consulte [Atualizar um playtest](#updating-a-playtest). |
| `--no-wait` | `publish`, `delete` | Não | Retorna assim que a publicação ou a exclusão entra na fila. Não pode ser combinada com `--timeout`. |
| `--timeout <duration>` | `publish`, `delete` | Não | Por quanto tempo aguardar, como `90s`, `10m` ou `2h`. O padrão é `5m`; no máximo `7d`. |
| `--confirm` (`--yes`, `-y`) | `create`, `update`, `publish`, `delete` | Não | Ignora o prompt de confirmação. Sem ela e sem um terminal, o comando se recusa a fazer a alteração. |
| `--seller-id <id>` | todos | Se não estiver salva | ID do vendedor no Partner Center. Consulte [Contexto](https://docs.xbox.com/pt-BR/tools/xbox-cli/commands/context.md). |
| `--base-url <url>` | todos | Não | URL base para as solicitações, substituindo a chave de configuração `XboxPartner:BaseUrl`. |
| `--output <format>` | todos | Não | `json` (padrão), `json-compact` ou `table`. `create`, `update`, `publish` e `delete` recusam `table`. |

## Exemplos

Liste playtests, obtenha um e compare dois:

```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
```

Crie um playtest para um público:

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

Altere a data de término de um playtest:

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

Publique um playtest:

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

Exclua um playtest:

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

## Ler playtests

`playtest list` grava uma matriz `playtests`. Sua tabela tem as colunas `PLAYTEST ID`, `NAME`, `STATUS`, `TYPE`,
`START` e `END`. Um trecho:

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

`playtest get` grava o playtest da forma como o serviço o retorna. `etag` é a versão a ser passada para
`update --if-match`, e `audiences.audienceIds` lista os públicos que podem participar. Sua tabela tem
linhas `FIELD` e `VALUE`.

`playtest diff` grava `hasDiffData`, `current` e `compared`. Quando `hasDiffData` é `false`,
não há nada a comparar, e `compared` é omitido. Sua tabela mostra somente os campos que
diferem, nas colunas `FIELD`, `CURRENT` e `COMPARED`. As imagens não são comparadas.

## Criar um playtest

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

`playtest create` cria um playtest privado em rascunho e o grava como `playtest get` faz. Executá-lo
novamente cria outro playtest; remova um que você não queira com
[`playtest delete`](#deleting-a-playtest).

Cada criação envia uma chave de idempotência, um novo GUID, a menos que você passe `--idempotency-key`. Uma criação que
repete uma chave retorna o playtest que essa chave criou e ignora todas as opções diferentes.

Quando o resultado é desconhecido, como após um tempo limite, o comando sai com `3` e imprime um comando
que tenta novamente com a mesma chave:

```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
```

A nova tentativa retorna o playtest se a primeira solicitação o criou e, caso contrário, o cria. Quando uma
opção contém uma quebra de linha, somente a chave é impressa; execute o mesmo comando com
`--idempotency-key` e essa chave. Se a nova tentativa for recusada, por exemplo porque a data de término já passou,
verifique `playtest list` antes de criar o playtest com uma nova chave.

## Pacotes

Um playtest pode ter um pacote para PC e um pacote para console. Escolha um pacote pronto para um
playtest em [`xbox package list`](https://docs.xbox.com/pt-BR/tools/xbox-cli/commands/package#listing-packages) e passe seu `id` para a opção
da plataforma correspondente:

```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
```

Em `update`, uma opção de pacote que você omite mantém seu pacote, uma nova ID o substitui e `""`
o remove:

```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 ""
```

## Atualizar um playtest

> [!WARNING]
>
> Qualquer atualização retorna um playtest publicado para rascunho, assim como editá-lo no Partner Center. Publique-o
> novamente com `playtest publish` para disponibilizá-lo aos jogadores.

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

`playtest update` altera somente as opções que você passa e exige pelo menos uma. Ele grava o playtest
atualizado como `playtest get` faz. A arte do jogo configurada no Partner Center é mantida; outras artes vinculadas
ao playtest são substituídas por um espaço reservado.

Para evitar substituir a alteração de outra pessoa, passe a `etag` de `playtest get` em `--if-match`.
As aspas duplas ao redor dela são opcionais, e `*`, etags fracas (`W/`) e listas de etags são
recusadas:

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

Quando o resultado é desconhecido, o comando sai com `3`. Verifique o playtest com `playtest get` antes
de tentar novamente.

## Escolher públicos

Um público é um grupo de jogadores, como testadores, que o vendedor gerencia no Partner Center.
Passe uma `id` de [`audience list`](https://docs.xbox.com/pt-BR/tools/xbox-cli/commands/audience) para `--audience-id` e repita-a para adicionar mais:

```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
```

Sem `--audience-id`, `create` cria um playtest sem públicos, e `update` os mantém. Em
`update`, as IDs que você passa substituem todos os públicos do playtest. Para remover todos os públicos, passe
somente `""`:

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

`""` não pode ser combinado com IDs de público, e `create` o recusa. Um playtest precisa de pelo menos um
público para ser publicado.

## Publicar um playtest

Se o jogo usar os serviços do XBOX, defina a configuração e o embargo deles antes de publicar. Consulte
[Usar os serviços do XBOX em um playtest](https://docs.xbox.com/pt-BR/tools/xbox-cli/xbox-services-in-a-playtest.md).

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

A publicação oferece o playtest aos seus públicos a partir da data de início. O comando publica a
versão que lê primeiro; se o playtest mudar nesse intervalo, a publicação falha com `412` e
não altera nada.

Antes de pedir sua confirmação, o comando verifica a configuração dos serviços do XBOX do jogo, por exemplo se
a data de embargo é posterior à data de término do playtest, e lista em stderr tudo o que deve ser revisado. Essas
verificações são apenas consultivas; `--confirm` publica sem pedir confirmação.

Em seguida, o serviço executa as próprias verificações. Quando uma delas bloqueia a publicação, nada entra na fila, e o
comando lista cada verificação em stderr e sai com `1`. Corrija os erros e publique novamente. Um playtest
bloqueado por falta de classificações etárias precisa que o questionário de classificação etária seja concluído no Partner Center.

Depois que a publicação entra na fila, o comando aguarda até que o playtest esteja `Scheduled`, `Live` ou
`PublishFailed` e o grava como `playtest get` faz. Ctrl+C interrompe a espera, mas a publicação
continua. Com `--no-wait`, o comando grava `publishJobId` e eventuais `warnings` assim que a
publicação entra na fila; acompanhe-a com `playtest get`.

| Código de saída | Significado |
| - | - |
| `0` | O playtest está `Scheduled` ou `Live`. Com `--no-wait`, a publicação entrou na fila. |
| `1` | Não publicado, por exemplo porque uma verificação o bloqueou ou o playtest mudou. |
| `2` | A publicação falhou: o playtest está `PublishFailed`. |
| `3` | A solicitação foi enviada, mas seu resultado é desconhecido. Verifique o playtest com `playtest get` antes de publicar novamente. |
| `4` | A publicação entrou na fila, mas a espera terminou antes que ela fosse concluída. Verifique-a com `playtest get`. |

## Excluir um playtest

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

`playtest delete` exclui a versão do playtest que lê primeiro. Ele aguarda até que o playtest
esteja `Deleted` ou não exista mais e, em seguida, grava a resposta do serviço, com `status`. Ctrl+C interrompe a espera, mas
a exclusão continua. Com `--no-wait`, ele grava a resposta assim que a exclusão entra na fila.
Após um `412`, a exclusão pode já estar na fila; portanto, aguarde um minuto e verifique com `playtest get`
antes de excluir novamente.

| Código de saída | Significado |
| - | - |
| `0` | Excluído. Com `--no-wait`, a exclusão entrou na fila. |
| `1` | Não excluído, por exemplo porque o playtest mudou ou seu status não permite a exclusão. |
| `3` | A solicitação foi enviada, mas seu resultado é desconhecido. Verifique o playtest com `playtest get` antes de excluir novamente. |
| `4` | A exclusão entrou na fila, mas o playtest não estava `Deleted` antes de a espera terminar. Verifique-o com `playtest get`. |

## Datas

`--start` e `--end` aceitam datas e horas no formato ISO 8601, como `2026-11-01T09:00:00-07:00` ou
`2026-11-01T16:00:00Z`. Uma data sem hora significa meia-noite UTC, e uma hora sem deslocamento está em
UTC. Quando uma atualização passa somente uma data, o serviço a verifica em relação à outra data do playtest.

## Erros

As falhas vão para stderr e saem com `1`, a menos que as tabelas de códigos de saída acima indiquem o contrário. `create` e
`update` saem com `3` quando o resultado é desconhecido. Uma falha que o serviço retorna inclui seu status
HTTP, e `--verbose` adiciona a resposta do serviço, cujo campo `code` é mostrado aqui:

| Status | `code` | Significado |
| - | - | - |
| 400 | `invalid_playtest_request` | `create` ou `update` enviou uma solicitação inválida, como um término que não é posterior ao início. |
| 400 | `playtest_audience_not_found` | Uma `--audience-id` não é um dos públicos do vendedor. A mensagem mostra o comando `audience list` para verificar. |
| 400 | `playtest_package_not_found` | O jogo não tem nenhum pacote com essa ID. |
| 400 | `playtest_package_ambiguous` | A ID do pacote corresponde a mais de um conjunto de pacotes e nenhum deles está na ramificação Main do jogo, ou a mais de um grupo de mercado e nenhum deles é `default`. |
| 400 | `playtest_package_platform_mismatch` | Um pacote não corresponde à plataforma da sua opção, como um pacote para console em `--pc-package-id`. Verifique a plataforma dele com `xbox package list`. |
| 400 | `playtest_request_rejected` | O Partner Center rejeitou a solicitação, como um `create` ou `update` com uma data de término no passado ou um pacote que ainda não está disponível para playtests, ou um `publish` de um playtest excluído. |
| 403 | `audience_permission_denied` | Você passou `--audience-id` sem a permissão de Leitura de grupos de clientes do Partner Center para o vendedor. Nada foi alterado. Solicite acesso a um gerente da conta do Partner Center. |
| 403 | `package_permission_denied` | Em `list`, `get` e `diff`, você não tem a permissão de Leitura de Pacotes no jogo, que a função Desenvolvedor inclui. Nos outros comandos, você não tem permissão para alterar os playtests do jogo. Solicite acesso a um gerente da conta do Partner Center. |
| 403 | `playtest_not_enabled` | Os playtests não estão habilitados para o jogo e o vendedor, ou o serviço não conseguiu verificar no momento. Se eles deveriam estar habilitados, tente novamente mais tarde. |
| 404 | `playtest_not_found` | O jogo não tem nenhum playtest com essa ID ou ID de `--compare-to`. A mensagem mostra o comando `playtest list` para verificar. |
| 404 | `game_not_found` | O vendedor não tem nenhum jogo com essa ID da Store. Verifique `--store-id` e `--seller-id`. |
| 409 | `playtest_not_editable` | O status do playtest não permite `update` no momento, por exemplo enquanto ele está sendo publicado. Verifique-o com `playtest get`. |
| 409 | `playtest_ended` | O playtest terminou, e `update` não passou `--end`. Passe um `--end` futuro com a alteração. |
| 409 | `playtest_not_publishable` | O status do playtest não permite `publish`, ou ele mudou desde que foi lido. Verifique-o com `playtest get`. |
| 409 | `playtest_not_deletable` | O status do playtest não permite `delete`. Verifique-o com `playtest get`. |
| 412 | `playtest_precondition_failed` | O playtest mudou desde que foi lido. Para `update`, execute `playtest get`, verifique se sua alteração ainda se aplica e tente novamente com a nova `etag`. Para `publish` e `delete`, verifique o playtest e tente novamente. |
| 422 | `playtest_publish_blocked` | As verificações de publicação do serviço falharam; portanto, nada entrou na fila. O comando lista cada verificação. |

Para outras falhas, o comando mostra a mensagem do serviço. Um 429 significa que você enviou solicitações
demais; aguarde o tempo indicado pela mensagem antes de tentar novamente.


## Related topics

- [Usar o Playtest](https://docs.xbox.com/pt-BR/publishing/game-publishing/concepts/playtest-preview.md)
- [Seu primeiro playtest](https://docs.xbox.com/pt-BR/tools/xbox-cli/first-playtest.md)
- [Visão geral do Playtest](https://docs.xbox.com/pt-BR/publishing/game-publishing/concepts/playtest.md)
- [Usar os serviços do XBOX em um playtest](https://docs.xbox.com/pt-BR/tools/xbox-cli/xbox-services-in-a-playtest.md)
- [Opções de teste de pré-lançamento](https://docs.xbox.com/pt-BR/publishing/game-publishing/publishing-processes/managed-creators/publishing-processes-prerelease.md)
