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.
- package/.claude-plugin/marketplace.json +2 -2
- package/.claude-plugin/plugin.json +2 -2
- package/CHANGELOG.md +33 -0
- package/README.md +52 -19
- package/agents/android-architect.md +14 -70
- package/agents/android-performance-engineer.md +14 -73
- package/agents/android-test-engineer.md +23 -76
- package/agents/flutter-architect.md +17 -73
- package/agents/flutter-performance-engineer.md +14 -83
- package/agents/flutter-test-engineer.md +18 -82
- package/agents/ios-architect.md +14 -74
- package/agents/ios-performance-engineer.md +14 -73
- package/agents/ios-test-engineer.md +18 -75
- package/agents/lead-mobile.md +40 -67
- package/agents/mobile-accessibility-auditor.md +31 -0
- package/agents/mobile-code-reviewer.md +19 -48
- package/agents/mobile-release-engineer.md +33 -0
- package/agents/mobile-staff-engineer.md +19 -66
- package/agents/plugin-native-expert.md +14 -78
- package/agents/rn-architect.md +13 -76
- package/agents/rn-performance-engineer.md +14 -74
- package/agents/rn-test-engineer.md +16 -77
- package/bin/reis-mobile.mjs +30 -5
- package/commands/reis-mobile.md +7 -2
- package/commands/test.md +71 -0
- package/core/install/claude-plugin.mjs +9 -2
- package/docs/agent-context.md +57 -0
- package/package.json +2 -1
- package/skills/mobile-accessibility/SKILL.md +69 -0
- package/skills/mobile-accessibility/references/android.md +54 -0
- package/skills/mobile-accessibility/references/flutter.md +59 -0
- package/skills/mobile-accessibility/references/ios.md +50 -0
- package/skills/mobile-accessibility/references/react-native.md +38 -0
- package/skills/mobile-debug/SKILL.md +2 -1
- package/skills/mobile-debug/references/android/anr.md +59 -0
- package/skills/mobile-debug/references/android/memory-leaks.md +43 -0
- package/skills/mobile-debug/references/android.md +6 -0
- package/skills/mobile-debug/references/deep-links.md +60 -0
- package/skills/mobile-release/SKILL.md +70 -0
- package/skills/mobile-release/references/android.md +47 -0
- package/skills/mobile-release/references/ci-cd.md +94 -0
- package/skills/mobile-release/references/flutter.md +37 -0
- package/skills/mobile-release/references/ios.md +48 -0
- package/skills/mobile-release/references/react-native.md +36 -0
- package/skills/mobile-release/references/store-copy.md +52 -0
- package/skills/mobile-test/SKILL.md +21 -6
- package/skills/mobile-test/references/android.md +67 -55
- 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.
|
|
25
|
+
## 2. Bind the request to the project
|
|
26
26
|
|
|
27
|
-
|
|
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** —
|
|
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
|
-
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
5
|
+
## Resolve the module and test environment
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
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
|
-
|
|
12
|
+
From the directory containing the wrapper, discover available tasks before choosing one:
|
|
12
13
|
|
|
13
|
-
```
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
14
|
+
```bash
|
|
15
|
+
./gradlew projects
|
|
16
|
+
./gradlew '<module-path>:tasks' --all
|
|
17
|
+
adb devices -l
|
|
18
|
+
```
|
|
18
19
|
|
|
19
|
-
|
|
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
|
-
|
|
22
|
+
## Select the smallest test that proves the behavior
|
|
23
23
|
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
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
|
-
|
|
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
|
-
- `
|
|
40
|
-
-
|
|
41
|
-
-
|
|
42
|
-
-
|
|
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
|
-
##
|
|
39
|
+
## Espresso: action, synchronization and assertion
|
|
45
40
|
|
|
46
|
-
|
|
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
|
-
|
|
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
|
-
|
|
55
|
-
|
|
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
|
-
|
|
61
|
-
|
|
62
|
-
|
|
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
|
-
##
|
|
69
|
+
## Compose, Hilt and storage
|
|
65
70
|
|
|
66
|
-
-
|
|
67
|
-
- Hilt:
|
|
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
|
-
##
|
|
75
|
+
## Run and inspect evidence
|
|
70
76
|
|
|
71
|
-
|
|
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
|
-
|
|
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
|
-
|
|
79
|
-
|
|
80
|
-
|
|
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
|
-
|
|
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.
|