/flutter-app

name: flutter-app
description: Work on a Flutter/Dart repository (one with a pubspec.yaml) in the sandbox — resolve private pub dependencies, run analyze/test, and QA the UI on an Android emulator or by compiling to web, and screenshot it. Use whenever the repo you are working in is a Flutter app, and especially before reporting that you cannot see or exercise a mobile app's UI.

flutter-app — building and QA'ing an app that is not a website

A Flutter repo breaks an assumption the rest of the sandbox is built on: its pull requests have no deploy `previewUrl`, so the usual "open the preview and look at it" does not apply — and neither does giving up.

First: check which sandbox image you are on

The Flutter SDK ships only in the **Android sandbox image**. If `qa-android` is on your `PATH` (equivalently, `$STUDIO_SANDBOX_ANDROID_EMULATOR` is set), you are on it: the SDK is at `/opt/flutter` (already on `PATH`), and there is an Android emulator to run the app for real — see [Running the app on the emulator](#running-the-app-on-the-emulator-qa-android).

Otherwise you are on the default image, which has **no Flutter SDK**: no `flutter analyze`, no `flutter test`, no way to see the UI. Do not try to install the SDK into the sandbox. Do what reading the code can do, then say in your report that you could not build or run the app **and that the repo must be switched to the Android emulator image in Settings → Repositories**. That is the fix; do not spend the run working around it.

Check the version pin first

`flutter analyze` produces different findings on different releases. Compare the image's `flutter --version` against whatever the repo's CI pins (commonly `FLUTTER_VERSION` in `.github/workflows/*.yml`, or `.fvmrc`). If they differ, **say so in your report** and treat analyzer findings that the repo's own gate would not produce as suspect. Do not "fix" them silently.

Private dependencies

Most real apps pull packages from private git repos:

dependencies:
  some_internal_lib:
    git:
      url: https://github.com/acme/internal-flutter-lib.git
      ref: v1.2.3

`flutter pub get` fetches those over plain HTTPS, and the sandbox is already set up for it: the daemon installs the run's credentials in the pod's git config at boot, so `flutter pub get` needs no preparation. Just run it.

> **Never run `gh auth setup-git` here.** The first thing it writes is an empty > `credential.<url>.helper`, which git reads as "discard every helper configured > earlier" — and because `GIT_CONFIG_GLOBAL` points at the daemon's config, that > write lands in the same file and deletes the credentials the pod booted with. > A `pub get` that worked will start 404ing.

What the credentials reach is decided before the run starts: Studio walks the `git:` dependencies in `pubspec.yaml`, and the dependencies of those, and mints the token for this repository plus **every same-owner repository in that graph** (capped at 20), plus any **git credential** the organization configured for the host. So a normal private dependency tree resolves, and three cases do not:

• **A repository outside the token and with no configured credential.** The

minted token belongs to one GitHub App installation and covers only the repositories that installation was granted, so a dependency under a different owner — or one the installation was never given — is out of reach. The fix is not yours to apply: someone adds a git credential for that host in Settings → Repositories (a PAT stored as an org secret), and the next boot installs it for every git in the pod, `pub get` included. **Report that as the blocker and name the host**; do not go looking for a token yourself.

• **A private dependency added on your working branch.** The walk read each

repository's default branch, so a `git:` dependency your PR introduces is not in the token. Say so in your report rather than working around it.

• **A repository the organization did not authorize for Studio.** The walk stops

at the grant, by design.

So a 404 from `pub get` is one of those three — **report it**. Do not go looking for another token, and never paste one into `pubspec.yaml`, a git URL, or a config file.

`flutter pub get` on a cold sandbox takes a few minutes. Run it once.

The checks

flutter analyze        # the repo's own gate, usually
flutter test           # unit + widget tests

Run these before you hand over. They are fast and they are what CI will say.

Running the app on the emulator (`qa-android`)

Only on the Android sandbox image. This builds the app's Android target, boots a headless emulator, installs the app and launches its real `main()` — native plugins included, so Firebase, push and the rest behave as on a phone.

qa-android start                 # build + boot + install + launch; exit 2 = still going, then `qa-android wait`
qa-android ui                    # what's on screen: "x,y [clickable]<TAB>label" per element
qa-android shot /app/org/output/qa/01.png
qa-android tap 640 1480          # an x,y from `ui`, or read off the screenshot
qa-android type "search term"
qa-android key ENTER             # BACK, HOME, ENTER, TAB, DEL, ...
qa-android swipe 360 1200 360 400   # scroll down
qa-android shot /app/org/output/qa/02.png
qa-android logs 80               # the app's output — where startup crashes land
qa-android stop

Then `Read` the PNGs. A screenshot you never opened is not verification. To show them to a person, embed each as a markdown image in your comment — `` renders on the task; a bare path or a code span does not.

**Run `qa-android start` in the foreground**, with the Bash tool's longest timeout (600000 ms). It returns within about nine minutes: exit 0 means the app is up, 1 that it failed (the reason is printed), and 2 that the build is still going — run `qa-android wait` to keep waiting, as many times as it takes. Never background it and end your