Execução de dispositivo da Developer Device Platform para iOS

Visualizar

Este produto ou recurso está sujeito aos Termos das Soluções Pré-GA na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os produtos e recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Neste guia, descrevemos como executar um XCTest do iOS usando a CLI do gcloud alpha device-run e encontrar os resultados no console do Google Cloud . Ele pressupõe que você tem uma conta e um projeto do Google Cloud .

Se você estiver migrando do Firebase Test Lab para a Developer Device Platform, consulte nosso guia de migração, a tradução de comandos e flags e a habilidade de migração para agentes de IA.

Para usar a CLI device-run, você precisa fornecer o ID do projeto do Google Cloud. Consulte gcloud alpha device-run para ver um resumo dos comandos.

Antes de começar

Estas etapas pressupõem que você já:

1. Criou um projeto do Google Cloud .
2. Configure a Developer Device Platform seguindo o Guia de início rápido.
3. Autenticado com gcloud no terminal.
4. Analisou a visão geral do Device Run para informações gerais.
5. Compilou os testes e os empacotou em um ZIP.

Etapa 1. Configurar a execução do teste

Dica: para ver todas as opções disponíveis para o comando submit xctest, execute gcloud alpha device-run sessions submit xctest --help.

É possível personalizar a execução do teste usando as seguintes flags opcionais (embora pelo menos uma instância da flag --device seja obrigatória):

• Vários dispositivos: especifique a flag --device várias vezes para executar o mesmo teste em vários dispositivos simultaneamente: --device iphonese3-18-4 --device iphonese3-26-3 ou --device iphonese3-18-4,iphonese3-26-3.
• Apps adicionais: instale um ou mais pacotes .ipa adicionais antes de iniciar o teste usando --additional-apps: --additional-apps=/path/to/AdditionalApp.ipa
• Arquivo .xctestrun personalizado: transmita um arquivo de configuração personalizado com --xctestrun-file: --xctestrun-file=/path/to/CustomTests.xctestrun
• Versões do Apple Xcode: acesse diretamente pela CLI as versões do Xcode compatíveis com a flag --xcode-version, por exemplo: --xcode-version=xcode-16-4
• Tempo limite do teste: limite a duração da execução: --xctest-timeout=10m (o intervalo válido é de 1m a 1h, e o padrão é 5m).
• Rótulos: anexe metadados definidos pelo usuário à sessão: --labels=env=staging,owner=my-team
• Localidade: defina a localidade do dispositivo: --locale=en-US
• Enviar arquivos para o dispositivo: envie arquivos para o contêiner de dados do app antes da execução do teste: --other-files-to-push=/tmp/data.txt=com.example.app:/Documents/data.txt
• Extrair arquivos do dispositivo: extraia arquivos do contêiner de dados do app após a execução do teste: --paths-to-pull=com.example.app:/Documents/output.txt
• Novas tentativas de teste instável: defina o número máximo de tentativas de executar novamente testes instáveis: --flaky-test-attempts=3 (o padrão é 1 tentativa).
• Bucket do Cloud Storage personalizado: especifique um bucket do Cloud Storage personalizado para entradas e saídas: --bucket-name=my-custom-bucket (o padrão é PROJECT_ID-devicerun).
• Como o upload de arquivos ZIP ou IPA grandes pode ser demorado, é possível fazer referência direta aos arquivos usando os caminhos gs:// do Cloud Storage para economizar tempo.

Execuções síncronas e assíncronas

Por padrão, o comando de envio é bloqueador (síncrono). Ele vai aguardar a conclusão do teste e imprimir uma tabela de resumo dos resultados.

Para enviar a sessão e retornar imediatamente após o upload de arquivos para o Cloud Storage, adicione a flag --async:

gcloud alpha device-run sessions submit xctest \
  --device iphonese3-18-4 \
  --test ./IOS_TESTS.zip \
  --async

Isso retorna um ID de sessão imediatamente. Em seguida, aguarde usando o comando sessions wait:

gcloud alpha device-run sessions wait SESSION_ID

O comando será bloqueado até que o job seja concluído.

Vários dispositivos

Para executar o mesmo teste em vários dispositivos, forneça a flag --device com vários IDs de dispositivo separados por vírgulas ou com várias flags --device, cada uma especificando um ID do dispositivo diferente.

Separado por vírgulas

gcloud alpha device-run sessions submit xctest \
  --device iphonese3-18-4,iphonese3-26-3 \
  --test ./IOS_TESTS.zip

