Skip to content

Commit 38cf062

Browse files
abueideclaude
abueide
and
claude
committed
docs: add deploy, app lifecycle, and readiness probe commands
Document new user-layer commands added as part of the test suite standardization effort: - ios.sh: simulator ready, deploy, app status/stop - android.sh: emulator ready, deploy, app status/stop - SUITE_NAME env var for test isolation - IOS_RUNTIME_DIR / ANDROID_RUNTIME_DIR state files Updated across all reference docs: - plugins/android/REFERENCE.md - plugins/ios/REFERENCE.md - wiki/reference/android.md - wiki/reference/ios.md - wiki/reference/cli-commands.md Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 3c1bf8a commit 38cf062

5 files changed

Lines changed: 331 additions & 28 deletions

File tree

‎plugins/android/REFERENCE.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -93,7 +93,12 @@ Use in `devbox.json`:
9393
- `devbox run --pure android.sh emulator start [--pure] [device]`
9494
- `--pure`: Start fresh emulator with wiped data (clean Android OS state for deterministic tests)
9595
- Without `--pure`: Reuses existing emulator if running (faster for development, preserves data)
96+
- Auto-detects pure mode when `IN_NIX_SHELL=pure` or `DEVBOX_PURE_SHELL=1`
9697
- `devbox run --pure android.sh emulator stop`
98+
- `devbox run --pure android.sh emulator ready`
99+
- Silent readiness probe: exit 0 if emulator is booted, exit 1 if not
100+
- Reads emulator serial from suite-namespaced state file
101+
- Checks `adb -s $serial shell getprop sys.boot_completed`
97102
- `devbox run --pure android.sh emulator reset [device]`
98103

99104
**Convenience aliases:**
@@ -103,6 +108,33 @@ Use in `devbox.json`:
103108
**Behavior:**
104109
- Without `--pure`: Checks if an emulator with the same AVD is already running and reuses it
105110
- With `--pure`: Always starts a new emulator instance with `-wipe-data` flag (fresh Android OS)
111+
- Emulator serial is saved to `$ANDROID_RUNTIME_DIR/${SUITE_NAME:-default}/emulator-serial.txt`
112+
113+
### Deploy
114+
115+
```bash
116+
android.sh deploy [apk_path]
117+
```
118+
- Installs and launches an app on an already-running emulator (no build, no emulator start)
119+
- If `apk_path` is provided, installs the specified APK
120+
- If no arguments, auto-detects APK using the same resolution as `run`
121+
- Reads emulator serial from suite-namespaced state file
122+
- Saves app ID and activity to state files for use by `app status` and `app stop`
123+
124+
### App Lifecycle
125+
126+
```bash
127+
android.sh app status
128+
```
129+
- Checks if the deployed app is running on the emulator
130+
- Exit 0 if running, exit 1 if not
131+
- Reads app ID and emulator serial from suite-namespaced state files
132+
133+
```bash
134+
android.sh app stop
135+
```
136+
- Stops the deployed app via `adb shell am force-stop`
137+
- Reads app ID and emulator serial from suite-namespaced state files
106138

107139
### Run app
108140

@@ -163,5 +195,12 @@ Use in `devbox.json`:
163195
- Or set in test suite environment sections (process-compose spawns new shells)
164196
- Cannot be set within script definitions (too late, init hook already ran)
165197

198+
### Runtime state
199+
- `ANDROID_RUNTIME_DIR` - Directory for runtime state files (default: `.devbox/virtenv/android`)
200+
- `SUITE_NAME` - Test suite name for state isolation (default: "default")
201+
- Each suite gets its own subdirectory under `$ANDROID_RUNTIME_DIR/$SUITE_NAME/`
202+
- State files: `emulator-serial.txt`, `app-id.txt`, `app-activity.txt`
203+
- Set in process-compose environment blocks for parallel test execution
204+
166205
### App configuration
167206
- `ANDROID_APP_APK` - Path or glob pattern for APK (relative to project root; empty = auto-detect)

