Ejecución de dispositivos de la plataforma de dispositivos para desarrolladores para iOS

Vista previa

Este producto o función está sujeto a las "Condiciones de la Oferta de la Fase Previa a la DG" en la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio. Los productos y las funciones de la fase previa a la DG están disponibles “tal como están” y pueden estar sujetos a asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

En esta guía, se describe cómo ejecutar una XCTest de iOS con la CLI de gcloud alpha device-run y encontrar los resultados en la consola de Google Cloud . Se supone que tienes una cuenta y un proyecto de Google Cloud .

Si migras de Firebase Test Lab a Developer Device Platform, consulta nuestra guía de migración, la traducción de comandos y marcas, y la habilidad de migración para agentes de IA.

Para usar la CLI de device-run, deberás proporcionar el ID del proyecto de Google Cloud. Consulta gcloud alpha device-run para obtener un resumen de los comandos.

Antes de comenzar

En estos pasos, se da por sentado que ya hiciste lo siguiente:

1. Crear un proyecto de Google Cloud
2. Configura Developer Device Platform siguiendo la guía de inicio rápido.
3. Autenticado con gcloud en la terminal.
4. Revisaste la descripción general de Device Run para obtener información general.
5. Compilaste tus pruebas y las empaquetaste en un archivo ZIP.

Paso 1: Configura la ejecución de la prueba

Sugerencia: Para ver todas las opciones disponibles del comando submit xctest, ejecuta gcloud alpha device-run sessions submit xctest --help.

Puedes personalizar la ejecución de prueba con las siguientes marcas opcionales (aunque se requiere al menos una instancia de la marca --device):

• Varios dispositivos: Especifica la marca --device varias veces para ejecutar la misma prueba en varios dispositivos de forma simultánea: --device iphonese3-18-4 --device iphonese3-26-3 o --device iphonese3-18-4,iphonese3-26-3
• Apps adicionales: Instala uno o más paquetes .ipa adicionales antes de iniciar la prueba con --additional-apps: --additional-apps=/path/to/AdditionalApp.ipa
• Archivo .xctestrun personalizado: Pasa un archivo de configuración personalizado con --xctestrun-file: --xctestrun-file=/path/to/CustomTests.xctestrun
• Versiones de Apple Xcode: Accede directamente a través de la CLI a las versiones de Xcode compatibles con la marca --xcode-version, por ejemplo: --xcode-version=xcode-16-4
• Tiempo de espera de la prueba: Limita la duración de la ejecución: --xctest-timeout=10m (el rango válido es de 1m a 1h, y el valor predeterminado es 5m).
• Etiquetas: Adjunta metadatos definidos por el usuario a la sesión: --labels=env=staging,owner=my-team
• Configuración regional: Establece la configuración regional del dispositivo: --locale=en-US
• Enviar archivos al dispositivo: Envía archivos al contenedor de datos de la app antes de la ejecución de la prueba: --other-files-to-push=/tmp/data.txt=com.example.app:/Documents/data.txt
• Extrae archivos del dispositivo: Extrae archivos del contenedor de datos de la app después de la ejecución de la prueba: --paths-to-pull=com.example.app:/Documents/output.txt
• Reintentos de pruebas inestables: Establece la cantidad máxima de intentos para volver a ejecutar pruebas inestables: --flaky-test-attempts=3 (el valor predeterminado es 1 intento).
• Bucket de Cloud Storage personalizado: Especifica un bucket de Cloud Storage personalizado para las entradas y salidas: --bucket-name=my-custom-bucket (el valor predeterminado es PROJECT_ID-devicerun).
• Debido a que subir archivos ZIP o IPA grandes puede llevar mucho tiempo, puedes hacer referencia directamente a tus archivos con sus rutas de acceso de Cloud Storage gs:// para ahorrar tiempo de carga.

Ejecuciones síncronas y asíncronas

De forma predeterminada, el comando de envío es bloqueante (síncrono). Esperará a que se complete la prueba y, luego, imprimirá una tabla de resumen de los resultados.

Para enviar la sesión y regresar de inmediato después de subir archivos a Cloud Storage, agrega la marca --async:

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

Esto devuelve un ID de sesión de inmediato. Luego, puedes esperar a que se complete con el comando sessions wait:

gcloud alpha device-run sessions wait SESSION_ID

El comando se bloqueará hasta que se complete el trabajo.

Varios dispositivos

Para ejecutar la misma prueba en varios dispositivos, proporciona la marca --device con varios IDs de dispositivo separados por comas o con varias marcas --device, cada una de las cuales especifica un ID de dispositivo diferente.

Separados por comas

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

Varias marcas

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

Tiempo de espera de la prueba

Limita la duración de la ejecución de la prueba:

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

El rango válido es de 1m a 1h, y el valor predeterminado es 5m.

Versiones de software

Descubre y usa los paquetes de software y las versiones disponibles de Apple Xcode, y, además, inspecciona sus ciclos de vida, las versiones compatibles y los metadatos antes de configurar las ejecuciones de pruebas.

Primero, enumera todos los paquetes de software disponibles y sus versiones:

gcloud alpha device-run software-versions list

Recibirás un resultado similar al siguiente:

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

Luego, describe un paquete específico con su ID de recurso exacto de la lista:

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

Recibirás un resultado similar al siguiente:

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'

Ahora que sabes qué versiones de software están disponibles, puedes usarlas en tus ejecuciones de prueba con la marca --xcode-version, de la siguiente manera:

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

