Maestro en CI con GitHub Actions — del editor a producción sin tocar emuladores manuales nunca más

Hoy CI mobile deja de ser doloroso. Pero antes del primer push, la pregunta honesta que cualquier QA se hace cuando ve “Maestro en CI”: ¿esto va a correr el lunes en mi pipeline, o es teoría con repo de juguete?

Spoiler: el repo que vas a forkear corre Maestro en GitHub Actions verde en 2 minutos 10 segundos, primer intento, cero debug. Lo validé tres veces (verde inicial, force-fail para verificar artifacts, verde de cleanup) antes de publicar esta guía. Los tres runs están vivos en adrianagit87/calidad-sin-humo-mobile-ci-maestro, los puedes inspeccionar uno por uno. Lo único que cambia entre ese repo y tu pipeline real son tres líneas. Te las marco al final.

¿Por qué CI mobile fue históricamente un sufrimiento?

El dato simple: hasta 2024, levantar un emulador Android en un runner de CI tardaba 15 minutos. Cada vez. En cada PR. Multiplicalo por una suite de 50 PRs por semana y entiendes por qué la mayoría de equipos LATAM tienen Maestro corriendo en la laptop de un QA y nada más.

La diferencia no es solo cuantitativa. Tres piezas técnicas se alinearon en los últimos 2 años para que esto sea viable, y vale la pena nombrarlas para que entiendas dónde mirar cuando algo se rompa:

• KVM (Kernel Virtual Machine) — la aceleración por hardware del emulador. En palabras simples: sin KVM, una máquina virtual (como el emulador Android) emula el CPU por software, y eso es ~15 veces más lento. CON KVM, la máquina virtual aprovecha el CPU físico directamente. Resultado concreto: el emulador Android tardaba 15 minutos en bootear, ahora bootea en 90 segundos. GitHub habilitó KVM en sus runners Linux a mediados de 2024 — ese fue el cambio que destrabó todo. (Las 3 líneas raras de echo 'KERNEL=="kvm"...' que vas a ver en el workflow.yml son exactamente la configuración que habilita ese acceso.)

• Runners Linux gratis del free tier de GitHub. Los “runners” son las máquinas que GitHub te presta gratis para correr tu CI. El free tier te da 2000 min/mes en Linux contra 200 min/mes en macOS — Linux te rinde 10 veces más. Antes de KVM, Linux no servía para Android (emulador inutilizablemente lento) y había que pagar macOS o Maestro Cloud. Ahora Linux gana en todo.

• La GitHub Action reactivecircus/android-emulator-runner. Una “Action” en GitHub Actions es como un plugin reusable que alguien de la comunidad publicó. Esta action específica sabe levantar un emulador Android, esperar a que bootee, ejecutar tu script de tests, y cerrarlo al final. Sin ella, tendrías que escribir 100+ líneas de YAML manejando todo eso a mano. Con ella, son 6 líneas en tu workflow.

Las tres juntas son la receta que hace viable correr Maestro en CI gratis para repos personales y equipos chicos. Antes la única alternativa era pagar Maestro Cloud o tragar runners macOS 10x más caros.

Pre-requisitos

• Tener Maestro CLI funcionando local (lo cubrimos en Parte 2)
• Cuenta GitHub gratis
• Eso es todo. No necesitas Android Studio, no necesitas SDK manager local, no necesitas Java en tu máquina

1. Forkea y arranca: verde en 5 minutos

Antes de explicarte una sola línea del workflow.yml, quiero que veas verde con tus propios ojos. La regla pedagógica de esta serie: primero corre, después entiende.

Paso 1 — Forkear el repo

¿Qué significa “hacer fork”? Es crear una copia personal del repo en tu cuenta de GitHub. La copia queda independiente del original — puedes modificarla todo lo que quieras sin afectar el repo del autor. Es lo que necesitas para que GitHub Actions corra el workflow contra TU copia, usando los minutos gratis de TU cuenta.

Ve a adrianagit87/calidad-sin-humo-mobile-ci-maestro, haz click en el botón “Fork” arriba a la derecha, y confirma. En 5 segundos tienes tu copia en tu-usuario/calidad-sin-humo-mobile-ci-maestro. El repo es público, licencia MIT, diseñado para forkear y aprender.

Paso 2 — Habilitar Actions en tu fork

