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

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 prueba de instrumentación de Android o un ejecutable de Android independiente con la CLI de gcloud beta device-run y encontrar los resultados en Google Cloud console. 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 esta Google Cloud CLI, deberás proporcionar tu Google Cloud ID de proyecto. Consulta gcloud beta 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 de.
2. Configuraste Developer Device Platform 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 una prueba instrumentada para Android o preparaste un ejecutable de Android independiente (como un objeto binario de C++ compilado, un ejecutor de comparativas o una secuencia de comandos de shell).

Paso 1: Configura la ejecución de la prueba o del ejecutable

Sugerencia: Para ver todas las opciones disponibles para los comandos submit, ejecuta gcloud beta device-run sessions submit instrumentation --help o gcloud beta device-run sessions submit android-executable --help.

Ahora que ejecutaste una sesión, explora algunas opciones de configuración:

Opciones para pruebas de instrumentación y ejecutables

• Varios dispositivos: Para ejecutar la misma prueba o ejecutable en varios dispositivos, proporciona la marca --device con varios IDs de dispositivo separados por comas, como --device shiba-34,tokay-36, o con varias marcas --device cada una de las cuales especifica un ID de dispositivo distinto (por ejemplo, --device shiba-34 --device tokay-36).
• Enviar archivos al dispositivo: Envía archivos adicionales (como pesos del modelo de AA, entradas de prueba o .so bibliotecas compartidas) al dispositivo antes de la ejecución con --other-files-to-push=SOURCE=DEST,.... SOURCE admite rutas de acceso locales y de Cloud Storage (gs://...), y DEST es la ruta de acceso de destino en el dispositivo.
• Extraer archivos del dispositivo: Extrae los archivos o directorios generados del dispositivo después de que se complete la ejecución con --paths-to-pull=DEVICE_PATH,....
• Bucket de Cloud Storage personalizado: Especifica un nombre de bucket de Cloud Storage existente (sin un esquema o ruta de acceso gs://) con --bucket-name=. Si no especificas un bucket, Google Cloud CLI usa o crea un bucket predeterminado llamado PROJECT_ID-devicerun.
• Reintentos de pruebas inestables: Establece la cantidad máxima de intentos por trabajo o fragmento para controlar la inestabilidad: --flaky-test-attempts=3 (el valor predeterminado es 1 intento).
• Entorno y diagnóstico del dispositivo: Configura la orientación del dispositivo (--orientation=portrait o landscape), la configuración regional (--locale=en-US), la ubicación GPS simulada (--coordinates=LATITUDE,LONGITUDE), la grabación de video de la pantalla (--video=always o on-failure), la recopilación de dumpsys (--dumpsys=always o on-failure) o la recopilación de bugreport (--bugreport=always o on-failure).
• Etiquetas: Adjunta etiquetas de par clave-valor definidas por el usuario a la sesión con --labels=KEY=VALUE,....

Opciones de prueba de instrumentación

• Apps adicionales: De manera opcional, puedes especificar uno o más archivos APK, AAB o APKS para instalar antes de ejecutar las pruebas con la --apps=path1,path2,...,path_n marca. El orden que especifiques es el orden en el que se instalarán estas apps.
• Tiempo de espera de la prueba: Limita la duración de la ejecución: --instrumentation-timeout=10m (el rango válido es de 1m a 3h y el valor predeterminado es 5m).

Opciones de ejecutable de Android

• Argumentos ejecutables: Pasa argumentos de línea de comandos al ejecutable con --executable-args=ARG,... como una lista separada por comas o repitiendo la marca. Cada elemento se convierte en un argumento, por lo que debes volver a escribir las líneas de comandos separadas por espacios en formato separado por comas (por ejemplo, --executable-args="--input=a.file,--threads=4"). Para pasar un argumento que contenga una coma, agrega el prefijo ^SEP^ al valor para especificar un separador diferente (por ejemplo, --executable-args="^;^--shape=1,224,224,3;--threads=4").
• Variables de entorno: Establece variables de entorno para el proceso ejecutable en el dispositivo con --executable-env-vars=KEY=VALUE,... (por ejemplo, --executable-env-vars=LD_LIBRARY_PATH=/data/local/tmp/lib).
• Tiempo de espera ejecutable: Limita la duración de la ejecución del ejecutable: --executable-timeout=10m (el rango válido es de 1m a 3h y el valor predeterminado es 5m, sin incluir el tiempo de preparación y limpieza del dispositivo).

Ejecuciones síncronas y asíncronas

De forma predeterminada, el comando submit es bloqueador (síncrono). Esperará a que se complete la prueba o el ejecutable 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:

Prueba de instrumentación de Android

Para un :

gcloud beta device-run sessions submit instrumentation \
  --device shiba-35 \
  --test ./ANDROID_TESTS.apk \
  --async

Ejecutable de Android

gcloud beta device-run sessions submit android-executable \
  --device shiba-35 \
  --executable ./MY_EXECUTABLE \
  --async

Esto muestra un ID de sesión de inmediato. Luego, puedes esperar con el comando sessions wait:

gcloud beta device-run sessions wait SESSION_ID

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

Varios dispositivos

Para ejecutar la misma prueba o ejecutable 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 distinto.

Prueba de instrumentación de Android

gcloud beta device-run sessions submit instrumentation \
  --device shiba-34,tokay-36 \
  --test ./ANDROID_TESTS.apk

O bien:

gcloud beta device-run sessions submit instrumentation \
  --device shiba-34 \
  --device tokay-36 \
  --test ./ANDROID_TESTS.apk

Ejecutable de Android

gcloud beta device-run sessions submit android-executable \
  --device shiba-34,tokay-36 \
  --executable ./MY_EXECUTABLE

O bien:

gcloud beta device-run sessions submit android-executable \
  --device shiba-34 \
  --device tokay-36 \
  --executable ./MY_EXECUTABLE

Tiempo de espera de la prueba y del ejecutable

Limita la duración de la ejecución de la prueba o del ejecutable:

Prueba de instrumentación de Android

gcloud beta device-run sessions submit instrumentation \
  --device shiba-35 \
  --test ./ANDROID_TESTS.apk \
  --instrumentation-timeout=10m

Ejecutable de Android

gcloud beta device-run sessions submit android-executable \
  --device shiba-35 \
  --executable ./MY_EXECUTABLE \
  --executable-timeout=10m

El rango válido es de 1m a 3h para las ejecuciones de Android y el valor predeterminado es 5m.

Versiones de software

Descubre y usa los paquetes de software y las versiones disponibles de AndroidX Test Orchestrator y examina sus ciclos de vida, versiones compatibles y metadatos antes de configurar las ejecuciones de prueba.

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

gcloud beta 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 beta device-run software-versions describe androidx-test-orchestrator-1-4-1

Recibirás un resultado similar al siguiente:

id: androidx-test-orchestrator-1-4-1
isDefault: true
lifecycle:
  state: ACTIVE
name: AndroidX Test Orchestrator 1.4.1
softwareType: ANDROIDX_TEST_ORCHESTRATOR
version: 1.4.1

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

gcloud beta device-run sessions submit instrumentation \
  --device shiba-35 \
  --test ./ANDROID_TESTS.apk \
  --orchestrator-version=1.4.1

Consulta Habilita Orchestrator para obtener más información.

Habilita Orchestrator

Para las pruebas de instrumentación, Developer Device Platform admite Android Test Orchestrator, que te permite ejecutar cada una de las pruebas de tu app dentro de su propia invocación de Instrumentation.

Cuando usas Orchestrator, haces lo siguiente:

• Evitas el estado compartido. Cada prueba se ejecuta en su propia instancia de Instrumentation. Por lo tanto, si tus pruebas comparten el estado de la app, la mayor parte de ese estado compartido se quitará de la CPU o la memoria del dispositivo después de cada prueba. Para quitar todo el estado compartido de la CPU y la memoria del dispositivo después de cada prueba, incluye el parámetro de configuración clearPackageData de la siguiente manera: --additional-test-options clearPackageData=true

• Aísla las fallas. Si falla una prueba, solo se elimina su propia instancia de Instrumentation. Esto significa que las demás pruebas se siguen ejecutando y proporcionan resultados de prueba completos.

Android Test Orchestrator está desactivado de forma predeterminada en Developer Device Platform. Para habilitar Orchestrator y especificar la versión que se usará durante la ejecución de la prueba, pasa la versión que seleccionaste a la --orchestrator-version=ORCHESTRATOR_VERSION marca en tu sessions submit instrumentation comando, de la siguiente manera:

gcloud beta device-run sessions submit instrumentation \
  --device shiba-35 \
  --test ./ANDROID_TESTS.apk \
  --orchestrator-version=1.4.1

Establece la marca en auto para usar la versión de Orchestrator predeterminada del sistema.

Nota: Dado que cada prueba de Orchestrator ejecuta su propia instancia de Instrumentation, el aumento en los tiempos de ejecución podría aumentar el uso de la cuota o el tiempo de facturación y hacer que excedas los límites de tiempo de espera de tus dispositivos. Es posible que debas aumentar la configuración de tiempo de espera de la instrumentación con la marca --instrumentation-timeout según corresponda.

Paso 2: Elige dispositivos

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

gcloud beta device-run devices list

Resultado de ejemplo:

ID        MAKE    NAME     MODEL FORM      OS_VERSION CAPACITY  AVAILABILITY  PRODUCTS
tegu-35   Google  Pixel 9a tegu  PHYSICAL  35         MEDIUM    LOW           Automation, Streaming
tokay-34  Google  Pixel 9  tokay PHYSICAL  34         HIGH      HIGH          Automation, Streaming

Consulta el Catálogo de dispositivos para obtener información sobre cómo filtrar esta lista. Para orientarte a un dispositivo específico para tu ejecución, usa su ID correspondiente (por ejemplo, tegu-35) en el comando submit.

Paso 3: Ejecuta la prueba o el ejecutable

Puedes enviar un APK de prueba de instrumentación de Android o un ejecutable de Android independiente.

Ejecuta una prueba de instrumentación

Ten en cuenta que estas marcas son obligatorias para las pruebas de instrumentación de Android:

• Dispositivo: Especifica un dispositivo con --device: --device shiba-35
• Prueba: Especifica el APK de prueba con --test: --test /path/to/test.apk

Para ejecutar la prueba de instrumentación, emite un sessions submit instrumentation comando similar al siguiente, con tus propios IDs de dispositivo y ruta de acceso de prueba:

gcloud beta device-run sessions submit instrumentation \
  --device shiba-34 \
  --apps /path/to/app.apk \
  --test /path/to/test.apk

Ejecuta un ejecutable de Android

Para ejecutar un ejecutable independiente (como un objeto binario de C++ compilado, un ejecutor de comparativas de aprendizaje automático integrado en el dispositivo como LiteRT o una secuencia de comandos de shell) directamente en un dispositivo Android sin empaquetarlo en un APK, usa el sessions submit android-executable comando.

Ten en cuenta que estas marcas son obligatorias para los ejecutables de Android:

• Dispositivo: Especifica un dispositivo con --device: --device shiba-35
• Ejecutable: Especifica la ruta de acceso local o de Cloud Storage al ejecutable con --executable: --executable /path/to/my_executable.

Para ejecutar el ejecutable, emite un comando similar al siguiente, con tus propios IDs de dispositivo y ruta de acceso ejecutable:

gcloud beta device-run sessions submit android-executable \
  --device shiba-34 \
  --executable /path/to/my_executable \
  --executable-args="--input=/data/local/tmp/file.name,--threads=4" \
  --other-files-to-push=/path/to/model.tflite=/data/local/tmp/model.tflite \
  --paths-to-pull=/data/local/tmp/output

La carpeta del informe de resultados del trabajo se puede encontrar en una ruta de acceso de Cloud Storage como gs://BUCKET_NAME/automation/sessions/SESSION_ID/. Consulta el resultado del comando para obtener el vínculo, que es similar a https://console.cloud.google.com/storage/browser/BUCKET_NAME/automation/sessions/SESSION_ID/.

Paso 4: Usa la fragmentación

Para incluir pruebas de instrumentación de Developer Device Platform en un flujo de trabajo de integración continua y entrega continua (CI/CD), debes considerar la fragmentación de las pruebas. Con la fragmentación de pruebas, se divide un conjunto de pruebas de instrumentación en subgrupos (fragmentos) que se ejecutan por separado de forma aislada. Developer Device Platform ejecuta automáticamente cada fragmento en paralelo con varios dispositivos y completa todo el conjunto de pruebas en menos tiempo.

Precaución: La fragmentación de pruebas puede tener un costo superior. Aunque la fragmentación de pruebas reduce el tiempo que lleva ejecutar todas las pruebas, la sobrecarga de iniciar tu app en cada fragmento puede aumentar los tiempos de cada dispositivo.

Paso 4.1: Elige la opción de fragmentación

Si tus trabajos solo tienen una pequeña cantidad de casos de prueba o el tiempo total de ejecución de todos los casos de prueba no es largo, no es necesario usar la fragmentación. Si tienes una gran cantidad de casos de prueba o el tiempo total de ejecución de todos sus casos de prueba es largo, considera usar la fragmentación.

Developer Device Platform admite la fragmentación inteligente y uniforme. Cuando decidas cómo fragmentar tus pruebas, considera las siguientes opciones:

• Si todos los casos de prueba tardan una cantidad de tiempo similar, usa la fragmentación uniforme dividiendo todos los casos de prueba en n fragmentos.

• Cuando el tiempo de ejecución de los diferentes casos de prueba varía mucho, usa la fragmentación inteligente. Developer Device Platform usa el tiempo histórico de ejecución de pruebas para crear diferentes fragmentos y trata de completar todos los fragmentos en una duración similar.

Nota: La cantidad de fragmentos es configurable, por lo que, cuando Developer Device Platform ejecuta muchos fragmentos en paralelo, las ejecuciones de prueba podrían verse limitadas por la disponibilidad de dispositivos. Por este motivo, recomendamos que la cantidad de dispositivos especificada en la marca --device sea menor o igual que la cantidad de fragmentos.

Fragmentación uniforme

Para fragmentar tus pruebas con la fragmentación uniforme, incluye las marcas --sharding-option=uniform y --uniform-sharding-count= en el comando sessions submit instrumentation, de la siguiente manera:

gcloud beta device-run sessions submit instrumentation \
    --test path/to/test.apk \
 --device shiba-34,tokay-36 \
    --sharding-option=uniform \
    --uniform-sharding-count=2

Deberías ver un resultado que indique Job status: 2 running. El servicio crea dos trabajos, uno para cada dispositivo. Debido a que las entradas de ambos trabajos son idénticas, el servicio centraliza la validación y la realiza solo una vez.

Verás las dos publicaciones de empleo enumeradas por separado en el resultado final del comando cuando se complete:

JOB NAME  EXECUTION NAME  EXECUTION RESULT
job-000   execution-000   PASSED
job-001   execution-000   PASSED

Fragmentación inteligente

Para fragmentar tus pruebas con la fragmentación inteligente, incluye las marcas --sharding-option=smart, --smart-sharding-max-shard-count=, --smart-sharding-target-duration= (en minutos o 1 h) y --smart-sharding-record-name= en el comando sessions submit instrumentation, de la siguiente manera:

gcloud beta device-run sessions submit instrumentation \
    --test path/to/test.apk \
    --device shiba-34,shiba-35,tokay-36 \
    --sharding-option=smart \
    --smart-sharding-max-shard-count=3 \
    --smart-sharding-target-duration=5m \
    --smart-sharding-record-name=test.yaml

Deberías ver un resultado final que indique que se ejecutaron tres trabajos:

Session [session-3cd0564a] finished with result [ERROR].
JOB NAME  EXECUTION NAME  EXECUTION RESULT
job-000   execution-000   PASSED
job-001   execution-000   PASSED
job-002   execution-000   PASSED

A continuación, se ofrece un resumen de las marcas de fragmentación inteligente que se usan aquí:

• --smart-sharding-max-shard-count=SMART_SHARDING_MAX_SHARD_COUNT - Especifica la cantidad máxima de fragmentos que se crearán para la fragmentación inteligente. Si no se establece o se establece en 0, se usan los límites máximos definidos por el sistema. El rango válido es de 0 a 20 para dispositivos físicos y de 0 a 200 para dispositivos virtuales.

• --smart-sharding-target-duration=SMART_SHARDING_TARGET_DURATION - Especifica el tiempo de ejecución objetivo (p.ej., 2 m, 10 m, 1 h) por fragmento para la fragmentación inteligente. El rango válido es de 2 m a 1 h. Es obligatorio cuando --sharding-option=smart.

• --smart-sharding-record-name=SMART_SHARDING_RECORD_NAME - Especifica el nombre del archivo de registro de fragmentación inteligente, sin incluir la extensión del archivo. Es obligatorio cuando --sharding-option=smart. Este archivo YAML se encuentra en el Google Cloud bucket de Storage especificado por --bucket-name en el smart-sharding/ directorio. Si el archivo no existe, se creará automáticamente; de lo contrario, su contenido se actualizará cuando se complete la sesión.

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

Para el modo asíncrono y síncrono de los comandos sessions submit instrumentation y sessions submit android-executable, puedes usar el comando sessions describe para consultar el estado del trabajo durante la ejecución o obtener el resultado después de que se complete:

gcloud beta device-run sessions describe SESSION_ID

El resultado resume los resultados de la prueba y los vínculos a los resultados en Google Cloud console. Por ejemplo:

Session SESSION_ID finished with result [FAILED].
Result files are stored at [https://console.cloud.google.com/storage/browser/BUCKET_NAME/automation/sessions/SESSION_ID/].
JOB NAME  EXECUTION NAME  EXECUTION RESULT
job-000   all             FAILED: 2 test cases failed, 5 passed

Usa el siguiente comando para enumerar todas las sesiones en ejecución y completadas:

gcloud beta device-run sessions list

Recibirás un resultado que contiene la lista de sesiones en tu proyecto, similar al siguiente:

SESSION_ID                                    START_TIME                STATE
session-4825e153                              2026-07-28T16:38:43.155Z  DONE
session-813ca602                              2026-07-28T22:40:32.415Z  DONE
session-67cd0570                              2026-07-16T08:25:55.474Z  DONE
session-17cc299c                              2026-07-14T14:31:33.649Z  DONE
session-911d0763                              2026-07-09T00:39:02.051Z  DONE
session-4e943fea                              2026-07-15T23:08:32.252Z  DONE
session-0132e458                              2026-08-20T18:33:19.751Z  DONE
session-1077f07b                              2026-07-28T22:35:43.848Z  DONE
session-71b054c6                              2026-07-15T01:15:41.643Z  DONE
session-4f8b2e45                              2026-08-06T23:11:56.161Z  DONE

El comando de lista sessions admite todas las opciones de marca estándar de Google Cloud CLI Cloud. Por ejemplo:

gcloud beta device-run sessions list --limit 5

Esto genera resultados similares a los siguientes:

SESSION_ID                            START_TIME                STATE
session-4825e153                      2026-07-28T16:38:43.155Z  DONE
session-813ca602                      2026-07-28T22:40:32.415Z  DONE
93ec2df2-d5bf-4c36-b7f7-c2a4fb0dc3ce  2026-07-03T05:10:58.015Z  DONE
session-67cd0570                      2026-07-16T08:25:55.474Z  DONE
session-17cc299c                      2026-07-14T14:31:33.649Z  DONE

Para encontrar todas las sesiones en ejecución, ejecuta lo siguiente:

gcloud beta device-run sessions list --filter RUNNING

Si tienes sesiones en ejecución, verás resultados similares a los siguientes:

SESSION_ID        START_TIME  STATE
session-d7ff8b81              RUNNING

De lo contrario, recibirás Listed 0 items.

Para cancelar una sesión en ejecución, ejecuta este comando con tu ID de sesión:

gcloud beta device-run sessions cancel SESSION_ID

El comando se muestra de inmediato, ya que la sesión solo se marca para cancelarse. La cancelación se realiza de forma asíncrona en el backend.

Si la sesión ya finalizó, solo se imprimirá el estado actual. Solicitar la cancelación de una sesión finalizada no es un error.

¿Qué sigue?

A continuación, busca y analiza registros.