Várias sinalizações

gcloud alpha device-run sessions submit xctest \
  --device iphonese3-18-4 \
  --device iphonese3-26-3 \
  --test ./IOS_TESTS.zip

Testar tempo limite

Limite a duração da execução do teste:

gcloud alpha device-run sessions submit xctest \
  --device iphonese3-18-4 \
  --test ./IOS_TESTS.zip \
  --xctest-timeout=10m

O intervalo válido é de 1m a 1h, e o padrão é 5m.

Versões de software

Descubra e use pacotes de software e versões disponíveis do Apple Xcode e inspecione os ciclos de vida, as versões compatíveis e os metadados antes de configurar as execuções de teste.

Primeiro, liste todos os pacotes de software disponíveis e as versões deles:

gcloud alpha device-run software-versions list

Recebendo uma saída semelhante a:

ID                                NAME                              SOFTWARE_TYPE               VERSION  STATE   IS_DEFAULT
androidx-test-orchestrator-1-4-1  AndroidX Test Orchestrator 1.4.1  ANDROIDX_TEST_ORCHESTRATOR  1.4.1    ACTIVE  True
androidx-test-orchestrator-1-6-1  AndroidX Test Orchestrator 1.6.1  ANDROIDX_TEST_ORCHESTRATOR  1.6.1    ACTIVE
xcode-16-4                        Xcode 16.4                        XCODE                       16.4     ACTIVE
xcode-26-2                        Xcode 26.2                        XCODE                       26.2     ACTIVE  True

Em seguida, descreva um pacote específico usando o ID de recurso exato da lista:

gcloud alpha device-run software-versions describe xcode-16-4

Recebendo uma saída semelhante a:

id: xcode-16-4
lifecycle:
  state: ACTIVE
name: Xcode 16.4
softwareType: XCODE
supportedIosVersions:

-   '15.0'
-   '15.1'
-   '15.2'
-   '15.4'
-   '15.7'
-   '16.0'
-   '16.1'
-   '16.2'
-   '16.3'
-   '16.5'
-   '16.6'
-   '18.0'
-   '18.3'
-   '18.4'
version: '16.4'

Agora que você sabe quais versões de software estão disponíveis, use-as nas execuções de teste com a flag --xcode-version, desta forma:

gcloud alpha device-run sessions submit xctest \
  --device iphonese3-18-4 \
  --test ./IOS_TESTS.zip \
  --xcode-version=16.4

Etapa 2. Escolher tipos de dispositivos

Usando a CLI device-run, os testes do iOS podem ser executados em dispositivos físicos disponíveis. Para ver a lista completa de dispositivos disponíveis, acesse o Catálogo de dispositivos interativo ou execute:

gcloud alpha device-run devices list

Exemplo de saída:

ID                MAKE   NAME           MODEL        HARDWARE_TYPE  OS_VERSION  CAPACITY  AVAILABILITY  PRODUCTS
iphonese3-18-4    Apple  iPhone SE 3             iphonese3    PHYSICAL       18.4        NONE      NONE          Automation
iphonese3-26-3    Apple  iPhone SE 3             iphonese3    PHYSICAL       26.3        NONE      NONE          Automation

Consulte o Catálogo de dispositivos para saber como filtrar essa lista. Para segmentar um dispositivo específico para a execução do teste, use o ID correspondente (por exemplo, iphonese3-18-4) no comando de envio.

Etapa 3. Preparar e empacotar o XCTest

Antes de executar os testes, é necessário compilá-los, garantir que estejam assinados, verificar as assinaturas de código e empacotar os artefatos resultantes em um arquivo ZIP que contenha a configuração do .xctestrun e os pacotes de teste do aplicativo.

Dica: está migrando do Firebase Test Lab? O Device Run aceita o mesmo pacote de teste que o Firebase Test Lab: o diretório Debug-iphoneos/ e o arquivo .xctestrun de Build/Products, conforme descrito em Executar um XCTest. Se você já tiver um pipeline de build e empacotamento para o Firebase Test Lab, poderá reutilizá-lo sem mudanças e transmitir o .zip resultante para --test. Para o restante da migração, consulte a seção do iOS de Tradução de flags e comandos.

1. Criar testes para dispositivos iOS físicos

Abra o projeto no Xcode e crie o app e os destinos de teste:

1. Verifique se a assinatura de código está configurada corretamente no Xcode (especificando um perfil de provisionamento válido e uma identidade de desenvolvedor) para o destino do app e o destino do executor de teste.

