Skip to content

Commit 5fffc1d

Browse files
sherwinskisherwinski
authored
docs(appium): per-SDK prerequisites, run-all/--releases, fix stale vpx note (#49)
1 parent 2f91030 commit 5fffc1d

1 file changed

Lines changed: 40 additions & 2 deletions

File tree

‎appium/scripts/README.md‎

Lines changed: 40 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,15 @@ The script checks all of these up front and prints the exact install command for
5656

5757
> **CI vs local:** CI runs on BrowserStack (Node 24) without this script. Notification-dependent tests (in `02_push.spec.ts` and `12_activity.spec.ts`) are skipped on BrowserStack iOS via `isBrowserStackIos()` because BrowserStack requires an Enterprise Signing Certificate for those notification flows, which we don't have yet (temporary — they'll be re-enabled once signing support is available), so for now they only run locally. If your local Node is 26+, the script sets `WDIO_USE_NATIVE_FETCH=1` automatically.
5858
59+
### Per-SDK prerequisites
60+
61+
`bootstrap.sh` handles the shared tooling. Individual SDKs need a bit more the first time:
62+
63+
- **All wrapper SDKs:** install the SDK repo's own deps once (`bun install` in the repo root). `build.sh` packs the SDK from source but does not install its deps.
64+
- **flutter:** enable Swift Package Manager once — `flutter config --enable-swift-package-manager`. Without it, `flutter build ios` falls back to CocoaPods, which fails on the prebuilt OneSignal XCFramework with `Multiple commands produce …/XCFrameworkIntermediates/…`.
65+
- **dotnet:** the demo targets **.NET 10**, so use the **official .NET 10 SDK** (Homebrew's `dotnet` can't install workloads), then `dotnet workload install maui`. iOS builds require **Xcode 26.6 / iOS 26.5 SDK** — run `xcodebuild -downloadPlatform iOS` to get the matching simulator runtime. On Apple Silicon, if the tarball SDK is killed with "Code Signature Invalid", ad-hoc re-sign it (`codesign --force --sign - …`).
66+
- **unity:** install the exact editor the demo pins — see `examples/demo/ProjectSettings/ProjectVersion.txt` (e.g. `6000.4.11f1`) — **with the iOS Build Support module**, and activate a Unity license (Unity Hub → Preferences → Licenses). On recent macOS, `brew install rsync`: Apple's bundled `openrsync` fails the Unity XCFramework dSYM copy during the Xcode build.
67+
5968
## Usage
6069

6170
```bash
@@ -69,7 +78,7 @@ If `--platform` or `--sdk` are not provided, the script prompts interactively.
6978
| Flag | Description |
7079
| --------------- | ----------------------------------------------------------- |
7180
| `--platform=P` | `ios` or `android` |
72-
| `--sdk=S` | `flutter` or `react-native` |
81+
| `--sdk=S` | `flutter`, `react-native`, `cordova`, `capacitor`, `expo`, `dotnet`, `unity`, `android`, `ios` |
7382
| `--spec=GLOB` | Spec file glob (default: `tests/specs/**/*.spec.ts`) |
7483
| `--skip` | Skip build, device launch, and app reset (rerun tests only) |
7584
| `--skip-build` | Skip app build (reuse existing `.app`/`.apk`) |
@@ -116,6 +125,22 @@ Skip only the build (simulator + reset still happen):
116125
./run-local.sh --platform=ios --sdk=flutter --skip-build
117126
```
118127

128+
## Running all combos (`run-all.sh`)
129+
130+
`run-all.sh` loops `run-local.sh` over every SDK/platform combo and prints a PASS/FAIL summary.
131+
132+
```bash
133+
./run-all.sh # every combo, both platforms
134+
./run-all.sh --platform=ios # iOS only
135+
./run-all.sh --sdks=flutter,react-native # subset of SDKs
136+
./run-all.sh --releases # check out the latest release point per repo first
137+
./run-all.sh --bail # stop after the first failing combo
138+
```
139+
140+
`--releases` runs `checkout-releases.sh`, which checks out the newest stable `rel/X.Y.Z` branch (or newest semver tag for expo/ios) in each SDK repo, honoring the `*_DIR` overrides from `.env`. Repos with uncommitted changes are skipped, never clobbered.
141+
142+
> Within each combo the specs still **bail on the first failing test** locally (`mochaOpts.bail = isLocal`), so one early failure hides the specs after it.
143+
119144
### Environment Variables
120145

