@nyby/detox-component-testing 1.5.0 → 1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nyby/detox-component-testing",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Component testing support for Detox and React Native",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -42,10 +42,10 @@
     "react-native-launch-arguments": "*"
   },
   "devDependencies": {
+    "@types/node": "^25.5.0",
     "@types/react": "^19.2.14",
     "@types/react-native": "^0.72.8",
     "prettier": "^3.8.1",
     "typescript": "^5.9.3"
-  },
-  "packageManager": "yarn@1.22.22+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e"
+  }
 }

package/src/ComponentHarness.tsx

@@ -1,26 +1,36 @@
-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';
+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";
 
 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>
       );
     }
@@ -28,8 +38,8 @@ class RenderErrorBoundary extends ReactComponent<{children: ReactNode}, ErrorBou
   }
 }
 
-const PROP_PREFIX = 'detoxProp_';
-const SPY_PREFIX = 'detoxSpy_';
+const PROP_PREFIX = "detoxProp_";
+const SPY_PREFIX = "detoxSpy_";
 
 interface MountPayload {
   id: string;
@@ -51,14 +61,14 @@ function parseLaunchArgs(args: 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((e: {nativeEvent: {text: string}}) => {
+  const handleControl = useCallback((e: { nativeEvent: { text: string } }) => {
     try {
       setMountPayload(JSON.parse(e.nativeEvent.text));
     } catch (_e) {}
@@ -68,9 +78,9 @@ export function ComponentHarness() {
   if (mountPayload) {
     activeMount = mountPayload;
   } else if (launchArgs.detoxComponentName) {
-    const {props, spies} = parseLaunchArgs(launchArgs);
+    const { props, spies } = parseLaunchArgs(launchArgs);
     activeMount = {
-      id: '0',
+      id: "0",
       name: launchArgs.detoxComponentName as string,
       props,
       spies,
@@ -78,12 +88,12 @@ export function ComponentHarness() {
   }
 
   return (
-    <View style={{flex: 1}}>
+    <View style={{ flex: 1 }}>
       <TextInput
         testID="detox-harness-control"
         onEndEditing={handleControl}
         style={{
-          position: 'absolute',
+          position: "absolute",
           bottom: 0,
           left: 0,
           right: 0,
@@ -94,7 +104,7 @@ export function ComponentHarness() {
       />
       {activeMount && (
         <>
-          <Text testID="detox-mount-id" style={{height: 1}}>
+          <Text testID="detox-mount-id" style={{ height: 1 }}>
             {activeMount.id}
           </Text>
           <RenderErrorBoundary>
@@ -111,13 +121,13 @@ 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: []};
+    initialData[name] = { count: 0, lastArgs: [] };
   });
 
   const [spyData, setSpyData] = useState(initialData);
@@ -139,25 +149,24 @@ 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 || {}}>
-      {debugTreeConfig ? <DebugTree {...debugTreeConfig}>{content}</DebugTree> : 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>
     </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,13 +12,16 @@ 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>,
   defaultProps?: Partial<P>,
 ): void {
-  if (typeof nameOrComponent === 'string') {
+  if (typeof nameOrComponent === "string") {
     registry.set(nameOrComponent, {
       Component: componentOrProps as ComponentType<P>,
       defaultProps: (defaultProps || {}) as Partial<P>,
@@ -28,7 +31,7 @@ export function registerComponent<P>(
     const name = Component.displayName || Component.name;
     if (!name) {
       throw new Error(
-        '[detox-component-testing] Component must have a name or displayName to register without an explicit name.',
+        "[detox-component-testing] Component must have a name or displayName to register without an explicit name.",
       );
     }
     registry.set(name, {

package/src/configureHarness.ts

@@ -1,5 +1,4 @@
-import {ComponentType, ReactNode} from 'react';
-import {DebugTreeProps} from './DebugTree';
+import { ComponentType, ReactNode } from "react";
 
 export interface WrapperProps {
   children: ReactNode;
@@ -8,29 +7,18 @@ export interface WrapperProps {
 
 export interface HarnessConfig {
   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 {
   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

@@ -1,48 +1,48 @@
-import {mkdirSync, renameSync, writeFileSync} from 'fs';
-import {join} from 'path';
+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.
+ * Capture a screenshot and native view hierarchy to the given directory.
+ * Used by both the `debug()` helper and the custom test environment.
  */
-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`);
+export async function captureArtifacts(
+  name: string,
+  outputDir: string,
+  deviceRef: {
+    takeScreenshot: (n: string) => Promise<string>;
+    generateViewHierarchyXml: () => Promise<string>;
+  },
+) {
+  mkdirSync(outputDir, { recursive: true });
 
   // Screenshot via Detox, then move to our artifacts dir
   try {
-    const tempPath = await device.takeScreenshot(`debug-${name}`);
+    const tempPath = await deviceRef.takeScreenshot(`debug-${name}`);
     if (tempPath) {
-      renameSync(tempPath, screenshotPath);
+      renameSync(tempPath, join(outputDir, `debug-${name}.png`));
     }
   } 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');
+    const xml = await deviceRef.generateViewHierarchyXml();
+    writeFileSync(join(outputDir, `debug-${name}-view.xml`), xml, "utf8");
   } catch {}
 }
+
+/**
+ * Capture a screenshot 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-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");
+  await captureArtifacts(name, dir, device);
+}

package/src/detox-env.d.ts

@@ -5,6 +5,6 @@ declare const device: {
   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

@@ -1,47 +1,17 @@
-const DetoxCircusEnvironment = require('detox/runners/jest/testEnvironment');
-const {mkdirSync, writeFileSync} = require('fs');
-const {join} = require('path');
+const DetoxCircusEnvironment = require("detox/runners/jest/testEnvironment");
+const { join } = require("path");
+const { captureArtifacts } = require("./debug");
 
 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);
+    if (event.name === "test_done" && event.test.errors.length > 0) {
+      const safeName = event.test.name.replace(/[^a-zA-Z0-9_-]/g, "_");
+      const outputDir = join(process.cwd(), "artifacts");
+      await captureArtifacts(safeName, outputDir, this.global.device);
     }
   }
-
-  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,4 +1,7 @@
-export {registerComponent} from './ComponentRegistry';
-export {ComponentHarness} from './ComponentHarness';
-export {configureHarness, WrapperProps, HarnessConfig} from './configureHarness';
-export {DebugTree, DebugTreeProps} from './DebugTree';
+export { registerComponent } from "./ComponentRegistry";
+export { ComponentHarness } from "./ComponentHarness";
+export {
+  configureHarness,
+  WrapperProps,
+  HarnessConfig,
+} from "./configureHarness";

package/src/mount.ts

@@ -9,32 +9,37 @@ export interface SpyExpectation {
   lastCalledWith(...args: any[]): Promise<void>;
 }
 
-const SPY_MARKER = '__detoxSpy__' as const;
+const SPY_MARKER = "__detoxSpy__" as const;
 
 let mountCounter = 0;
 let appLaunched = false;
 
 export function spy(name: string): SpyMarker {
-  return {[SPY_MARKER]: true, name};
+  return { [SPY_MARKER]: true, name };
 }
 
 type MountProps = Record<string, string | number | boolean | SpyMarker>;
 
-export async function assertNoRenderError(): Promise<void> {
+async function assertNoRenderError(): Promise<void> {
   try {
-    await waitFor(element(by.id('detox-render-error')))
+    await waitFor(element(by.id("detox-render-error")))
       .toExist()
       .withTimeout(500);
   } catch {
     return; // Element not found — no render error, all good
   }
   // Element exists — read the error message and throw
-  const attrs = (await element(by.id('detox-render-error-message')).getAttributes()) as any;
-  const message = attrs.text || attrs.label || 'Unknown render error';
+  const attrs = (await element(
+    by.id("detox-render-error-message"),
+  ).getAttributes()) as any;
+  const message = attrs.text || attrs.label || "Unknown render error";
   throw new Error(`Component render error: ${message}`);
 }
 
-export async function mount(componentName: string, props?: MountProps): Promise<void> {
+export async function mount(
+  componentName: string,
+  props?: MountProps,
+): Promise<void> {
   const payload = {
     id: String(++mountCounter),
     name: componentName,
@@ -44,7 +49,7 @@ export async function mount(componentName: string, props?: MountProps): Promise<
 
   if (props) {
     Object.entries(props).forEach(([key, value]) => {
-      if (value && typeof value === 'object' && SPY_MARKER in value) {
+      if (value && typeof value === "object" && SPY_MARKER in value) {
         payload.spies.push(key);
       } else {
         payload.props[key] = value;
@@ -52,19 +57,19 @@ export async function mount(componentName: string, props?: MountProps): Promise<
     });
   }
 
-  const launchArgs: Record<string, any> = {detoxComponentName: componentName};
+  const launchArgs: Record<string, any> = { detoxComponentName: componentName };
   Object.entries(payload.props).forEach(([key, value]) => {
     launchArgs[`detoxProp_${key}`] = value;
   });
   payload.spies.forEach((name) => {
     launchArgs[`detoxSpy_${name}`] = true;
   });
-  await device.launchApp({newInstance: true, launchArgs});
+  await device.launchApp({ newInstance: true, launchArgs });
   appLaunched = true;
   // Harness sets id '0' for the initial launch-args mount
   try {
-    await waitFor(element(by.id('detox-mount-id')))
-      .toHaveText('0')
+    await waitFor(element(by.id("detox-mount-id")))
+      .toHaveText("0")
       .withTimeout(5000);
   } catch (e) {
     await assertNoRenderError(); // Throws with the actual error if one exists
@@ -79,13 +84,19 @@ export function expectSpy(name: string): SpyExpectation {
   const getExpect = () => expect as unknown as (e: any) => any;
   return {
     async toHaveBeenCalled() {
-      await getExpect()(element(by.id(`spy-${name}-count`))).not.toHaveText('0');
+      await getExpect()(element(by.id(`spy-${name}-count`))).not.toHaveText(
+        "0",
+      );
     },
     async toHaveBeenCalledTimes(n: number) {
-      await getExpect()(element(by.id(`spy-${name}-count`))).toHaveText(String(n));
+      await getExpect()(element(by.id(`spy-${name}-count`))).toHaveText(
+        String(n),
+      );
     },
     async lastCalledWith(...args: any[]) {
-      await getExpect()(element(by.id(`spy-${name}-lastArgs`))).toHaveText(JSON.stringify(args));
+      await getExpect()(element(by.id(`spy-${name}-lastArgs`))).toHaveText(
+        JSON.stringify(args),
+      );
     },
   };
 }

package/src/test.ts

@@ -1,2 +1,2 @@
-export {mount, spy, expectSpy} from './mount';
-export {debug} from './debug';
+export { mount, spy, expectSpy } from "./mount";
+export { debug } from "./debug";

package/dist/DebugTree.d.ts

@@ -1,20 +0,0 @@
-import React from 'react';
-export declare function captureTree(ref: any, usefulProps?: Set<string>, skipNames?: Set<string>, nativeDuplicates?: Set<string>): string;
-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 declare function DebugTree({ children, usefulProps, skipNames, nativeDuplicates }: DebugTreeProps): React.JSX.Element;
-//# sourceMappingURL=DebugTree.d.ts.map

package/dist/DebugTree.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"DebugTree.d.ts","sourceRoot":"","sources":["../src/DebugTree.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAsC,MAAM,OAAO,CAAC;AAiN3D,wBAAgB,WAAW,CACzB,GAAG,EAAE,GAAG,EACR,WAAW,GAAE,GAAG,CAAC,MAAM,CAAwB,EAC/C,SAAS,GAAE,GAAG,CAAC,MAAM,CAAsB,EAC3C,gBAAgB,GAAE,GAAG,CAAC,MAAM,CAA6B,GACxD,MAAM,CAQR;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,oFAAoF;IACpF,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,qFAAqF;IACrF,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,EAAC,QAAQ,EAAE,WAAW,EAAE,SAAS,EAAE,gBAAgB,EAAC,EAAE,cAAc,qBAsC7F"}