@unrulysystems/rn-playwright-driver-runner 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,281 @@
+/**
+ * Public configuration surface for the runner.
+ *
+ * A project provides these facts once in `rn-driver.config.ts`; the runner
+ * translates them into a deterministic native-lifecycle plan per platform. The
+ * shape intentionally separates the developer's *app-specific* facts (bundle
+ * id, schemes, Gradle tasks, launch kind) from the *generic* lifecycle the
+ * runner owns (simulator selection, Metro ownership, companion startup, token
+ * passing, Hermes target wait, cleanup).
+ */
+type Platform = 'ios' | 'android';
+/**
+ * How the app process is brought up relative to the touch companion.
+ * - `launch`/`activate`: the iOS companion launches/foregrounds the app.
+ * - `attach`: the companion only injects; the host owns the launch. Required for
+ *   `expo-dev-client`, where the host must point the dev launcher straight at
+ *   Metro (see {@link LaunchKind}).
+ */
+type LaunchMode = 'launch' | 'activate' | 'attach';
+/**
+ * The flavor of RN app being launched.
+ * - `plain`: a standard Expo/RN app that connects to Metro on cold launch.
+ * - `expo-dev-client`: a development build whose launcher must be handed the
+ *   Metro URL at native launch (iOS: `simctl launch --initialUrl`), otherwise it
+ *   lands on the dev-launcher screen and never registers a Hermes target.
+ */
+type LaunchKind = 'plain' | 'expo-dev-client';
+interface MetroConfig {
+    /** Full Metro URL. When set, host/port are derived from it. */
+    url?: string;
+    /** Command used to start Metro when it is not already running. */
+    command?: string;
+    /** Host to bind/probe. Defaults to `127.0.0.1`. */
+    host?: string;
+    /**
+     * Metro port (default 8081). When the runner owns Metro it verifies this port
+     * is free and fails fast if occupied — it does NOT auto-probe a different port,
+     * because `command` pins the port the packager binds (REQ-METRO-003).
+     */
+    port?: number;
+    /** Reuse an already-running packager at the resolved URL instead of starting one. */
+    reuseExisting?: boolean;
+    /** Bound for Metro `packager-status:running`. Defaults to 90_000ms. */
+    readyTimeoutMs?: number;
+}
+interface LaunchConfig {
+    mode: LaunchMode;
+    kind: LaunchKind;
+    /**
+     * Metro URL handed to the dev launcher for `expo-dev-client`. Defaults to the
+     * resolved Metro URL. Ignored for `plain`.
+     */
+    initialUrl?: string;
+}
+interface CompanionConfig {
+    /** Local port the touch companion listens on. Defaults to 9999. */
+    port?: number;
+    /**
+     * Bound for the companion to accept its first authenticated request. Defaults
+     * to 300_000ms on iOS to cover a cold `xcodebuild test` build (FU-2).
+     */
+    readyTimeoutMs?: number;
+}
+interface IosConfig {
+    /** App bundle identifier, e.g. `com.company.app`. */
+    bundleId: string;
+    /** Path to the `.xcworkspace`, e.g. `ios/App.xcworkspace`. */
+    workspace: string;
+    /** Scheme that builds the app, e.g. `App`. */
+    appScheme: string;
+    /** UI-test scheme. Defaults to `${appScheme}UITests`. */
+    uitestScheme?: string;
+    /**
+     * Explicit `xcodebuild` destination
+     * (`platform=iOS Simulator,id=<udid>`). When omitted the runner selects a
+     * booted iPhone, else the newest available iPhone runtime.
+     */
+    destination?: string;
+    launch: LaunchConfig;
+    companion?: CompanionConfig;
+    /**
+     * App-specific pre-launch seeds written via `simctl spawn defaults write`
+     * (e.g. dev-menu onboarding flags). Keeps app-specific facts out of the
+     * generic lifecycle.
+     */
+    defaults?: Record<string, string | number | boolean>;
+}
+interface AndroidConfig {
+    /** Android application id, e.g. `com.company.app`. */
+    packageName: string;
+    /** Launch activity, e.g. `.MainActivity`. */
+    activity: string;
+    /** Gradle tasks that build the app + androidTest APKs. */
+    gradleTasks?: string[];
+    /** Built app APK path. Defaults to the standard debug output path. */
+    appApkPath?: string;
+    /** Built androidTest APK path. Defaults to the standard debug output path. */
+    testApkPath?: string;
+    /**
+     * `am instrument` target, e.g.
+     * `com.company.app.test/com.rndriver.touchcompanion.RNDriverTouchCompanion`.
+     * Defaults to `${packageName}.test/com.rndriver.touchcompanion.RNDriverTouchCompanion`.
+     */
+    instrumentationTarget?: string;
+    launch: LaunchConfig;
+    companion?: CompanionConfig;
+}
+interface PlaywrightConfig {
+    /** Playwright config path passed as `--config`. */
+    config?: string;
+    /** Default spec paths/globs when none are passed on the CLI. */
+    specs?: string[];
+}
+interface RnDriverConfig {
+    metro?: MetroConfig;
+    ios?: IosConfig;
+    android?: AndroidConfig;
+    playwright?: PlaywrightConfig;
+    /** Driver request timeout (`RN_TIMEOUT`). */
+    timeoutMs?: number;
+}
+/**
+ * Identity helper that provides editor/type checking for `rn-driver.config.ts`.
+ * Performs no I/O.
+ */
+declare function defineRnDriverConfig(config: RnDriverConfig): RnDriverConfig;
+
+/**
+ * A single OS command. `args` and `env` MUST NEVER contain a secret value — a
+ * token reaches a process only via a file path (`stdinFromFile`, or a path in
+ * `args`/`env`), never as a literal.
+ */
+interface CommandSpec {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly env?: Readonly<Record<string, string>>;
+    readonly cwd?: string;
+    /** Pipe this file's bytes to stdin (keeps secret values out of argv). */
+    readonly stdinFromFile?: string;
+    /** Pipe this literal (non-secret) content to stdin (e.g. generated config XML). */
+    readonly stdinContents?: string;
+}
+/**
+ * A poll-until-ready check with a bounded timeout. The executor polls; a probe
+ * that does not pass within `timeoutMs` is a stage failure.
+ */
+type ReadinessProbe = {
+    readonly kind: 'metro-status';
+    readonly metroUrl: string;
+    readonly timeoutMs: number;
+} | {
+    readonly kind: 'hermes-target';
+    readonly platform: Platform;
+    readonly metroUrl: string;
+    readonly appId: string;
+    readonly deviceNameMatch?: string;
+    readonly timeoutMs: number;
+} | {
+    readonly kind: 'xctest-hello';
+    readonly port: number;
+    readonly tokenFile: string;
+    readonly timeoutMs: number;
+} | {
+    readonly kind: 'instrumentation-hello';
+    readonly port: number;
+    readonly tokenFile: string;
+    readonly timeoutMs: number;
+};
+type StepAction = {
+    readonly type: 'command';
+    readonly command: CommandSpec;
+    /** Long-lived process (Metro, companion). Tracked by `processKey` for cleanup. */
+    readonly background?: boolean;
+    readonly processKey?: string;
+    /** Best-effort command: a non-zero exit does not fail the run (bash `|| true`). */
+    readonly allowFailure?: boolean;
+} | {
+    readonly type: 'write-file';
+    readonly path: string;
+    readonly contents: string;
+    readonly mode?: number;
+} | {
+    readonly type: 'free-port';
+    readonly port: number;
+} | {
+    readonly type: 'probe';
+    readonly probe: ReadinessProbe;
+    /**
+     * Bounded retry: if the probe times out, re-run `command` and probe again,
+     * up to `max` extra attempts (REQ-AND-005 — re-issue `am start` when the
+     * app loses a transient Hermes-registration race instead of failing).
+     */
+    readonly retry?: {
+        readonly command: CommandSpec;
+        readonly max: number;
+    };
+};
+/** The lifecycle stage a step belongs to. A failure is attributed to its stage. */
+type Stage = 'config' | 'metro' | 'device' | 'build' | 'companion' | 'app-launch' | 'hermes-target' | 'playwright' | 'cleanup';
+interface Step {
+    readonly id: string;
+    readonly stage: Stage;
+    readonly description: string;
+    readonly action: StepAction;
+    /** Skipped when `--skip-build` reuses an already-built native project. */
+    readonly skippable?: boolean;
+}
+/**
+ * Teardown is emitted declaratively by the planner (so `--dry-run` shows it) and
+ * run defensively by the executor (so it is idempotent — REQ-CLEAN-001). Each
+ * action is a no-op when its precondition does not hold.
+ */
+type CleanupAction = {
+    readonly type: 'kill-process';
+    readonly processKey: string;
+    readonly description: string;
+} | {
+    readonly type: 'free-port';
+    readonly port: number;
+    readonly description: string;
+} | {
+    readonly type: 'remove-file';
+    readonly path: string;
+    readonly description: string;
+} | {
+    readonly type: 'command';
+    readonly command: CommandSpec;
+    readonly description: string;
+};
+interface Plan {
+    readonly platform: Platform;
+    readonly steps: readonly Step[];
+    readonly cleanup: readonly CleanupAction[];
+    /** The driver env contract handed to Playwright — token files only, no values. */
+    readonly driverEnv: Readonly<Record<string, string>>;
+    /** The Playwright invocation run after the world is up. */
+    readonly playwright: CommandSpec;
+}
+
+interface MetroOverrides {
+    readonly url?: string;
+    readonly host?: string;
+    readonly port?: number;
+}
+interface BuildPlanOptions {
+    readonly metroOverrides?: MetroOverrides;
+    /** Positional spec paths; override the config spec list when non-empty. */
+    readonly specs?: readonly string[];
+    /** Args after `--`; always appended to the Playwright invocation. */
+    readonly passthrough?: readonly string[];
+}
+/**
+ * Build the plan for a platform using placeholder (no-I/O) resolution. This is
+ * the `--dry-run` path and the unit-test entry point: identical config yields an
+ * identical plan with zero side effects.
+ */
+declare function buildDryRunPlan(config: RnDriverConfig, platform: Platform, opts?: BuildPlanOptions): Plan;
+
+/**
+ * Render a {@link Plan} as auditable text for `--dry-run`. Token material appears
+ * only as the placeholder file path (dry-run resolution fills `tokenFile` with
+ * `<token-file>`), so this output never leaks a secret value.
+ */
+declare function renderPlan(plan: Plan): string;
+
+interface ValidationResult {
+    readonly ok: boolean;
+    readonly errors: readonly string[];
+}
+/**
+ * Validate a loaded config for the selected platforms. Runs before any side
+ * effect; failures name the offending field and the expected shape (REQ-CFG-003).
+ * Unknown keys are reported as typo protection (REQ-CFG-004).
+ */
+declare function validateConfig(config: unknown, platforms: readonly Platform[]): ValidationResult;
+declare class ConfigValidationError extends Error {
+    readonly errors: readonly string[];
+    constructor(errors: readonly string[]);
+}
+
+export { type AndroidConfig, type BuildPlanOptions, type CleanupAction, type CommandSpec, type CompanionConfig, ConfigValidationError, type IosConfig, type LaunchConfig, type LaunchKind, type LaunchMode, type MetroConfig, type MetroOverrides, type Plan, type Platform, type PlaywrightConfig, type ReadinessProbe, type RnDriverConfig, type Stage, type Step, type StepAction, type ValidationResult, buildDryRunPlan, defineRnDriverConfig, renderPlan, validateConfig };