121146
All env vars can be set in `.env` or exported in your shell. See [`.env.example`](.env.example) for the full list.
@@ -125,6 +150,15 @@ All env vars can be set in `.env` or exported in your shell. See [`.env.example`
125150
| `ONESIGNAL_APP_ID` | -- | OneSignal app ID (written to demo app `.env`) |
126151
| `ONESIGNAL_API_KEY` | -- | OneSignal REST API key |
127152
| `FLUTTER_DIR` | `../../OneSignal-Flutter-SDK` | Path to the Flutter SDK repo |
153+
| `RN_DIR` | `../../react-native-onesignal` | React Native SDK repo |
154+
| `CORDOVA_DIR` | `../../OneSignal-Cordova-SDK` | Cordova SDK repo |
155+
| `CAPACITOR_DIR` | `../../OneSignal-Capacitor-SDK` | Capacitor SDK repo |
156+
| `EXPO_DIR` | `../../onesignal-expo-plugin` | Expo plugin repo |
157+
| `DOTNET_DIR` | `../../DotNet/OneSignal-DotNet-SDK`| .NET MAUI SDK repo |
158+
| `UNITY_DIR` | `../../OneSignal-Unity-SDK` | Unity SDK repo |
159+
| `ANDROID_DIR` | `../../OneSignal-Android-SDK` | Native Android SDK repo |
160+
| `IOS_DIR` | `../../OneSignal-iOS-SDK` | Native iOS SDK repo |
161+
| `UNITY_PATH` | Unity Hub editor path | Unity Editor binary (unity builds) |
128162
| `APP_PATH` | auto-detected from build | Path to `.app` or `.apk` |
129163
| `BUNDLE_ID` | `com.onesignal.example` | App bundle/package ID |
130164
| `DEVICE` | `iPhone 17` / `Samsung Galaxy S26` | Device name for WebdriverIO |
@@ -147,10 +181,14 @@ All env vars can be set in `.env` or exported in your shell. See [`.env.example`
147181

148182
- **Appium fails to start**: Make sure Appium and the required drivers are installed (`appium driver list --installed`). The script checks both up front and prints the install command for anything missing.
149183

150-
- **`vpx: command not found`**: Install [Vite+](https://vite.plus) with `curl -fsSL https://vite.plus | bash`. If `vp` is installed but `vpx` is missing, run `vp --version` once — `vp` creates the `vpx` symlink on its first run.
184+
- **`vpx: command not found`**: Run `./bootstrap.sh` (installs Vite+ and creates the `vpx` symlink), or install manually with `curl -fsSL https://vite.plus | bash`. The installer sometimes omits the `vpx` symlink — if `vp` exists but `vpx` doesn't, create it and open a new shell: `ln -sf ../current/bin/vp ~/.vite-plus/bin/vpx`. (The npm `vite-plus` package ships no `vpx`.)
151185

152186
- **`UND_ERR_INVALID_ARG` / fetch errors on Node 26+**: webdriverio's undici dispatcher is rejected by Node 26+'s `fetch`. The script exports `WDIO_USE_NATIVE_FETCH=1` automatically when it detects Node 26+; if you invoke `vpx wdio run` manually, export it yourself.
153187

154188
- **Test waiting for the notification permission alert fails**: A reused simulator remembers a previously-decided notification permission, and `simctl privacy` can't reset it. The script's app reset uninstalls the app, which restores the prompt — avoid `--skip`/`--skip-reset` when running the push specs.
155189

156190
- **Misleading "element not displayed" failures**: Live in-app marketing campaigns on the configured app can cover the UI. Use the OneSignal app dedicated to Appium tests (set `ONESIGNAL_APP_ID`/`ONESIGNAL_API_KEY` in `.env`) rather than a general or shared app.
191+
192+
- **Only a few specs ran before the suite stopped**: Local runs bail on the first failing test (`mochaOpts.bail = isLocal`), so one early failure masks the specs after it. Use `--spec` to isolate a spec, or fix the first failure and re-run.
193+
194+
- **Image-notification / Live-Activity tests fail locally**: The `02_push` image test and `12_activity` are skipped on BrowserStack and only run locally, so they need manual attention. The image test's attachment check can be too short for the simulator (rich media downloads slower than the wait), so it may flake — confirm manually by sending the notification and long-pressing the banner to see the attached image.

0 commit comments

Comments
 (0)