Ejecución de dispositivo de la plataforma para desarrolladores

En esta guía, se describe cómo ejecutar una prueba de instrumentación de Android con la gcloud beta device-run CLI y encontrar los resultados en Google Cloud console. Se supone que tienes una Google Cloud cuenta y un proyecto.

Para usar esta Google Cloud CLI, deberás proporcionar tu Google Cloud proyecto ID.

Antes de comenzar

En estos pasos, se supone que ya creaste un Google Cloud proyecto, completaste los pasos de configuración en la plataforma de dispositivos para desarrolladores Guía de inicio rápido y te autenticaste con gcloud en la terminal.

Además, deberás tener una prueba de instrumentación de Android lista para ejecutarse. Consulta Cómo compilar pruebas instrumentadas para obtener orientación.

Además, debes haber identificado los IDs de los dispositivos en los que deseas ejecutar tus cargas de trabajo. Consulta Catálogo de dispositivos para obtener instrucciones.

Ejecutar una prueba

Ahora que conoces los IDs de los dispositivos disponibles para probar tu app, puedes especificar dispositivos con el gcloud beta device-run sessions submit instrumentation comando y la --device marca para ejecutar pruebas de instrumentación.

Para ejecutar la prueba, emite un comando similar al siguiente, pero con tus propios IDs de dispositivo y ruta de prueba:

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

La carpeta del informe de resultados del trabajo se puede encontrar en una ruta de Cloud Storage, como gs://<your_project_id>/automation/sessions/session-id/. Consulta el resultado de la prueba para obtener el vínculo, similar a https://console.cloud.google.com/storage/browser/your_project_id/automation/sessions/session-id/.

Cómo configurar la ejecución de la prueba

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

  • Para ejecutar las mismas pruebas en varios dispositivos, proporciona la marca --device flag varias veces, como --device shiba-34 --device tokay-36.
  • De manera opcional, puedes especificar uno o más APKs para instalar antes de ejecutar las pruebas con la marca --apps=path1,path2,...,path_n. El orden que especifiques es el orden en el que se instalarán estas apps.
  • Debes especificar tu APK de prueba con la marca --test.
  • Cuando especificas una ruta de acceso local con las marcas --apps o --test, la CLI de Google Cloud la copia automáticamente a tu bucket de Cloud Storage en gs://my-project-id/automation/inputs/date_time_four_chars_suffix/ cada vez que ejecutas el comando.
  • Debido a que subir APKs grandes puede llevar mucho tiempo, puedes hacer referencia directamente a tus APKs con sus rutas de acceso gs:// de Cloud Storage para ahorrar tiempo de carga.

El comando sessions submit instrumentation bloquea los resultados de la sesión de forma predeterminada, lo que significa que esperará a que finalice la ejecución de la prueba y generará resultados similares a los siguientes:

Using the default Cloud Storage bucket [gs://<my-project-id>] for input and result files. Will create the bucket if it does not exist.
Uploading [app.apk].
Uploading [test.apk].

Initiated long-running operation [operation-number] to create session.
Creating session [session-id] in location [global].
Result files will be stored at [https://console.cloud.google.com/storage/browser/<my-project-id>/automation/sessions/session-id/].
Waiting for session [session-id] to complete....done.

Session [session-id] finished with result [FAILED].
JOB NAME  EXECUTION NAME  EXECUTION RESULT
job-000   all             FAILED: 2 test cases failed, 5 passed

Para ejecutar el comando de forma asíncrona, incluye la marca --async. Esto permite que el comando salga inmediatamente después de subir archivos a Cloud Storage y de imprimir el ID de operación y el ID de sesión. Puedes usar el comando operations wait y el ID de operación para esperar la ejecución. Se bloqueará hasta que se complete el trabajo:

gcloud beta device-run operations wait your_operation_id

Usar la fragmentación

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

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

La plataforma de dispositivos para desarrolladores 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. La plataforma de dispositivos para desarrolladores 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.

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 \
    --device 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 las realiza solo una vez.

Verás los dos trabajos enumerados 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 \
    --device shiba-35 \
    --device 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 incluye 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-max-shard-count: Especifica la cantidad máxima de fragmentos que se crearán. La cantidad de dispositivos especificados en la marca --device debe ser menor o igual que este valor.

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

Explora y administra la ejecución de la prueba

Para el modo asíncrono y síncrono del comando sessions submit instrumentation, 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/your_project_id-devicerun/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

Recibe 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

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

gcloud beta device-run sessions cancel your_session_id

¿Qué sigue?

A continuación, busca y analiza registros.