Migra de Firebase Test Lab y Flank a Developer Device Platform con IA

Esta habilidad ayuda a traducir las configuraciones y los flujos de trabajo de ejecución de pruebas heredados (de Flank o gcloud firebase test) a la superficie de la CLI de gcloud beta device-run moderna y orientada a los recursos.

Asignación de la estructura de comandos y recursos

La CLI de Device Run organiza los comandos por recurso: devices, software-versions y sessions:

1. Catálogo de dispositivos (devices)

  • List Devices:
    • Heredado: gcloud firebase test android/ios models list
    • Nuevo: gcloud beta device-run devices list [--filter="..."]
    • Ejemplo: gcloud beta device-run devices list --filter="platform:android"
  • Describe Device:
    • Heredado: gcloud firebase test android/ios models describe {MODEL}
    • Nuevo: gcloud beta device-run devices describe {DEVICE}
    • Ejemplo: gcloud beta device-run devices describe redfin-30
  • Verifica la capacidad de los dispositivos y la disponibilidad de la flota:
    • Heredado: gcloud firebase test android/ios list-device-capacities
    • Nuevo: Se incorporó directamente en el recurso Device (availability.capacity y availability.available). Se puede inspeccionar con gcloud beta device-run devices describe {DEVICE} o filtrar directamente con gcloud beta device-run devices list --filter="availability.capacity=CAPACITY_HIGH".

2. Versiones de software (software-versions)

  • List Supported Software Versions (Xcode & Android Test Orchestrator):
    • Heredado: gcloud firebase test ios xcode-versions list
    • Nuevo: gcloud beta device-run software-versions list
  • Describe Software Version:
    • Nuevo: gcloud beta device-run software-versions describe {SOFTWARE_VERSION}
    • Ejemplo: gcloud beta device-run software-versions describe xcode-16-4

3. Sesiones de automatización (sessions)

  • Submit Android Instrumentation:
    • Heredado: gcloud firebase test android run --type=instrumentation ...
    • Nuevo: gcloud beta device-run sessions submit instrumentation ...
  • Submit iOS XCTest:
    • Heredado: gcloud firebase test ios run --type=xctest ...
    • Nuevo: gcloud beta device-run sessions submit xctest ...
  • Wait for Session Completion:
    • Heredado: Solo bloqueo de la CLI síncrono
    • Nuevo: gcloud beta device-run sessions wait {SESSION}
  • Describe / Inspect Session:
    • Legado: Visualiza el vínculo web en Firebase console o en los resultados de Cloud Tool
    • Nuevo: gcloud beta device-run sessions describe {SESSION} [--full]
  • List Past Sessions:
    • Heredado: Consulta el historial de la matriz en la consola web
    • Nuevo: gcloud beta device-run sessions list
  • Cancelar sesión:
    • Heredado: Solo consola web (sin comando de CLI)
    • Nuevo: gcloud beta device-run sessions cancel {SESSION}

Tabla de referencia de asignación de marcas

En la siguiente tabla, se asignan los parámetros de Firebase Test Lab y Flank heredados a sus equivalentes admitidos en gcloud beta device-run:

Tipo de prueba Grupo de atributos Parámetro heredado (Firebase/Flank) Parámetro de destino (device-run) Lógica de formato o conversión
Común (iOS y Android) Parámetros y recursos principales Flanco --project --project Es una marca global estándar Google Cloud (--project=PROJECT_ID) o una configuración activa de Google Cloud CLI.
Común (iOS y Android) Parámetros y recursos principales --client-details --labels Diccionario de pares clave=valor.
Común (iOS y Android) Configuración y segmentación por dispositivo --device model={M},version={V} --device={M}-{V} Asigna el modelo y la versión del SO a la cadena de ID de --device. Acepta una lista separada por comas de varios dispositivos en una sola marca (p. ej., --device=mediumphone-arm-32,shiba-36).
Común (iOS y Android) Control de ejecución y falta de confiabilidad --async --async Mapas 1:1 El comando permanece síncrono de forma predeterminada. Pasa este parámetro para que se muestre de inmediato. Supervisa o espera con gcloud beta device-run sessions wait <SESSION_ID>.
Común (iOS y Android) Control de ejecución y falta de confiabilidad --num-flaky-test-attempts {R} --flaky-test-attempts {A} Número entero. Convierte el recuento de reintentos $R$ en el límite de intentos totales: $A = R + 1$ (el valor predeterminado es 1).
Común (iOS y Android) Control de ejecución y falta de confiabilidad N/A --flaky-test-parallel-retry Booleano. Indica si se deben volver a intentar las pruebas fallidas en paralelo (el valor predeterminado es secuencial).
Común (iOS y Android) Control de ejecución y falta de confiabilidad N/A --flaky-test-retry-level String. Reintento de nivel: shard o test (el valor predeterminado es shard).
Común (iOS y Android) Salida y almacenamiento --results-bucket --bucket-name Es el bucket en el que se suben los artefactos de salida de la prueba (el valor predeterminado es gs://[PROJECT_ID]-devicerun).
Común (iOS y Android) Salida y almacenamiento --results-dir Administración automática No se admite la configuración de subdirectorios personalizados; todos los artefactos de prueba se organizan automáticamente en automation/sessions/{session_id}/ dentro del bucket especificado por --bucket-name.
Común (iOS y Android) Salida y almacenamiento --record-video --video Valores válidos: always o on-failure.
Común (iOS y Android) Salida y almacenamiento --directories-to-pull --paths-to-pull Lista de rutas de acceso para extraer del dispositivo después de la ejecución.
Android común Parámetros y recursos principales --app --apps List. Si se proporcionan varios APKs o AABs de la aplicación, pásalos todos a --apps.
Android común Parámetros y recursos principales --additional-apks --apps List. Combina valores de listas adicionales directamente en la lista principal --apps.
Android común Parámetros y recursos principales --obb-files --other-files-to-push Diccionario en formato SOURCE=DEST. Envía archivos OBB directamente a la ruta del dispositivo (/sdcard/Android/obb/{package_name}/).
Android común Parámetros y recursos principales --other-files --other-files-to-push Diccionario en formato SOURCE=DEST.
Android común Configuración y segmentación por dispositivo --device locale={L} --locale={L} Asigna la configuración regional del dispositivo de Maps a la marca --locale de nivel superior (language-region, p. ej., --locale=en-US).
Android común Configuración y segmentación por dispositivo --device orientation={O} --orientation={O} Asigna la orientación del dispositivo a la marca --orientation de nivel superior (portrait o landscape).
Android común Configuración y segmentación por dispositivo N/A --coordinates Coordenadas de ubicación ficticia (p. ej., latitude,longitude) 37.4220,-122.0841).
Android común Control de ejecución y falta de confiabilidad --grant-permissions Configuración predeterminada automatizada Automatizada. Los permisos de tiempo de ejecución se otorgan automáticamente de forma predeterminada (equivalente a --grant-permissions=all).|
Android común Salida y almacenamiento N/A --dumpsys Recopila dumpsys del dispositivo (always o on-failure).
Android común Salida y almacenamiento N/A --bugreport Recopila el informe de errores del dispositivo (always o on-failure).
Instrumentación de Android Parámetros y recursos principales --type=instrumentation sessions submit instrumentation La estructura de subcomandos determina el tipo de prueba en lugar de una marca --type.
Instrumentación de Android Parámetros y recursos principales --test --test Es la ruta de acceso al archivo binario que contiene las pruebas de instrumentación.
Instrumentación de Android Control de ejecución y falta de confiabilidad --timeout --instrumentation-timeout Duración (p. ej., 10m, 20s, 1h). Rango válido: de 1m a 3h (el valor predeterminado es 5m).
Instrumentación de Android Control de ejecución y falta de confiabilidad --num-uniform-shards {N} --sharding-option=uniform
--uniform-sharding-count={N} 		La configuración de la marca activa la estrategia de fragmentación uniforme (rango de recuento válido: de 1 a 20 físicos y de 1 a 200 virtuales).
Instrumentación de Android Control de ejecución y falta de confiabilidad Flanco --shard-time {S} --sharding-option=smart
--smart-sharding-target-duration={S} 		Activa el sharding inteligente con el tiempo de ejecución objetivo (p. ej., 2m, 10m, 1h). Rango válido: de 2m a 1h.
Instrumentación de Android Control de ejecución y falta de confiabilidad Flanco --smart-flank-gcs-path --smart-sharding-record-name={name}
--bucket-name={bucket} 		Nombre del registro de fragmentación YAML (sin incluir la extensión) dentro de --bucket-name en automation/smart-sharding/.
Instrumentación de Android Control de ejecución y falta de confiabilidad Flanco --max-test-shards {N} --smart-sharding-max-shard-count={N} Se asigna a un límite máximo de fragmentos cuando se habilita el fragmentado inteligente (de 0 a 20 físicos y de 0 a 200 virtuales).
Instrumentación de Android Ejecutor y destinos de pruebas --test-runner-class --test-runner-class Clase de ejecutor completamente calificada.
Instrumentación de Android Ejecutor y destinos de pruebas --test-targets --test-targets Diccionario que admite claves como package, notPackage, class, notClass, annotation, notAnnotation y size. No se admitirán formatos como testfile o notTestfile.
Instrumentación de Android Ejecutor y destinos de pruebas --use-orchestrator --orchestrator-version Toma auto (organizador predeterminado) o una cadena de versión específica (p. ej., 1.6).
Instrumentación de Android Ejecutor y destinos de pruebas --environment-variables --additional-test-options Diccionario de opciones que se pasan al ejecutor de pruebas. Aquí no se permiten los formatos admitidos en --test-targets.
iOS común Parámetros y recursos principales --additional-ipas --additional-apps Lista de archivos .ipa que se instalarán en el dispositivo antes de la ejecución de la prueba.
iOS común Parámetros y recursos principales --other-files --other-files-to-push Diccionario en formato SOURCE=BUNDLE_ID:DEVICE_PATH.
iOS común Salida y almacenamiento --directories-to-pull --paths-to-pull Lista de archivos o directorios para extraer después de la prueba en formato BUNDLE_ID:DEVICE_PATH.
Solo iOS XCTest Parámetros y recursos principales --type=xctest sessions submit xctest La estructura del subcomando determina el tipo de prueba en lugar de una marca --type.
Solo iOS XCTest Parámetros y recursos principales --test --test Ruta de acceso al archivo ZIP que contiene la app para iOS y los archivos de XCTest.
Solo iOS XCTest Control de ejecución y falta de confiabilidad --timeout --xctest-timeout Duración máxima permitida para la ejecución de XCTest (rango válido: de 1m a 1h; el valor predeterminado es 5m).
Solo iOS XCTest Ejecutor y destinos de pruebas --xctestrun-file --xctestrun-file Ruta de acceso al archivo .xctestrun personalizado.
Solo iOS XCTest Ejecutor y destinos de pruebas --xcode-version --xcode-version ID de catálogo o cadena de versión de Xcode que se usará (p. ej., xcode-16-4 o 16.4). Consulta con software-versions list.

