rnxsim 0.0.0 → 0.1.313

package/detox/config-loader.ts

@@ -0,0 +1,135 @@
+// parse detox configuration from various locations
+// maps detox device config to sootsim settings
+
+import * as fs from 'fs'
+import * as path from 'path'
+
+export interface DetoxConfig {
+  testRunner?: {
+    args?: Record<string, any>
+    jest?: { setupTimeout?: number; teardownTimeout?: number }
+  }
+  apps?: Record<string, { type: string; binaryPath?: string; build?: string }>
+  devices?: Record<string, { type: string; device?: { type?: string } }>
+  configurations?: Record<string, { device?: string; app?: string }>
+  testMatch?: string[]
+  testDir?: string
+}
+
+export interface SootSimDetoxConfig {
+  testFiles: string[]
+  testTimeout: number
+  sootsimUrl: string
+  deviceModel: string
+  maxWorkers: number
+}
+
+// search order: .detoxrc.js, .detoxrc.json, detox.config.js, detox.config.json, package.json#detox
+export function loadDetoxConfig(projectDir: string): DetoxConfig | null {
+  const candidates = [
+    '.detoxrc.js',
+    '.detoxrc.json',
+    'detox.config.js',
+    'detox.config.json',
+  ]
+
+  for (const file of candidates) {
+    const filePath = path.join(projectDir, file)
+    if (fs.existsSync(filePath)) {
+      try {
+        if (file.endsWith('.json')) {
+          return JSON.parse(fs.readFileSync(filePath, 'utf8'))
+        }
+        // for JS files, we can't easily require them without running them
+        // return a basic config indicating file was found
+        return { testDir: 'e2e' }
+      } catch {
+        continue
+      }
+    }
+  }
+
+  // check package.json
+  const pkgPath = path.join(projectDir, 'package.json')
+  if (fs.existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'))
+      if (pkg.detox) return pkg.detox
+    } catch {}
+  }
+
+  return null
+}
+
+// find test files matching detox patterns
+export function findDetoxTestFiles(
+  projectDir: string,
+  config: DetoxConfig | null,
+): string[] {
+  const testDirs = ['e2e', 'test/e2e', 'detox', '__tests__/e2e']
+  const patterns = [
+    '.test.ts',
+    '.test.js',
+    '.test.tsx',
+    '.test.jsx',
+    '.spec.ts',
+    '.spec.js',
+  ]
+
+  // if config specifies a test dir, prioritize it
+  if (config?.testDir) {
+    testDirs.unshift(config.testDir)
+  }
+
+  const files: string[] = []
+
+  for (const dir of testDirs) {
+    const fullDir = path.join(projectDir, dir)
+    if (!fs.existsSync(fullDir)) continue
+
+    const entries = fs.readdirSync(fullDir, { recursive: true })
+    for (const entry of entries) {
+      const entryStr = String(entry)
+      if (patterns.some((p) => entryStr.endsWith(p))) {
+        files.push(path.join(fullDir, entryStr))
+      }
+    }
+  }
+
+  return files
+}
+
+// map detox device type to sootsim device model
+export function mapDetoxDevice(config: DetoxConfig | null): string {
+  if (!config?.devices) return 'iphone-15-pro'
+
+  const devices = Object.values(config.devices)
+  for (const dev of devices) {
+    const type = dev.device?.type?.toLowerCase() || ''
+    if (type.includes('se')) return 'iphone-se'
+    if (type.includes('16 pro max') || type.includes('16-pro-max'))
+      return 'iphone-16-pro-max'
+    if (type.includes('16 pro') || type.includes('16-pro')) return 'iphone-16-pro'
+    if (type.includes('16')) return 'iphone-16'
+    if (type.includes('15 pro max') || type.includes('15-pro-max'))
+      return 'iphone-15-pro-max'
+    if (type.includes('15 pro') || type.includes('15-pro')) return 'iphone-15-pro'
+    if (type.includes('15')) return 'iphone-15'
+  }
+
+  return 'iphone-15-pro'
+}
+
+// generate a sootsim-compatible config from detox config
+export function toSootSimConfig(
+  projectDir: string,
+  config: DetoxConfig | null,
+): SootSimDetoxConfig {
+  return {
+    testFiles: findDetoxTestFiles(projectDir, config),
+    testTimeout: config?.testRunner?.jest?.setupTimeout || 120000,
+    sootsimUrl: process.env.SOOTSIM_URL || 'http://localhost:5173',
+    deviceModel: mapDetoxDevice(config),
+    maxWorkers: 1,
+  }
+}

