reis-mobile 0.5.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/.claude-plugin/plugin.json +2 -2
  3. package/CHANGELOG.md +33 -0
  4. package/README.md +52 -19
  5. package/agents/android-architect.md +14 -70
  6. package/agents/android-performance-engineer.md +14 -73
  7. package/agents/android-test-engineer.md +23 -76
  8. package/agents/flutter-architect.md +17 -73
  9. package/agents/flutter-performance-engineer.md +14 -83
  10. package/agents/flutter-test-engineer.md +18 -82
  11. package/agents/ios-architect.md +14 -74
  12. package/agents/ios-performance-engineer.md +14 -73
  13. package/agents/ios-test-engineer.md +18 -75
  14. package/agents/lead-mobile.md +40 -67
  15. package/agents/mobile-accessibility-auditor.md +31 -0
  16. package/agents/mobile-code-reviewer.md +19 -48
  17. package/agents/mobile-release-engineer.md +33 -0
  18. package/agents/mobile-staff-engineer.md +19 -66
  19. package/agents/plugin-native-expert.md +14 -78
  20. package/agents/rn-architect.md +13 -76
  21. package/agents/rn-performance-engineer.md +14 -74
  22. package/agents/rn-test-engineer.md +16 -77
  23. package/bin/reis-mobile.mjs +30 -5
  24. package/commands/reis-mobile.md +7 -2
  25. package/commands/test.md +71 -0
  26. package/core/install/claude-plugin.mjs +9 -2
  27. package/docs/agent-context.md +57 -0
  28. package/package.json +2 -1
  29. package/skills/mobile-accessibility/SKILL.md +69 -0
  30. package/skills/mobile-accessibility/references/android.md +54 -0
  31. package/skills/mobile-accessibility/references/flutter.md +59 -0
  32. package/skills/mobile-accessibility/references/ios.md +50 -0
  33. package/skills/mobile-accessibility/references/react-native.md +38 -0
  34. package/skills/mobile-debug/SKILL.md +2 -1
  35. package/skills/mobile-debug/references/android/anr.md +59 -0
  36. package/skills/mobile-debug/references/android/memory-leaks.md +43 -0
  37. package/skills/mobile-debug/references/android.md +6 -0
  38. package/skills/mobile-debug/references/deep-links.md +60 -0
  39. package/skills/mobile-release/SKILL.md +70 -0
  40. package/skills/mobile-release/references/android.md +47 -0
  41. package/skills/mobile-release/references/ci-cd.md +94 -0
  42. package/skills/mobile-release/references/flutter.md +37 -0
  43. package/skills/mobile-release/references/ios.md +48 -0
  44. package/skills/mobile-release/references/react-native.md +36 -0
  45. package/skills/mobile-release/references/store-copy.md +52 -0
  46. package/skills/mobile-test/SKILL.md +21 -6
  47. package/skills/mobile-test/references/android.md +67 -55
  48. package/skills/mobile-test/references/ios.md +76 -53