Orientación práctica para la traducción

Sigue estos lineamientos para traducir las configuraciones de Firebase Test Lab y Flank a ejecuciones en dispositivos:

1. Especificaciones del dispositivo

En gcloud beta device-run, --device acepta una lista separada por comas de cadenas de ID de modelo y versión. A diferencia de Firebase, que requería una marca --device por dispositivo, device-run permite especificar varios dispositivos en una sola marca. La configuración regional, la orientación y las coordenadas simuladas del dispositivo se especifican con marcas de nivel superior independientes:

  • ❌ --device model=MediumPhone.arm,version=32,locale=en,orientation=portrait
  • ✅ --device=mediumphone-arm-32 --locale=en-US --orientation=portrait

2. Diccionarios y listas

Convierte las marcas separadas por comas en listas (--apps, --paths-to-pull) o diccionarios de par clave-valor (--other-files-to-push, --additional-test-options):

  • ❌ --other-files /sdcard/file1.txt=local/file1.txt,/sdcard/file2.txt=local/file2.txt
  • ✅ --other-files-to-push local/file1.txt=/sdcard/file1.txt,local/file2.txt=/sdcard/file2.txt

3. Estrategias de fragmentación

  • Fragmentación uniforme:
    • Establece --sharding-option=uniform.
    • Establece --uniform-sharding-count={count} (de 1 a 20 para dispositivos físicos y de 1 a 200 para dispositivos virtuales).
  • Fragmentación inteligente:
    • Establece --sharding-option=smart.
    • Establece --smart-sharding-target-duration={duration} (p. ej., 2m, 10m, 1h; rango válido: de 2m a 1h).
    • Establece --smart-sharding-record-name={record_name} (apunta al registro de seguimiento de YAML dentro de --bucket-name en automation/smart-sharding/).
    • Establece --smart-sharding-max-shard-count={max_count} (límite máximo opcional: de 0 a 20 para ubicaciones físicas y de 0 a 200 para ubicaciones virtuales).

4. Ejecución asíncrona

  • Async & Waiting: Cuando se especifica --async, la CLI devuelve de inmediato el ID de sesión creado. Puedes esperar a que se complete la sesión en los flujos de trabajo de CI/CD con gcloud beta device-run sessions wait <SESSION_ID>:

5. Configuración declarativa de YAML (--flags-file)

Para configuraciones complejas o equipos que prefieren mantener archivos con control de versiones en lugar de comandos largos de la terminal, gcloud proporciona un preprocesador de argumentos --flags-file universal (consulta $ gcloud topic flags-file):

gcloud beta device-run sessions submit instrumentation --flags-file=device-run-flags.yaml