Paso 2: Elige los tipos de dispositivos

Con la CLI de device-run, las pruebas de iOS se pueden ejecutar en los dispositivos físicos disponibles. Para ver la lista completa de dispositivos disponibles, visita el catálogo de dispositivos interactivo o ejecuta lo siguiente:

gcloud alpha device-run devices list

Resultado de ejemplo:

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

Consulta el catálogo de dispositivos para obtener información sobre cómo filtrar esta lista. Para orientar la ejecución de prueba a un dispositivo específico, usa su ID correspondiente (p. ej., iphonese3-18-4) en el comando de envío.

Paso 3: Prepara y empaqueta tu XCTest

Antes de ejecutar las pruebas, debes compilarlas, asegurarte de que estén firmadas, verificar las firmas de código y empaquetar los artefactos resultantes en un archivo ZIP que contenga tu configuración de .xctestrun y los paquetes de prueba de la aplicación.

Sugerencia: ¿Migrarás desde Firebase Test Lab? Device Run acepta el mismo paquete de prueba que Firebase Test Lab: el directorio Debug-iphoneos/ y el archivo .xctestrun de Build/Products, como se describe en Ejecuta una XCTest. Si ya tienes una canalización de compilación y empaquetado para Firebase Test Lab, puedes reutilizarla sin cambios y pasar el .zip resultante a --test. Para el resto de la migración, consulta la sección de iOS de Traducción de marcas y comandos.

1. Compila tus pruebas para dispositivos iOS físicos

Abre tu proyecto en Xcode y compila tu app y los destinos de prueba para realizar las pruebas:

1. Asegúrate de que la firma de código esté configurada correctamente en Xcode (especificando un perfil de aprovisionamiento y una identidad de desarrollador válidos) tanto para el destino de la app como para el del ejecutor de pruebas.

2. Compila para realizar pruebas con Xcode (Product > Build For > Testing) o con xcodebuild.

   En el caso de un espacio de trabajo, haz lo siguiente:

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

   Para un proyecto independiente, haz lo siguiente:

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

Esto genera los productos de compilación en ./build/Build/Products.

Nota: No es necesario que registres los UDID de los dispositivos de Device Run en tu cuenta de desarrollador de Apple. Developer Device Platform vuelve a firmar tu aplicación y los paquetes de prueba con un perfil de aprovisionamiento de lab antes de instalarlos en el dispositivo físico, por lo que solo se requiere un certificado de desarrollo local y un perfil de aprovisionamiento válidos para completar los pasos de compilación y empaquetado.

2. Verifica los productos y las firmas de la compilación

Después de compilar, verifica que la aplicación, el ejecutor y el manifiesto de .xctestrun se hayan generado en ./build/Build/Products/. Si se firma de forma local, puedes verificar las firmas del paquete con codesign:

1. Verifica el paquete de aplicación:

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

   Resultado esperado: YourApp.app: valid on disk

2. Si ejecutas una XCUITest, también verifica el paquete del ejecutor de pruebas:

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

   Resultado esperado: YourApp-Runner.app: valid on disk

Nota: Solo se produce un paquete YourApp-Runner.app independiente para los destinos de pruebas de IU (XCUITest). En cambio, las pruebas de unidades alojadas en la aplicación se incorporan en la app host y están cubiertas por la verificación de YourApp.app.

3. Crea el archivo ZIP

Comprime el directorio Debug-iphoneos y el archivo .xctestrun que se encuentran en la carpeta de productos de salida de la compilación en un solo archivo ZIP.

Precaución: El directorio Debug-iphoneos/ y el archivo .xctestrun deben residir directamente en la raíz del archivo ZIP. NO comprimas la carpeta externa Products/ o build/.

Ejecuta el siguiente comando desde el directorio de productos de compilación:

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

Esto crea el MyTests.zip empaquetado que está listo para usarse con la marca --test.

Paso 4: Ejecuta tu XCTest

Ten en cuenta que estas marcas son obligatorias:

• Dispositivo: Especifica un dispositivo con --device: --device iphonese3-18-4
• Prueba: Especifica el archivo ZIP de prueba con --test: --test ./MyTests.zip

Para ejecutar tu XCTest, usa el comando gcloud alpha device-run sessions submit xctest. Debes proporcionar el archivo ZIP de prueba (MyTests.zip) compilado en el paso anterior.

Para ejecutar una sesión de prueba básica, haz lo siguiente:

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

Cuando comienza la ejecución, la CLI muestra el ID de sesión creado y el destino de Cloud Storage en el que se almacenarán los resultados:

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

Paso 5: Explora y administra tu ejecución de prueba

Puedes hacer un seguimiento de las ejecuciones activas y administrar las sesiones históricas con estos comandos:

• Describe session: Consulta el progreso en vivo o los resultados finales de una sesión: gcloud alpha device-run sessions describe SESSION_ID Agrega --full para ver los detalles completos, incluidas las asignaciones de dispositivos, los IDs de ejecución y las rutas de artefactos de Cloud Storage.
• Enumera las sesiones: Consulta tus ejecuciones recientes: gcloud alpha device-run sessions list --limit=10
• Cancelar sesión: Detén una sesión de prueba en ejecución: gcloud alpha device-run sessions cancel SESSION_ID
• Cancelar operación: Detén una operación pendiente o activa: gcloud alpha device-run operations cancel OPERATION_ID

¿Qué sigue?

A continuación, busca y analiza registros.