Prepare & launch the Maestro smoke-test suite

This skill is a setup + handoff flow. Its job is to get everything ready so .maestro/scripts/run-smoke-tests.sh will work on the first try, then give the user the CLI command.

It does NOT own the test-runner mechanics. Ordering, per-flow recording, report generation, and the "recordings are kept only for failures, outside the repo" contract all live in the script itself.

Scope (what this skill is responsible for)

1. Tooling — set up the pinned Maestro and Java with .maestro/scripts/configure-toolchain.sh, and confirm adb is on PATH.
2. Device — confirm the devices the profile needs exist: a phone, plus a tablet for full. Pass AVD names and the runner starts them, the tablet only when the POS flows begin. Choose the runner --device and --pos-device values with the user.
3. APK — the runner installs the latest release by itself; ask only whether the user wants a local release build instead.
4. .env.local — check it with lint-env.py and the doctor, which name missing variables without printing values.
5. Handoff — print the exact CLI command. If the user explicitly asks ("run it", "go ahead", etc.), invoke the script for them and stream its output.

Everything below the handoff — P2 ordering, store selection, seed/cleanup, animation restore, retry accounting, artifact policy, HTML + JUnit reports — is handled by .maestro/scripts/run-smoke-tests.sh.

Steps

1. Check tooling

Run source .maestro/scripts/configure-toolchain.sh. It installs the pinned Maestro 2.9.0 into the workspace, selects Java 21 and fails with a clear message when either is missing. Then run command -v adb; if adb is missing, tell the user to install the Android SDK platform-tools and stop.

Each Bash call starts a new shell, so put source .maestro/scripts/configure-toolchain.sh && in front of every later command that runs Maestro, the doctor or the runner.

2. Ensure an emulator is running

Run adb devices. Count the lines whose second column is device.

• 0 devices: list AVDs with emulator -list-avds.
  • If none → tell the user to create one in Android Studio (AVD Manager) and stop.
  • If exactly one → ask the user if they want to boot it, then emulator -avd <name> -no-snapshot-save & (backgrounded). Find its emulator-* serial in adb devices and poll adb -s <serial> shell getprop sys.boot_completed until 1 (up to ~90s); a phone on wireless adb can be attached too.
  • If multiple → ask which one to boot.
• 1+ devices: proceed. For full, a tablet AVD must exist too; pass its name as --pos-device and the runner starts it, or offer --profile core instead.

3. Choose the app build

The runner needs the non-debuggable production package, com.woocommerce.android. When it is missing from the device, the runner downloads and installs the latest stable GitHub release, so there is nothing to do by default.

Ask whether the user wants to test the current checkout instead. If so, run ./gradlew :WooCommerce:assembleVanillaRelease in the foreground and pass --apk WooCommerce/build/outputs/apk/vanilla/release/WooCommerce-vanilla-release.apk to the runner. Debug and wasabi builds are rejected.

4. Validate .maestro/.env.local

Run .maestro/scripts/lint-env.py, then source .maestro/scripts/configure-toolchain.sh && .maestro/scripts/doctor.sh --profile <profile> --device <serial>, adding --pos-device <tablet serial> for full. Both name missing or malformed variables without printing their values, and the doctor checks the store block each flow needs: flows tagged store_shared use the MAESTRO_WOO_SHARED_* block, every other flow the MAESTRO_WOO_LAB_* block. .maestro/env.example lists every variable and what it is for.

If anything is missing:

1. List the variable names the doctor reported.
2. Ask the user to edit .maestro/.env.local directly.
3. Run the doctor again; do not read the file yourself.

Never commit .env.local. Never ask the user to paste secret values into chat. Never echo secret values back to the user.

5. Hand off the CLI command

Once steps 1–4 all pass, print the command the user should run:

source .maestro/scripts/configure-toolchain.sh && .maestro/scripts/run-smoke-tests.sh --profile full --device <phone serial> --pos-device <tablet serial>

Tell the user:

• Without --profile, the runner runs smoke_core only and excludes quarantine.
• full runs every flow except the quarantined ones: the phone flows on --device, then the POS flows on the tablet passed with --pos-device.
• Each flow runs against the store it needs: store_shared flows on the shared store, the rest on the lab store. --store lab|shared forces one store for every flow, and the runner refuses destructive flows on the shared store.
• Destructive flows need seeded fixtures. full and pos seed them without --seed, and cleanup deletes what the run created when it exits.
• It captures and restores device animation settings.
• Screen recordings are kept only for failed lab-store flows; shared-store credential paths use screenshots only.
• Artifacts (recordings, logs, HTML + JUnit report) are written OUTSIDE the repo, under $HOME/woocommerce-maestro-output/<timestamp>/ by default. Override with --output-dir <path> or the WOO_MAESTRO_OUTPUT_DIR env var.
• The HTML report auto-opens at the end on macOS, or can be opened manually from the path the script prints.

If the user asks to run it ("go ahead", "run it", "yes please", etc.), invoke the script yourself via Bash and stream its output. Pass --apk only if the user chose a local build in step 3.

When the script exits, read the last line of its output (it prints Report: and Result: summary lines) and relay a one-line summary to the user plus the clickable file:// path to the HTML report. If any flows failed, call out the first failing flow by name — it's usually the most actionable one.

Notes

• The skill's job ends at handoff. Don't reinvent the test-runner behaviour here — if something about per-flow recording, ordering, or artifact location needs to change, change it in .maestro/scripts/run-smoke-tests.sh.
• .env.local is git-ignored. Never stage or commit it, even if the user asks you to save their credentials.
• Artifacts default to $HOME/woocommerce-maestro-output/ (outside the repo) — the repo's .gitignore still excludes the legacy .maestro/output/ path for safety.
• Do NOT parallelize. adb shell screenrecord only supports one invocation per device, and Maestro runs one flow at a time against a single emulator. The script runs sequentially by design.