!NOTA Por qué las claves requieren --: gcloud inyecta claves YAML directamente en el analizador de la CLI como marcas de línea de comandos. Todas las claves del archivo YAML deben tener el prefijo -- (p. ej., --device:, --apps:). Sin --, gcloud los rechaza como argumentos posicionales no reconocidos.

A continuación, se muestra un ejemplo que demuestra las marcas de diccionario y lista con varios valores:

# device-run-flags.yaml
--device:
  -   mediumphone-arm-32
  -   shiba-36
--apps:
  -   app-debug.apk
  -   test-helper.apk
--test: app-debug-androidTest.apk
--bucket-name: my-bucket
--sharding-option: smart
--smart-sharding-target-duration: 2m
--smart-sharding-record-name: timing-record
--paths-to-pull:
  -   /sdcard/screenshots
  -   /sdcard/coverage.ec
--additional-test-options:
  coverage: "true"
  clearPackageData: "true"

Traducciones de ejemplo

Usa estos ejemplos para traducir tus configuraciones existentes de Firebase Test Lab y Flank a la ejecución en dispositivos.

Firebase Test Lab para la ejecución en el dispositivo

firebase cmd:

gcloud firebase test android run \
  --app=app-debug.apk \
  --test=app-debug-androidTest.apk \
  --device model=shiba,version=36 \
  --timeout=5m \
  --num-flaky-test-attempts=2 \
  --directories-to-pull=/sdcard/screenshots \
  --environment-variables coverage=true

Se traduce como:

gcloud beta device-run sessions submit instrumentation \
  --device=shiba-36 \
  --apps=app-debug.apk \
  --test=app-debug-androidTest.apk \
  --instrumentation-timeout=5m \
  --flaky-test-attempts=3 \
  --paths-to-pull=/sdcard/screenshots \
  --additional-test-options coverage=true

Configuraciones de Flank para la ejecución en el dispositivo

flank options (flank.yml):

gcloud:
  app: app-debug.apk
  test: app-debug-androidTest.apk
  device:
    -   model: mediumphone-arm
      version: 32
  shard-time: 120
  smart-flank-gcs-path: gs://my-bucket/automation/smart-sharding/timing-record.yaml

Se traduce como:

Traduce directamente al comando de la CLI moderna:

gcloud beta device-run sessions submit instrumentation \
  --device=mediumphone-arm-32 \
  --apps=app-debug.apk \
  --test=app-debug-androidTest.apk \
  --bucket-name=my-bucket \
  --sharding-option=smart \
  --smart-sharding-target-duration=2m \
  --smart-sharding-record-name=timing-record

Opción 2: Archivo de marcas YAML declarativo (--flags-file)

Si prefieres mantener las configuraciones en un archivo YAML con control de versiones en lugar de cadenas de secuencia de comandos de shell, usa la función --flags-file integrada de gcloud:

# device-run-flags.yaml
# Note: gcloud requires keys to start with '--'
--device:
  -   mediumphone-arm-32
--apps:
  -   app-debug.apk
--test: app-debug-androidTest.apk
--bucket-name: my-bucket
--sharding-option: smart
--smart-sharding-target-duration: 2m
--smart-sharding-record-name: timing-record

Envía con la CLI:

gcloud beta device-run sessions submit instrumentation --flags-file=device-run-flags.yaml

(También puedes agregar o anular marcas en la línea de comandos, como agregar --async).

Descubrimiento del catálogo de dispositivos

listing & inspecting devices:

# List all available Android devices
gcloud beta device-run devices list --filter="platform:android"

# Filter devices with high fleet capacity (replaces legacy list-device-capacities)
gcloud beta device-run devices list --filter="availability.capacity=CAPACITY_HIGH"

# Describe a specific device (OS versions, form factors, orientation, locales, capacity)
gcloud beta device-run devices describe redfin-30

Ciclo de vida de la sesión de extremo a extremo en CI/CD

submitting, waiting, and inspecting sessions:

# 1. Submit asynchronously and capture session ID
SESSION_ID=$(gcloud beta device-run sessions submit instrumentation \
  --apps=app-debug.apk \
  --test=app-debug-androidTest.apk \
  --device=mediumphone-arm-32 \
  --async \
  --format="value(name)")

# 2. Wait for session completion in CI/CD pipeline
gcloud beta device-run sessions wait "$SESSION_ID"

# 3. Describe session summary (or pass --full for complete details)
gcloud beta device-run sessions describe "$SESSION_ID"

# 4. Cancel a running session if aborted
gcloud beta device-run sessions cancel "$SESSION_ID"