GitHub deshabilita Actions por default en forks por seguridad. Ve a la pestaña Actions de tu fork y haz click en “I understand my workflows, go ahead and enable them”. Una sola vez, ya queda activo.

Paso 3 — Disparar el primer run

Tenés tres opciones:

# Opción A: push trivial (modifica el README, commit, push)
git clone https://github.com/TU-USUARIO/calidad-sin-humo-mobile-ci-maestro.git
cd calidad-sin-humo-mobile-ci-maestro
echo "" >> README.md
git commit -am "chore: trigger CI"
git push

# Opción B: workflow_dispatch desde la UI
# Ve a Actions > Maestro CI > Run workflow > Run workflow

# Opción C: abre un PR contra main
# El workflow corre también en pull_request

Paso 4 — Ver el run

Vuelve a la pestaña Actions. Vas a ver tu workflow con un círculo amarillo (queued), después azul (in progress), después verde (success). En total: ~2 minutos.

Pero ahora la pregunta: ¿qué hace ese workflow.yml por debajo, y cómo lo adaptas a tu app real? Para eso necesitas entender línea por línea. Vamos.

2. El workflow.yml verificado, línea por línea

Acá está el archivo completo, las 52 líneas que validé en CI:

name: Maestro CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  workflow_dispatch:

jobs:
  smoke-test:
    name: Smoke test (Android API 33)
    runs-on: ubuntu-latest
    timeout-minutes: 20

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Enable KVM acceleration
        run: |
          echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules
          sudo udevadm control --reload-rules
          sudo udevadm trigger --name-match=kvm

      - name: Set up JDK 17
        uses: actions/setup-java@v4
        with:
          java-version: "17"
          distribution: "temurin"

      - name: Install Maestro CLI
        run: |
          curl -fsSL https://get.maestro.mobile.dev | bash
          echo "$HOME/.maestro/bin" >> $GITHUB_PATH

      - name: Run Maestro on Android emulator
        uses: reactivecircus/android-emulator-runner@v2
        with:
          api-level: 33
          arch: x86_64
          profile: pixel_6
          emulator-options: -no-window -gpu swiftshader_indirect -noaudio -no-boot-anim
          disable-animations: true
          script: |
            maestro download-samples
            adb install -r samples/wikipedia.apk
            maestro test .maestro/

      - name: Upload artifacts on failure
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: maestro-failure-${{ github.run_number }}
          path: |
            ~/.maestro/tests/**
            **/*.png
          retention-days: 7

Vamos por bloques.

2.1 — Triggers: cuándo corre el workflow

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  workflow_dispatch:

Tres triggers, cada uno con un propósito distinto:

• push: branches: [main] — corre cuando haces merge a main. Es tu smoke continuo de la rama principal.
• pull_request: branches: [main] — corre cuando alguien abre un PR contra main. Es el gate de calidad: si Maestro falla, el PR queda marcado en rojo. Este es el trigger que cambia la cultura del equipo.
• workflow_dispatch — habilita el botón “Run workflow” en la UI de GitHub. Útil para correr el workflow manualmente sin hacer push, por ejemplo después de actualizar un secret o para re-validar después de un cambio externo.

on:
  schedule:
    - cron: "0 3 * * *" # 03:00 UTC todos los días

2.2 — Runner y timeout

runs-on: ubuntu-latest
timeout-minutes: 20

Linux, no macOS. Esta es la decisión más importante del workflow. macOS runners cuestan 10x más minutos del free tier de GitHub (200 min/mes en macOS vs 2000 min/mes en Linux). Con KVM habilitado en Linux desde mediados de 2024, ya no hay ventaja real de macOS para Android. La única razón para usar macOS sería testing iOS — y para eso tienes otra historia (xcrun simctl, no adb install).

timeout-minutes: 20 es protección: si algo se cuelga (emulator boot infinito, Maestro test que loopea), GitHub mata el job a los 20 min en lugar de gastarte minutos del free tier indefinidamente.

2.3 — Habilitar KVM

- name: Enable KVM acceleration
  run: |
    echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules
    sudo udevadm control --reload-rules
    sudo udevadm trigger --name-match=kvm

KVM (Kernel Virtual Machine) es la aceleración por hardware que hace que el emulador Android arranque en 90 segundos en lugar de 15 minutos. Estas tres líneas configuran los permisos de /dev/kvm para que el action de emulator pueda usarlo.

