rnxsim 0.1.490 → 0.1.492

package/cli/app-state-reset.ts

@@ -1,10 +1,6 @@
-// resets the GUEST APP to a fresh launch through the engine's own soft-reload
-// bridge (`SootSim.bridges.hotRemount.reloadExternalApp`). that re-runs the
-// guest app entry while keeping the engine bundle + worker alive — no heavy
-// metro re-fetch of every lazy chunk, and the sim id does NOT rotate. when
-// `resetStorage` is set it clears the guest app's tenant-scoped storage via the
-// engine's own clear path (scoped localStorage + open-and-clear of the known
-// tenant IndexedDBs / secure-store) — the maestro `clearState` contract.
+// resets the guest app through the engine lifecycle bridge. a storage reset
+// replaces the tenant worker before clearing its scoped stores, which is the
+// maestro `clearState` contract. a plain reload keeps the faster reload path.
 //
 // this replaces a host-realm `localStorage.clear()` + `indexedDB.deleteDatabase`
 // loop that was wrong twice: (1) `localStorage.clear()` wiped engine settings
@@ -17,8 +13,14 @@
 export function resetGuestAppStateEval(resetStorage: boolean): string {
   return `(async () => {
     const bridge = globalThis.SootSim && globalThis.SootSim.bridges && globalThis.SootSim.bridges.hotRemount
-    if (!bridge || typeof bridge.reloadExternalApp !== 'function') return false
-    await bridge.reloadExternalApp({ resetStorage: ${resetStorage ? 'true' : 'false'} })
+    if (!bridge) return false
+    if (${resetStorage ? 'true' : 'false'}) {
+      if (typeof bridge.resetExternalApp !== 'function') return false
+      const result = await bridge.resetExternalApp({ strategy: 'full' })
+      return result.failures.length === 0 && result.relaunched
+    }
+    if (typeof bridge.reloadExternalApp !== 'function') return false
+    await bridge.reloadExternalApp()
     return true
   })()`
 }

package/cli/cloud-client.ts

@@ -59,6 +59,7 @@ export const MAX_RNX_CLOUD_BUNDLE_BYTES = RNX_CLOUD_MAX_ARTIFACT_BYTES
 
 // every message this module writes names the command through this constant.
 const REMOTE_COMMAND = 'rnx ios --remote'
+const PREVIEW_COMMAND = 'rnx preview'
 
 // a Metro asset dest is a shallow tree of images. a walk that runs past this
 // is pointed at something else entirely, and its extra entries cannot resolve