package/detox/element-types.ts

@@ -0,0 +1,39 @@
+import type { Matcher } from './matchers'
+
+// element interaction object returned by element(matcher)
+export interface SootSimElement {
+  // reference to the matcher for lazy evaluation
+  _matcher: Matcher
+
+  tap(point?: { x?: number; y?: number }): Promise<void>
+  multiTap(times: number): Promise<void>
+  longPress(duration?: number): Promise<void>
+  longPressAndDrag(
+    duration: number,
+    normalizedStartX: number,
+    normalizedStartY: number,
+    targetElement: SootSimElement,
+    normalizedEndX: number,
+    normalizedEndY: number,
+    speed?: string,
+    holdDuration?: number,
+  ): Promise<void>
+  typeText(text: string): Promise<void>
+  replaceText(text: string): Promise<void>
+  clearText(): Promise<void>
+  scroll(pixels: number, direction: 'up' | 'down' | 'left' | 'right'): Promise<void>
+  scrollTo(edge: 'top' | 'bottom' | 'left' | 'right'): Promise<void>
+  swipe(
+    direction: 'up' | 'down' | 'left' | 'right',
+    speed?: 'fast' | 'slow',
+    percentage?: number,
+    normalizedStartingPointX?: number,
+    normalizedStartingPointY?: number,
+  ): Promise<void>
+  setColumnToValue(column: number, value: string): Promise<void>
+  pinch(scale: number, speed?: 'fast' | 'slow', angle?: number): Promise<void>
+  rotate(radians: number, speed?: 'fast' | 'slow'): Promise<void>
+  takeScreenshot(name: string): Promise<string>
+  getAttributes(): Promise<any>
+  atIndex(index: number): SootSimElement
+}

package/detox/expectations.ts

