diff --git a/.cursor/skills/engine-e2e/SKILL.md b/.cursor/skills/engine-e2e/SKILL.md new file mode 100644 index 0000000000..fe2ab0356b --- /dev/null +++ b/.cursor/skills/engine-e2e/SKILL.md @@ -0,0 +1,112 @@ +--- +name: engine-e2e +description: Run Wix Engine (mobile-apps-engine) iOS E2E tests locally to validate RNN changes. Use when you need to test RNN fixes against the Engine's Detox test suite. +--- + +# Running Engine E2E Tests Against Local RNN Changes + +The Engine app (`@wix/wix-one-app-engine`) in `~/Documents/mobile-apps-engine` consumes RNN +from `node_modules/react-native-navigation`. To test RNN changes against the Engine's E2E +suite, you patch the Engine's copy of RNN, rebuild the native binary, and run the tests. + +## Prerequisites + +- Node via nvm (`nvm use default`) +- The `CI` env var must be **unset** (not `0`, fully unset) to avoid CI-specific codepaths. + Use `env -u CI` before every command. +- The Engine repo at `~/Documents/mobile-apps-engine` with `yarn install` already done. + +## Step 1: Patch RNN in Engine's node_modules + +Apply your RNN source changes to the corresponding files under: +``` +~/Documents/mobile-apps-engine/node_modules/react-native-navigation/ios/ +``` +The directory structure mirrors the RNN repo's `ios/` folder exactly. + +## Step 2: Rebuild the iOS Native Binary + +```bash +cd ~/Documents/mobile-apps-engine +unset PREFIX && . ~/.nvm/nvm.sh > /dev/null && nvm use default > /dev/null +env -u CI yarn workspace @wix/mobile-apps-engine-native-builds build-local-ios +``` + +This runs `xcodebuild` with `-quiet` flag — expect no output until it finishes. +Takes ~10-15 minutes on M-series Macs. + +The build output (`.app` bundle) lands in: +``` +packages/native/mobile-apps-engine-native-builds/dist/binaries.json +``` + +### Troubleshooting Build + +- **Keychain error** (`SecKeychainUnlock`): The `CI` env var is set. Use `env -u CI`. +- **Signing errors**: Expected for local builds — the script handles ad-hoc signing. + +## Step 3: Build JS Bundles (first time only) + +These are needed once per checkout. Skip if already built. + +```bash +env -u CI yarn workspace @wix/mobile-apps-engine-extra-bundle local:build +env -u CI yarn workspace @wix/mobile-apps-dependencies local:build +``` + +## Step 4: Run E2E Tests + +```bash +cd ~/Documents/mobile-apps-engine +unset PREFIX && . ~/.nvm/nvm.sh > /dev/null && nvm use default > /dev/null +env -u CI yarn workspace @wix/wix-one-app-engine test:e2e:ios -w d +``` + +The `-w d` flag selects the Detox worker count. + +### Specific suites relevant to RNN + +| Suite file | What it tests | +|-----------|---------------| +| `e2e/suites/ExternalLinks.test.js` | Deep link navigation, back button | +| `e2e/suites/ExternalLinksModes.test.js` | Deep link modes (pop to root, tab switch) | +| `e2e/suites/ExternalLinksPushNotifications.test.js` | Push notification deep links | +| `e2e/suites/ExtenalLinksWithSiteSelect.test.js` | Deep links with site selection | +| `e2e/suites/EngineUIComponents.test.js` | Error screen, UI components | +| `e2e/suites/LaunchArgs.test.js` | Launch arguments | +| `e2e/suites/LazyModules.test.js` | Lazy-loaded modules | + +### Example: Run the deep-link suites + +```bash +env -u CI yarn workspace @wix/wix-one-app-engine test:e2e:ios -w d \ + e2e/suites/ExternalLinks.test.js \ + e2e/suites/ExternalLinksModes.test.js \ + e2e/suites/ExternalLinksPushNotifications.test.js +``` + +### Troubleshooting Tests + +- **`Error: No dist version found`**: The native build hasn't run or failed. + Run step 2 again. +- **`Cannot find module .../mobile-apps-engine-extra-bundle/index.js`**: + Run step 3 (`local:build` for extra-bundle). +- **`ENOENT .../metadata.json`**: Run step 3 (`local:build` for mobile-apps-dependencies). +- **`Unable to resolve module @rozenite/...`**: The Rozenite plugin import is broken. + Patch `packages/wix-one-app-engine/src/rozenitePlugin/helper/rozenite-network-inspector.ts` + to make the import optional with a no-op fallback. +- **Tests time out on `navigateBack()`**: The `navigateBack()` helper taps + `element(by.id('pop'))` on iOS. This relies on RNN's `setBackButtonTestID` working + correctly. If the back button's view hierarchy changed (e.g., iOS 26 Liquid Glass), + the testID isn't applied and the element can't be found. + +## Key Engine Files + +| File | Purpose | +|------|---------| +| `packages/wix-one-app-engine/e2e/helpers/utils.js` | Test helpers including `navigateBack()` | +| `packages/wix-one-app-engine/demo-modules/deep-links/module.js` | Deep link route definitions | +| `packages/wix-one-app-engine/demo-modules/deep-links/Screens.js` | Deep link screen components | +| `packages/wix-one-app-engine/internalScripts/test-e2e.js` | E2E test runner script | +| `packages/native/mobile-apps-engine-native-builds/local_build_scripts/build_ios.js` | Local iOS build script | +