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

Vista previa

Este producto o esta función se encuentra sujeto a las "Condiciones de la oferta de la fase previa a la DG" en la sección Condiciones del servicio generales 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 gcloud alpha device-run CLI y encontrar los resultados en la Google Cloud consola. Se supone que tienes una Google Cloud cuenta y un proyecto de.

Si estás migrando 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 de tu Google Cloud proyecto. Consulta gcloud alpha device-run para obtener un resumen de los comandos.

Antes de comenzar

En estos pasos, se supone que ya hiciste lo siguiente:

1. Creaste un Google Cloud proyecto.
2. Configuraste la plataforma de dispositivos para desarrolladores siguiendo la Guía de inicio rápido.
3. Te autenticaste 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 para el comando submit xctest, ejecuta gcloud alpha device-run sessions submit xctest --help.

Puedes personalizar la ejecución de la 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 las versiones de Xcode compatibles con la CLI 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
• Extraer 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 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 gs:// de Cloud Storage para ahorrar tiempo de carga.

Ejecuciones síncronas y asíncronas

De forma predeterminada, el comando submit es bloqueador (síncrono). Esperará a que se complete la prueba y mostrará 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 muestra un ID de sesión de inmediato. Luego, puedes esperar 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 dispositivos separados por comas o con varias marcas --device, cada una de las cuales especifica un ID de dispositivo distinto.

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 examina sus ciclos de vida, versiones compatibles y metadatos antes de configurar las ejecuciones de prueba.

Primero, haz una lista de 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 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 aprender a filtrar esta lista. Para orientar un dispositivo específico para la ejecución de prueba, usa su ID correspondiente (p. ej., iphonese3-18-4) en el comando submit.

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 .xctestrun y los paquetes de prueba de la aplicación.

Sugerencia: ¿Estás migrando desde Firebase Test Lab? Device Run acepta el mismo paquete de pruebas que Firebase Test Lab: el directorio Debug-iphoneos/ y el .xctestrun archivo 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 volver a usarla 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 objetivos de prueba para realizar pruebas:

1. Asegúrate de que la firma de código esté configurada correctamente en Xcode (especifica un perfil de aprovisionamiento y una identidad de desarrollador válidos) para el objetivo de la app y el objetivo 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"
   

   En el caso de 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 UDIDs del dispositivo Device Run en tu cuenta de desarrollador de Apple. La plataforma de dispositivos para desarrolladores vuelve a firmar tu aplicación y los paquetes de prueba con un perfil de aprovisionamiento de laboratorio 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 compilación

Después de la compilación, verifica que la aplicación, el ejecutor y el manifiesto .xctestrun se hayan generado en ./build/Build/Products/. Si se firmó 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 objetivos de prueba de IU (XCUITest). 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 ubicado en la carpeta de productos de salida de 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/ ni 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 comience la ejecución, la CLI mostrará 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 la ejecución de la prueba

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

• Describir sesión: 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 acceso de artefactos de Cloud Storage.
• Enumerar 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.