‎plugins/ios/REFERENCE.md‎

Lines changed: 63 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -60,17 +60,68 @@ Configure the plugin by setting environment variables in `devbox.json` or `plugi
6060

6161
Start simulator:
6262
```bash
63-
devbox run --pure start:sim [device]
63+
ios.sh simulator start [--pure] [device]
6464
```
6565
- If `device` is specified, uses that device name
6666
- Otherwise uses `IOS_DEFAULT_DEVICE`
6767
- Boots simulator if not already running
68+
- `--pure`: Creates a fresh, isolated test simulator with clean state (for deterministic tests)
69+
- Auto-detects pure mode when `IN_NIX_SHELL=pure` or `DEVBOX_PURE_SHELL=1`
70+
- Saves simulator UDID to `$IOS_RUNTIME_DIR/${SUITE_NAME:-default}/simulator-udid.txt`
71+
- In pure mode, test simulator name includes suite label for isolation (e.g., `"iPhone 17 (iOS 26.2) Test-ios-e2e"`)
72+
73+
**Convenience aliases:**
74+
- `devbox run --pure start:sim [device]` (equivalent to `ios.sh simulator start` without `--pure`)
75+
- `devbox run --pure stop:sim` (equivalent to `ios.sh simulator stop`)
6876

6977
Stop simulator:
7078
```bash
71-
devbox run --pure stop:sim
79+
ios.sh simulator stop
80+
```
81+
- In pure mode (test simulator exists): shuts down and deletes the test simulator, cleans up state files
82+
- In normal mode: shuts down the simulator via `ios_stop()`
83+
84+
Check simulator readiness:
85+
```bash
86+
ios.sh simulator ready
87+
```
88+
- Silent readiness probe: exit 0 if simulator is booted, exit 1 if not
89+
- Reads UDID from suite-namespaced state file, falls back to finding any booted simulator
90+
- Designed for use as a process-compose readiness probe
91+
92+
Reset simulators:
93+
```bash
94+
ios.sh simulator reset
95+
```
96+
- Stops all running simulators
97+
- Deletes simulators matching device definitions
98+
99+
### Deploy
100+
101+
```bash
102+
ios.sh deploy [app_path]
103+
```
104+
- Installs and launches an app on an already-running simulator (no build, no simulator start)
105+
- If `app_path` is provided, installs the specified .app bundle
106+
- If no arguments, auto-detects .app using `ios_find_app()` (same resolution as `run`)
107+
- Reads simulator UDID from suite-namespaced state file
108+
- Extracts bundle ID from the app's `Info.plist`
109+
- Saves bundle ID to `$IOS_RUNTIME_DIR/${SUITE_NAME:-default}/bundle-id.txt`
110+
111+
### App Lifecycle
112+
113+
```bash
114+
ios.sh app status
72115
```
73-
- Shuts down all running simulators
116+
- Checks if the deployed app is running on the simulator
117+
- Exit 0 if running, exit 1 if not
118+
- Reads bundle ID and simulator UDID from suite-namespaced state files
119+
120+
```bash
121+
ios.sh app stop
122+
```
123+
- Terminates the deployed app via `xcrun simctl terminate`
124+
- Reads bundle ID and simulator UDID from suite-namespaced state files
74125

75126
### Build
76127

@@ -152,7 +203,7 @@ Also available as the `ios_xcodebuild()` shell function (from `platform/core.sh`
152203
### Run App
153204

154205
```bash
155-
devbox run --pure ios.sh run [app_path] [device]
206+
ios.sh run [app_path] [device]
156207
```
157208
- Starts simulator, builds, resolves, installs, and launches the app
158209
- If `app_path` is provided, skips build step and installs the provided .app bundle
@@ -386,6 +437,14 @@ These are set automatically by the plugin:
386437
- `PATH` — Updated with Xcode tools and plugin scripts
387438
- `IOS_NODE_BINARY` — Node.js binary path (if available, for React Native)
388439

440+
### Runtime State
441+
442+
- `IOS_RUNTIME_DIR` — Directory for runtime state files (default: `.devbox/virtenv/ios/runtime`)
443+
- `SUITE_NAME` — Test suite name for state isolation (default: "default")
444+
- Each suite gets its own subdirectory under `$IOS_RUNTIME_DIR/$SUITE_NAME/`
445+
- State files: `simulator-udid.txt`, `test-simulator-udid.txt` (pure mode only), `bundle-id.txt`
446+
- Set in process-compose environment blocks for parallel test execution
447+
389448
### Runtime Variables
390449

391450
Set during simulator/app operations:

‎wiki/reference/android.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,7 +83,11 @@ android.sh run [apk_path] [device]
8383
- `devbox run --pure android.sh emulator start [--pure] [device]`
8484
- `--pure`: Start fresh emulator with wiped data (clean Android OS state for deterministic tests)
8585
- Without `--pure`: Reuses existing emulator if running (faster for development, preserves data)
86+
- Auto-detects pure mode when `IN_NIX_SHELL=pure` or `DEVBOX_PURE_SHELL=1`
8687
- `devbox run --pure android.sh emulator stop`
88+
- `devbox run --pure android.sh emulator ready`
89+
- Silent readiness probe: exit 0 if emulator is booted, exit 1 if not
90+
- Reads emulator serial from suite-namespaced state file
8791
- `devbox run --pure android.sh emulator reset [device]`
8892

8993
**Convenience aliases:**
@@ -93,6 +97,30 @@ android.sh run [apk_path] [device]
9397
**Behavior:**
9498
- Without `--pure`: Checks if an emulator with the same AVD is already running and reuses it
9599
- With `--pure`: Always starts a new emulator instance with `-wipe-data` flag (fresh Android OS)
100+
- Emulator serial is saved to `$ANDROID_RUNTIME_DIR/${SUITE_NAME:-default}/emulator-serial.txt`
101+
102+
### Deploy
103+
104+
```bash
105+
android.sh deploy [apk_path]
106+
```
107+
- Installs and launches an app on an already-running emulator (no build, no emulator start)
108+
- If `apk_path` is provided, installs the specified APK
109+
- If no arguments, auto-detects APK using the same resolution as `run`
110+
- Saves app ID and activity to state files for use by `app status` and `app stop`
111+
112+
### App Lifecycle
113+
114+
```bash
115+
android.sh app status
116+
```
117+
- Checks if the deployed app is running on the emulator
118+
- Exit 0 if running, exit 1 if not
119+
120+
```bash
121+
android.sh app stop
122+
```
123+
- Stops the deployed app via `adb shell am force-stop`
96124

97125
### Device management
98126

@@ -138,6 +166,13 @@ Configuration is managed via environment variables in `devbox.json`, not via CLI
138166
- Or set in test suite environment sections (process-compose spawns new shells)
139167
- Cannot be set within script definitions (too late, init hook already ran)
140168

169+
### Runtime state
170+
- `ANDROID_RUNTIME_DIR` - Directory for runtime state files (default: `.devbox/virtenv/android`)
171+
- `SUITE_NAME` - Test suite name for state isolation (default: "default")
172+
- Each suite gets its own subdirectory under `$ANDROID_RUNTIME_DIR/$SUITE_NAME/`
173+
- State files: `emulator-serial.txt`, `app-id.txt`, `app-activity.txt`
174+
- Set in process-compose environment blocks for parallel test execution
175+
141176
### App configuration
142177
- `ANDROID_APP_APK` - Path or glob pattern for APK (relative to project root; empty = auto-detect)
143178
- `ANDROID_BUILD_CONFIG` - Build configuration: Debug or Release (default: Debug)

0 commit comments

Comments
 (0)