@@ -0,0 +1,94 @@
1
+ # CI/CD for mobile apps
2
+
3
+ ## Pipeline shape
4
+
5
+ | Trigger | Jobs |
6
+ |---|---|
7
+ | Pull request | Static analysis or lint, unit tests, a debug or release build per platform that compiles (no signing, no upload) |
8
+ | Merge to the main branch | The above, plus a signed build uploaded to internal testing (Play internal track, TestFlight internal) |
9
+ | Release tag (`v1.4.0`) | Signed release builds, symbol upload, upload to the release track, artifacts attached to the release |
10
+
11
+ Keep Android and iOS in separate jobs: Android runs on Linux runners, iOS needs macOS runners, which cost more and are slower — do not run iOS builds on every push if the team does not need them.
12
+
13
+ ## Principles
14
+
15
+ - **Reproducible toolchain.** Pin the Flutter version, Node version, JDK, Xcode version (`sudo xcode-select -s /Applications/Xcode_<version>.app` or the runner image's documented selector) and Ruby/fastlane through `Gemfile.lock`. CI that builds with a different toolchain than developers is how "works on my machine" reaches the store.
16
+ - **Caching.** Gradle (`~/.gradle/caches`, or `gradle/actions/setup-gradle`), pub cache, `node_modules` keyed by the lock file, CocoaPods `Pods/` keyed by `Podfile.lock`. Never cache build outputs across different commits for release builds.
17
+ - **Secrets.** Keystore as a base64 CI secret decoded to a temporary file; keystore passwords, the Play service account JSON, the App Store Connect API key (`.p8`, key ID, issuer ID) and `match` passwords as secrets. Nothing written to logs; files deleted at the end of the job. Release jobs run only on protected branches or tags, so a pull request from a fork cannot read them.
18
+ - **Build numbers from CI.** Derive the build number from the run number or the store's latest build (fastlane `latest_testflight_build_number`, `google_play_track_version_codes`) instead of committing a bump on every build.
19
+ - **Artifacts.** Keep the `.aab`/`.ipa`, the R8 mapping, dSYMs, Dart symbols and source maps for every release build.
20
+ - **One way to ship.** Once CI publishes, nobody uploads from a laptop: a manual upload skips the checks and breaks the build number sequence.
21
+
22
+ ## GitHub Actions sketch (Flutter, Android)
23
+
24
+ Adapt names and versions to the project; check each action's current major version in its repository.
25
+
26
+ ```yaml
27
+ name: android-release
28
+ on:
29
+ push:
30
+ tags: ['v*']
31
+
32
+ jobs:
33
+ android:
34
+ runs-on: ubuntu-latest
35
+ steps:
36
+ - uses: actions/checkout@v4
37
+ - uses: actions/setup-java@v4
38
+ with:
39
+ distribution: temurin
40
+ java-version: '17'
41
+ - uses: subosito/flutter-action@v2
42
+ with:
43
+ flutter-version-file: pubspec.yaml # or a pinned flutter-version
44
+ cache: true
45
+ - run: flutter pub get
46
+ - run: flutter analyze
47
+ - run: flutter test
48
+ - name: Decode keystore
49
+ run: |
50
+ echo "$ANDROID_KEYSTORE_BASE64" | base64 -d > android/app/upload.jks
51
+ cat > android/key.properties <<EOF
52
+ storeFile=upload.jks
53
+ storePassword=$ANDROID_KEYSTORE_PASSWORD
54
+ keyAlias=$ANDROID_KEY_ALIAS
55
+ keyPassword=$ANDROID_KEY_PASSWORD
56
+ EOF
57
+ env:
58
+ ANDROID_KEYSTORE_BASE64: ${{ secrets.ANDROID_KEYSTORE_BASE64 }}
59
+ ANDROID_KEYSTORE_PASSWORD: ${{ secrets.ANDROID_KEYSTORE_PASSWORD }}
60
+ ANDROID_KEY_ALIAS: ${{ secrets.ANDROID_KEY_ALIAS }}
61
+ ANDROID_KEY_PASSWORD: ${{ secrets.ANDROID_KEY_PASSWORD }}
62
+ - run: flutter build appbundle --release --build-number=${{ github.run_number }} --obfuscate --split-debug-info=build/symbols
63
+ - uses: actions/upload-artifact@v4
64
+ with:
65
+ name: android-release
66
+ path: |
67
+ build/app/outputs/bundle/release/app-release.aab
68
+ build/app/outputs/mapping/release/mapping.txt
69
+ build/symbols
70
+ ```
71
+
72
+ `flutter-version-file` reads the version from the `environment.flutter` constraint only when it is an exact version; otherwise pin `flutter-version`. Upload to Play in a following step with fastlane `supply` or an upload action, using the service account secret.
73
+
74
+ ## fastlane
75
+
76
+ - `Fastfile` lanes per platform: `beta` (build, upload to internal testing or TestFlight) and `release` (upload to production or submit for review).
77
+ - iOS signing: `match` (certificates and profiles in an encrypted store) with `readonly: true` in CI; `app_store_connect_api_key` for authentication instead of an Apple ID with two-factor authentication.
78
+ - Android upload: `upload_to_play_store(track: 'internal', aab: ...)` with `json_key_data` from a secret.
79
+ - Run with `bundle exec fastlane <lane>` so CI uses the fastlane version in `Gemfile.lock`.
80
+
81
+ ## Other services
82
+
83
+ - **EAS (Expo):** `eas build` and `eas submit` run on Expo's builders; trigger them from CI with `EXPO_TOKEN`, or use EAS Workflows. `eas update` in CI publishes over-the-air updates — gate it like a release.
84
+ - **Codemagic, Bitrise, Xcode Cloud, Azure DevOps, GitLab CI:** the same pipeline shape applies; prefer the service's managed code signing when the team already uses it, and keep secrets in the service's encrypted variables.
85
+
86
+ ## Reviewing an existing pipeline
87
+
88
+ - [ ] Toolchain versions pinned and matching local development.
89
+ - [ ] Secrets never printed (`set -x`, `cat` of decoded files, verbose tool flags) and not available to untrusted pull requests.
90
+ - [ ] Release jobs restricted to tags or protected branches.
91
+ - [ ] Tests run before the signed build, and a failure stops the upload.
92
+ - [ ] Symbols and mapping files uploaded or archived for every release build.
93
+ - [ ] Build numbers cannot collide between parallel runs or re-runs.
94
+ - [ ] Third-party actions pinned to a version (or a commit SHA for sensitive jobs).
@@ -0,0 +1,37 @@
1
+ # Releasing a Flutter app
2
+
3
+ A Flutter release is an Android release and an iOS release produced by the Flutter tool. Store details, signing and rollout follow [android.md](android.md) and [ios.md](ios.md); this guide covers what Flutter changes.
4
+
5
+ ## Version
6
+
7
+ - `pubspec.yaml` holds both numbers: `version: 1.4.0+42` → version name `1.4.0`, build number `42`.
8
+ - On Android it becomes `versionName`/`versionCode` through `flutter.versionName` and `flutter.versionCode` in `android/app/build.gradle(.kts)`. On iOS it becomes `FLUTTER_BUILD_NAME`/`FLUTTER_BUILD_NUMBER`, which `Info.plist` must reference (`$(FLUTTER_BUILD_NAME)`, `$(FLUTTER_BUILD_NUMBER)`). Check both files: a hard-coded value there silently ignores `pubspec.yaml`.
9
+ - CI can override without editing the file: `--build-name=1.4.0 --build-number=$GITHUB_RUN_NUMBER`.
10
+
11
+ ## Build
12
+
13
+ ```bash
14
+ flutter build appbundle --release --obfuscate --split-debug-info=build/symbols
15
+ flutter build ipa --release --obfuscate --split-debug-info=build/symbols \
16
+ --export-options-plist=ios/ExportOptions.plist
17
+ ```
18
+
19
+ - `--obfuscate` requires `--split-debug-info`. The symbol files in that folder are per build and per architecture: archive them with the build or stack traces from that release cannot be read.
20
+ - Symbolize a stack trace with `flutter symbolize -i trace.txt -d build/symbols/app.android-arm64.symbols`. Crashlytics needs the symbols uploaded (`firebase crashlytics:symbols:upload --app=<firebase-app-id> build/symbols`).
21
+ - Obfuscation renames Dart types: code that relies on `runtimeType.toString()` or type names in logs and analytics changes behavior in release.
22
+ - Pass environment configuration with `--dart-define` or `--dart-define-from-file`, and check which file the release command uses. Anything passed this way is in the binary: no secrets.
23
+ - Android signing: `android/key.properties` (untracked) read by the `signingConfigs.release` block. A release build that falls back to `signingConfig = signingConfigs.debug` — the default in new projects — is rejected by Play and must be caught before upload.
24
+
25
+ ## Before uploading
26
+
27
+ - [ ] `flutter analyze` and `flutter test` pass on the release commit.
28
+ - [ ] The app runs in `--release` (or `--profile`) on a real device: assertions, `kDebugMode` branches and the debug banner behave differently in debug.
29
+ - [ ] `debugPrint` and logging do not print sensitive data in release.
30
+ - [ ] Plugins that need platform setup for release are configured: Android permissions and R8 keep rules some plugins document, iOS usage descriptions, `Podfile` platform version.
31
+ - [ ] `flutter build ipa` warnings about the app icon, launch image or bundle identifier are resolved.
32
+ - [ ] App size checked (`--analyze-size`) when the release adds assets or packages.
33
+
34
+ ## Automation
35
+
36
+ - fastlane lanes in `android/` and `ios/` run after `flutter build`, or call it themselves.
37
+ - Codemagic and GitHub Actions with `subosito/flutter-action` are common CI setups; pin the Flutter version to the one the team uses locally (`.fvmrc` or a documented version) so CI builds what was tested. See [ci-cd.md](ci-cd.md).
@@ -0,0 +1,48 @@
1
+ # Releasing on iOS
2
+
3
+ App Store Connect, TestFlight and signing basics also appear in `mobile-ios` → `references/performance-release.md`; this guide focuses on getting a version out safely.
4
+
5
+ ## Version
6
+
7
+ - **Version** (`CFBundleShortVersionString`, build setting `MARKETING_VERSION`) is what users see.
8
+ - **Build** (`CFBundleVersion`, build setting `CURRENT_PROJECT_VERSION`) identifies the upload. App Store Connect rejects a build number already used for the same version; incrementing it for every upload avoids the problem entirely.
9
+ - Keep both in build settings, not hard-coded in `Info.plist`, so every target (app, extensions, widgets) shares them. Extensions whose version differs from the app produce an upload warning or error.
10
+ - `agvtool new-version -all <n>` and `agvtool new-marketing-version <x.y.z>` update them when the project uses Apple Generic versioning; fastlane's `increment_build_number` wraps it.
11
+
12
+ ## Archive, export and upload
13
+
14
+ ```bash
15
+ xcodebuild -workspace App.xcworkspace -scheme App -configuration Release \
16
+ -archivePath build/App.xcarchive archive
17
+ xcodebuild -exportArchive -archivePath build/App.xcarchive \
18
+ -exportOptionsPlist ExportOptions.plist -exportPath build/export
19
+ ```
20
+
21
+ - Use `-project App.xcodeproj` when there is no workspace (no CocoaPods).
22
+ - `ExportOptions.plist` sets the method (App Store Connect distribution), team and signing style.
23
+ - Upload with Xcode's Organizer, the Transporter app, or fastlane (`upload_to_testflight`, `upload_to_app_store`) using an App Store Connect API key.
24
+ - Automatic signing in CI needs the API key or an account with access; manual signing needs the distribution certificate and provisioning profile installed. fastlane `match` keeps them in an encrypted repository or bucket.
25
+
26
+ ## Symbols
27
+
28
+ - Release builds need **Debug Information Format = DWARF with dSYM File**.
29
+ - The dSYMs are inside the archive (`App.xcarchive/dSYMs`). Upload them to the crash reporter (Crashlytics `upload-symbols`, Sentry, others) and keep the archive: Xcode Organizer symbolicates its own crash reports only when it has the matching dSYM.
30
+
31
+ ## Before uploading
32
+
33
+ - [ ] The build uses the current minimum Xcode and iOS SDK Apple requires for uploads (confirm on Apple's upcoming requirements page).
34
+ - [ ] Every permission the app requests has its `NS...UsageDescription` string, written for the user.
35
+ - [ ] `PrivacyInfo.xcprivacy` declares required-reason APIs and collected data, and third-party SDKs ship their own manifests and signatures.
36
+ - [ ] `ITSAppUsesNonExemptEncryption` set in `Info.plist` when the app uses only exempt encryption (HTTPS), so each build does not ask for export compliance.
37
+ - [ ] Capabilities and entitlements (push, associated domains, App Groups, Sign in with Apple) enabled for the App ID and present in the distribution profile. Push needs `aps-environment` = `production` in distribution builds, which the profile sets.
38
+ - [ ] No `NSAllowsArbitraryLoads` without a justification Apple will accept.
39
+ - [ ] App Privacy details in App Store Connect match the data the app and its SDKs collect.
40
+ - [ ] Review notes and a demo account when features need login; release notes ready — see [store-copy.md](store-copy.md).
41
+
42
+ ## TestFlight and rollout
43
+
44
+ - **Internal testers** (members of the App Store Connect team) get builds after processing, without review. **External testers** need the first build of a version to pass Beta App Review.
45
+ - TestFlight builds expire after 90 days.
46
+ - For updates, **phased release** distributes the version over seven days to users with automatic updates on; it can be paused (for a limited total time) or released to everyone. Anyone can still update manually from the App Store during the phase.
47
+ - Choose manual or scheduled release after approval when the launch must match a backend change or an announcement.
48
+ - A bad version cannot be withdrawn to the previous binary: remove it from sale only in extreme cases, and ship a fix with a new build (expedited review can be requested for critical bugs).
@@ -0,0 +1,36 @@
1
+ # Releasing a React Native app
2
+
3
+ A React Native release is an Android and an iOS release plus a JavaScript bundle. Store details, signing and rollout follow [android.md](android.md) and [ios.md](ios.md); EAS Build and Submit commands are also in `mobile-rn` → `references/performance-release.md`.
4
+
5
+ ## Version
6
+
7
+ - **Bare React Native:** `versionCode`/`versionName` in `android/app/build.gradle`, and `MARKETING_VERSION`/`CURRENT_PROJECT_VERSION` in the Xcode project. `package.json`'s `version` is not used by either store unless a script copies it.
8
+ - **Expo:** `expo.version` in `app.json`/`app.config.(js|ts)` is the version name; `android.versionCode` and `ios.buildNumber` are the build numbers. With EAS, `"cli": { "appVersionSource": "remote" }` in `eas.json` lets EAS keep the build numbers, and `"autoIncrement": true` on the production profile increments them on each build.
9
+
10
+ ## Build
11
+
12
+ - **Expo / EAS:** `eas build --platform all --profile production`, then `eas submit`. Credentials (keystore, certificates, provisioning) are managed by EAS unless the project configured local credentials.
13
+ - **Bare:** `./gradlew bundleRelease` in `android/`, and an Xcode archive for iOS.
14
+ - Environment: values in `EXPO_PUBLIC_*`, `react-native-config` and similar end up in the JavaScript bundle. Confirm the release build points at production and holds no secrets.
15
+
16
+ ## Symbols and source maps
17
+
18
+ - JavaScript stack traces from release builds need the **source map** of that exact bundle. With Hermes, the map must be the composed one (Metro map combined with the Hermes bytecode map); crash reporters' React Native integrations (Sentry, Bugsnag, Crashlytics tooling) document how to generate and upload it.
19
+ - The native side still needs the R8 mapping and dSYMs, as in the Android and iOS guides.
20
+
21
+ ## Over-the-air updates
22
+
23
+ - EAS Update (or another OTA service) changes JavaScript and assets without a store review. It cannot change native code, permissions or native dependencies: those need a store build.
24
+ - The **runtime version** decides which binaries can receive an update. A policy such as `fingerprint` or `appVersion` prevents shipping JavaScript that calls native code the installed binary does not have; a manual runtime version that nobody bumps is the classic cause of crashes after an update.
25
+ - Publish to a **channel** mapped to the production build (`eas update --channel production`), test it first on a preview channel with a build from the same commit, and know how to roll back (republish a previous update or roll back to the embedded bundle — check `eas update --help` for the commands in the installed CLI version).
26
+ - Store rules still apply: an OTA update must not change the app's purpose or add features that would need review.
27
+
28
+ ## Before uploading
29
+
30
+ - [ ] `tsc --noEmit`, lint and tests pass on the release commit.
31
+ - [ ] Release build tested on real devices: Hermes, minification and the absence of the dev menu change behavior.
32
+ - [ ] `console.log` removed from release bundles (a Babel plugin such as `transform-remove-console`) when logs can contain user data.
33
+ - [ ] Config plugins and `expo prebuild` output match the committed native folders, when the project commits them.
34
+ - [ ] `expo-doctor` (Expo) or the React Native upgrade helper's checklist shows no version mismatches for native dependencies.
35
+
36
+ See [ci-cd.md](ci-cd.md) for pipelines.
@@ -0,0 +1,52 @@
1
+ # Release notes and store listing copy
2
+
3
+ ## Limits
4
+
5
+ Check the console when a field is rejected; these are the long-standing limits.
6
+
7
+ | Field | Google Play | App Store |
8
+ |---|---|---|
9
+ | App name | 30 characters | 30 characters |
10
+ | Short text | Short description: 80 | Subtitle: 30 |
11
+ | Editable without a new version | — | Promotional text: 170 |
12
+ | Description | 4,000 | 4,000 |
13
+ | Keywords | — (indexed from the listing text) | 100 bytes, comma-separated |
14
+ | Release notes | 500 per language | What's New: 4,000 |
15
+
16
+ The App Store description, keywords and What's New change only with a new version; promotional text changes at any time. Google Play listing text changes independently of releases.
17
+
18
+ ## Release notes from the git history
19
+
20
+ 1. **Collect the range.** `git log <last-release-tag>..HEAD --no-merges --pretty='%h %s'`. In a monorepo, limit it to the app folder (`-- apps/mobile`). When commits reference issues or pull requests, read their titles for context.
21
+ 2. **Drop the noise.** Merges, version bumps, CI and tooling changes, formatting, typo fixes in code, dependency bumps without user impact, and reverted pairs.
22
+ 3. **Classify what is left.** New or changed features, fixes the user could notice, performance improvements the user could feel, and internal changes (refactors, infrastructure, removed APIs).
23
+ 4. **Write per audience:**
24
+ - **Store notes (users):** only what users can see or feel, in plain language and benefit first. No ticket numbers, class names, library names or "various bug fixes" as the only line. Within the limit, in every listed language — flag missing translations instead of inventing them.
25
+ - **Changelog (developers):** technical and complete, with commit hashes or issue references, grouped by type.
26
+ - **QA notes (internal):** the risky areas — new features, refactored core flows, data migrations, removed code, SDK upgrades — each with what to test and on which OS versions or devices.
27
+ 5. **Do not invent.** A change is described only when a commit or issue supports it. When a commit message is unclear, read the diff (`git show <hash> --stat`, then the relevant hunk) or list it as "needs description" for the team.
28
+
29
+ Template:
30
+
31
+ ```markdown
32
+ ## Store — <version>
33
+ <3–6 short lines, most valuable first>
34
+
35
+ ## Changelog — <version> (<date>)
36
+ ### Added
37
+ ### Changed
38
+ ### Fixed
39
+ ### Performance
40
+ ### Internal
41
+
42
+ ## QA focus — <version>
43
+ - <area>: <what changed> → <what to test, where>
44
+ ```
45
+
46
+ ## Store listing
47
+
48
+ - **First 80–170 characters matter most:** the short description (Play) and subtitle or promotional text (App Store) are what users read before tapping. Lead with what the app does for the user, not the company.
49
+ - **Description structure:** one-sentence value proposition, three to six feature bullets written as benefits, then details (plans, requirements, support contact). No claims the app does not deliver and no competitor names.
50
+ - **Keywords (App Store):** no repeated words already in the app name or subtitle, no spaces after commas, no competitor or trademarked names.
51
+ - **Policy traps:** Google Play rejects keyword stuffing, misleading claims ("#1", "best") without attribution, and emojis or capitals used to attract attention in the title; Apple rejects references to other platforms and pricing claims that do not match the in-app purchases.
52
+ - **Localization:** translate the listing for each market the app is sold in, and keep screenshots consistent with the localized UI.
@@ -22,14 +22,27 @@ Detect the stack first (the router result, or `pubspec.yaml`, Gradle files, the
22
22
 
23
23
  A cross-platform app with native code (`android/`, `ios/`, native modules) uses the native reference for that code.
24
24
 
25
- ## 2. Follow the project before this skill
25
+ ## 2. Bind the request to the project
26
26
 
27
- Read the existing tests, test dependencies, helpers and folder layout before writing anything. A project that already uses mockito, XCTest or Detox gets tests in that style unless the user asks to migrate; consistency beats preference.
27
+ Use the [shared project brief](../../docs/agent-context.md). Reuse a supplied brief and fill only missing evidence; do not repeat discovery performed by the calling command or agent. Read the relevant implementation, nearest tests, fixtures, dependency injection and test configuration before proposing a test.
28
+
29
+ Infer the operation from the request:
30
+
31
+ | Operation | Work |
32
+ |---|---|
33
+ | Run | Execute the requested existing suite or the smallest relevant suite; report failures without silently changing application behavior. |
34
+ | Write | Add tests for the named behavior using the current framework and fixtures. |
35
+ | Fix | Reproduce the failing test, distinguish a product defect from a test defect, and preserve the intended assertion while fixing the cause. |
36
+ | Audit | Inspect existing tests and give evidence-backed gaps; do not add dependencies or rewrite suites as part of a review. |
37
+
38
+ For each selected behavior, record an actual **source path and symbol → input/trigger → observable result → dependency seam → test path → execution command**. Name the repository, service, state owner or native bridge involved instead of returning a generic testing checklist. An unknown product rule is a gap to surface, not a fixture to invent.
39
+
40
+ A project that already uses mockito, XCTest or Detox gets tests in that style unless the user asks to migrate. Use its existing build variant, test target and helper conventions. Examples in references illustrate a technique; their application symbols and command placeholders must be replaced with repository evidence.
28
41
 
29
42
  ## 3. What to test, in order of value
30
43
 
31
44
  1. **Business rules** — use cases, view models, reducers, mappers — with their edge cases: empty data, missing fields, boundary values.
32
- 2. **State changes** — the exact sequence of states on success and on failure.
45
+ 2. **State changes** — observable states and transitions on success and failure; require an exact sequence only when the contract guarantees every emission. A conflating state holder may skip intermediate values.
33
46
  3. **Error handling** — a failing data source becomes the expected user-facing state.
34
47
  4. **Critical UI states** — loading, error, empty, content, and what the user can do in each.
35
48
  5. **End-to-end flows** — only the few journeys that must never break (sign-in, purchase), because they are slow and fragile.
@@ -44,7 +57,7 @@ Most tests belong at the top of this list. If a behavior can be verified without
44
57
 
45
58
  ## 5. Determinism
46
59
 
47
- - No real network, disk, clock, randomness or sleeps. Inject a clock and dispatchers or schedulers; use the platform's virtual time or fake async.
60
+ - Isolate network, time and randomness in unit tests. Integration tests may use a temporary database or filesystem when that is the behavior under test; create and clean it per test. Avoid production services and arbitrary sleeps. Inject a clock and dispatchers or schedulers; use the platform's virtual time or fake async.
48
61
  - Each test sets up its own state; order must not matter.
49
62
  - A flaky test is a bug. Find the race (unawaited async work, animations, shared state) instead of adding retries or longer timeouts.
50
63
 
@@ -56,8 +69,10 @@ Most tests belong at the top of this list. If a behavior can be verified without
56
69
 
57
70
  ## 7. Run before reporting
58
71
 
59
- Run the tests you wrote with the command in the platform reference and fix until they pass. Never weaken an assertion or delete a test to make the suite green. Instrumented, UI and end-to-end tests need a device, emulator or simulator: ask before starting one.
72
+ Resolve the command from the project's scripts, Gradle tasks, Xcode scheme/test plan or CI before execution; do not run an example with guessed names. Run the relevant existing test first when reproducing a failure, then run the changed tests and their affected suite. Never weaken an assertion or delete a test to make the suite green.
73
+
74
+ For instrumented, UI and end-to-end tests, discover available devices and the project's runner policy. Use a compatible local emulator or simulator when authorized by the task; do not erase its data or silently switch to a physical device. If the SDK, runtime or destination is unavailable, report the exact blocker and the resolved command that remains unrun. A build, a skipped test or an empty filtered run is not a passing test: inspect the test count and results.
60
75
 
61
76
  ## Output
62
77
 
63
- When writing tests, report the files created, what each test covers and the command that ran them. When auditing, list the files reviewed, fragile or flaky tests with the reason, and untested scenarios prioritized by risk, each with a concrete suggestion.
78
+ Report the operation, source symbols and behaviors covered, files changed, exact command and working directory, executed test counts/result and any report artifact. Separate passed, failed, skipped and blocked checks. When auditing, link each gap or flaky test to a concrete path, the missing assertion or race, and the smallest useful test to add.
@@ -1,83 +1,95 @@
1
1
  # Testing native Android apps
2
2
 
3
- For setting up a test stack from scratch (dependencies, UI tests, screenshot tests, Hilt), follow [android/setup/GUIDE.md](android/setup/GUIDE.md). This file covers writing tests in an existing setup.
3
+ Use this reference for Kotlin/Java tests, including native Android modules inside Flutter or React Native apps. For a new test setup, use [android/setup/GUIDE.md](android/setup/GUIDE.md); first inspect the current module rather than installing its entire example stack.
4
4
 
5
- ## Detect the setup
5
+ ## Resolve the module and test environment
6
6
 
7
- - Test dependencies in the module build files and `gradle/libs.versions.toml`: JUnit 4 or 5, `kotlinx-coroutines-test`, Turbine, MockK or Mockito-Kotlin, Truth or AssertJ, Robolectric, `androidx.compose.ui:ui-test-junit4`, Espresso, `hilt-android-testing`.
8
- - Source sets: **local tests** in `src/test` run on the JVM; **instrumented tests** in `src/androidTest` need a device or emulator.
9
- - Existing helpers: a `MainDispatcherRule`, fakes, a `:core:testing` module, custom test runners.
7
+ 1. Read `settings.gradle` or `settings.gradle.kts` to find the owning module. Inspect its build file, convention plugins, version catalog and CI invocation for the active build type and product flavors.
8
+ 2. Locate the subject and its nearest test. Identify the real constructor, injected repository/dispatcher, observable state, test fixture and source set. `src/test` normally holds JVM tests; `src/androidTest` holds device tests. Check variant-specific and custom source sets before choosing a destination file.
9
+ 3. Reuse the installed JUnit engine, assertion library, coroutine test helpers and mocking tool. Do not switch a JUnit 4 suite to JUnit 5 because an example uses another runner.
10
+ 4. For instrumentation, inspect `testInstrumentationRunner`, runner arguments, AndroidX test dependencies and any Hilt runner. `AndroidJUnitRunner` is the standard runner; preserve a configured custom subclass. Espresso needs the module's `androidTestImplementation` setup, including `espresso-core` and the test runner. Resolve versions from the project instead of copying documentation versions. See [Espresso setup](https://developer.android.com/training/testing/espresso/setup).
10
11
 
11
- ## Local unit tests: ViewModels, coroutines and Flow
12
+ From the directory containing the wrapper, discover available tasks before choosing one:
12
13
 
13
- ```kotlin
14
- class MainDispatcherRule(val dispatcher: TestDispatcher = UnconfinedTestDispatcher()) : TestWatcher() {
15
- override fun starting(description: Description) = Dispatchers.setMain(dispatcher)
16
- override fun finished(description: Description) = Dispatchers.resetMain()
17
- }
14
+ ```bash
15
+ ./gradlew projects
16
+ ./gradlew '<module-path>:tasks' --all
17
+ adb devices -l
18
+ ```
18
19
 
19
- class LoginViewModelTest {
20
- @get:Rule val mainDispatcherRule = MainDispatcherRule()
20
+ Replace `<module-path>` with the discovered Gradle path, including its leading colon. The task listing determines the unit, connected or managed-device task for the requested variant. Do not assume `:app`, `Debug` or a connected device exists.
21
21
 
22
- private val repository = FakeAuthRepository()
22
+ ## Select the smallest test that proves the behavior
23
23
 
24
- @Test
25
- fun `emits success when credentials are valid`() = runTest {
26
- repository.nextResult = Result.success(fakeUser)
27
- val viewModel = LoginViewModel(repository)
24
+ | Subject | Test and concrete observation |
25
+ |---|---|
26
+ | Mapper, validator, use case | JVM test with inputs and expected domain result, including a meaningful boundary or failure case. |
27
+ | ViewModel or Flow producer | JVM coroutine test with the project's dispatcher rule; trigger the action and observe the state or emitted event. |
28
+ | Stateless composable | Existing Compose test harness; interact with a semantic node and assert the resulting state or callback effect. |
29
+ | Android Views screen | Espresso instrumentation test against real view IDs and a controlled dependency seam. |
30
+ | DAO, worker or persistent store | Existing Room/WorkManager/DataStore harness; assert stored values, constraints or work outcome and clean resources. |
28
31
 
29
- viewModel.uiState.test { // Turbine
30
- assertEquals(LoginUiState.Idle, awaitItem())
31
- viewModel.submit("user@example.com", "secret")
32
- assertEquals(LoginUiState.Loading, awaitItem())
33
- assertEquals(LoginUiState.Success(fakeUser), awaitItem())
34
- }
35
- }
36
- }
37
- ```
32
+ ## Coroutines and Flow
38
33
 
39
- - `runTest` skips `delay` with virtual time; `advanceUntilIdle()` and `advanceTimeBy()` control it with a `StandardTestDispatcher`.
40
- - Inject dispatchers into repositories and use cases instead of hardcoding `Dispatchers.IO`; tests pass the test dispatcher.
41
- - Code that uses `viewModelScope` needs `Dispatchers.Main` replaced (the rule above).
42
- - The names above are illustrative; use the project's classes.
34
+ - Reuse the project's `MainDispatcherRule` or equivalent when the subject uses `viewModelScope`. Share the test scheduler across injected dispatchers; hardcoded `Dispatchers.IO` work is not controlled by virtual time.
35
+ - Use `runTest` and the project's Flow helper, such as Turbine. Start collection before the action when the contract requires observing emissions; launch long-lived collectors in a scope cancelled at test completion.
36
+ - A `StateFlow` can conflate rapid updates. Assert its stable final state unless intermediate states are part of the contract; to test loading, pause a fake dependency until the assertion has observed that state, then complete it. Do not assume a synchronous fake guarantees `Idle → Loading → Success` emissions.
37
+ - With `StandardTestDispatcher`, explicitly drive scheduled work where necessary using `runCurrent`, `advanceTimeBy` or `advanceUntilIdle`. Do not replace a race with a real delay. See [testing Kotlin coroutines](https://developer.android.com/kotlin/coroutines/test) and [testing flows](https://developer.android.com/kotlin/flow/test).
43
38
 
44
- ## Compose UI tests
39
+ ## Espresso: action, synchronization and assertion
45
40
 
46
- ```kotlin
47
- class LoginScreenTest {
48
- @get:Rule val composeRule = createComposeRule()
41
+ Bind the test to a real Activity/Fragment, view IDs, launch state and expected result. Reuse an existing fake backend or dependency override before launch. Use the app's actual validation rule or response; checking that a button exists does not prove submitting the form works.
49
42
 
50
- @Test
51
- fun showsErrorWhenLoginFails() {
52
- composeRule.setContent { LoginScreen(state = LoginUiState.Error("Invalid credentials"), onSubmit = {}) }
43
+ This illustrative body assumes the inspected app rejects an empty form and exposes these IDs/resources. Replace them with the actual screen's symbols and use the project's test imports and runner:
53
44
 
54
- composeRule.onNodeWithText("Invalid credentials").assertIsDisplayed()
55
- composeRule.onNodeWithText("Sign in").performClick()
45
+ ```kotlin
46
+ @Test
47
+ fun submittingEmptyFormShowsRequiredEmailError() {
48
+ ActivityScenario.launch(SignInActivity::class.java).use {
49
+ onView(withId(R.id.email)).perform(clearText(), closeSoftKeyboard())
50
+ onView(withId(R.id.submit)).perform(click())
51
+ onView(withId(R.id.email_error))
52
+ .check(matches(withText(R.string.email_required)))
53
+ .check(matches(isDisplayed()))
56
54
  }
57
55
  }
58
56
  ```
59
57
 
60
- - Test stateless composables with state passed in; they need no ViewModel or DI.
61
- - Prefer finding nodes by text or content description; add `Modifier.testTag` only where there is no user-visible handle.
62
- - These tests are instrumented by default; with Robolectric configured, they can run as local tests.
58
+ `ActivityScenario` is `androidx.test.core.app.ActivityScenario`; the other calls come from Espresso's `Espresso`, `ViewActions`, `ViewMatchers` and `ViewAssertions`. Match resource imports to the owning module. `use` closes the activity after the assertion, including on failure. See [testing activities](https://developer.android.com/guide/components/activities/testing).
59
+
60
+ For asynchronous work outside Espresso's built-in synchronization:
61
+
62
+ 1. Identify the operation that makes the assertion race. Use the app's existing `IdlingResource`, or connect one to that operation's actual lifecycle. An unconnected counter cannot synchronize anything.
63
+ 2. Register it through `IdlingRegistry.getInstance().register(resource)` before the first Espresso interaction that needs it. If startup work is under test, arrange the dependency and registration before launching the activity; an auto-launch rule can run before `@Before`.
64
+ 3. With `CountingIdlingResource`, increment before scheduling work and decrement on every completion path, including errors and cancellation. Finish relevant state updates before marking the operation idle.
65
+ 4. Unregister through `IdlingRegistry.getInstance().unregister(resource)` in `@After` or guaranteed cleanup. Restore dependency overrides as well. Avoid `Thread.sleep`, unbounded waits and increasing timeouts to hide a race.
66
+
67
+ Keep idling resources free of Activity/View references. See [Espresso idling resources](https://developer.android.com/training/testing/espresso/idling-resource).
63
68
 
64
- ## Views, Espresso and Hilt
69
+ ## Compose, Hilt and storage
65
70
 
66
- - Espresso: `onView(withId(R.id.submit)).perform(click())`, `check(matches(isDisplayed()))`. Disable animations on test devices, and use idling resources for background work instead of sleeps.
67
- - Hilt: annotate the test with `@HiltAndroidTest`, add `HiltAndroidRule`, use a custom runner that sets `HiltTestApplication`, and replace modules with `@TestInstallIn`. Details in [android/setup/references/android/training/dependency-injection/hilt-testing.md](android/setup/references/android/training/dependency-injection/hilt-testing.md).
71
+ - Compose: use the installed `createComposeRule` or `createAndroidComposeRule` harness. Assert after an interaction, including a callback value when testing a stateless composable. Prefer semantics such as text/content description, using a test tag when a node otherwise cannot be identified. Run through the project's configured instrumentation or Robolectric setup.
72
+ - Hilt: preserve `@HiltAndroidTest`, `HiltAndroidRule`, custom runner and module replacement conventions; install fakes before the subject is created. See [the Hilt test guide](android/setup/references/android/training/dependency-injection/hilt-testing.md).
73
+ - Room: use an isolated database for DAO behavior and `MigrationTestHelper` for migrations. WorkManager: use the existing `work-testing` harness. DataStore: use a temporary location and cancel its scope during teardown. Do not replace a persistence test with a mock of the persistence operation.
68
74
 
69
- ## Other components
75
+ ## Run and inspect evidence
70
76
 
71
- - **Room**: test DAOs against `Room.inMemoryDatabaseBuilder`; test migrations with `MigrationTestHelper` in instrumented tests.
72
- - **WorkManager**: `work-testing` provides test drivers to run workers synchronously.
73
- - **DataStore**: create it in a temporary folder per test.
77
+ The following commands are templates. Replace task paths and class names with values found above; use `--tests` only for a Gradle JVM test task:
74
78
 
75
- ## Commands
79
+ ```bash
80
+ ./gradlew '<unit-test-task-path>' --tests '<fully-qualified-test-class>'
81
+ ./gradlew '<instrumentation-test-task-path>'
82
+ ```
83
+
84
+ For one instrumentation class or method, reuse the project's runner-argument convention. Alternatively, after building and installing the matching app/test APKs, inspect the installed instrumentation component and select it explicitly:
76
85
 
77
86
  ```bash
78
- ./gradlew :app:testDebugUnitTest # local tests of one module
79
- ./gradlew :app:testDebugUnitTest --tests '*LoginViewModelTest'
80
- ./gradlew :app:connectedDebugAndroidTest # instrumented tests, needs a device or emulator
87
+ adb -s '<serial>' shell pm list instrumentation
88
+ adb -s '<serial>' shell am instrument -w \
89
+ -e class '<fully-qualified-test-class>#<test-method>' \
90
+ '<test-package>/<runner-class>'
81
91
  ```
82
92
 
83
- For coverage, enable `enableUnitTestCoverage` / `enableAndroidTestCoverage` on the build type and run the coverage report task the Android Gradle plugin creates for it; check the task name for the project's AGP version.
93
+ Do not infer the test package from the app namespace. Read the runner output and test counts: no matching tests is not success. Gradle local reports live under the module's `build/reports/tests` and XML results under `build/test-results`; connected-test output is under `build/reports/androidTests/connected` and `build/outputs/androidTest-results/connected`. Report the actual generated path and selected device. See [command-line testing](https://developer.android.com/studio/test/command-line).
94
+
95
+ For coverage, inspect the module's AGP version and existing configuration, then discover the generated report task. Do not add a coverage plugin or change toolchain versions just to execute an existing test suite.