@nyby/detox-component-testing 1.4.0 → 1.5.0

package/src/ComponentHarness.tsx

@@ -1,27 +1,26 @@
-import React, { Component as ReactComponent, useState, useRef, useCallback, ReactNode } from 'react';
-import { View, Text, TextInput, ScrollView } from 'react-native';
-import { LaunchArguments } from 'react-native-launch-arguments';
-import { getComponent } from './ComponentRegistry';
-import { getWrapper } from './configureHarness';
+import React, {Component as ReactComponent, useState, useRef, useCallback, ReactNode} from 'react';
+import {View, Text, TextInput, ScrollView} from 'react-native';
+import {LaunchArguments} from 'react-native-launch-arguments';
+import {getComponent} from './ComponentRegistry';
+import {getWrapper, getDebugTreeConfig} from './configureHarness';
+import {DebugTree} from './DebugTree';
 
 interface ErrorBoundaryState {
   error: Error | null;
 }
 
-class RenderErrorBoundary extends ReactComponent<{ children: ReactNode }, ErrorBoundaryState> {
-  state: ErrorBoundaryState = { error: null };
+class RenderErrorBoundary extends ReactComponent<{children: ReactNode}, ErrorBoundaryState> {
+  state: ErrorBoundaryState = {error: null};
 
   static getDerivedStateFromError(error: Error) {
-    return { error };
+    return {error};
   }
 
   render() {
     if (this.state.error) {
       return (
         <ScrollView testID="detox-render-error">
-          <Text testID="detox-render-error-message">
-            {this.state.error.message}
-          </Text>
+          <Text testID="detox-render-error-message">{this.state.error.message}</Text>
         </ScrollView>
       );
     }
@@ -39,7 +38,10 @@ interface MountPayload {
   spies: string[];
 }
 
-function parseLaunchArgs(args: Record<string, any>): { props: Record<string, any>; spies: string[] } {
+function parseLaunchArgs(args: Record<string, any>): {
+  props: Record<string, any>;
+  spies: string[];
+} {
   const props: Record<string, any> = {};
   const spies: string[] = [];
   Object.entries(args).forEach(([key, value]) => {
@@ -49,16 +51,16 @@ function parseLaunchArgs(args: Record<string, any>): { props: Record<string, any
       spies.push(key.slice(SPY_PREFIX.length));
     }
   });
-  return { props, spies };
+  return {props, spies};
 }
 
 export function ComponentHarness() {
   const launchArgs = LaunchArguments.value() as Record<string, any>;
   const [mountPayload, setMountPayload] = useState<MountPayload | null>(null);
 
-  const handleControl = useCallback((text: string) => {
+  const handleControl = useCallback((e: {nativeEvent: {text: string}}) => {
     try {
-      setMountPayload(JSON.parse(text));
+      setMountPayload(JSON.parse(e.nativeEvent.text));
     } catch (_e) {}
   }, []);
 
@@ -66,7 +68,7 @@ export function ComponentHarness() {
   if (mountPayload) {
     activeMount = mountPayload;
   } else if (launchArgs.detoxComponentName) {
-    const { props, spies } = parseLaunchArgs(launchArgs);
+    const {props, spies} = parseLaunchArgs(launchArgs);
     activeMount = {
       id: '0',
       name: launchArgs.detoxComponentName as string,
@@ -76,15 +78,25 @@ export function ComponentHarness() {
   }
 
   return (
-    <View style={{ flex: 1 }}>
+    <View style={{flex: 1}}>
       <TextInput
         testID="detox-harness-control"
-        onChangeText={handleControl}
-        style={{ height: 1 }}
+        onEndEditing={handleControl}
+        style={{
+          position: 'absolute',
+          bottom: 0,
+          left: 0,
+          right: 0,
+          height: 44,
+          opacity: 0.01,
+          zIndex: 9999,
+        }}
       />
       {activeMount && (
         <>
-          <Text testID="detox-mount-id" style={{ height: 1 }}>{activeMount.id}</Text>
+          <Text testID="detox-mount-id" style={{height: 1}}>
+            {activeMount.id}
+          </Text>
           <RenderErrorBoundary>
             <ComponentRenderer key={activeMount.id} mount={activeMount} />
           </RenderErrorBoundary>
@@ -99,23 +111,23 @@ interface SpyData {
   lastArgs: any[];
 }
 
-function ComponentRenderer({ mount }: { mount: MountPayload }) {
-  const { Component, defaultProps } = getComponent(mount.name);
+function ComponentRenderer({mount}: {mount: MountPayload}) {
+  const {Component, defaultProps} = getComponent(mount.name);
   const spyNames = mount.spies || [];
 
   const initialData: Record<string, SpyData> = {};
-  spyNames.forEach(name => {
-    initialData[name] = { count: 0, lastArgs: [] };
+  spyNames.forEach((name) => {
+    initialData[name] = {count: 0, lastArgs: []};
   });
 
   const [spyData, setSpyData] = useState(initialData);
 
   const spyFnsRef = useRef<Record<string, (...args: any[]) => void>>({});
   const spyProps: Record<string, (...args: any[]) => void> = {};
-  spyNames.forEach(name => {
+  spyNames.forEach((name) => {
     if (!spyFnsRef.current[name]) {
       spyFnsRef.current[name] = (...callArgs: any[]) => {
-        setSpyData(prev => ({
+        setSpyData((prev) => ({
           ...prev,
           [name]: {
             count: (prev[name]?.count || 0) + 1,
@@ -127,20 +139,25 @@ function ComponentRenderer({ mount }: { mount: MountPayload }) {
     spyProps[name] = spyFnsRef.current[name];
   });
 
-  const props = { ...defaultProps, ...(mount.props || {}), ...spyProps };
+  const props = {...defaultProps, ...(mount.props || {}), ...spyProps};
   const Wrapper = getWrapper();
+  const debugTreeConfig = getDebugTreeConfig();
+
+  const content = (
+    <View testID="component-harness-root" style={{flex: 1}}>
+      <Component {...props} />
+      {spyNames.map((name) => (
+        <View key={name}>
+          <Text testID={`spy-${name}-count`}>{String(spyData[name].count)}</Text>
+          <Text testID={`spy-${name}-lastArgs`}>{JSON.stringify(spyData[name].lastArgs)}</Text>
+        </View>
+      ))}
+    </View>
+  );
 
   return (
     <Wrapper launchArgs={mount.props || {}}>
-      <View testID="component-harness-root" style={{ flex: 1 }}>
-        <Component {...props} />
-        {spyNames.map(name => (
-          <View key={name}>
-            <Text testID={`spy-${name}-count`}>{String(spyData[name].count)}</Text>
-            <Text testID={`spy-${name}-lastArgs`}>{JSON.stringify(spyData[name].lastArgs)}</Text>
-          </View>
-        ))}
-      </View>
+      {debugTreeConfig ? <DebugTree {...debugTreeConfig}>{content}</DebugTree> : content}
     </Wrapper>
   );
 }

package/src/ComponentRegistry.ts

@@ -1,4 +1,4 @@
-import { ComponentType } from 'react';
+import {ComponentType} from 'react';
 
 export interface ComponentEntry<P = any> {
   Component: ComponentType<P>;
@@ -12,10 +12,7 @@ export function registerComponent<P>(
   Component: ComponentType<P>,
   defaultProps?: Partial<P>,
 ): void;
-export function registerComponent<P>(
-  Component: ComponentType<P>,
-  defaultProps?: Partial<P>,
-): void;
+export function registerComponent<P>(Component: ComponentType<P>, defaultProps?: Partial<P>): void;
 export function registerComponent<P>(
   nameOrComponent: string | ComponentType<P>,
   componentOrProps?: ComponentType<P> | Partial<P>,

package/src/DebugTree.tsx

@@ -0,0 +1,280 @@
+import React, {useCallback, useRef, useState} from 'react';
+import {Text, TextInput, View} from 'react-native';
+
+type Fiber = {
+  type: any;
+  memoizedProps: Record<string, any>;
+  child: Fiber | null;
+  sibling: Fiber | null;
+  return: Fiber | null;
+  tag: number;
+  stateNode: any;
+};
+
+type TreeNode = {
+  name: string;
+  props?: Record<string, any>;
+  text?: string;
+  children?: TreeNode[];
+};
+
+// React fiber tags
+const FunctionComponent = 0;
+const ClassComponent = 1;
+const HostComponent = 5;
+const HostText = 6;
+const ForwardRef = 11;
+const MemoComponent = 14;
+const SimpleMemoComponent = 15;
+
+const DEFAULT_USEFUL_PROPS = new Set([
+  'testID',
+  'accessibilityLabel',
+  'accessibilityRole',
+  'title',
+  'name',
+  'variant',
+  'size',
+  'value',
+  'placeholder',
+  'disabled',
+  'selected',
+  'checked',
+  'visible',
+]);
+
+const DEFAULT_SKIP_NAMES = new Set([
+  'StaticContainer',
+  'EnsureSingleNavigator',
+  'PreventRemoveProvider',
+  'NavigationContent',
+  'NavigationStateContext',
+  'ScreenStackHeaderConfig',
+  'RenderErrorBoundary',
+  'DebugTree',
+  'PressabilityDebugView',
+]);
+
+const DEFAULT_NATIVE_DUPLICATES = new Set([
+  'RCTText',
+  'RCTView',
+  'RCTScrollView',
+  'RCTCustomScrollView',
+  'RCTScrollContentView',
+  'RCTSinglelineTextInputView',
+  'RCTUITextField',
+]);
+
+function findFiberFromRef(ref: any): Fiber | null {
+  if (!ref) return null;
+
+  // React Native: __internalInstanceHandle is the fiber node
+  if (ref.__internalInstanceHandle) {
+    return ref.__internalInstanceHandle;
+  }
+
+  // React DEV builds
+  if (ref._internalFiberInstanceHandleDEV) {
+    return ref._internalFiberInstanceHandleDEV;
+  }
+
+  // React DOM style: __reactFiber$ key on the node
+  for (const key of Object.getOwnPropertyNames(ref)) {
+    if (key.startsWith('__reactFiber$')) {
+      return ref[key];
+    }
+  }
+
+  return null;
+}
+
+function getComponentName(fiber: Fiber): string | null {
+  const {type, tag} = fiber;
+
+  if (tag === HostText) return null;
+
+  if (tag === HostComponent) {
+    return typeof type === 'string' ? type : null;
+  }
+
+  if (tag === FunctionComponent || tag === ClassComponent || tag === SimpleMemoComponent) {
+    return type?.displayName || type?.name || null;
+  }
+
+  if (tag === ForwardRef) {
+    return type?.displayName || type?.render?.displayName || type?.render?.name || null;
+  }
+
+  if (tag === MemoComponent) {
+    return type?.displayName || type?.type?.displayName || type?.type?.name || null;
+  }
+
+  return null;
+}
+
+function isUserComponent(fiber: Fiber): boolean {
+  const {tag} = fiber;
+  return (
+    tag === FunctionComponent ||
+    tag === ClassComponent ||
+    tag === ForwardRef ||
+    tag === MemoComponent ||
+    tag === SimpleMemoComponent
+  );
+}
+
+function extractProps(fiber: Fiber, usefulProps: Set<string>): Record<string, any> | undefined {
+  const {memoizedProps} = fiber;
+  if (!memoizedProps) return undefined;
+
+  const result: Record<string, any> = {};
+  let hasProps = false;
+
+  for (const key of Object.keys(memoizedProps)) {
+    if (key === 'children' || key === 'style') continue;
+    if (usefulProps.has(key)) {
+      const val = memoizedProps[key];
+      if (typeof val === 'string' || typeof val === 'number' || typeof val === 'boolean') {
+        result[key] = val;
+        hasProps = true;
+      }
+    }
+  }
+
+  if (memoizedProps.onPress) {
+    result.onPress = true;
+    hasProps = true;
+  }
+
+  return hasProps ? result : undefined;
+}
+
+function getTextContent(fiber: Fiber): string | undefined {
+  if (fiber.tag === HostText) {
+    return typeof fiber.memoizedProps === 'string' ? fiber.memoizedProps : undefined;
+  }
+  if (typeof fiber.memoizedProps?.children === 'string') {
+    return fiber.memoizedProps.children;
+  }
+  return undefined;
+}
+
+function shouldShow(fiber: Fiber, skipNames: Set<string>, nativeDuplicates: Set<string>): boolean {
+  const name = getComponentName(fiber);
+  if (!name) return false;
+  if (skipNames.has(name)) return false;
+  if (nativeDuplicates.has(name)) return false;
+
+  if (isUserComponent(fiber)) return true;
+
+  if (fiber.tag === HostComponent) {
+    const props = fiber.memoizedProps;
+    if (props?.testID || props?.accessibilityLabel) return true;
+    if (typeof props?.children === 'string') return true;
+  }
+
+  return false;
+}
+
+function walkFiber(
+  fiber: Fiber | null,
+  collect: TreeNode[],
+  usefulProps: Set<string>,
+  skipNames: Set<string>,
+  nativeDuplicates: Set<string>,
+): void {
+  if (!fiber) return;
+
+  const name = getComponentName(fiber);
+  const show = fiber.tag !== HostText && shouldShow(fiber, skipNames, nativeDuplicates);
+
+  if (show && name) {
+    const node: TreeNode = {name};
+    const props = extractProps(fiber, usefulProps);
+    if (props) node.props = props;
+    const text = getTextContent(fiber);
+    if (text) node.text = text;
+
+    const childNodes: TreeNode[] = [];
+    walkFiber(fiber.child, childNodes, usefulProps, skipNames, nativeDuplicates);
+    if (childNodes.length > 0) node.children = childNodes;
+
+    collect.push(node);
+  } else {
+    walkFiber(fiber.child, collect, usefulProps, skipNames, nativeDuplicates);
+  }
+
+  walkFiber(fiber.sibling, collect, usefulProps, skipNames, nativeDuplicates);
+}
+
+export function captureTree(
+  ref: any,
+  usefulProps: Set<string> = DEFAULT_USEFUL_PROPS,
+  skipNames: Set<string> = DEFAULT_SKIP_NAMES,
+  nativeDuplicates: Set<string> = DEFAULT_NATIVE_DUPLICATES,
+): string {
+  const fiber = findFiberFromRef(ref);
+  if (!fiber) return '[]';
+
+  const tree: TreeNode[] = [];
+  walkFiber(fiber.child, tree, usefulProps, skipNames, nativeDuplicates);
+
+  return JSON.stringify(tree);
+}
+
+export interface DebugTreeProps {
+  children: React.ReactNode;
+  /** Props to include in tree output. Defaults to testID, accessibilityLabel, etc. */
+  usefulProps?: string[];
+  /** Component names to skip (internal wrappers that add noise). */
+  skipNames?: string[];
+  /** Native component names that duplicate their parent (e.g. RCTText inside Text). */
+  nativeDuplicates?: string[];
+}
+
+/**
+ * Debug component that captures the React component tree on demand.
+ * Wrap your test content with this. Trigger via Detox:
+ *
+ *   await element(by.id('debug-tree-control')).replaceText('dump');
+ *   const attrs = await element(by.id('debug-tree-output')).getAttributes();
+ */
+export function DebugTree({children, usefulProps, skipNames, nativeDuplicates}: DebugTreeProps) {
+  const rootRef = useRef<View>(null);
+  const [tree, setTree] = useState('');
+
+  const usefulPropsSet = usefulProps ? new Set(usefulProps) : DEFAULT_USEFUL_PROPS;
+  const skipNamesSet = skipNames ? new Set(skipNames) : DEFAULT_SKIP_NAMES;
+  const nativeDuplicatesSet = nativeDuplicates
+    ? new Set(nativeDuplicates)
+    : DEFAULT_NATIVE_DUPLICATES;
+
+  const handleCommand = useCallback(
+    (text: string) => {
+      if (text === 'dump' && rootRef.current) {
+        const result = captureTree(
+          rootRef.current,
+          usefulPropsSet,
+          skipNamesSet,
+          nativeDuplicatesSet,
+        );
+        setTree(result);
+      }
+    },
+    [usefulPropsSet, skipNamesSet, nativeDuplicatesSet],
+  );
+
+  return (
+    <>
+      <TextInput testID="debug-tree-control" onChangeText={handleCommand} style={{height: 1}} />
+      <View ref={rootRef} style={{flex: 1}} collapsable={false}>
+        {children}
+      </View>
+      {tree ? (
+        <Text testID="debug-tree-output" style={{height: 1}}>
+          {tree}
+        </Text>
+      ) : null}
+    </>
+  );
+}

package/src/configureHarness.ts

@@ -1,4 +1,5 @@
-import { ComponentType, ReactNode } from 'react';
+import {ComponentType, ReactNode} from 'react';
+import {DebugTreeProps} from './DebugTree';
 
 export interface WrapperProps {
   children: ReactNode;
@@ -6,17 +7,30 @@ export interface WrapperProps {
 }
 
 export interface HarnessConfig {
-  wrapper: ComponentType<WrapperProps>;
+  wrapper?: ComponentType<WrapperProps>;
+  debugTree?: boolean | Omit<DebugTreeProps, 'children'>;
 }
 
-const DefaultWrapper = ({ children }: WrapperProps) => children;
+const DefaultWrapper = ({children}: WrapperProps) => children;
 
 let globalWrapper: ComponentType<WrapperProps> | null = null;
+let globalDebugTree: boolean | Omit<DebugTreeProps, 'children'> | null = null;
 
 export function configureHarness(config: HarnessConfig): void {
-  globalWrapper = config.wrapper;
+  if (config.wrapper) {
+    globalWrapper = config.wrapper;
+  }
+  if (config.debugTree !== undefined) {
+    globalDebugTree = config.debugTree;
+  }
 }
 
 export function getWrapper(): ComponentType<WrapperProps> {
   return globalWrapper || DefaultWrapper;
 }
+
+export function getDebugTreeConfig(): Omit<DebugTreeProps, 'children'> | null {
+  if (!globalDebugTree) return null;
+  if (globalDebugTree === true) return {};
+  return globalDebugTree;
+}

package/src/debug.ts

@@ -0,0 +1,48 @@
+import {mkdirSync, renameSync, writeFileSync} from 'fs';
+import {join} from 'path';
+
+/**
+ * Capture a screenshot, React component tree, and native view hierarchy.
+ * Drop this anywhere in a test to inspect the current screen state.
+ *
+ * Usage:
+ *   import { debug } from '@nyby/detox-component-testing/test';
+ *   await debug();              // artifacts/debug-1.png, debug-1-tree.json, debug-1-view.xml
+ *   await debug('after-tap');   // artifacts/debug-after-tap.png, etc.
+ */
+let counter = 0;
+
+export async function debug(label?: string, outputDir?: string) {
+  const name = label || String(++counter);
+  const dir = outputDir || join(process.cwd(), 'artifacts');
+  mkdirSync(dir, {recursive: true});
+
+  const screenshotPath = join(dir, `debug-${name}.png`);
+  const treePath = join(dir, `debug-${name}-tree.json`);
+  const viewPath = join(dir, `debug-${name}-view.xml`);
+
+  // Screenshot via Detox, then move to our artifacts dir
+  try {
+    const tempPath = await device.takeScreenshot(`debug-${name}`);
+    if (tempPath) {
+      renameSync(tempPath, screenshotPath);
+    }
+  } catch {}
+
+  // React component tree via DebugTree harness
+  try {
+    await element(by.id('debug-tree-control')).replaceText('dump');
+    await waitFor(element(by.id('debug-tree-output')))
+      .toExist()
+      .withTimeout(3000);
+    const attrs = await element(by.id('debug-tree-output')).getAttributes();
+    const tree = (attrs as any).text || (attrs as any).label || '[]';
+    writeFileSync(treePath, tree, 'utf8');
+  } catch {}
+
+  // Native view hierarchy
+  try {
+    const xml = await device.generateViewHierarchyXml();
+    writeFileSync(viewPath, xml, 'utf8');
+  } catch {}
+}

package/src/detox-env.d.ts

@@ -1,6 +1,10 @@
 // Ambient declarations for Detox globals injected by the test runner at runtime.
-declare const device: { launchApp(config?: any): Promise<void> };
+declare const device: {
+  launchApp(config?: any): Promise<void>;
+  takeScreenshot(name: string): Promise<string>;
+  generateViewHierarchyXml(): Promise<string>;
+};
 declare function element(matcher: any): any;
-declare const by: { id(id: string): any };
+declare const by: {id(id: string): any};
 declare function waitFor(e: any): any;
 declare function expect(e: any): any;

package/src/environment.js

@@ -0,0 +1,47 @@
+const DetoxCircusEnvironment = require('detox/runners/jest/testEnvironment');
+const {mkdirSync, writeFileSync} = require('fs');
+const {join} = require('path');
+
+class CustomDetoxEnvironment extends DetoxCircusEnvironment {
+  async handleTestEvent(event, state) {
+    await super.handleTestEvent(event, state);
+
+    if (event.name === 'test_done' && event.test.errors.length > 0) {
+      await this._dumpDebugInfo(event.test);
+    }
+  }
+
+  async _dumpDebugInfo(test) {
+    const outputDir = join(process.cwd(), 'artifacts');
+    const safeName = test.name.replace(/[^a-zA-Z0-9_-]/g, '_');
+
+    mkdirSync(outputDir, {recursive: true});
+
+    // Screenshot (saved by Detox into its own artifacts folder)
+    try {
+      await this.global.device.takeScreenshot(`debug-${safeName}`);
+    } catch (_e) {}
+
+    // Component tree via DebugTree
+    try {
+      const {element, by, waitFor} = this.global;
+
+      await element(by.id('debug-tree-control')).replaceText('dump');
+      await waitFor(element(by.id('debug-tree-output')))
+        .toExist()
+        .withTimeout(3000);
+
+      const attrs = await element(by.id('debug-tree-output')).getAttributes();
+      const tree = attrs.text || attrs.label || '[]';
+      writeFileSync(join(outputDir, `componenttree-${safeName}.json`), tree, 'utf8');
+    } catch (_e) {}
+
+    // Native view hierarchy
+    try {
+      const xml = await this.global.device.generateViewHierarchyXml();
+      writeFileSync(join(outputDir, `viewhierarchy-${safeName}.xml`), xml, 'utf8');
+    } catch (_e) {}
+  }
+}
+
+module.exports = CustomDetoxEnvironment;

package/src/index.ts

@@ -1,3 +1,4 @@
-export { registerComponent, getComponent, getAll, ComponentEntry } from './ComponentRegistry';
-export { ComponentHarness } from './ComponentHarness';
-export { configureHarness, WrapperProps, HarnessConfig } from './configureHarness';
+export {registerComponent} from './ComponentRegistry';
+export {ComponentHarness} from './ComponentHarness';
+export {configureHarness, WrapperProps, HarnessConfig} from './configureHarness';
+export {DebugTree, DebugTreeProps} from './DebugTree';