@@ -656,6 +657,36 @@ export async function produceCloudArtifact(
    * the default; a box that accepts a larger artifact passes its own.
    */
   maxBytes: number = MAX_RNX_CLOUD_BUNDLE_BYTES,
+): Promise<CloudArtifactProduction> {
+  return produceArtifact(
+    bundlePath,
+    assetsPath,
+    maxBytes,
+    REMOTE_COMMAND,
+    'allow-placeholders',
+  )
+}
+
+/** prepares a standalone preview whose bytes must represent every Metro asset. */
+export async function producePreviewArtifact(
+  bundlePath: string,
+  assetsPath?: string,
+): Promise<CloudArtifactProduction> {
+  return produceArtifact(
+    bundlePath,
+    assetsPath,
+    Number.POSITIVE_INFINITY,
+    PREVIEW_COMMAND,
+    'require-assets',
+  )
+}
+
+async function produceArtifact(
+  bundlePath: string,
+  assetsPath: string | undefined,
+  maxBytes: number,
+  command: string,
+  assetPolicy: 'allow-placeholders' | 'require-assets',
 ): Promise<CloudArtifactProduction> {
   const source = await loadBundleSource(bundlePath)
   const descriptors = extractAssetDescriptors(source)
@@ -680,7 +711,7 @@ export async function produceCloudArtifact(
     const placement = placements.get(label)
     if (placement?.mismatched && dest) {
       throw new Error(
-        `${REMOTE_COMMAND} found ${variant.descriptor.name}.${variant.descriptor.type} in ${dest.directory}, but its bytes are not the ones this bundle was built against. Rebuild with \`react-native bundle --assets-dest ${dest.directory}\` so the bundle and the images match.`,
+        `${command} found ${variant.descriptor.name}.${variant.descriptor.type} in ${dest.directory}, but its bytes are not the ones this bundle was built against. Rebuild with \`react-native bundle --assets-dest ${dest.directory}\` so the bundle and the images match.`,
       )
     }
     const relative = placement?.files.get(variant.scale)
@@ -690,7 +721,7 @@ export async function produceCloudArtifact(
     if (placement && placement.files.size > 0) return null
     if (placement && placement.ambiguous.length > 0 && dest) {
       throw new Error(
-        `${REMOTE_COMMAND} found more than one image for ${label} in ${dest.directory} and none of them is the one Metro hashed: ${placement.ambiguous.sort().join(', ')}. Pass --assets <dir> to name the directory \`react-native bundle --assets-dest\` wrote.`,
+        `${command} found more than one image for ${label} in ${dest.directory} and none of them is the one Metro hashed: ${placement.ambiguous.sort().join(', ')}. Pass --assets <dir> to name the directory \`react-native bundle --assets-dest\` wrote.`,
       )
     }
     // a stand-in is only honest when the asset is genuinely absent from a
@@ -700,12 +731,17 @@ export async function produceCloudArtifact(
     // chose.
     if (assetsPath) {
       throw new Error(
-        `${REMOTE_COMMAND} could not find ${label} under --assets ${dest?.directory ?? resolve(assetsPath)}. Point --assets at the directory \`react-native bundle --assets-dest\` wrote, or drop the flag to let ${REMOTE_COMMAND} find it.`,
+        `${command} could not find ${label} under --assets ${dest?.directory ?? resolve(assetsPath)}. Point --assets at the directory \`react-native bundle --assets-dest\` wrote, or drop the flag to let ${command} find it.`,
       )
     }
     if (search.truncated) {
       throw new Error(
-        `${REMOTE_COMMAND} stopped listing ${search.searched.join(', ')} after ${MAX_ASSET_DEST_FILES} files and never reached ${label}, so it cannot tell a missing asset from an unread one. Pass --assets <dir> to name the directory \`react-native bundle --assets-dest\` wrote.`,
+        `${command} stopped listing ${search.searched.join(', ')} after ${MAX_ASSET_DEST_FILES} files and never reached ${label}, so it cannot tell a missing asset from an unread one. Pass --assets <dir> to name the directory \`react-native bundle --assets-dest\` wrote.`,
+      )
+    }
+    if (assetPolicy === 'require-assets') {
+      throw new Error(
+        `${command} could not find ${label}. Pass --assets <dir> pointing at the directory \`react-native bundle --assets-dest <dir>\` wrote, or build with \`--assets-dest\`.`,
       )
     }
     // no scale of this asset exists anywhere the search looked. an image can
@@ -726,7 +762,7 @@ export async function produceCloudArtifact(
       metroIosAssetDestRelatives(variant.descriptor.httpServerLocation, filename)[0] ??
       filename
     throw new Error(
-      `${REMOTE_COMMAND} could not read ${join(dest?.directory ?? '.', classic)} for ${variant.descriptor.name}.${variant.descriptor.type} at scale ${variant.scale}, and has no stand-in for a .${variant.descriptor.type} asset. Build the bundle with --assets-dest, or pass --assets <dir>.`,
+      `${command} could not read ${join(dest?.directory ?? '.', classic)} for ${variant.descriptor.name}.${variant.descriptor.type} at scale ${variant.scale}, and has no stand-in for a .${variant.descriptor.type} asset. Build the bundle with --assets-dest, or pass --assets <dir>.`,
     )
   })
   const artifact = await buildRnxCloudArtifact(embedded.code, {
@@ -742,14 +778,14 @@ export async function produceCloudArtifact(
   const warnings: string[] = []
   if (substituted.length > 0) {
     warnings.push(
-      `${REMOTE_COMMAND} embedded a placeholder image for ${substituted.length} asset(s) no scale of which is in ${search.searched.join(', ') || 'any asset dest directory'}: ${substituted.join(', ')}. Build the bundle with --assets-dest, or pass --assets <dir>, to ship the real images.`,
+      `${command} embedded a placeholder image for ${substituted.length} asset(s) no scale of which is in ${search.searched.join(', ') || 'any asset dest directory'}: ${substituted.join(', ')}. Build the bundle with --assets-dest, or pass --assets <dir>, to ship the real images.`,
     )
   }
   // an artifact this close to the ceiling is one asset away from being refused,
   // and the producer knows which assets it would be.
   if (bytes.length >= Math.floor(maxBytes * 0.8)) {
     warnings.push(
-      `${REMOTE_COMMAND} artifact is ${bytes.length} bytes, ${Math.round((bytes.length / maxBytes) * 100)}% of the ${maxBytes}-byte limit.${largestEmbeddedAssets(assets.sizes, 5)}`,
+      `${command} artifact is ${bytes.length} bytes, ${Math.round((bytes.length / maxBytes) * 100)}% of the ${maxBytes}-byte limit.${largestEmbeddedAssets(assets.sizes, 5)}`,
     )
   }
   return {

package/cli/command-registry.ts

@@ -18,6 +18,7 @@ export interface RnxCommandAvailability {
 }
 
 const NODE_COMMAND_NAMES = [
+  'test',
   'detox',
   'maestro',
   'record',
@@ -39,6 +40,8 @@ const NODE_COMMAND_NAMES = [
   'open',
   'ios',
   'android',
+  'remote',
+  'preview',
   'box',
   'list',
   'use',

package/cli/commands/detox.ts

@@ -11,7 +11,14 @@
 // moduleNameMapper for `^detox$`.
 
 import { spawn } from 'child_process'
-import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync } from 'fs'
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  statSync,
+  writeFileSync,
+  unlinkSync,
+} from 'fs'
 import { createRequire } from 'module'
 import { tmpdir } from 'os'
 import { dirname, resolve, join, relative } from 'path'
@@ -107,12 +114,20 @@ export async function runDetox(args: string[], opts: RunDetoxOpts = {}): Promise
     return []
   })
 
-  // test dir discovery. external test suites set RNX_TEST_DIR; otherwise
-  // we auto-detect the conventional locations.
+  // test dir discovery. an explicit suite owns its root; otherwise external
+  // suites set RNX_TEST_DIR and conventional locations remain the fallback.
   const detoxDirs = ['e2e', 'test/e2e', 'detox']
-  let testDir: string | null = process.env.RNX_TEST_DIR
-    ? resolve(process.cwd(), process.env.RNX_TEST_DIR)
-    : null
+  const explicitTarget =
+    positional[0] && existsSync(resolve(process.cwd(), positional[0]))
+      ? resolve(process.cwd(), positional[0])
+      : null
+  let testDir: string | null = explicitTarget
+    ? statSync(explicitTarget).isDirectory()
+      ? explicitTarget
+      : dirname(explicitTarget)
+    : process.env.RNX_TEST_DIR
+      ? resolve(process.cwd(), process.env.RNX_TEST_DIR)
+      : null
   if (!testDir) {
     for (const dir of detoxDirs) {
       const full = resolve(process.cwd(), dir)
@@ -137,24 +152,39 @@ export async function runDetox(args: string[], opts: RunDetoxOpts = {}): Promise
     await ensureShellRunning(port)
   }
 
-  // build the jest command. prefer the user's config if they passed --config
-  // or if a rnx-detox.config.cjs exists in cwd. otherwise point at our
-  // preset directly via --preset-free inline config.
+  // build the jest command. customer config remains authoritative for setup,
+  // transforms, roots, and timeouts; the generated wrapper adds only RNX's
+  // Detox module mapping and cleanup hook.
   const jestArgs: string[] = ['jest']
   const localConfig =
     configFlag ||
     firstExisting(['rnx-detox.config.cjs', 'jest.config.cjs', 'jest.config.js'])
 
   let tempConfig: string | null = null
+  const presetPath = resolve(resolveDetoxDir(), 'jest-preset.cjs')
   if (localConfig) {
-    jestArgs.push('--config', resolve(process.cwd(), localConfig))
+    const localConfigPath = resolve(process.cwd(), localConfig)
+    // Keep the wrapper beside the customer config so a relative rootDir keeps
+    // resolving from the same directory Jest would have used directly.
+    tempConfig = join(dirname(localConfigPath), `rnx-detox-${process.pid}.config.cjs`)
+    writeFileSync(
+      tempConfig,
+      `const rnx = require(${JSON.stringify(presetPath)})\n` +
+        `const customer = require(${JSON.stringify(localConfigPath)})\n` +
+        `module.exports = {\n` +
+        `  ...rnx,\n` +
+        `  ...customer,\n` +
+        `  moduleNameMapper: { ...rnx.moduleNameMapper, ...customer.moduleNameMapper, '^detox$': rnx.moduleNameMapper['^detox$'] },\n` +
+        `  setupFilesAfterEnv: [...new Set([...(customer.setupFilesAfterEnv || []), ...(rnx.setupFilesAfterEnv || [])])],\n` +
+        `}\n`,
+    )
+    jestArgs.push('--config', tempConfig)
   } else {
     // no local config — write a temp config that pulls in our preset.
     // jest's --preset flag has quirky module resolution that breaks with
     // subpath exports, so we generate a real config file instead.
     // scope roots + testMatch to the discovered test dir so jest doesn't
     // scan the entire repo (which causes haste collisions in monorepos).
-    const presetPath = resolve(resolveDetoxDir(), 'jest-preset.cjs')
     // an external suite may optionally declare its own ignore patterns via e2e/jest-ignore.cjs
     const suiteIgnoreFile = testDir ? join(testDir, 'e2e', 'jest-ignore.cjs') : null
     let suiteIgnorePatterns: string[] = []

package/cli/commands/flow.ts

@@ -61,6 +61,7 @@ const FLOW_BOOLEAN_FLAGS = [
 ]
 
 const FLOW_VALUE_FLAGS = [
+  '--app',
   '--out',
   '--base-url',
   '--device',
@@ -430,7 +431,7 @@ flow extension:
   const targetApp = targetAppResolution.target
 
   const parsedBridgeArgs = parseBridgeCliArgs(args, FLOW_BRIDGE_ARG_OPTIONS)
-  const url = getFlag('--url') || ''
+  const url = getFlag('--app') || getFlag('--url') || ''
 
   // --base-url pins the run to one shell, so a caller can build an engine from
   // a known tree, serve it, and measure that build instead of whatever the

package/cli/commands/maestro.ts

@@ -470,6 +470,22 @@ export async function runMaestro(
     if (exit !== 0 && worstExit === 0) worstExit = exit
 
     const upload = getLastFlowPreviewUploadResult()
+    if (upload?.shareId || upload?.previewUrl) {
+      try {
+        fs.writeFileSync(
+          path.join(cwd, 'preview-result.json'),
+          JSON.stringify({
+            previewId: upload.shareId,
+            previewUrl: upload.previewUrl,
+          }),
+        )
+      } catch {}
+    } else if (args.includes('--preview')) {
+      console.error('  error: required hosted recording upload failed')
+      if (exit === 0) exit = 1
+      if (worstExit === 0) worstExit = 1
+    }
+
     if (shouldRegisterRun({ uploadedShare: Boolean(upload), auth })) {
       const traceSteps = getLastFlowTraceSteps()
       const failedStep = traceSteps.find((step) => step.status === 'failure')
@@ -488,6 +504,20 @@ export async function runMaestro(
       })
       if (run) {
         console.log(`  run: ${run.id}${run.traceUrl ? ` · replay: ${run.traceUrl}` : ''}`)
+        try {
+          fs.writeFileSync(
+            path.join(cwd, 'test-result.json'),
+            JSON.stringify({
+              runId: run.id,
+              previewUrl: run.previewUrl,
+              traceUrl: run.traceUrl,
+            }),
+          )
+        } catch {}
+      } else if (process.env.RNX_REQUIRE_REGISTRATION === 'true') {
+        console.error('  error: required hosted run registration failed')
+        if (exit === 0) exit = 1
+        if (worstExit === 0) worstExit = 1
       }
     }
   }

package/cli/commands/platform.ts

@@ -258,6 +258,21 @@ export async function runPlatformCommand(
   return runOpenCommand(args, { port: opts.port })
 }
 
+/** Runs the existing remote session path without changing the local platform commands. */
+export function runRemotePlatformCommand(
+  platform: RuntimePlatform,
+  args: string[],
+  opts: { port?: number } = {},
+): Promise<number | undefined> {
+  if (platform === 'android') {
+    console.error(
+      `  ${rnxPublicBrand.commandName} remote android is not available: rnxsim/cloud only creates iOS simulators`,
+    )
+    return Promise.resolve(1)
+  }
+  return runPlatformCommand(platform, ['--remote', ...args], opts)
+}
+
 /**
  * `rnx ios --remote` — the app runs in a Box.
  *

package/cli/commands/preview.ts

@@ -0,0 +1,104 @@
+import { createHash } from 'node:crypto'
+import { brotliBundle } from 'sootsim-engine/preview/compress-node'
+import {
+  runPresignedUpload,
+  type InitRequestBody,
+} from 'sootsim-engine/preview/presigned-upload'
+import { authHeaderValue, cloudAccountIdOrExit, resolveCliAuth } from '../auth'
+import { producePreviewArtifact } from '../cloud-client'
+import { openUrl } from '../open-url'
+import { resolveDefaultUploadOrigin, resolvePublicPreviewOrigin } from './upload'
+
+function takeValue(args: string[], flag: string): string | null {
+  const index = args.indexOf(flag)
+  if (index < 0) return null
+  const value = args[index + 1]
+  args.splice(index, 2)
+  if (!value || value.startsWith('-')) throw new Error(`${flag} requires a value`)
+  return value
+}
+
+export async function runPreview(args: string[]): Promise<number> {
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`
+rnx preview — publish a prebuilt React Native bundle as a standalone share
+
+usage:
+  rnx preview <bundle.js|https://bundle-url> [--assets <dir>] [--platform ios|android] [--open]
+
+The share contains the immutable build and its Metro assets. It is not a recorded replay.
+`)
+    return 0
+  }
+  try {
+    const input = [...args]
+    const assets = takeValue(input, '--assets')
+    const origin = await resolveDefaultUploadOrigin(
+      takeValue(input, '--origin') ?? undefined,
+    )
+    const publicOrigin = resolvePublicPreviewOrigin(
+      origin,
+      takeValue(input, '--public-origin') ?? undefined,
+    )
+    const platform = takeValue(input, '--platform') ?? 'ios'
+    const openIndex = input.indexOf('--open')
+    const open = openIndex >= 0
+    if (open) input.splice(openIndex, 1)
+    if (platform !== 'ios' && platform !== 'android') {
+      throw new Error('--platform must be ios or android')
+    }
+    if (input.length !== 1 || input[0]?.startsWith('-')) {
+      throw new Error('usage: rnx preview <bundle.js|https://bundle-url>')
+    }
+    const auth = resolveCliAuth()
+    if (!auth) throw new Error('rnx preview needs `rnx login` or RNX_API_KEY')
+    const accountId = cloudAccountIdOrExit(auth)
+
+    const artifact = await producePreviewArtifact(input[0], assets ?? undefined)
+    const bundle = brotliBundle(artifact.bytes)
+    const initBody: InitRequestBody = {
+      kind: 'build',
+      buildPlatform: platform,
+      contentHash: createHash('sha256').update(artifact.bytes).digest('hex'),
+      bundleSizeBytes: artifact.bytes.byteLength,
+      bundleContentType: 'application/javascript',
+      bundleEncoding: 'br',
+      bundleMinified: true,
+      bundleOrigin: null,
+      entry: null,
+      isTransformed: false,
+      deviceSpec:
+        platform === 'android'
+          ? { model: 'pixel-8', width: 412, height: 915 }
+          : { model: 'iphone-16', width: 402, height: 874 },
+      files: [],
+    }
+    const { finalize } = await runPresignedUpload({
+      originBase: origin,
+      endpoints: {
+        init: '/api/v1/previews',
+        finalize: '/api/v1/previews/finalize',
+      },
+      initBody,
+      bundleBytes: bundle,
+      filesByHash: new Map(),
+      authHeader: authHeaderValue(auth),
+      accountId,
+    })
+    const url = finalize.url.startsWith('http')
+      ? finalize.url
+      : `${publicOrigin}${finalize.url}`
+    console.log(`  preview: ${url}`)
+    console.log(
+      `  artifact: sha256:${artifact.sha256} (${artifact.bytes.byteLength} bytes)`,
+    )
+    for (const warning of artifact.warnings) console.warn(`  warning: ${warning}`)
+    if (open) await openUrl(url)
+    return 0
+  } catch (error) {
+    console.error(
+      `  rnx preview failed: ${error instanceof Error ? error.message : String(error)}`,
+    )
+    return 1
+  }
+}

package/cli/commands/test.ts

@@ -0,0 +1,224 @@
+// rnx test — choose the existing Maestro or Detox interpreter from a test path.
+
+import { existsSync, readFileSync, statSync } from 'fs'
+import { createServer, type Server } from 'node:http'
+import { basename, extname, join, resolve } from 'path'
+import { buildShellUrl, resolveShellBaseUrlForBridgePort } from './control'
+import { runDetox } from './detox'
+import { runMaestro } from './maestro'
+
+type TestRunner = 'maestro' | 'detox'
+
+export interface RunTestOptions {
+  port?: number
+  verbose?: boolean
+}
+
+const MAESTRO_CONFIG_NAMES = new Set(['config.yaml', 'config.yml'])
+const DETOX_CONFIG_NAME = /^jest\.config\.(?:[cm]?[jt]s)$/
+const VALUE_FLAGS = new Set([
+  '--app',
+  '--config',
+  '--sim',
+  '--session',
+  '--tab',
+  '--port',
+  '--device',
+  '--driver',
+  '--base-url',
+  '--url',
+  '-t',
+  '--testNamePattern',
+  '--grep',
+  '--maxWorkers',
+  '--shard',
+  '--outputFile',
+])
+
+function isDetoxPackageConfig(path: string): boolean {
+  if (basename(path) !== 'package.json') return false
+  try {
+    const value: unknown = JSON.parse(readFileSync(path, 'utf8'))
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return false
+    return 'detox' in value || 'jest' in value
+  } catch {
+    return false
+  }
+}
+
+function classifyTestPath(path: string): TestRunner | null {
+  const name = basename(path)
+  const extension = extname(path).toLowerCase()
+  if (MAESTRO_CONFIG_NAMES.has(name) || extension === '.yaml' || extension === '.yml') {
+    return 'maestro'
+  }
+  if (DETOX_CONFIG_NAME.test(name) || isDetoxPackageConfig(path)) return 'detox'
+  if (
+    ['.js', '.cjs', '.mjs', '.ts', '.cts', '.mts', '.tsx', '.jsx'].includes(extension)
+  ) {
+    return 'detox'
+  }
+  if (!existsSync(path) || !statSync(path).isDirectory()) return null
+  if (existsSync(join(path, 'config.yaml')) || existsSync(join(path, 'config.yml'))) {
+    return 'maestro'
+  }
+  if (existsSync(join(path, '.maestro')) || basename(path) === '.maestro')
+    return 'maestro'
+  if (
+    existsSync(join(path, 'rnx-detox.config.cjs')) ||
+    existsSync(join(path, 'jest.config.cjs')) ||
+    existsSync(join(path, 'jest.config.js')) ||
+    isDetoxPackageConfig(join(path, 'package.json')) ||
+    existsSync(join(path, 'e2e')) ||
+    existsSync(join(path, 'detox'))
+  ) {
+    return 'detox'
+  }
+  return null
+}
+
+function valueAfter(args: string[], name: string): string | null {
+  const index = args.indexOf(name)
+  if (index < 0) return null
+  const value = args[index + 1]
+  return value && !value.startsWith('-') ? value : null
+}
+
+function targetFromArgs(args: string[]): string | null {
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index]
+    if (VALUE_FLAGS.has(arg)) {
+      index += 1
+      continue
+    }
+    if (!arg.startsWith('-')) return arg
+  }
+  return null
+}
+
+function withoutApp(args: string[]): string[] {
+  const appIndex = args.indexOf('--app')
+  return args.filter((_, index) => index !== appIndex && index !== appIndex + 1)
+}
+
+function isDetoxConfigPath(path: string): boolean {
+  return DETOX_CONFIG_NAME.test(basename(path)) || isDetoxPackageConfig(path)
+}
+
+function restoreRnxUrl(previous: string | undefined): void {
+  if (previous === undefined) {
+    delete process.env.RNX_URL
+  } else {
+    process.env.RNX_URL = previous
+  }
+}
+
+interface TestAppTarget {
+  target: string
+  close: () => Promise<void>
+}
+
+function closeServer(server: Server): Promise<void> {
+  return new Promise((resolveClose, rejectClose) => {
+    server.close((error) => {
+      if (error) rejectClose(error)
+      else resolveClose()
+    })
+  })
+}
+
+async function servePrebuiltBundle(path: string): Promise<TestAppTarget> {
+  const file = resolve(process.cwd(), path)
+  const stat = statSync(file)
+  if (!stat.isFile() || extname(file) !== '.js') {
+    throw new Error('--app must name a regular Metro .js bundle or a packager target')
+  }
+  const bundle = readFileSync(file)
+  if (bundle.length === 0) throw new Error('--app bundle is empty')
+
+  const server = createServer((request, response) => {
+    if (new URL(request.url || '/', 'http://127.0.0.1').pathname !== '/bundle.js') {
+      response.writeHead(404).end()
+      return
+    }
+    response.writeHead(200, {
+      'access-control-allow-origin': '*',
+      'cache-control': 'no-store',
+      'content-type': 'application/javascript; charset=utf-8',
+      'content-length': String(bundle.length),
+    })
+    response.end(bundle)
+  })
+  await new Promise<void>((resolveListen, rejectListen) => {
+    server.once('error', rejectListen)
+    server.listen(0, '127.0.0.1', () => {
+      server.off('error', rejectListen)
+      resolveListen()
+    })
+  })
+  const address = server.address()
+  if (!address || typeof address === 'string') {
+    await closeServer(server)
+    throw new Error('could not start the local prebuilt-bundle server')
+  }
+  return {
+    target: `http://127.0.0.1:${address.port}/bundle.js`,
+    close: () => closeServer(server),
+  }
+}
+
+async function resolveTestAppTarget(app: string): Promise<TestAppTarget> {
+  const localPath = resolve(process.cwd(), app)
+  if (existsSync(localPath)) return servePrebuiltBundle(localPath)
+  return { target: app, close: async () => {} }
+}
+
+export async function runTest(
+  args: string[],
+  opts: RunTestOptions = {},
+): Promise<number> {
+  const target = targetFromArgs(args)
+  const app = valueAfter(args, '--app')
+  if (!target || !app) {
+    console.error('  usage: rnx test <flow-or-suite> --app <bundle>')
+    return 1
+  }
+
+  const targetPath = resolve(process.cwd(), target)
+  const runner = classifyTestPath(targetPath)
+  if (!runner) {
+    console.error(`  error: could not detect a Maestro flow or Detox suite at ${target}`)
+    return 1
+  }
+
+  const forwarded = withoutApp(args).filter((arg) => arg !== target)
+  const appTarget = await resolveTestAppTarget(app)
+  try {
+    if (runner === 'maestro') {
+      const code = await runMaestro(
+        ['test', targetPath, '--url', appTarget.target, ...forwarded],
+        opts,
+      )
+      return typeof code === 'number' ? code : 0
+    }
+
+    const detoxArgs = isDetoxConfigPath(targetPath)
+      ? ['--config', targetPath, ...forwarded]
+      : [targetPath, ...forwarded]
+    const previousRnxUrl = process.env.RNX_URL
+    process.env.RNX_URL = await buildShellUrl(
+      appTarget.target,
+      resolveShellBaseUrlForBridgePort(
+        opts.port ?? (Number(process.env.SOOTSIM_PORT) || 5173),
+      ),
+    )
+    try {
+      await runDetox(detoxArgs, opts)
+      return 0
+    } finally {
+      restoreRnxUrl(previousRnxUrl)
+    }
+  } finally {
+    await appTarget.close()
+  }
+}