@1aboveio/app-dev-skills 0.0.0-stage → 0.1.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/README.md +29 -2
- package/package.json +33 -4
- package/skills/airflow/LICENSE +3 -0
- package/skills/airflow/SKILL.md +199 -0
- package/skills/airflow/release-check.mjs +93 -0
- package/skills/android-foundation/LICENSE +3 -0
- package/skills/android-foundation/SKILL.md +192 -0
- package/skills/android-foundation/assets/android-ci-job.yml +217 -0
- package/skills/android-foundation/references/ci.md +87 -0
- package/skills/android-foundation/references/gotchas.md +221 -0
- package/skills/android-foundation/references/setup.md +164 -0
- package/skills/android-foundation/release-check.mjs +93 -0
- package/skills/android-foundation/scripts/device-run.sh +176 -0
- package/skills/android-foundation/scripts/device-run.test.mjs +172 -0
- package/skills/app-debug/LICENSE +3 -0
- package/skills/app-debug/SKILL.md +110 -0
- package/skills/app-debug/references/common-errors.md +128 -0
- package/skills/app-debug/release-check.mjs +93 -0
- package/skills/better-auth/LICENSE +3 -0
- package/skills/better-auth/SKILL.md +598 -0
- package/skills/better-auth/references/feishu-api.md +270 -0
- package/skills/better-auth/release-check.mjs +93 -0
- package/skills/ios-foundation/LICENSE +3 -0
- package/skills/ios-foundation/SKILL.md +184 -0
- package/skills/ios-foundation/references/setup.md +243 -0
- package/skills/ios-foundation/release-check.mjs +93 -0
- package/skills/monorepo/LICENSE +3 -0
- package/skills/monorepo/SKILL.md +462 -0
- package/skills/monorepo/release-check.mjs +93 -0
- package/skills/nextjs-fullstack/LICENSE +3 -0
- package/skills/nextjs-fullstack/SKILL.md +211 -0
- package/skills/nextjs-fullstack/conventions.md +318 -0
- package/skills/nextjs-fullstack/frontend-conventions.md +61 -0
- package/skills/nextjs-fullstack/nextjs16.md +287 -0
- package/skills/nextjs-fullstack/release-check.mjs +93 -0
- package/skills/nextjs-fullstack/server-actions.md +409 -0
- package/skills/prisma-setup/LICENSE +3 -0
- package/skills/prisma-setup/SKILL.md +181 -0
- package/skills/prisma-setup/nextjs.md +258 -0
- package/skills/prisma-setup/release-check.mjs +93 -0
- package/skills/prisma-setup/turborepo.md +301 -0
- package/skills/pyspark/LICENSE +3 -0
- package/skills/pyspark/SKILL.md +127 -0
- package/skills/pyspark/assets/templates/etl.py +748 -0
- package/skills/pyspark/assets/templates/utils/__init__.py +1 -0
- package/skills/pyspark/assets/templates/utils/hudi_metadata.py +14 -0
- package/skills/pyspark/references/diagnosis-and-profiling.md +169 -0
- package/skills/pyspark/references/etl-contract.md +129 -0
- package/skills/pyspark/references/production-validation.md +131 -0
- package/skills/pyspark/references/reconciliation.md +38 -0
- package/skills/pyspark/references/transformation-design.md +190 -0
- package/skills/pyspark/references/velocity-feature-calculation.md +193 -0
- package/skills/pyspark/release-check.mjs +93 -0
- package/skills/pyspark/scripts/spark_eventlog_summary.py +223 -0
- package/skills/python-backend/LICENSE +3 -0
- package/skills/python-backend/SKILL.md +325 -0
- package/skills/python-backend/assets/uv-install.sh +48 -0
- package/skills/python-backend/references/uv-installs.md +83 -0
- package/skills/python-backend/release-check.mjs +93 -0
- package/skills/shadcn/LICENSE +3 -0
- package/skills/shadcn/SKILL.md +120 -0
- package/skills/shadcn/assets/shadcn-small.png +0 -0
- package/skills/shadcn/assets/shadcn.png +0 -0
- package/skills/shadcn/cli.md +411 -0
- package/skills/shadcn/customization.md +224 -0
- package/skills/shadcn/mcp.md +101 -0
- package/skills/shadcn/release-check.mjs +93 -0
- package/skills/shadcn/rules/base-vs-radix.md +323 -0
- package/skills/shadcn/rules/component-selection.md +67 -0
- package/skills/shadcn/rules/composition.md +195 -0
- package/skills/shadcn/rules/data-table.md +201 -0
- package/skills/shadcn/rules/forms.md +255 -0
- package/skills/shadcn/rules/icons.md +103 -0
- package/skills/shadcn/rules/styling.md +167 -0
- package/skills/zod-v4/LICENSE +3 -0
- package/skills/zod-v4/SKILL.md +286 -0
- package/skills/zod-v4/release-check.mjs +93 -0
|
@@ -0,0 +1,217 @@
|
|
|
1
|
+
# Android job for the repo's ci.yml. Merge these pieces into the existing workflow:
|
|
2
|
+
# 1. the `android` filter into the `changes` job (and its output),
|
|
3
|
+
# 2. the `android` job,
|
|
4
|
+
# 3. the `android` lines into `gate`.
|
|
5
|
+
# Replace every <placeholder>. See references/ci.md.
|
|
6
|
+
|
|
7
|
+
jobs:
|
|
8
|
+
changes:
|
|
9
|
+
# ...existing changes job...
|
|
10
|
+
outputs:
|
|
11
|
+
android: ${{ steps.filter.outputs.android }}
|
|
12
|
+
steps:
|
|
13
|
+
- uses: actions/checkout@v4
|
|
14
|
+
- id: filter
|
|
15
|
+
uses: dorny/paths-filter@ceb8a2b8f2d89434be7ff52d3de7ec3738c5cc9d # v4.0.3
|
|
16
|
+
with:
|
|
17
|
+
filters: |
|
|
18
|
+
shared: &shared
|
|
19
|
+
- 'package.json'
|
|
20
|
+
- 'pnpm-lock.yaml'
|
|
21
|
+
- '.github/workflows/ci.yml'
|
|
22
|
+
android:
|
|
23
|
+
- *shared
|
|
24
|
+
- '<android-workspace>/**'
|
|
25
|
+
- '<backend-paths-the-journey-drives>/**'
|
|
26
|
+
- '<device-harness-and-journey-scripts>'
|
|
27
|
+
|
|
28
|
+
android:
|
|
29
|
+
name: Android foundation (APK + device journey)
|
|
30
|
+
needs: changes
|
|
31
|
+
# Fork guard: fork code must never reach the self-hosted Android runners.
|
|
32
|
+
if: >-
|
|
33
|
+
needs.changes.outputs.android == 'true' &&
|
|
34
|
+
(github.event_name != 'pull_request' ||
|
|
35
|
+
github.event.pull_request.head.repo.full_name == github.repository)
|
|
36
|
+
runs-on: [<self-hosted-android-runner-labels>]
|
|
37
|
+
timeout-minutes: 60
|
|
38
|
+
services:
|
|
39
|
+
postgres:
|
|
40
|
+
image: postgres:<major>
|
|
41
|
+
env:
|
|
42
|
+
POSTGRES_USER: postgres
|
|
43
|
+
POSTGRES_PASSWORD: postgres
|
|
44
|
+
POSTGRES_DB: <ci-db-name>
|
|
45
|
+
ports: ['5432/tcp']
|
|
46
|
+
options: >-
|
|
47
|
+
--health-cmd "pg_isready -U postgres"
|
|
48
|
+
--health-interval 10s --health-timeout 5s --health-retries 5
|
|
49
|
+
steps:
|
|
50
|
+
- uses: actions/checkout@v4
|
|
51
|
+
with:
|
|
52
|
+
persist-credentials: false
|
|
53
|
+
- uses: actions/setup-node@v4
|
|
54
|
+
with:
|
|
55
|
+
node-version: '<node-major>'
|
|
56
|
+
- uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4
|
|
57
|
+
with:
|
|
58
|
+
version: '<pnpm-version>'
|
|
59
|
+
run_install: false
|
|
60
|
+
- uses: actions/setup-java@v4
|
|
61
|
+
with:
|
|
62
|
+
distribution: temurin
|
|
63
|
+
java-version: '17'
|
|
64
|
+
|
|
65
|
+
- name: Preflight Android runner
|
|
66
|
+
run: |
|
|
67
|
+
echo "runner=$RUNNER_NAME nproc=$(nproc)"
|
|
68
|
+
test -c /dev/kvm || { echo "runner has no /dev/kvm device" >&2; exit 1; }
|
|
69
|
+
test -r /dev/kvm
|
|
70
|
+
test -w /dev/kvm
|
|
71
|
+
node -e 'const fs = require("node:fs"); fs.accessSync("/dev/kvm", fs.constants.R_OK | fs.constants.W_OK)'
|
|
72
|
+
for component in platform-tools/adb platforms/android-<api> build-tools/<build-tools> \
|
|
73
|
+
ndk/<ndk> cmake/<cmake> emulator system-images/android-<emulator-api>/<target>/x86_64; do
|
|
74
|
+
test -e "$ANDROID_SDK_ROOT/$component" || { echo "runner image lacks $component" >&2; exit 1; }
|
|
75
|
+
done
|
|
76
|
+
|
|
77
|
+
- name: Allocate per-slot Android ports
|
|
78
|
+
run: |
|
|
79
|
+
if [[ "$RUNNER_NAME" =~ -([0-9]+)$ ]]; then slot=$((10#${BASH_REMATCH[1]})); else
|
|
80
|
+
echo "cannot derive a slot from $RUNNER_NAME" >&2; exit 2; fi
|
|
81
|
+
(( slot >= 1 && slot <= 15 )) || { echo "slot out of range: $slot" >&2; exit 2; }
|
|
82
|
+
emulator_port=$((5554 + 2 * slot))
|
|
83
|
+
{
|
|
84
|
+
echo "ANDROID_ADB_SERVER_PORT=$((5037 + slot))"
|
|
85
|
+
echo "ANDROID_EMULATOR_PORT=$emulator_port"
|
|
86
|
+
echo "ANDROID_EMULATOR_SERIAL=emulator-$emulator_port"
|
|
87
|
+
echo "ANDROID_BACKEND_PORT=$((<backend-base-port> + 10 * slot))"
|
|
88
|
+
echo "ANDROID_METRO_PORT=$((<metro-base-port> + 10 * slot))"
|
|
89
|
+
} | tee -a "$GITHUB_ENV"
|
|
90
|
+
|
|
91
|
+
# Optional: only on runners with a Gradle distribution mirror.
|
|
92
|
+
- name: Route the Gradle wrapper through the mirror
|
|
93
|
+
run: |
|
|
94
|
+
mirror="${GRADLE_DISTRIBUTIONS_MIRROR:?runner must set GRADLE_DISTRIBUTIONS_MIRROR}"
|
|
95
|
+
props=<android-project>/gradle/wrapper/gradle-wrapper.properties
|
|
96
|
+
node -e '
|
|
97
|
+
const fs = require("node:fs")
|
|
98
|
+
const [file, raw] = process.argv.slice(1)
|
|
99
|
+
const mirror = raw.replace(/\/?$/, "/")
|
|
100
|
+
const text = fs.readFileSync(file, "utf8")
|
|
101
|
+
const next = text.replace(
|
|
102
|
+
/^distributionUrl=https\\:\/\/services\.gradle\.org\/distributions\//m,
|
|
103
|
+
"distributionUrl=" + mirror.replace(/:/g, "\\:"),
|
|
104
|
+
)
|
|
105
|
+
if (next === text) throw new Error("distributionUrl was not rewritten")
|
|
106
|
+
fs.writeFileSync(file, next)
|
|
107
|
+
' "$props" "$mirror"
|
|
108
|
+
grep '^distributionUrl=' "$props"
|
|
109
|
+
|
|
110
|
+
- name: Install dependencies
|
|
111
|
+
timeout-minutes: 12
|
|
112
|
+
run: pnpm install --frozen-lockfile
|
|
113
|
+
|
|
114
|
+
- name: Native tests and typecheck
|
|
115
|
+
run: |
|
|
116
|
+
pnpm --filter <android-workspace-package> test
|
|
117
|
+
pnpm --filter <android-workspace-package> typecheck
|
|
118
|
+
|
|
119
|
+
- name: Relax durability on the disposable Postgres
|
|
120
|
+
env:
|
|
121
|
+
PG_CONTAINER: ${{ job.services.postgres.id }}
|
|
122
|
+
run: |
|
|
123
|
+
docker exec "$PG_CONTAINER" psql -U postgres -v ON_ERROR_STOP=1 \
|
|
124
|
+
-c "ALTER SYSTEM SET synchronous_commit = off" -c "ALTER SYSTEM SET fsync = off" \
|
|
125
|
+
-c "SELECT pg_reload_conf()"
|
|
126
|
+
|
|
127
|
+
- name: Native auth against real PostgreSQL
|
|
128
|
+
env:
|
|
129
|
+
DATABASE_URL: postgresql://postgres:postgres@127.0.0.1:${{ job.services.postgres.ports['5432'] }}/<ci-db-name>
|
|
130
|
+
run: <native-auth-integration-test-command>
|
|
131
|
+
|
|
132
|
+
- name: Bundle Android JavaScript
|
|
133
|
+
env:
|
|
134
|
+
EXPO_PUBLIC_API_URL: https://app.invalid
|
|
135
|
+
run: pnpm --filter <android-workspace-package> exec expo export --platform android
|
|
136
|
+
|
|
137
|
+
- name: Build x86_64 debug APK
|
|
138
|
+
timeout-minutes: 30
|
|
139
|
+
env:
|
|
140
|
+
EXPO_PUBLIC_API_URL: https://app.invalid
|
|
141
|
+
ANDROID_USER_HOME: ${{ github.workspace }}/.cache/android-user
|
|
142
|
+
run: |
|
|
143
|
+
mkdir -p "$ANDROID_USER_HOME"
|
|
144
|
+
cpus="$(nproc)"
|
|
145
|
+
if [ -r /sys/fs/cgroup/cpu.max ]; then
|
|
146
|
+
read -r quota period < /sys/fs/cgroup/cpu.max
|
|
147
|
+
if [ "$quota" != max ]; then cpus=$(( (quota + period - 1) / period )); fi
|
|
148
|
+
fi
|
|
149
|
+
echo "gradle max-workers=$cpus (nproc=$(nproc))"
|
|
150
|
+
<android-project>/gradlew --project-dir <android-project> :app:assembleDebug --no-daemon \
|
|
151
|
+
-PreactNativeArchitectures=x86_64 --max-workers="$cpus"
|
|
152
|
+
|
|
153
|
+
- uses: actions/setup-python@v5
|
|
154
|
+
with:
|
|
155
|
+
python-version: '3.12'
|
|
156
|
+
|
|
157
|
+
- name: Test device orchestration
|
|
158
|
+
run: <orchestration-unit-test-commands>
|
|
159
|
+
|
|
160
|
+
- name: Install UI automation
|
|
161
|
+
run: |
|
|
162
|
+
# Create the venv where the journey wrapper looks for it.
|
|
163
|
+
python3 -m venv <venv-dir-the-wrapper-reads>
|
|
164
|
+
<venv-dir-the-wrapper-reads>/bin/python3 -m pip install uiautomator2==<harness-pinned-version>
|
|
165
|
+
|
|
166
|
+
- name: Start the slot's ADB server
|
|
167
|
+
run: |
|
|
168
|
+
adb="$ANDROID_SDK_ROOT/platform-tools/adb"
|
|
169
|
+
"$adb" -P "$ANDROID_ADB_SERVER_PORT" start-server
|
|
170
|
+
"$adb" -P "$ANDROID_ADB_SERVER_PORT" version | head -1
|
|
171
|
+
|
|
172
|
+
- name: Device journey
|
|
173
|
+
uses: reactivecircus/android-emulator-runner@a421e43855164a8197daf9d8d40fe71c6996bb0d # v2.38.0
|
|
174
|
+
env:
|
|
175
|
+
SHARD_ADMIN_URL: postgresql://postgres:postgres@127.0.0.1:${{ job.services.postgres.ports['5432'] }}/postgres
|
|
176
|
+
SHARD_DB_NAME: <ci-db-name>
|
|
177
|
+
with:
|
|
178
|
+
api-level: <emulator-api>
|
|
179
|
+
arch: x86_64
|
|
180
|
+
target: <target>
|
|
181
|
+
disable-animations: true
|
|
182
|
+
enable-hw-keyboard: true
|
|
183
|
+
emulator-port: ${{ env.ANDROID_EMULATOR_PORT }}
|
|
184
|
+
cores: 4
|
|
185
|
+
# At 2 GB (the usual AVD value) the guest kernel's vsock allocations fail and adb drops
|
|
186
|
+
# mid-journey, taking every adb reverse with it (references/gotchas.md).
|
|
187
|
+
ram-size: 4096M
|
|
188
|
+
disable-linux-hw-accel: false
|
|
189
|
+
script: bash <path/to/foundation-journey-wrapper.sh>
|
|
190
|
+
|
|
191
|
+
# The sanitized capture (screenshots, UI dumps, backend and Metro logs; no auth codes,
|
|
192
|
+
# cookies or payment payloads), so a failure is diagnosed from the run, not the runner.
|
|
193
|
+
# <device-capture-dir> must be the directory the journey wrapper actually writes.
|
|
194
|
+
- uses: actions/upload-artifact@v4
|
|
195
|
+
if: always()
|
|
196
|
+
with:
|
|
197
|
+
name: android-device-capture
|
|
198
|
+
path: <device-capture-dir>/
|
|
199
|
+
if-no-files-found: warn
|
|
200
|
+
retention-days: 7
|
|
201
|
+
- uses: actions/upload-artifact@v4
|
|
202
|
+
with:
|
|
203
|
+
name: android-debug-apk
|
|
204
|
+
path: <android-project>/app/build/outputs/apk/debug/*.apk
|
|
205
|
+
if-no-files-found: error
|
|
206
|
+
retention-days: 7
|
|
207
|
+
|
|
208
|
+
gate:
|
|
209
|
+
# ...existing gate job; add:
|
|
210
|
+
needs: [changes, android] # plus the existing jobs
|
|
211
|
+
steps:
|
|
212
|
+
- env:
|
|
213
|
+
ANDROID: ${{ needs.changes.outputs.android }}
|
|
214
|
+
ANDROID_RESULT: ${{ needs.android.result }}
|
|
215
|
+
run: |
|
|
216
|
+
# inside the existing check script:
|
|
217
|
+
check android "$ANDROID_RESULT" "$ANDROID"
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
# Android CI
|
|
2
|
+
|
|
3
|
+
Add an Android job to the repo's one `ci.yml`: build the debug APK and run the foundation
|
|
4
|
+
journey on an emulator. Copy [assets/android-ci-job.yml](../assets/android-ci-job.yml) and
|
|
5
|
+
fill every `<placeholder>`. Follow the `github-actions` skill for the `changes` job, the
|
|
6
|
+
`gate` job, runner labels, pinning and hardening; this file covers only what is Android-
|
|
7
|
+
specific.
|
|
8
|
+
|
|
9
|
+
## Wire it in
|
|
10
|
+
|
|
11
|
+
1. Add an `android` filter to the `changes` job: the app workspace, the native project,
|
|
12
|
+
the backend code the journey drives, the device harness and journey scripts, the
|
|
13
|
+
lockfile, and `ci.yml`. Leave docs out.
|
|
14
|
+
2. Add the `android` job with `needs: changes` and
|
|
15
|
+
`if: needs.changes.outputs.android == 'true'` plus the fork guard: fork pull requests
|
|
16
|
+
never run on the self-hosted Android runners.
|
|
17
|
+
3. Add `android` to `gate`'s `needs:` and a `check android "$ANDROID_RESULT" "$ANDROID"`
|
|
18
|
+
line. Require only `gate`.
|
|
19
|
+
4. Before merging, open one Android-only PR and one docs-only PR. Confirm the job runs on
|
|
20
|
+
the first, is skipped on the second, and `gate` passes on both.
|
|
21
|
+
|
|
22
|
+
## Runner
|
|
23
|
+
|
|
24
|
+
- Run on a self-hosted Linux x64 runner class that has `/dev/kvm` mapped in and the SDK
|
|
25
|
+
preinstalled: platform-tools, the platform, build-tools, NDK, CMake, emulator and the
|
|
26
|
+
x86_64 system image the job boots. Never download SDK components in the job.
|
|
27
|
+
- Preflight before any slow step: assert `/dev/kvm` is a character device, readable and
|
|
28
|
+
writable, and check it with Node's `fs.accessSync(R_OK | W_OK)`. The emulator action uses
|
|
29
|
+
that check; a host where `test -r/-w` passes but `accessSync` fails boots the emulator in
|
|
30
|
+
software for 10+ minutes. Assert each SDK component path exists.
|
|
31
|
+
- Never let the emulator fall back to software: set `disable-linux-hw-accel: false`.
|
|
32
|
+
- Derive per-slot ports from the runner's slot number when slots share a host network:
|
|
33
|
+
ADB server, emulator console (even port, 5554–5584), backend and Metro. Export them to
|
|
34
|
+
`$GITHUB_ENV` and start the ADB server on its own port.
|
|
35
|
+
- Size Gradle from the cgroup CPU quota (`/sys/fs/cgroup/cpu.max`), not `nproc`. `nproc`
|
|
36
|
+
reports every host core and thrashes the native build.
|
|
37
|
+
- Route the Gradle wrapper distribution and Maven repositories through the runner's
|
|
38
|
+
dependency proxy when it has one. Fail when the proxy variable is missing; never fall
|
|
39
|
+
back to direct downloads.
|
|
40
|
+
|
|
41
|
+
## Build
|
|
42
|
+
|
|
43
|
+
- Build `x86_64` only (`-PreactNativeArchitectures=x86_64`), with `--no-daemon`. Report
|
|
44
|
+
this APK as emulator evidence only. The all-ABI build stays a local or release step.
|
|
45
|
+
- Bundle the JavaScript with `expo export --platform android` before the native build so
|
|
46
|
+
bundling errors fail fast.
|
|
47
|
+
- Give the job `timeout-minutes: 60`, the install step its own short timeout, and the
|
|
48
|
+
APK build `timeout-minutes: 30`.
|
|
49
|
+
|
|
50
|
+
## Database and journey
|
|
51
|
+
|
|
52
|
+
- Run PostgreSQL as a job service on a random host port, with a health check. Turn off
|
|
53
|
+
`fsync` and `synchronous_commit` on it: the database is disposable.
|
|
54
|
+
- Run the native auth/integration tests against that service before the device journey.
|
|
55
|
+
- Unit-test the device orchestration scripts (journey wrapper, slot allocator, code
|
|
56
|
+
lookup) before booting the emulator.
|
|
57
|
+
- Pin the UI automation package in a venv at the path the journey wrapper reads; use the
|
|
58
|
+
Python version the harness supports (3.12 on CI).
|
|
59
|
+
- Boot the emulator with the SHA-pinned `reactivecircus/android-emulator-runner`, or the
|
|
60
|
+
runner's preinstalled emulator under an owned process group. Use the API level, target
|
|
61
|
+
and ABI of the preinstalled image, `disable-animations: true`, `ram-size: 4096M` (or
|
|
62
|
+
`-memory 4096` when launching the emulator directly), and the slot's console port. Run
|
|
63
|
+
the journey wrapper as its `script`. At 2 GB, the usual `avdmanager` value, adb drops
|
|
64
|
+
mid-journey
|
|
65
|
+
([gotchas](gotchas.md#the-adb-transport-drops-mid-journey)).
|
|
66
|
+
|
|
67
|
+
## Evidence
|
|
68
|
+
|
|
69
|
+
- Upload the sanitized device capture (screenshots, UI dumps, backend and Metro logs) with
|
|
70
|
+
`if: always()` and a 7-day retention, from the directory the journey wrapper actually
|
|
71
|
+
writes. Sanitize before upload: no authentication codes, session cookies, customer data or
|
|
72
|
+
payment payloads. Diagnose a CI failure from this artifact; never require runner access.
|
|
73
|
+
- Print enough to name the cause from the log alone: the message of the wait that timed
|
|
74
|
+
out (not only its exception class), the screen size and orientation, the labels on screen
|
|
75
|
+
and whether it scrolls, and the runner's free disk at preflight. A repo that uploads no
|
|
76
|
+
capture needs these in the log.
|
|
77
|
+
- Upload the APK with `if-no-files-found: error`.
|
|
78
|
+
- Treat one green run as one run. Fix flaky device failures at their cause instead of
|
|
79
|
+
rerunning, and do not change product code for them. An adb drop after boot means guest
|
|
80
|
+
RAM ([gotchas](gotchas.md#the-adb-transport-drops-mid-journey)). A `RemoteDisconnected`
|
|
81
|
+
with the adb transport still up means the uiautomator2 server was relaunched
|
|
82
|
+
([gotchas](gotchas.md#remotedisconnected-right-after-a-new-process-connects)).
|
|
83
|
+
|
|
84
|
+
## Traps
|
|
85
|
+
|
|
86
|
+
Known CI symptoms and their fixes are in [gotchas.md](gotchas.md#ci-runners), along with
|
|
87
|
+
the emulator and adb traps that also hit CI.
|
|
@@ -0,0 +1,221 @@
|
|
|
1
|
+
# Android foundation gotchas
|
|
2
|
+
|
|
3
|
+
Known traps, each as signal, cause and fix. Match the signal before you dig. If none
|
|
4
|
+
matches, [confirm the suspected cause](#confirm-a-suspected-cause) before changing code.
|
|
5
|
+
|
|
6
|
+
## Emulator and AVD
|
|
7
|
+
|
|
8
|
+
### A hand-written AVD misses the screen
|
|
9
|
+
|
|
10
|
+
- **Signal:** taps or swipes land nowhere, or a control below the fold never scrolls into
|
|
11
|
+
view, though the same journey passes elsewhere. The device reports `Physical size:
|
|
12
|
+
320x480`.
|
|
13
|
+
- **Cause:** `config.ini` was written from scratch without the hardware keys. Without
|
|
14
|
+
`hw.lcd.*` the emulator defaults to 320x480, so a journey's display override and fixed
|
|
15
|
+
coordinates no longer match.
|
|
16
|
+
- **Fix:** copy the hardware keys from an `avdmanager`-made AVD on the same runner:
|
|
17
|
+
`hw.lcd.width`, `hw.lcd.height`, `hw.lcd.density` and `disk.dataPartition.size`. Set
|
|
18
|
+
`hw.ramSize=4096` instead of copying its value; see
|
|
19
|
+
[adb transport drops](#the-adb-transport-drops-mid-journey).
|
|
20
|
+
|
|
21
|
+
### `avdmanager` cannot see an installed image
|
|
22
|
+
|
|
23
|
+
- **Signal:** `avdmanager create avd --package …` fails with `Package path is not valid` and
|
|
24
|
+
lists only the images under its own SDK.
|
|
25
|
+
- **Cause:** `avdmanager` derives its SDK root from its own install location. It ignores
|
|
26
|
+
`ANDROID_SDK_ROOT` and `ANDROID_HOME`, so an image under another root (a slot-local
|
|
27
|
+
overlay, for example) is invisible to it.
|
|
28
|
+
- **Fix:** write the AVD's `.ini` and `config.ini` yourself, with `image.sysdir.1` relative
|
|
29
|
+
to the SDK root the emulator uses. Then apply
|
|
30
|
+
[the hardware keys](#a-hand-written-avd-misses-the-screen). An image that ships a `data/`
|
|
31
|
+
tree instead of `userdata.img` is fine: the emulator seeds userdata from it on first
|
|
32
|
+
boot.
|
|
33
|
+
|
|
34
|
+
### The emulator boots in software
|
|
35
|
+
|
|
36
|
+
- **Signal:** boot takes 10+ minutes.
|
|
37
|
+
- **Cause:** KVM is unusable to the emulator. A host where `test -r/-w /dev/kvm` passes but
|
|
38
|
+
Node's `fs.accessSync(R_OK | W_OK)` fails still falls back to software.
|
|
39
|
+
- **Fix:** check KVM with `accessSync` in the preflight, and set
|
|
40
|
+
`disable-linux-hw-accel: false`.
|
|
41
|
+
|
|
42
|
+
### Two jobs fight over `emulator-5554` or Metro's port
|
|
43
|
+
|
|
44
|
+
- **Cause:** runner slots share the host network, and the ports are not slot-derived.
|
|
45
|
+
- **Fix:** derive the ADB server, emulator console, backend and Metro ports from the slot
|
|
46
|
+
number ([ci.md](ci.md#runner)).
|
|
47
|
+
|
|
48
|
+
## Metro and adb
|
|
49
|
+
|
|
50
|
+
### Lost `adb reverse`
|
|
51
|
+
|
|
52
|
+
- **Signal:** earlier steps passed, then a screen's first Metro asset fails: `Unable to
|
|
53
|
+
download asset from url: http://127.0.0.1:8081/assets/…`, often an icon font. With
|
|
54
|
+
`expo-font`/`expo-asset`, every mounted icon reports a rejection (a burst of a dozen or
|
|
55
|
+
more). API calls on the same screen still succeed.
|
|
56
|
+
- **Cause:** an adb transport reconnect keeps the emulator in `device` state but deletes
|
|
57
|
+
every `adb reverse` mapping; `adb reverse --list` comes back empty. UI automation
|
|
58
|
+
recovers, Metro becomes unreachable, and a debug build loads assets from Metro. A
|
|
59
|
+
backend reached at `10.0.2.2` does not use adb, so it keeps working. The usual trigger is
|
|
60
|
+
an [adb transport drop](#the-adb-transport-drops-mid-journey); fix that first.
|
|
61
|
+
- **Fix:** re-prove the bridge before every step whose screen is the first to load a Metro
|
|
62
|
+
asset: re-apply the reverse and check, from inside the device, that Metro answers. Doing
|
|
63
|
+
it only at app launch is not enough. Release builds embed their assets, so this is a
|
|
64
|
+
harness failure, not a product failure.
|
|
65
|
+
|
|
66
|
+
### The adb transport drops mid-journey
|
|
67
|
+
|
|
68
|
+
- **Signal:** the host adb server's transport trace (`ADB_TRACE=transport`) shows
|
|
69
|
+
`remote local: terminated (data)` then `emulator-NNNN: connection terminated: read
|
|
70
|
+
failed` after boot, while the emulator stays up. About 0.5 s later the device is back
|
|
71
|
+
in `device` state, but [every `adb reverse` is gone](#lost-adb-reverse). Steps fail at
|
|
72
|
+
random, often during bursts of guest-to-host data (`dumpsys`, hierarchy dumps,
|
|
73
|
+
logcat). A drop during boot, before `sys.boot_completed`, is normal: adbd restarts once.
|
|
74
|
+
- **Cause:** guest memory, seen on x86_64 API 35/36 images with `android15-6.6` kernels
|
|
75
|
+
6.6.50 and 6.6.66. GKI `android15-6.6-2025-09` and later cap these pieces at about
|
|
76
|
+
28 KiB, which should avoid it, but no emulator image with such a kernel was tested. The guest kernel sends adb
|
|
77
|
+
data over virtio-vsock in pieces of up to 64 KiB, each needing one contiguous 128 KiB
|
|
78
|
+
allocation. At 2 GB (the usual AVD value), a busy journey fragments guest memory until that
|
|
79
|
+
allocation fails. adbd's `write()` gets `ENOMEM` (`error 12: Out of memory`), adbd
|
|
80
|
+
treats it as fatal, logs `connection terminated: write failed` and closes the transport
|
|
81
|
+
itself, so the host side is not the cause. In the traced runs only the job's own adb
|
|
82
|
+
server was connected to the emulator.
|
|
83
|
+
- **Fix:** give the guest 4 GB: `hw.ramSize=4096` in the AVD's `config.ini`, replacing any
|
|
84
|
+
existing value. At 4 GB the guest kept 127+ free blocks of 128 KiB or larger, with no
|
|
85
|
+
allocation stalls and no drops; at 2 GB it fell to 1 such block, with hundreds of
|
|
86
|
+
stalls. Keep re-proving `adb reverse` before Metro-dependent steps as a safety net.
|
|
87
|
+
- **Confirm:** with `adb root`, set `persist.adb.trace_mask=rwx,transport`, restart
|
|
88
|
+
adbd, and look for `writex: fd=N error 12` in `/data/adb/adb-*`. Guest tracepoints
|
|
89
|
+
`vsock/virtio_transport_{alloc,recv}_pkt` show adbd's own `SHUTDOWN` going out first;
|
|
90
|
+
`/proc/buddyinfo` shows order-5 and larger blocks (128 KiB+ contiguous) near zero.
|
|
91
|
+
- **Dead ends:**
|
|
92
|
+
- `-feature -VirtioVsockPipe`: adb stays `offline` forever on API 35.
|
|
93
|
+
- adb over TCP through the emulator console's `redir`: works only on boots where guest
|
|
94
|
+
`eth0` gets `10.0.2.15`.
|
|
95
|
+
- A newer emulator or platform-tools: no relevant fix in their release notes.
|
|
96
|
+
|
|
97
|
+
### `RemoteDisconnected` right after a new process connects
|
|
98
|
+
|
|
99
|
+
- **Signal:** the first uiautomator2 RPC in a newly started Python process raises
|
|
100
|
+
`RemoteDisconnected`. The adb transport stays registered: the trace shows `tcp:9008`
|
|
101
|
+
refused (`OPEN` then immediate `CLSE`), then a single stream `CLSE` with no response,
|
|
102
|
+
and no `connection terminated`.
|
|
103
|
+
- **Cause:** uiautomator2 keeps its on-device server inside an adb shell session owned by
|
|
104
|
+
the Python process that started it. When that process exits the server dies, and the
|
|
105
|
+
next process relaunches it. An RPC sent while it starts gets cut off, especially with
|
|
106
|
+
uiautomator2's own restart and retry bypassed.
|
|
107
|
+
- **Fix:** drive the whole journey from one process, or wait until the server answers
|
|
108
|
+
`/ping` before the first RPC. This is not an [adb drop](#the-adb-transport-drops-mid-journey).
|
|
109
|
+
|
|
110
|
+
## Journey harness
|
|
111
|
+
|
|
112
|
+
### A navigation check passes on the previous screen
|
|
113
|
+
|
|
114
|
+
- **Signal:** intermittently, a wait right after the next tap times out even though the
|
|
115
|
+
app works. The screen at failure is the destination of the previous navigation, often
|
|
116
|
+
scrolled by the harness's own swipes, and the app records no navigation for that tap.
|
|
117
|
+
- **Cause:** the check that should confirm arrival also matches text on the origin
|
|
118
|
+
screen, so it passes before the new screen lands. The next tap then hits the screen
|
|
119
|
+
mid-transition and is sometimes lost.
|
|
120
|
+
- **Fix:** after a navigation, wait for something only the destination shows, such as its
|
|
121
|
+
own record ID next to its label, never a value the origin also displays. To prove it,
|
|
122
|
+
make the unit tests' fake UI (the scripted hierarchy the harness tests read) keep the
|
|
123
|
+
origin on screen for a few reads and drop taps in that window; the test must fail
|
|
124
|
+
without the fix.
|
|
125
|
+
- **Example:** after `Original Payment Transaction` on a refund, the check waited for the
|
|
126
|
+
original's Provider Reference, which the refund also shows as `Parent Provider
|
|
127
|
+
Reference`. `Back to History` landed about 75 ms into the transition, and about one
|
|
128
|
+
cold run in three failed with `Timed out: return to History list`. Waiting for the
|
|
129
|
+
original's `Payment Transaction ID` fixed it.
|
|
130
|
+
|
|
131
|
+
### A wait never scrolls to its label
|
|
132
|
+
|
|
133
|
+
- **Signal:** a wait for a label times out only on a short or landscape screen (812x360,
|
|
134
|
+
for example) and passes on the phone. The screen at failure shows the content above the
|
|
135
|
+
label.
|
|
136
|
+
- **Cause:** UiAutomator lists only nodes that are on screen, and the wait checks the
|
|
137
|
+
hierarchy without scrolling. On a short screen the label sits below the fold.
|
|
138
|
+
- **First:** check `adb shell wm size`. A 320x480 screen is
|
|
139
|
+
[a hand-written AVD](#a-hand-written-avd-misses-the-screen), not this.
|
|
140
|
+
- **Fix:** scroll toward the label before or while waiting. To prove it, make the harness
|
|
141
|
+
test's fake UI keep the label off screen until a scroll; the test must fail without the
|
|
142
|
+
fix.
|
|
143
|
+
|
|
144
|
+
### A harness test fails on the runner's real state
|
|
145
|
+
|
|
146
|
+
- **Signal:** a harness unit test fails before the APK builds with a host-resource message
|
|
147
|
+
(`Retained native owner requires 2 GiB reserve`), and passes on a developer machine.
|
|
148
|
+
- **Cause:** the code under test reads real host state (free disk, SDK paths) that the
|
|
149
|
+
fixture does not fake, and the runner's state differs from the developer's.
|
|
150
|
+
- **Fix:** fake that state in the fixture. Then check the runner itself: a slot below the
|
|
151
|
+
threshold fails the real journey too.
|
|
152
|
+
|
|
153
|
+
### A new journey fails in the commit that adds it
|
|
154
|
+
|
|
155
|
+
- **Signal:** a journey added or changed in this commit fails waiting for a screen (`Select
|
|
156
|
+
your Store`) that the app no longer shows; the screen at failure shows the current app.
|
|
157
|
+
- **Cause:** often the journey was written against the old screen. A product regression
|
|
158
|
+
that only this journey exercises shows the same signal.
|
|
159
|
+
- **Fix:** read the screen at failure and the commit's product diff before choosing. If the
|
|
160
|
+
app shows the intended screen, update the journey; never change product code to match
|
|
161
|
+
a journey.
|
|
162
|
+
|
|
163
|
+
## CI runners
|
|
164
|
+
|
|
165
|
+
### The Android check is cancelled on the exact head
|
|
166
|
+
|
|
167
|
+
- **Signal:** the queue reads the cancelled check as failing.
|
|
168
|
+
- **Cause:** GitHub can deliver one push as two identical `pull_request` events.
|
|
169
|
+
- **Fix:** if Android has its own workflow, key `concurrency.group` on `github.run_id`
|
|
170
|
+
with `cancel-in-progress: false`.
|
|
171
|
+
|
|
172
|
+
### The native build takes ~20 minutes on an 8-CPU slot
|
|
173
|
+
|
|
174
|
+
- **Cause:** Gradle saw every host core.
|
|
175
|
+
- **Fix:** size `--max-workers` from the cgroup quota (`/sys/fs/cgroup/cpu.max`), not
|
|
176
|
+
`nproc`.
|
|
177
|
+
|
|
178
|
+
### Postgres setup hooks time out
|
|
179
|
+
|
|
180
|
+
- **Cause:** durability is on.
|
|
181
|
+
- **Fix:** disable `fsync` and `synchronous_commit` on the disposable service.
|
|
182
|
+
|
|
183
|
+
### The job never starts
|
|
184
|
+
|
|
185
|
+
- **Cause:** no online runner carries the label set.
|
|
186
|
+
- **Fix:** see the `github-actions` runner guide.
|
|
187
|
+
|
|
188
|
+
### `setup-java` or `setup-python` takes 10+ minutes on a new runner slot
|
|
189
|
+
|
|
190
|
+
- **Cause:** the slot's tool cache is empty, so the JDK or Python downloads from the
|
|
191
|
+
internet.
|
|
192
|
+
- **Fix:** seed the runner's `_tool/` directory from a sibling slot with the same image.
|
|
193
|
+
|
|
194
|
+
### A Backend call fails only in CI: the runner lacks a tool the app launches
|
|
195
|
+
|
|
196
|
+
- **Signal:** the journey passes locally but in CI a step that reaches the Backend
|
|
197
|
+
(receipt email, PDF share, export) gets a 5xx, and the backend log names a missing
|
|
198
|
+
program, e.g. `Receipt PDF generation failed: Browser was not found at the configured
|
|
199
|
+
executablePath`.
|
|
200
|
+
- **Cause:** the journey's Backend runs on the runner itself, and the self-hosted runner
|
|
201
|
+
image has no browser (or other app-launched tool). A developer machine does, so it only
|
|
202
|
+
fails in CI.
|
|
203
|
+
- **Fix:** don't install it on the runner, and don't treat it as a product bug. Point the
|
|
204
|
+
app's browser variable (`CHROMIUM_PATH`) at a wrapper that runs the pinned Playwright
|
|
205
|
+
image's browser: `github-actions` → `references/runners.md`, "A host process that needs
|
|
206
|
+
a browser binary". Prove it in CI; Docker Desktop on macOS cannot reach the wrapper's
|
|
207
|
+
host-network port.
|
|
208
|
+
|
|
209
|
+
### A failed run's Metro log is gone
|
|
210
|
+
|
|
211
|
+
- **Cause:** the journey writes raw service logs under the checkout (`test-results/`), and
|
|
212
|
+
the next job's checkout removes them.
|
|
213
|
+
- **Fix:** for a diagnosis, copy the Metro log and a full `adb logcat` to persistent
|
|
214
|
+
storage outside the checkout. Keep them off uploaded artifacts: they are unsanitized.
|
|
215
|
+
|
|
216
|
+
## Confirm a suspected cause
|
|
217
|
+
|
|
218
|
+
Inject the suspected cause on purpose, for example `adb reverse --remove tcp:8081` right
|
|
219
|
+
before the failing step, and check that it reproduces the exact failure signature: the same
|
|
220
|
+
step, error and error count. Then show that the fix passes the same injection. A cause that
|
|
221
|
+
does not reproduce its signature is a guess, and a fix for a guess is not proof.
|