2. Crie para teste usando o Xcode (Product > Build For > Testing) ou com xcodebuild.

   Para um espaço de trabalho:

   xcodebuild build-for-testing \
     -workspace YourProject.xcworkspace \
     -scheme YourScheme \
     -derivedDataPath ./build \
     -destination "generic/platform=iOS"
   

   Para um projeto independente:

   xcodebuild build-for-testing \
     -project YourProject.xcodeproj \
     -scheme YourScheme \
     -derivedDataPath ./build \
     -destination "generic/platform=iOS"
   

Isso gera os produtos de build em: ./build/Build/Products

Observação: não é necessário registrar os UDIDs dos dispositivos do Device Run na sua conta de desenvolvedor da Apple. A Developer Device Platform assina novamente o aplicativo e os pacotes de teste com um perfil de provisionamento de laboratório antes de instalá-los no dispositivo físico. Portanto, um certificado de desenvolvimento local válido e um perfil de provisionamento são tudo o que é necessário para concluir as etapas de build e empacotamento.

2. Verificar produtos e assinaturas de build

Após a criação, verifique se o aplicativo, o executor e o manifesto .xctestrun foram gerados em ./build/Build/Products/. Se assinado localmente, é possível verificar as assinaturas do pacote usando codesign:

1. Verifique o pacote de apps:

   codesign --verify --deep --verbose ./build/Build/Products/Debug-iphoneos/YourApp.app
   

   Saída esperada: YourApp.app: valid on disk

2. Se estiver executando um XCUITest, verifique também o pacote do executor de teste:

   codesign --verify --deep --verbose ./build/Build/Products/Debug-iphoneos/YourApp-Runner.app
   

   Saída esperada: YourApp-Runner.app: valid on disk

Observação: um pacote YourApp-Runner.app separado é produzido apenas para destinos de teste UI (XCUITest). Os testes de unidade hospedados em aplicativos são incorporados ao app host e são cobertos pela verificação de YourApp.app.

3. Criar o arquivo ZIP

Compacte o diretório Debug-iphoneos e o arquivo .xctestrun localizado na pasta de produtos de saída do build em um único arquivo ZIP.

Atenção: o diretório Debug-iphoneos/ e o arquivo .xctestrun precisam estar diretamente na raiz do arquivo ZIP. NÃO compacte a pasta externa Products/ ou build/.

Execute o seguinte comando no diretório de produtos de build:

cd ./build/Build/Products
zip -r MyTests.zip Debug-iphoneos *.xctestrun

Isso cria o MyTests.zip empacotado que está pronto para ser usado com a flag --test.

Etapa 4. Executar o XCTest

Estas flags são obrigatórias:

• Dispositivo: especifique um dispositivo usando --device: --device iphonese3-18-4.
• Teste: especifique o arquivo ZIP de teste usando --test: --test ./MyTests.zip.

Para executar o XCTest, use o comando gcloud alpha device-run sessions submit xctest. Forneça o arquivo ZIP de teste (MyTests.zip) compilado na etapa anterior.

Para executar uma sessão de teste básica:

gcloud alpha device-run sessions submit xctest \
  --device iphonese3-18-4 \
  --test ./MyTests.zip

Quando a execução começa, a CLI exibe o ID da sessão criado e o destino do Cloud Storage em que os resultados serão armazenados:

Creating session [session-ee78b0ed] in location [global].
Result files will be stored at [https://console.cloud.google.com/storage/browser/BUCKET_NAME/automation/sessions/session-ee78b0ed/].

Waiting for session [session-ee78b0ed] to complete....

Etapa 5. Analisar e gerenciar a execução do teste

É possível acompanhar as execuções ativas e gerenciar as sessões históricas usando estes comandos:

• Descrever sessão: consulte o progresso em tempo real ou os resultados finais de uma sessão: gcloud alpha device-run sessions describe SESSION_ID Adicione --full para ver detalhes completos, incluindo alocações de dispositivos, IDs de execução e caminhos de artefatos do Cloud Storage.
• Listar sessões: confira suas execuções recentes: gcloud alpha device-run sessions list --limit=10
• Cancelar sessão: interrompa uma sessão de teste em execução: gcloud alpha device-run sessions cancel SESSION_ID
• Cancelar operação: interrompa uma operação pendente ou ativa: gcloud alpha device-run operations cancel OPERATION_ID

A seguir

Em seguida, encontre e analise os registros.