package/dist/index.d.ts

@@ -0,0 +1,281 @@
+/**
+ * Public configuration surface for the runner.
+ *
+ * A project provides these facts once in `rn-driver.config.ts`; the runner
+ * translates them into a deterministic native-lifecycle plan per platform. The
+ * shape intentionally separates the developer's *app-specific* facts (bundle
+ * id, schemes, Gradle tasks, launch kind) from the *generic* lifecycle the
+ * runner owns (simulator selection, Metro ownership, companion startup, token
+ * passing, Hermes target wait, cleanup).
+ */
+type Platform = 'ios' | 'android';
+/**
+ * How the app process is brought up relative to the touch companion.
+ * - `launch`/`activate`: the iOS companion launches/foregrounds the app.
+ * - `attach`: the companion only injects; the host owns the launch. Required for
+ *   `expo-dev-client`, where the host must point the dev launcher straight at
+ *   Metro (see {@link LaunchKind}).
+ */
+type LaunchMode = 'launch' | 'activate' | 'attach';
+/**
+ * The flavor of RN app being launched.
+ * - `plain`: a standard Expo/RN app that connects to Metro on cold launch.
+ * - `expo-dev-client`: a development build whose launcher must be handed the
+ *   Metro URL at native launch (iOS: `simctl launch --initialUrl`), otherwise it
+ *   lands on the dev-launcher screen and never registers a Hermes target.
+ */
+type LaunchKind = 'plain' | 'expo-dev-client';
+interface MetroConfig {
+    /** Full Metro URL. When set, host/port are derived from it. */
+    url?: string;
+    /** Command used to start Metro when it is not already running. */
+    command?: string;
+    /** Host to bind/probe. Defaults to `127.0.0.1`. */
+    host?: string;
+    /**
+     * Metro port (default 8081). When the runner owns Metro it verifies this port
+     * is free and fails fast if occupied — it does NOT auto-probe a different port,
+     * because `command` pins the port the packager binds (REQ-METRO-003).
+     */
+    port?: number;
+    /** Reuse an already-running packager at the resolved URL instead of starting one. */
+    reuseExisting?: boolean;
+    /** Bound for Metro `packager-status:running`. Defaults to 90_000ms. */
+    readyTimeoutMs?: number;
+}
+interface LaunchConfig {
+    mode: LaunchMode;
+    kind: LaunchKind;
+    /**
+     * Metro URL handed to the dev launcher for `expo-dev-client`. Defaults to the
+     * resolved Metro URL. Ignored for `plain`.
+     */
+    initialUrl?: string;
+}
+interface CompanionConfig {
+    /** Local port the touch companion listens on. Defaults to 9999. */
+    port?: number;
+    /**
+     * Bound for the companion to accept its first authenticated request. Defaults
+     * to 300_000ms on iOS to cover a cold `xcodebuild test` build (FU-2).
+     */
+    readyTimeoutMs?: number;
+}
+interface IosConfig {
+    /** App bundle identifier, e.g. `com.company.app`. */
+    bundleId: string;
+    /** Path to the `.xcworkspace`, e.g. `ios/App.xcworkspace`. */
+    workspace: string;
+    /** Scheme that builds the app, e.g. `App`. */
+    appScheme: string;
+    /** UI-test scheme. Defaults to `${appScheme}UITests`. */
+    uitestScheme?: string;
+    /**
+     * Explicit `xcodebuild` destination
+     * (`platform=iOS Simulator,id=<udid>`). When omitted the runner selects a
+     * booted iPhone, else the newest available iPhone runtime.
+     */
+    destination?: string;
+    launch: LaunchConfig;
+    companion?: CompanionConfig;
+    /**
+     * App-specific pre-launch seeds written via `simctl spawn defaults write`
+     * (e.g. dev-menu onboarding flags). Keeps app-specific facts out of the
+     * generic lifecycle.
+     */
+    defaults?: Record<string, string | number | boolean>;
+}
+interface AndroidConfig {
+    /** Android application id, e.g. `com.company.app`. */
+    packageName: string;
+    /** Launch activity, e.g. `.MainActivity`. */
+    activity: string;
+    /** Gradle tasks that build the app + androidTest APKs. */
+    gradleTasks?: string[];
+    /** Built app APK path. Defaults to the standard debug output path. */
+    appApkPath?: string;
+    /** Built androidTest APK path. Defaults to the standard debug output path. */
+    testApkPath?: string;
+    /**
+     * `am instrument` target, e.g.
+     * `com.company.app.test/com.rndriver.touchcompanion.RNDriverTouchCompanion`.
+     * Defaults to `${packageName}.test/com.rndriver.touchcompanion.RNDriverTouchCompanion`.
+     */
+    instrumentationTarget?: string;
+    launch: LaunchConfig;
+    companion?: CompanionConfig;
+}
+interface PlaywrightConfig {
+    /** Playwright config path passed as `--config`. */
+    config?: string;
+    /** Default spec paths/globs when none are passed on the CLI. */
+    specs?: string[];
+}
+interface RnDriverConfig {
+    metro?: MetroConfig;
+    ios?: IosConfig;
+    android?: AndroidConfig;
+    playwright?: PlaywrightConfig;
+    /** Driver request timeout (`RN_TIMEOUT`). */
+    timeoutMs?: number;
+}
+/**
+ * Identity helper that provides editor/type checking for `rn-driver.config.ts`.
+ * Performs no I/O.
+ */
+declare function defineRnDriverConfig(config: RnDriverConfig): RnDriverConfig;
+
+/**
+ * A single OS command. `args` and `env` MUST NEVER contain a secret value — a
+ * token reaches a process only via a file path (`stdinFromFile`, or a path in
+ * `args`/`env`), never as a literal.
+ */
+interface CommandSpec {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly env?: Readonly<Record<string, string>>;
+    readonly cwd?: string;
+    /** Pipe this file's bytes to stdin (keeps secret values out of argv). */
+    readonly stdinFromFile?: string;
+    /** Pipe this literal (non-secret) content to stdin (e.g. generated config XML). */
+    readonly stdinContents?: string;
+}
+/**
+ * A poll-until-ready check with a bounded timeout. The executor polls; a probe
+ * that does not pass within `timeoutMs` is a stage failure.
+ */
+type ReadinessProbe = {
+    readonly kind: 'metro-status';
+    readonly metroUrl: string;
+    readonly timeoutMs: number;
+} | {
+    readonly kind: 'hermes-target';
+    readonly platform: Platform;
+    readonly metroUrl: string;
+    readonly appId: string;
+    readonly deviceNameMatch?: string;
+    readonly timeoutMs: number;
+} | {
+    readonly kind: 'xctest-hello';
+    readonly port: number;
+    readonly tokenFile: string;
+    readonly timeoutMs: number;
+} | {
+    readonly kind: 'instrumentation-hello';
+    readonly port: number;
+    readonly tokenFile: string;
+    readonly timeoutMs: number;
+};
+type StepAction = {
+    readonly type: 'command';
+    readonly command: CommandSpec;
+    /** Long-lived process (Metro, companion). Tracked by `processKey` for cleanup. */
+    readonly background?: boolean;
+    readonly processKey?: string;
+    /** Best-effort command: a non-zero exit does not fail the run (bash `|| true`). */
+    readonly allowFailure?: boolean;
+} | {
+    readonly type: 'write-file';
+    readonly path: string;
+    readonly contents: string;
+    readonly mode?: number;
+} | {
+    readonly type: 'free-port';
+    readonly port: number;
+} | {
+    readonly type: 'probe';
+    readonly probe: ReadinessProbe;
+    /**
+     * Bounded retry: if the probe times out, re-run `command` and probe again,
+     * up to `max` extra attempts (REQ-AND-005 — re-issue `am start` when the
+     * app loses a transient Hermes-registration race instead of failing).
+     */
+    readonly retry?: {
+        readonly command: CommandSpec;
+        readonly max: number;
+    };
+};
+/** The lifecycle stage a step belongs to. A failure is attributed to its stage. */
+type Stage = 'config' | 'metro' | 'device' | 'build' | 'companion' | 'app-launch' | 'hermes-target' | 'playwright' | 'cleanup';
+interface Step {
+    readonly id: string;
+    readonly stage: Stage;
+    readonly description: string;
+    readonly action: StepAction;
+    /** Skipped when `--skip-build` reuses an already-built native project. */
+    readonly skippable?: boolean;
+}
+/**
+ * Teardown is emitted declaratively by the planner (so `--dry-run` shows it) and
+ * run defensively by the executor (so it is idempotent — REQ-CLEAN-001). Each
+ * action is a no-op when its precondition does not hold.
+ */
+type CleanupAction = {
+    readonly type: 'kill-process';
+    readonly processKey: string;
+    readonly description: string;
+} | {
+    readonly type: 'free-port';
+    readonly port: number;
+    readonly description: string;
+} | {
+    readonly type: 'remove-file';
+    readonly path: string;
+    readonly description: string;
+} | {
+    readonly type: 'command';
+    readonly command: CommandSpec;
+    readonly description: string;
+};
+interface Plan {
+    readonly platform: Platform;
+    readonly steps: readonly Step[];
+    readonly cleanup: readonly CleanupAction[];
+    /** The driver env contract handed to Playwright — token files only, no values. */
+    readonly driverEnv: Readonly<Record<string, string>>;
+    /** The Playwright invocation run after the world is up. */
+    readonly playwright: CommandSpec;
+}
+
+interface MetroOverrides {
+    readonly url?: string;
+    readonly host?: string;
+    readonly port?: number;
+}
+interface BuildPlanOptions {
+    readonly metroOverrides?: MetroOverrides;
+    /** Positional spec paths; override the config spec list when non-empty. */
+    readonly specs?: readonly string[];
+    /** Args after `--`; always appended to the Playwright invocation. */
+    readonly passthrough?: readonly string[];
+}
+/**
+ * Build the plan for a platform using placeholder (no-I/O) resolution. This is
+ * the `--dry-run` path and the unit-test entry point: identical config yields an
+ * identical plan with zero side effects.
+ */
+declare function buildDryRunPlan(config: RnDriverConfig, platform: Platform, opts?: BuildPlanOptions): Plan;
+
+/**
+ * Render a {@link Plan} as auditable text for `--dry-run`. Token material appears
+ * only as the placeholder file path (dry-run resolution fills `tokenFile` with
+ * `<token-file>`), so this output never leaks a secret value.
+ */
+declare function renderPlan(plan: Plan): string;
+
+interface ValidationResult {
+    readonly ok: boolean;
+    readonly errors: readonly string[];
+}
+/**
+ * Validate a loaded config for the selected platforms. Runs before any side
+ * effect; failures name the offending field and the expected shape (REQ-CFG-003).
+ * Unknown keys are reported as typo protection (REQ-CFG-004).
+ */
+declare function validateConfig(config: unknown, platforms: readonly Platform[]): ValidationResult;
+declare class ConfigValidationError extends Error {
+    readonly errors: readonly string[];
+    constructor(errors: readonly string[]);
+}
+
+export { type AndroidConfig, type BuildPlanOptions, type CleanupAction, type CommandSpec, type CompanionConfig, ConfigValidationError, type IosConfig, type LaunchConfig, type LaunchKind, type LaunchMode, type MetroConfig, type MetroOverrides, type Plan, type Platform, type PlaywrightConfig, type ReadinessProbe, type RnDriverConfig, type Stage, type Step, type StepAction, type ValidationResult, buildDryRunPlan, defineRnDriverConfig, renderPlan, validateConfig };