@unrulysystems/rn-playwright-driver-runner 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @unrulysystems/rn-playwright-driver-runner
 
+## 0.1.1
+
+### Patch Changes
+
+- [#27](https://github.com/unrulysystems/rn-playwright-driver/pull/27) [`b8eb24e`](https://github.com/unrulysystems/rn-playwright-driver/commit/b8eb24e9daef7f00605fe06dcf520089f62f58be) Thanks [@alleneubank](https://github.com/alleneubank)! - Harden the runner and driver fixtures for dev-client dogfooding.
+
+  The runner now ships a Node-compatible `rn-driver` bin, supports Android
+  Expo dev-client deep-link launch, and documents runner-owned lifecycle
+  boundaries. The driver Playwright fixture resolves `@playwright/test` from the
+  consumer project so npm and Yarn installs use the app's Playwright instance.
+
 ## 0.1.0
 
 ### Initial Release

package/README.md

@@ -29,7 +29,7 @@ this package; your Playwright specs import the driver directly.)
 ## Install
 
 ```bash
-bun add -d @unrulysystems/rn-playwright-driver-runner
+npm install --save-dev @unrulysystems/rn-playwright-driver-runner
 ```
 
 This package orchestrates the platform companions; install and configure them per
@@ -68,6 +68,8 @@ export default defineRnDriverConfig({
   android: {
     packageName: 'com.company.app',
     activity: '.MainActivity',
+    // Required only for expo-dev-client launch:
+    // scheme: 'companyapp',
     launch: { mode: 'launch', kind: 'plain' },
   },
   playwright: {
@@ -77,7 +79,34 @@ export default defineRnDriverConfig({
 ```
 
 A plain (non dev-client) Expo app uses `launch: { mode: 'launch', kind: 'plain' }`
-on iOS — the companion launches the app itself.
+on both platforms. The companion launches the app itself on iOS; Android launches
+the configured `packageName`/`activity` directly.
+
+For Expo dev-client, the host owns native app launch so the app starts on the
+test Metro instead of stopping at the launcher UI:
+
+```ts
+export default defineRnDriverConfig({
+  metro: { command: 'npx expo start --localhost --port 8081' },
+  ios: {
+    bundleId: 'com.company.app',
+    workspace: 'ios/App.xcworkspace',
+    appScheme: 'App',
+    launch: { mode: 'attach', kind: 'expo-dev-client' },
+  },
+  android: {
+    packageName: 'com.company.app',
+    activity: '.MainActivity',
+    scheme: 'companyapp',
+    launch: { mode: 'launch', kind: 'expo-dev-client' },
+  },
+})
+```
+
+`launch.initialUrl` defaults to the resolved Metro URL on iOS and Android. iOS
+uses `simctl launch --initialUrl`; Android uses the configured
+`android.scheme` to open
+`<scheme>://expo-development-client/?url=<resolved-metro-url>`.
 
 ## Run
 
@@ -128,13 +157,57 @@ Token material always travels by `0600` file path (the driver's
 `--dry-run` output. Cleanup is defensive and idempotent — a crashed prior run
 never wedges the next (stale companion ports are freed at startup and teardown).
 
+### Playwright lifecycle boundary
+
+Invoke specs through `rn-driver test`, not a standalone `playwright test`
+command. The runner starts or reuses Metro, builds and launches the native app,
+starts the companion, waits for Hermes, sets the driver env contract, runs
+Playwright, and cleans up the state it owns.
+
+Runner-managed Playwright configs should not define app-level `globalSetup` or
+`globalTeardown` that starts/stops Metro, launches the native app, starts/stops a
+touch companion, or removes runner companion state. Keep those hooks for
+test-local concerns only. Specs should consume the environment that
+`rn-driver test` provides.
+
+### Runner env contract
+
+These names are the runner-owned surface between native lifecycle setup and
+Playwright/driver execution. Token values are never exposed; only file paths are.
+
+| Variable                                                               | Scope   | Meaning                                            |
+| ---------------------------------------------------------------------- | ------- | -------------------------------------------------- |
+| `RN_METRO_URL`                                                         | both    | Metro URL the app and driver should use            |
+| `RN_DEVICE_NAME`                                                       | both    | Hermes target device-name pin                      |
+| `RN_TIMEOUT`                                                           | both    | Driver request timeout                             |
+| `RN_TOUCH_BACKEND`                                                     | both    | `xctest` on iOS, `instrumentation` on Android      |
+| `RN_TOUCH_XCTEST_PORT`, `RN_TOUCH_XCTEST_TOKEN_FILE`                   | iOS     | XCTest companion port and token-file path          |
+| `RN_TOUCH_INSTRUMENTATION_PORT`, `RN_TOUCH_INSTRUMENTATION_TOKEN_FILE` | Android | Instrumentation companion port and token-file path |
+| `ANDROID_SERIAL`                                                       | Android | adb device pin for the selected emulator/device    |
+
+The runner also owns internal token/config file paths used to start companions
+and configure native test targets. Do not pass token values through argv, inline
+env, or docs.
+
+### Prebuild environment and priming
+
+`expo prebuild` runs inside the runner process, so it inherits the runner
+process environment. The intended stable marker for test-only Expo config,
+plugins, or native settings is `RN_E2E=1`; this package does not emit that marker
+yet, so treat it as the planned contract rather than current behavior.
+
+The implemented lifecycle already covers prebuild, Metro, app launch, companion
+startup, Hermes waits, Playwright env, and cleanup. Priming controls such as
+`RN_E2E_PRIMED=1` or a `prebuild.clean` option are future design space and are
+not available runner flags today.
+
 ## Requirements
 
-- The `rn-driver` CLI runs under **bun**. The `bin` is a thin bun shim (mirroring
-  the driver's `rn-inspect`) so a TypeScript `rn-driver.config.ts` loads without a
-  separate compile step. Install bun: <https://bun.sh>.
+- The `rn-driver` CLI runs under **Node >= 22**. The published `bin` is a thin
+  Node shim that loads built JavaScript from `dist`, so npm/Yarn consumers do not
+  need bun or nub on `PATH`.
 - The readiness probes use the global `WebSocket`/`fetch`, so embedding the
-  library API (the `.` export) standalone requires **bun** or **Node >= 22**.
+  library API (the `.` export) standalone requires **Node >= 22**.
 - The platform companion packages installed and their Expo config plugins added.
 - `xcrun`/`xcodebuild`/`pod` (iOS) and `adb`/`gradle` (Android) on `PATH`.
 

package/bin/rn-driver.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { run } from '../dist/cli.mjs'
+
+try {
+  process.exitCode = await run(process.argv.slice(2))
+} catch (error) {
+  console.error(error)
+  process.exitCode = 1
+}

package/dist/cli.js

@@ -216,9 +216,10 @@ function planAndroid(input) {
       }
     }
   });
-  const launchCommand = launchCommandFor(android, serial);
-  push(launchStep("android.launch-1", android, serial));
-  push(hermesStep("android.hermes-1", android, metro, resolved, hermesDeviceName, launchCommand));
+  const launch1Command = launchCommandFor(android, resolved, serial, { forceStopBefore: true });
+  const launch2Command = launchCommandFor(android, resolved, serial, { forceStopBefore: false });
+  push(launchStep("android.launch-1", android, launch1Command));
+  push(hermesStep("android.hermes-1", android, metro, resolved, hermesDeviceName, launch1Command));
   push({
     id: "android.forward-clean",
     stage: "companion",
@@ -275,8 +276,8 @@ function planAndroid(input) {
       }
     }
   });
-  push(launchStep("android.launch-2", android, serial));
-  push(hermesStep("android.hermes-2", android, metro, resolved, hermesDeviceName, launchCommand));
+  push(launchStep("android.launch-2", android, launch2Command));
+  push(hermesStep("android.hermes-2", android, metro, resolved, hermesDeviceName, launch2Command));
   const cleanup = [
     {
       type: "kill-process",
@@ -331,22 +332,34 @@ function planAndroid(input) {
     playwright: playwrightCommand(playwright, specs, passthrough)
   };
 }
-function launchCommandFor(android, serial) {
-  return adb(serial, [
-    "shell",
-    "am",
-    "start",
-    "-W",
-    "-n",
-    `${android.packageName}/${android.activity}`
-  ]);
-}
-function launchStep(id, android, serial) {
+function launchCommandFor(android, resolved, serial, opts) {
+  if (android.launch.kind === "plain") {
+    return adb(serial, [
+      "shell",
+      "am",
+      "start",
+      "-W",
+      "-n",
+      `${android.packageName}/${android.activity}`
+    ]);
+  }
+  if (!android.scheme) {
+    throw new Error('android.scheme is required when android.launch.kind is "expo-dev-client"');
+  }
+  const launchScript = `am start -a android.intent.action.VIEW -d ${shellSingleQuote(
+    devClientUrl(android.scheme, resolved.initialUrl)
+  )}`;
+  return adbShellScript(
+    serial,
+    opts.forceStopBefore ? `am force-stop ${android.packageName} && ${launchScript}` : launchScript
+  );
+}
+function launchStep(id, android, command) {
   return {
     id,
     stage: "app-launch",
     description: `Launch ${android.packageName}/${android.activity}`,
-    action: { type: "command", command: launchCommandFor(android, serial) }
+    action: { type: "command", command }
   };
 }
 function hermesStep(id, android, metro, resolved, deviceNameMatch, launchCommand) {
@@ -380,6 +393,12 @@ function debugHostXml(host) {
 function adb(serial, args) {
   return { command: "adb", args: ["-s", serial, ...args] };
 }
+function devClientUrl(scheme, initialUrl) {
+  return `${scheme}://expo-development-client/?url=${initialUrl}`;
+}
+function shellSingleQuote(value) {
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
 function adbShellScript(serial, remote) {
   return { command: "adb", args: ["-s", serial, "shell", remote] };
 }
@@ -425,8 +444,7 @@ function planIos(input) {
       // Pass the resolved UI-test scheme so a custom `ios.uitestScheme` scaffolds
       // the SAME target that companion startup later builds (default is
       // `${appScheme}UITests`).
-      command: npx([
-        "rn-driver-xctest-scaffold",
+      command: cmd("node_modules/.bin/rn-driver-xctest-scaffold", [
         "--ios-dir",
         "ios",
         "--project-name",
@@ -720,7 +738,7 @@ function placeholderIos(ios, metro) {
     initialUrl: ios.launch.initialUrl ?? metro.url
   };
 }
-function placeholderAndroid(android, _metro) {
+function placeholderAndroid(android, metro) {
   return {
     serial: "<android-serial>",
     touchPort: android.companion?.port ?? DEFAULTS.companionPort,
@@ -728,7 +746,8 @@ function placeholderAndroid(android, _metro) {
     hermesTimeoutMs: DEFAULTS.hermesTargetTimeoutMs,
     tokenFile: SECRET_PLACEHOLDER,
     deviceTokenFileName: DEFAULTS.androidTokenFileName,
-    instrumentationTarget: instrumentationTarget(android)
+    instrumentationTarget: instrumentationTarget(android),
+    initialUrl: android.launch.initialUrl ?? metro.url
   };
 }
 
@@ -755,7 +774,7 @@ function buildDryRunPlan(config, platform, opts = {}) {
   return planAndroid({
     android,
     metro,
-    resolved: placeholderAndroid(android),
+    resolved: placeholderAndroid(android, metro),
     playwright: config.playwright,
     timeoutMs: config.timeoutMs,
     specs,
@@ -1295,7 +1314,7 @@ async function resolveIosTarget(ios, metro, opts) {
     initialUrl: ios.launch.initialUrl ?? metro.url
   };
 }
-async function resolveAndroidTarget(android, _metro, opts) {
+async function resolveAndroidTarget(android, metro, opts) {
   const serial = await selectSerial(opts.device);
   await requireBooted(serial);
   const deviceName = (await capture("adb", ["-s", serial, "shell", "getprop", "ro.product.model"])).trim();
@@ -1308,7 +1327,8 @@ async function resolveAndroidTarget(android, _metro, opts) {
       hermesTimeoutMs: DEFAULTS.hermesTargetTimeoutMs,
       tokenFile,
       deviceTokenFileName: DEFAULTS.androidTokenFileName,
-      instrumentationTarget: instrumentationTarget(android)
+      instrumentationTarget: instrumentationTarget(android),
+      initialUrl: android.launch.initialUrl ?? metro.url
     },
     deviceName
   };
@@ -1413,6 +1433,7 @@ var IOS_KEYS = /* @__PURE__ */ new Set([
 var ANDROID_KEYS = /* @__PURE__ */ new Set([
   "packageName",
   "activity",
+  "scheme",
   "gradleTasks",
   "appApkPath",
   "testApkPath",
@@ -1514,6 +1535,8 @@ function validateAndroid(android, errors) {
   reportUnknownKeys("config.android", android, ANDROID_KEYS, errors);
   requireAndroidPackage("config.android.packageName", android.packageName, errors);
   requireAndroidActivity("config.android.activity", android.activity, errors);
+  if (android.scheme !== void 0)
+    requireAppScheme("config.android.scheme", android.scheme, errors);
   optionalString("config.android.appApkPath", android.appApkPath, errors);
   optionalString("config.android.testApkPath", android.testApkPath, errors);
   if (android.instrumentationTarget !== void 0)
@@ -1526,7 +1549,10 @@ function validateAndroid(android, errors) {
     errors.push("config.android.gradleTasks: expected an array of strings");
   }
   validateCompanion("config.android.companion", android.companion, errors);
-  validateLaunch("config.android.launch", android.launch, errors);
+  const launch = validateLaunch("config.android.launch", android.launch, errors);
+  if (launch?.kind === "expo-dev-client" && android.scheme === void 0) {
+    errors.push('config.android.scheme: required when android.launch.kind is "expo-dev-client"');
+  }
 }
 function validateCompanion(path4, companion, errors) {
   if (companion === void 0) return;
@@ -1572,6 +1598,7 @@ function requireString(path4, value, errors) {
 }
 var ANDROID_PACKAGE_RE = /^[A-Za-z][A-Za-z0-9_]*(\.[A-Za-z][A-Za-z0-9_]*)+$/;
 var ANDROID_ACTIVITY_RE = /^\.?[A-Za-z][A-Za-z0-9_]*(\.[A-Za-z][A-Za-z0-9_]*)*$/;
+var APP_SCHEME_RE = /^[a-z][a-z0-9+.-]*$/;
 function requireAndroidPackage(path4, value, errors) {
   if (typeof value !== "string" || value.trim() === "") {
     errors.push(`${path4}: required non-empty string`);
@@ -1588,6 +1615,17 @@ function requireAndroidActivity(path4, value, errors) {
   if (!ANDROID_ACTIVITY_RE.test(value))
     errors.push(`${path4}: expected an activity name (e.g. .MainActivity)`);
 }
+function requireAppScheme(path4, value, errors) {
+  if (typeof value !== "string" || value.trim() === "") {
+    errors.push(`${path4}: required non-empty string`);
+    return;
+  }
+  if (!APP_SCHEME_RE.test(value)) {
+    errors.push(
+      `${path4}: expected a valid URL scheme (lowercase letter, then lowercase letters, digits, +, ., or -)`
+    );
+  }
+}
 var ANDROID_INSTRUMENTATION_RE = /^[A-Za-z][A-Za-z0-9_]*(\.[A-Za-z][A-Za-z0-9_]*)*\/[A-Za-z][A-Za-z0-9_]*(\.[A-Za-z][A-Za-z0-9_]*)*$/;
 function requireInstrumentationTarget(path4, value, errors) {
   if (typeof value !== "string" || value.trim() === "") {