@@ -0,0 +1,537 @@
+// detox-compatible expectations for sootsim
+// expect(element).toExist(), .toBeVisible(), .toHaveText(), etc.
+// waitFor(element).toExist().withTimeout(ms)
+
+import { dragScrollNode } from './gestures'
+import type { SootSimElement } from './element-types'
+import type { Matcher } from './matchers'
+import type { SootSimNodeInfo } from '@sootsim/globals'
+import type { Page } from 'playwright'
+
+type FindFn = (matcher: Matcher) => Promise<any>
+type GetPageFn = () => Page
+const DEFAULT_VISIBILITY_THRESHOLD = 0.75
+
+// one scroll step on the container, reporting how far it actually travelled.
+// the caller ends the search when the container stops moving, which is how
+// detox ends a `whileElement(...).scroll()` on a device: the native scroll
+// throws once it reaches the end of the content.
+async function scrollMatcherElement(
+  page: Page,
+  findNode: FindFn,
+  matcher: Matcher,
+  pixels: number,
+  direction: 'up' | 'down' | 'left' | 'right',
+): Promise<number> {
+  const node = await findNode(matcher)
+  if (!node) {
+    throw new Error(`scroll container not found: ${JSON.stringify(matcher)}`)
+  }
+  const before = scrollOffsetOf(node)
+  await dragScrollNode(page, node, pixels, direction)
+  const after = scrollOffsetOf(await findNode(matcher))
+  return Math.abs(after.x - before.x) + Math.abs(after.y - before.y)
+}
+
+function scrollOffsetOf(node: any): { x: number; y: number } {
+  return { x: node?.scrollOffsetX ?? 0, y: node?.scrollOffsetY ?? 0 }
+}
+
+// how much of the node is actually on screen, as a fraction of its own area.
+// the engine already intersects every node with each clipping ancestor and
+// with the device surface when it builds `visibleFrame`, so that rect is the
+// on-screen area and needs no further clipping here. intersecting it a second
+// time against the interactive viewport (screen minus the home indicator band)
+// used to fail views that were 84% and 93% on screen, because iOS draws the
+// home indicator over app content rather than hiding it, and Detox's own
+// visibility percentage on iOS is computed against the app window.
+function visibleFraction(node: SootSimNodeInfo | null | undefined): number {
+  const totalArea = (node?.layout?.width ?? 0) * (node?.layout?.height ?? 0)
+  const frame = node?.visibleFrame
+  if (totalArea <= 0 || !frame) return 0
+  const visibleArea = Math.max(0, frame.width) * Math.max(0, frame.height)
+  return visibleArea / totalArea
+}
+
+export function isNodeVisible(node: SootSimNodeInfo | null | undefined): boolean {
+  return visibleFraction(node) >= DEFAULT_VISIBILITY_THRESHOLD
+}
+
+// the engine tags each rendered node with its id, so DOM focus is the source of
+// truth for both the `expect` and `waitFor` forms of toBeFocused.
+async function isNodeFocused(node: any, page: Page): Promise<boolean> {
+  const nodeId =
+    typeof node?.nodeId === 'number'
+      ? node.nodeId
+      : typeof node?.id === 'number'
+        ? node.id
+        : null
+  if (nodeId === null) return false
+  return page.evaluate((id) => {
+    const active = document.activeElement
+    return active?.getAttribute('data-sootsim-id') === String(id)
+  }, nodeId)
+}
+
+export function describeNodeVisibility(node: SootSimNodeInfo | null | undefined): string {
+  if (!node) return 'not found'
+  const absX = node.absolutePosition?.x ?? node.layout?.x ?? 0
+  const absY = node.absolutePosition?.y ?? node.layout?.y ?? 0
+  return JSON.stringify({
+    layout: node.layout,
+    absolutePosition: node.absolutePosition ?? null,
+    frame: {
+      x: absX,
+      y: absY,
+      right: absX + (node.layout?.width ?? 0),
+      bottom: absY + (node.layout?.height ?? 0),
+    },
+    visibleFrame: node.visibleFrame ?? null,
+    visibleFraction: visibleFraction(node),
+    threshold: DEFAULT_VISIBILITY_THRESHOLD,
+    style: node.style ?? null,
+  })
+}
+
+// expect(element) returns an object with assertion methods
+export function createExpect(findNode: FindFn, getPage: GetPageFn) {
+  return function sootsimExpect(el: SootSimElement): SootSimExpectation {
+    return new SootSimExpectation(el._matcher, findNode, getPage, false)
+  }
+}
+
+class SootSimExpectation {
+  private matcher: Matcher
+  private findNode: FindFn
+  private getPage: GetPageFn
+  private negated: boolean
+
+  constructor(matcher: Matcher, findNode: FindFn, getPage: GetPageFn, negated: boolean) {
+    this.matcher = matcher
+    this.findNode = findNode
+    this.getPage = getPage
+    this.negated = negated
+  }
+
+  get not(): SootSimExpectation {
+    return new SootSimExpectation(
+      this.matcher,
+      this.findNode,
+      this.getPage,
+      !this.negated,
+    )
+  }
+
+  async toExist(): Promise<void> {
+    const node = await this.findNode(this.matcher)
+    const exists = node !== null && node !== undefined
+    if (this.negated) {
+      if (exists) {
+        throw new Error(
+          `expected element NOT to exist but it does: ${JSON.stringify(this.matcher)}`,
+        )
+      }
+    } else {
+      if (!exists) {
+        throw new Error(
+          `expected element to exist but it was not found: ${JSON.stringify(this.matcher)}`,
+        )
+      }
+    }
+  }
+
+  async toBeVisible(): Promise<void> {
+    const node = await this.findNode(this.matcher)
+    const visible = isNodeVisible(node)
+    if (this.negated) {
+      if (visible) {
+        throw new Error(
+          `expected element NOT to be visible: ${JSON.stringify(this.matcher)}`,
+        )
+      }
+    } else {
+      if (!visible) {
+        throw new Error(
+          `expected element to be visible but it is ${describeNodeVisibility(node)}: ${JSON.stringify(this.matcher)}`,
+        )
+      }
+    }
+  }
+
+  async toBeNotVisible(): Promise<void> {
+    const node = await this.findNode(this.matcher)
+    const visible = isNodeVisible(node)
+    if (visible) {
+      throw new Error(
+        `expected element NOT to be visible: ${JSON.stringify(this.matcher)}`,
+      )
+    }
+  }
+
+  async toHaveText(expectedText: string): Promise<void> {
+    const node = await this.findNode(this.matcher)
+    if (!node) {
+      throw new Error(`element not found for toHaveText: ${JSON.stringify(this.matcher)}`)
+    }
+    const actualText = node.text || ''
+    const matches = actualText === expectedText || actualText.includes(expectedText)
+
+    if (this.negated) {
+      if (matches) {
+        throw new Error(
+          `expected text NOT to be "${expectedText}" but got "${actualText}": ${JSON.stringify(this.matcher)}`,
+        )
+      }
+    } else {
+      if (!matches) {
+        throw new Error(
+          `expected text "${expectedText}" but got "${actualText}": ${JSON.stringify(this.matcher)}`,
+        )
+      }
+    }
+  }
+
+  async toHaveId(expectedId: string): Promise<void> {
+    const node = await this.findNode(this.matcher)
+    if (!node) {
+      throw new Error(`element not found for toHaveId: ${JSON.stringify(this.matcher)}`)
+    }
+    const hasId = node.testID === expectedId || node.id === expectedId
+    if (this.negated) {
+      if (hasId) throw new Error(`expected element NOT to have id "${expectedId}"`)
+    } else {
+      if (!hasId)
+        throw new Error(
+          `expected element to have id "${expectedId}" but got "${node.testID || node.id}"`,
+        )
+    }
+  }
+
+  async toHaveLabel(expectedLabel: string): Promise<void> {
+    const node = await this.findNode(this.matcher)
+    if (!node) {
+      throw new Error(
+        `element not found for toHaveLabel: ${JSON.stringify(this.matcher)}`,
+      )
+    }
+    // check explicit accessibilityLabel, then derived text content
+    const actual = node.accessibilityLabel || node.text || ''
+    const matches = actual === expectedLabel
+    if (this.negated) {
+      if (matches)
+        throw new Error(`expected label NOT to be "${expectedLabel}" but it was`)
+    } else {
+      if (!matches)
+        throw new Error(
+          `expected label "${expectedLabel}" but got "${actual}": ${JSON.stringify(this.matcher)}`,
+        )
+    }
+  }
+
+  async toHaveAccessibilityRole(expectedRole: string): Promise<void> {
+    const node = await this.findNode(this.matcher)
+    if (!node) {
+      throw new Error(
+        `element not found for toHaveAccessibilityRole: ${JSON.stringify(this.matcher)}`,
+      )
+    }
+    const actual = node.accessibilityRole || ''
+    const matches = actual === expectedRole
+    if (this.negated) {
+      if (matches) throw new Error(`expected role NOT to be "${expectedRole}" but it was`)
+    } else {
+      if (!matches)
+        throw new Error(
+          `expected role "${expectedRole}" but got "${actual}": ${JSON.stringify(this.matcher)}`,
+        )
+    }
+  }
+
+  async toBeEnabled(): Promise<void> {
+    const node = await this.findNode(this.matcher)
+    if (!node) {
+      throw new Error(
+        `element not found for toBeEnabled: ${JSON.stringify(this.matcher)}`,
+      )
+    }
+    const disabled = node.accessibilityState?.disabled ?? false
+    if (this.negated) {
+      if (!disabled) throw new Error(`expected element to be disabled but it is enabled`)
+    } else {
+      if (disabled) throw new Error(`expected element to be enabled but it is disabled`)
+    }
+  }
+
+  async toBeFocused(): Promise<void> {
+    const node = await this.findNode(this.matcher)
+    if (!node) {
+      throw new Error(
+        `element not found for toBeFocused: ${JSON.stringify(this.matcher)}`,
+      )
+    }
+    const focused = await isNodeFocused(node, this.getPage())
+
+    if (this.negated) {
+      if (focused) {
+        throw new Error(
+          `expected element NOT to be focused: ${JSON.stringify(this.matcher)}`,
+        )
+      }
+    } else if (!focused) {
+      throw new Error(`expected element to be focused: ${JSON.stringify(this.matcher)}`)
+    }
+  }
+
+  async toHaveValue(value: string): Promise<void> {
+    const node = await this.findNode(this.matcher)
+    if (!node) {
+      throw new Error(
+        `element not found for toHaveValue: ${JSON.stringify(this.matcher)}`,
+      )
+    }
+    // value could be in text or props
+    const actual = node.text || ''
+    if (this.negated) {
+      if (actual.includes(value)) {
+        throw new Error(
+          `expected element NOT to have value "${value}" but got "${actual}"`,
+        )
+      }
+    } else {
+      if (!actual.includes(value)) {
+        throw new Error(`expected element to have value "${value}" but got "${actual}"`)
+      }
+    }
+  }
+
+  async toHaveSliderPosition(
+    normalizedPosition: number,
+    tolerance?: number,
+  ): Promise<void> {
+    // stub for slider tests -- sootsim doesn't have native sliders yet
+    await this.toExist()
+  }
+
+  async toHaveToggleValue(value: boolean): Promise<void> {
+    await this.toExist()
+  }
+}
+
+// waitFor(element) returns a chainable object that polls until the assertion passes
+export function createWaitFor(findNode: FindFn, getPage: GetPageFn) {
+  return function sootsimWaitFor(el: SootSimElement): SootSimWaitForChain {
+    return new SootSimWaitForChain(el._matcher, findNode, getPage)
+  }
+}
+
+class SootSimWaitForChain {
+  private matcher: Matcher
+  private findNode: FindFn
+  private getPage: GetPageFn
+  private assertionFn: (() => Promise<void>) | null = null
+  private _negated = false
+
+  constructor(matcher: Matcher, findNode: FindFn, getPage: GetPageFn) {
+    this.matcher = matcher
+    this.findNode = findNode
+    this.getPage = getPage
+  }
+
+  get not(): SootSimWaitForChain {
+    this._negated = true
+    return this
+  }
+
+  toExist(): SootSimWaitForAction {
+    this.assertionFn = async () => {
+      const node = await this.findNode(this.matcher)
+      const exists = node !== null && node !== undefined
+      if (this._negated ? exists : !exists) {
+        throw new Error(`waitFor toExist failed: ${JSON.stringify(this.matcher)}`)
+      }
+    }
+    return new SootSimWaitForAction(this.assertionFn, this.findNode, this.getPage)
+  }
+
+  toBeVisible(): SootSimWaitForAction {
+    this.assertionFn = async () => {
+      const node = await this.findNode(this.matcher)
+      const visible = isNodeVisible(node)
+      if (this._negated ? visible : !visible) {
+        throw new Error(
+          `waitFor toBeVisible failed (${describeNodeVisibility(node)}): ${JSON.stringify(this.matcher)}`,
+        )
+      }
+    }
+    return new SootSimWaitForAction(this.assertionFn, this.findNode, this.getPage)
+  }
+
+  toBeNotVisible(): SootSimWaitForAction {
+    this.assertionFn = async () => {
+      const node = await this.findNode(this.matcher)
+      const visible = isNodeVisible(node)
+      if (visible) {
+        throw new Error(`waitFor toBeNotVisible failed: ${JSON.stringify(this.matcher)}`)
+      }
+    }
+    return new SootSimWaitForAction(this.assertionFn, this.findNode, this.getPage)
+  }
+
+  toHaveText(expectedText: string): SootSimWaitForAction {
+    this.assertionFn = async () => {
+      const node = await this.findNode(this.matcher)
+      if (!node)
+        throw new Error(
+          `waitFor toHaveText: element not found: ${JSON.stringify(this.matcher)}`,
+        )
+      const actual = node.text || ''
+      const matches = actual === expectedText || actual.includes(expectedText)
+      if (this._negated ? matches : !matches) {
+        throw new Error(
+          `waitFor toHaveText: expected "${expectedText}" but got "${actual}" ${JSON.stringify(this.matcher)}`,
+        )
+      }
+    }
+    return new SootSimWaitForAction(this.assertionFn, this.findNode, this.getPage)
+  }
+
+  toHaveValue(value: string): SootSimWaitForAction {
+    this.assertionFn = async () => {
+      const node = await this.findNode(this.matcher)
+      if (!node) throw new Error(`waitFor toHaveValue: element not found`)
+      const actual = node.text || ''
+      if (!actual.includes(value)) {
+        throw new Error(`waitFor toHaveValue: expected "${value}" in "${actual}"`)
+      }
+    }
+    return new SootSimWaitForAction(this.assertionFn, this.findNode, this.getPage)
+  }
+
+  toBeFocused(): SootSimWaitForAction {
+    this.assertionFn = async () => {
+      const node = await this.findNode(this.matcher)
+      if (!node)
+        throw new Error(
+          `waitFor toBeFocused: element not found: ${JSON.stringify(this.matcher)}`,
+        )
+      const focused = await isNodeFocused(node, this.getPage())
+      if (this._negated ? focused : !focused) {
+        throw new Error(`waitFor toBeFocused failed: ${JSON.stringify(this.matcher)}`)
+      }
+    }
+    return new SootSimWaitForAction(this.assertionFn, this.findNode, this.getPage)
+  }
+}
+
+class SootSimWaitForAction {
+  private assertionFn: () => Promise<void>
+  private findNode: FindFn
+  private getPage: GetPageFn
+
+  constructor(assertionFn: () => Promise<void>, findNode: FindFn, getPage: GetPageFn) {
+    this.assertionFn = assertionFn
+    this.findNode = findNode
+    this.getPage = getPage
+  }
+
+  async withTimeout(ms: number): Promise<void> {
+    const start = Date.now()
+    const pollInterval = 100
+    let lastError: Error | null = null
+
+    while (Date.now() - start < ms) {
+      try {
+        await this.assertionFn()
+        return // assertion passed
+      } catch (e) {
+        lastError = e as Error
+        await new Promise((r) => setTimeout(r, pollInterval))
+      }
+    }
+
+    throw lastError || new Error(`waitFor timed out after ${ms}ms`)
+  }
+
+  // if no withTimeout is called, just run the assertion once
+  async then(resolve: (v: void) => void, reject: (e: any) => void): Promise<void> {
+    try {
+      // default 5 second timeout
+      await this.withTimeout(5000)
+      resolve(undefined)
+    } catch (e) {
+      reject(e)
+    }
+  }
+
+  whileElement(matcher: Matcher): SootSimWaitForScrollAction {
+    return new SootSimWaitForScrollAction(
+      this.assertionFn,
+      this.findNode,
+      this.getPage,
+      matcher,
+    )
+  }
+}
+
+class SootSimWaitForScrollAction {
+  private assertionFn: () => Promise<void>
+  private findNode: FindFn
+  private getPage: GetPageFn
+  private matcher: Matcher
+
+  constructor(
+    assertionFn: () => Promise<void>,
+    findNode: FindFn,
+    getPage: GetPageFn,
+    matcher: Matcher,
+  ) {
+    this.assertionFn = assertionFn
+    this.findNode = findNode
+    this.getPage = getPage
+    this.matcher = matcher
+  }
+
+  // detox scrolls the container until the expectation passes or the container
+  // can no longer move. bounding this by wall clock instead made the result
+  // depend on how fast the host dispatches pointer events: the same fixture and
+  // the same assertion pass on an idle machine and fail on a loaded one,
+  // because each 200px drag is a real pointer stream and fewer of them fit in
+  // the budget. end on scroll exhaustion, which is a property of the content.
+  async scroll(
+    pixels: number,
+    direction: 'up' | 'down' | 'left' | 'right',
+    _startPositionX?: number,
+    _startPositionY?: number,
+  ): Promise<void> {
+    const page = this.getPage()
+    let lastError: Error | null = null
+    let stalledSteps = 0
+
+    // two consecutive steps, so one settling frame that reports the same offset
+    // does not read as the end of the content.
+    while (stalledSteps < 2) {
+      try {
+        await this.assertionFn()
+        return
+      } catch (error) {
+        lastError = error as Error
+      }
+
+      const travelled = await scrollMatcherElement(
+        page,
+        this.findNode,
+        this.matcher,
+        pixels,
+        direction,
+      )
+      stalledSteps = travelled < 0.5 ? stalledSteps + 1 : 0
+    }
+
+    throw (
+      lastError ||
+      new Error(
+        `waitFor whileElement(...).scroll() reached the end of ${JSON.stringify(this.matcher)}`,
+      )
+    )
+  }
+}