Sin estas líneas, el emulator boot tarda 15x más. Las copias textual y olvidas que existen.

2.4 — JDK 17 + Maestro CLI

- name: Set up JDK 17
  uses: actions/setup-java@v4
  with:
    java-version: "17"
    distribution: "temurin"

- name: Install Maestro CLI
  run: |
    curl -fsSL https://get.maestro.mobile.dev | bash
    echo "$HOME/.maestro/bin" >> $GITHUB_PATH

JDK 17 lo necesita el Android SDK por debajo. Distribución temurin es la libre de Eclipse Adoptium.

Maestro se instala con el script oficial (curl -fsSL https://get.maestro.mobile.dev | bash), que pone el binario en $HOME/.maestro/bin. La línea echo "..." >> $GITHUB_PATH agrega esa ruta al PATH para que los siguientes steps puedan llamar maestro sin path absoluto.

2.5 — El action que hace todo el trabajo pesado

- name: Run Maestro on Android emulator
  uses: reactivecircus/android-emulator-runner@v2
  with:
    api-level: 33
    arch: x86_64
    profile: pixel_6
    emulator-options: -no-window -gpu swiftshader_indirect -noaudio -no-boot-anim
    disable-animations: true
    script: |
      maestro download-samples
      adb install -r samples/wikipedia.apk
      maestro test .maestro/

Este step usa reactivecircus/android-emulator-runner@v2, el estándar de facto para emulador Android en GitHub Actions. Manejado por la comunidad, 1.5k+ repos lo usan.

Qué hace cada parámetro:

El bloque script: son las tres líneas que importan:

1. maestro download-samples — descarga samples/wikipedia.apk desde el CDN oficial de Maestro
2. adb install -r samples/wikipedia.apk — instala el APK en el emulador (el -r permite reinstall si ya está)
3. maestro test .maestro/ — corre todos los .yaml de la carpeta .maestro/

2.6 — Artifacts on failure (lo cubrimos en la sección 3)

- name: Upload artifacts on failure
  if: failure()
  uses: actions/upload-artifact@v4
  with:
    name: maestro-failure-${{ github.run_number }}
    path: |
      ~/.maestro/tests/**
      **/*.png
    retention-days: 7

Este step solo se ejecuta cuando algo falló (el if: failure() lo controla). Sube los outputs de Maestro + cualquier PNG generado. Te explico el detalle en la siguiente sección, porque acá es donde está la diferencia entre “fallo críptico de CI” y “debug del lunes a la mañana en 5 minutos”.

3. Cuando algo falla: los artifacts

La promesa de cualquier guía de CI es “te aviso cuando falla”. La promesa que pocas guías cumplen es “te doy el contexto suficiente para que entiendas POR QUÉ falló sin reproducirlo local”. Maestro la cumple, gratis.

Para verificar esto, en mi setup hice un force-fail deliberado: agregué un flow con assertVisible: "TextoInexistenteParaForzarFallo" y pusheé. Run #26205431483 falló a los 2 minutos 34 segundos. El step Upload artifacts on failure se ejecutó automáticamente. Esto fue lo que GitHub puso disponible para descargar:

Cómo descargas el artifact

Cuando un workflow falla, ve al run en la pestaña Actions y en el bottom encuentras la sección Artifacts. Haces click en maestro-failure-{run_number} y bajas un ZIP. Adentro tienes esta estructura:

maestro-failure-2/
├── .maestro/tests/2026-05-21_043007/
│   ├── commands-(01-smoke).json         # 1.2 KB — log estructurado smoke
│   ├── commands-(02-force-fail).json    # 89 KB — log estructurado del flow que falló
│   ├── maestro.log                       # 17 KB — log textual de toda la ejecución
│   └── screenshot-❌-1779337835196-(02-force-fail).png  # 176 KB — AUTO-SCREENSHOT
└── work/calidad-sin-humo-mobile-ci-maestro/
    ├── 01-launch.png    # screenshot manual smoke que pasó
    └── 01-before-fail.png   # screenshot manual del flow que iba a fallar

El auto-screenshot del fallo es la pieza que cambia todo

Mira el nombre del archivo: screenshot-❌-1779337835196-(02-force-fail).png. Ese ❌ es literal en el filename. Maestro toma una captura del estado del emulador exactamente en el momento en que el assert falla, sin que la pidas. Si tu test rompía porque cambiaron un botón de lugar, vas a ver el botón en su nueva posición sin tener que reproducirlo en tu máquina.

Por qué if: failure() y no always

Una decisión deliberada del workflow: artifacts SOLO en fallos, no en cada run. Razones:

1. Storage: cada artifact con screenshots ronda 1.5-3 MB. Si subes en cada run verde, en 1 mes tienes 5 GB de artifacts inútiles que GitHub te cobra a partir del free tier.
2. Foco: cuando entras a un run, si hay artifact disponible es porque pasó algo interesante. Si siempre hay, dejas de mirarlo.
3. Retención: retention-days: 7 automáticamente borra los artifacts viejos. Una semana es suficiente para que reacciones al fallo, sin acumular basura.

4. De Wikipedia a TU app en CI

Hasta acá tu workflow corre Maestro contra Wikipedia oficial. Para que sirva en producción tienes que cambiar 3 cosas. Solo 3. El resto del YAML queda idéntico.

Los 3 cambios

Para el primero, las tres opciones más comunes que veo en repos reales:

# Opción A — APK como artifact de un build job previo
- name: Download APK from build job
  uses: actions/download-artifact@v4
  with:
    name: app-debug.apk
    path: builds/

# Opción B — APK desde GitHub Releases (releases privados con token)
- name: Download APK from latest release
  run: gh release download -p "*.apk" -R tu-org/tu-app -D builds/
  env:
    GH_TOKEN: ${{ secrets.GH_TOKEN }}

# Opción C — APK desde Google Cloud Storage
- name: Download APK from GCS
  run: gcloud storage cp gs://tu-bucket/builds/latest.apk builds/

Y después en el script del emulator-runner:

script: |
  adb install -r builds/*.apk
  maestro test .maestro/

Lo demás queda exactamente igual. Mismo reactivecircus/android-emulator-runner, mismos api-level: 33, mismas líneas de KVM, mismo artifact on failure.

Las 3 trampas reales del primer día

Cuando hagas esta migración, te vas a chocar con estas tres cosas. Te las marco para que las anticipes.

Trampa 1 — APK ofuscado en release builds. Si tu build de producción usa ProGuard/R8 (las herramientas que comprimen y “ofuscan” el código Android para hacerlo más liviano y difícil de leer por afuera), los IDs de los elementos de UI llegan a Maestro como :id/a, :id/b, :id/c — letras sin sentido. Maestro no puede tapearlos por ID porque esas letras cambian en cada release.

Solución concreta: en el próximo refinement le pides al equipo dev esto exacto: “Necesitamos que el script de build genere DOS variantes en cada compilación — una debug SIN ProGuard/R8 que apunta a CI de QA, y la release con todo activado que va a Play Store. Son ~5 líneas en build.gradle.” Casi todos los proyectos Android ya manejan este patrón internamente (se llama “build variants”), solo que el equipo QA muchas veces no se entera. Mientras consigues eso, hay un workaround: pídele al equipo dev que les agreguen accessibility IDs (etiquetas semánticas tipo accessibility-id="login_button") a los 5-10 elementos críticos. Los accessibility IDs son metadata aparte del código compilado y sobreviven a la ofuscación.

Trampa 2 — AAB en lugar de APK. Desde 2021 Google obliga a publicar a Play Store usando AAB (Android App Bundle), un formato más nuevo que el APK clásico. Si tu equipo dev publica directo a Play Store, lo que vas a recibir es un .aab. Maestro no lo instala directo — solo entiende .apk.

Solución concreta: dos caminos posibles.

• Camino fácil (recomendado): convences al equipo dev de generar un APK debug paralelo solo para CI de QA. Son las mismas ~5 líneas en build.gradle que mencioné en Trampa 1 — un solo cambio cubre ambas trampas. APK debug para QA, AAB para Play Store. Cero conflicto.
• Camino complicado: instalas bundletool (herramienta oficial de Google) en el runner y extraes el APK del AAB en tiempo de CI con bundletool build-apks --bundle=app.aab --output=app.apks. Funciona pero suma minutos al runner y un punto extra de fallo. Evítalo si puedes pelear por el camino fácil.

Trampa 3 — Tests que necesitan datos de seed (usuarios, productos, configuración). Si tu flow asume que existe un usuario qa@empresa.com / test123 o un producto con código SKU-001, ese dato tiene que existir en el ambiente al que apunta tu emulador. Esto NO es trampa de Maestro — es trampa de cualquier suite E2E (web o mobile, da igual).

Solución concreta, ordenada de más fácil a más sofisticada:

1. Tests pre-login únicamente. Tu primera versión de CI mobile prueba solo flujos que NO requieren autenticación: onboarding, búsqueda pública, navegación entre secciones. Cero setup de datos. Para empezar es perfecto y ya te valida toda la infraestructura.
2. Step de seed antes de los flows. Antes del maestro test, agregas un step en el workflow que llama a un endpoint admin de tu ambiente staging para crear el dato. Ejemplo concreto: curl -X POST https://staging.tuempresa.com/admin/test-user -d email=qa@test.com. Requiere coordinación con el equipo backend para que expongan ese endpoint solo en staging (NUNCA en producción).
3. Feature flag de “modo testing”. El equipo dev habilita un flag tipo ALLOW_TEST_USERS=true que solo está activo en builds de QA. Con el flag prendido, la app permite crear usuarios con dominio @test.com sin pasar verificaciones de email/SMS. Requiere varios sprints de coordinación pero es la solución más escalable cuando tu suite supera los 20-30 flows.

5. Maestro Cloud vs runner propio: cuándo conviene cada uno

Maestro Cloud es la oferta paid del equipo de Maestro: ellos manejan los devices/emuladores en su infraestructura, tú solo pusheas tus flows y recibes resultados. Cuesta desde USD $50/mes para teams chicos, plan free trial para evaluar.

Disclaimer honesto: no probé Maestro Cloud en este hands-on. La comparativa que sigue está basada en docs oficiales, posts de comunidad, y benchmarks publicados — no en pruebas mías. Si llegas al punto donde lo necesitas y tienes data real, escríbeme y la actualizo.

Mi recomendación honesta

Empieza con runner propio. Migra a Maestro Cloud cuando:

1. Tu suite supere 50 flows y los runs en GitHub Actions tarden >15 min
2. Necesites testear en devices reales (no emulator), por ejemplo para validar performance, sensors, o quirks de hardware específicos
3. Estés pagando GitHub Actions Pro/Enterprise y los minutos sigan siendo cuello de botella
4. Tu equipo necesite el dashboard de Cloud para que stakeholders no técnicos vean resultados sin entrar a GitHub

Si estás arrancando, runner propio cubre el 90% de los casos en LATAM. No te apures a pagar.

Cierre — qué tienes ahora

Si seguiste la guía completa, en estos 25 minutos pasaste de “nada en CI” a:

• ✅ Un repo público forkeado con Maestro corriendo en GitHub Actions
• ✅ Workflow.yml de 52 líneas que entiendes línea por línea
• ✅ Trigger en cada push a main y en cada PR
• ✅ Auto-screenshot del fallo + log estructurado cuando algo rompe
• ✅ El patrón de 3 cambios para llevarlo a tu app real
• ✅ Criterio para decidir si y cuándo migrar a Maestro Cloud

Cierre de la serie Mobile Testing

Esta guía cierra el arco que arrancó con el elefante en la sala y siguió con tu primer test mobile en 30 minutos. Si las tres piezas las hiciste hands-on, tienes base sólida para llevar mobile testing a tu equipo HOY. No es teoría más. Es práctica con código que corre.

Lo que viene después en el blog sobre mobile, sin fechas comprometidas:

• Playwright para mobile web — calidadsinhumo.com es una PWA (Progressive Web App: un sitio web que se puede instalar como app desde el browser, sin pasar por la Play Store). Testeada con Playwright emulando iPhone 15 y Pixel 5. Cuándo conviene esto en lugar de Maestro nativo.
• Appium vs Maestro vs Detox en 2026 — comparativa post-experiencia, no antes. Cada uno tiene su nicho.
• Testing de gestos complejos en mobile — swipe-to-delete, pinch-to-zoom, long-press. Los gestos donde Maestro brilla y donde Appium sufre.

Cuando los publique, los suscriptores del newsletter se enteran primero. Como siempre.