@nyby/detox-component-testing 1.0.0

package/README.md

@@ -0,0 +1,250 @@
+# @nyby/detox-component-testing
+
+Component testing for React Native with [Detox](https://github.com/wix/Detox). Mount individual components in isolation on a real device or emulator and test them with the full Detox API.
+
+## How It Works
+
+Unlike Cypress (where tests and components share the same browser runtime), Detox tests run in **Node.js** while components render on a **device/emulator**. The two communicate over WebSocket.
+
+```
+Test (Node.js/Jest)                    App (React Native on device)
+───────────────────                    ────────────────────────────
+mount('Stepper', { initial: 5 })  →   renders <Stepper initial={5} />
+element(by.id('increment')).tap() →   taps the native button
+expect(...).toHaveText('6')       →   asserts on the native view tree
+```
+
+This means test files **cannot** import React components or use JSX — they can only send serializable data (strings, numbers, booleans) to the device. The `mount()` function references components by the name they were registered with.
+
+## Setup
+
+### 1. Install dependencies
+
+```bash
+npm install @nyby/detox-component-testing react-native-launch-arguments
+```
+
+`react-native-launch-arguments` is a native module — rebuild your app after installing.
+
+### 2. Create a component test entry point
+
+Create `app.component-test.js` alongside your app entry:
+
+```js
+import { AppRegistry } from 'react-native';
+import { ComponentHarness } from '@nyby/detox-component-testing';
+import './component-tests/registry';
+
+AppRegistry.registerComponent('example', () => ComponentHarness);
+```
+
+### 3. Register your components
+
+Create `component-tests/registry.ts` to register components for testing:
+
+```ts
+import { registerComponent } from '@nyby/detox-component-testing';
+import { Stepper } from '../src/components/Stepper';
+import { LoginForm } from '../src/components/LoginForm';
+
+// Auto-infer name from Component.name
+registerComponent(Stepper, { initial: 0 });
+registerComponent(LoginForm);
+
+// Or use an explicit name
+registerComponent('MyComponent', MyComponent, { someProp: 'default' });
+```
+
+### 4. Switch entry point for component tests
+
+Update your index file to load the component test entry when running component tests:
+
+```js
+// index.js
+const { LaunchArguments } = require('react-native-launch-arguments');
+
+if (LaunchArguments.value().detoxComponentName) {
+  require('./app.component-test');
+} else {
+  require('./app');
+}
+```
+
+This keeps your production app clean — the harness and test components are only loaded during component testing.
+
+### 5. Configure Detox
+
+Add a component test configuration to `detox.config.js`:
+
+```js
+module.exports = {
+  // ... existing config
+  configurations: {
+    // ... existing configurations
+    "android.emu.component.debug": {
+      device: "emulator",
+      app: "android.debug",
+      testRunner: {
+        args: {
+          config: "component-tests/jest.config.js",
+          _: ["src/components"]
+        }
+      }
+    }
+  }
+};
+```
+
+### 6. Create Jest config for component tests
+
+Create `component-tests/jest.config.js`:
+
+```js
+module.exports = {
+  maxWorkers: 1,
+  globalSetup: "detox/runners/jest/globalSetup",
+  globalTeardown: "detox/runners/jest/globalTeardown",
+  testEnvironment: "detox/runners/jest/testEnvironment",
+  setupFilesAfterEnv: ["./setup.ts"],
+  testRunner: "jest-circus/runner",
+  testTimeout: 120000,
+  roots: ["<rootDir>/../src"],
+  testMatch: ["**/*.component.test.ts"],
+  transform: {
+    "\\.tsx?$": ["ts-jest", { tsconfig: "<rootDir>/../tsconfig.json" }]
+  },
+  reporters: ["detox/runners/jest/reporter"],
+  verbose: true
+};
+```
+
+## Writing Tests
+
+### Basic mounting
+
+```ts
+import { by, element, expect } from 'detox';
+import { mount } from '@nyby/detox-component-testing/test';
+
+describe('Stepper', () => {
+  it('renders with default props', async () => {
+    await mount('Stepper');
+    await expect(element(by.id('counter'))).toHaveText('0');
+  });
+
+  it('renders with custom props', async () => {
+    await mount('Stepper', { initial: 100 });
+    await expect(element(by.id('counter'))).toHaveText('100');
+  });
+});
+```
+
+### Testing callbacks with spies
+
+Use `spy()` to create a recording function for callback props, and `expectSpy()` to assert on it:
+
+```ts
+import { mount, spy, expectSpy } from '@nyby/detox-component-testing/test';
+
+it('fires onChange when incremented', async () => {
+  await mount('Stepper', { initial: 0, onChange: spy('onChange') });
+  await element(by.id('increment')).tap();
+
+  await expectSpy('onChange').toHaveBeenCalled();
+  await expectSpy('onChange').toHaveBeenCalledTimes(1);
+  await expectSpy('onChange').lastCalledWith(1);
+});
+```
+
+The spy system works across the process boundary — the app-side harness creates a real recording function and exposes call data via hidden UI elements that `expectSpy()` reads.
+
+### Performance
+
+The first `mount()` call per test file launches the app (~9s). Subsequent mounts within the same file swap the component in-place without restarting — typically under 100ms.
+
+```
+First mount:      ~9s  (app launch)
+Subsequent mounts: ~100ms (in-place swap)
+```
+
+## API Reference
+
+### App-side (import from `@nyby/detox-component-testing`)
+
+#### `registerComponent(Component, defaultProps?)`
+#### `registerComponent(name, Component, defaultProps?)`
+
+Register a component for testing. When called with just a component, the name is inferred from `Component.name` or `Component.displayName`.
+
+#### `ComponentHarness`
+
+Root component for the test harness. Register as your app's root component in the component test entry point.
+
+#### `configureHarness({ wrapper })`
+
+Set a global wrapper component for all mounted components (e.g. Redux Provider, theme provider):
+
+```js
+import { Provider } from 'react-redux';
+import { configureHarness } from '@nyby/detox-component-testing';
+import { createStore } from './store';
+
+configureHarness({
+  wrapper: ({ children, launchArgs }) => {
+    const store = createStore();
+    if (launchArgs.reduxState) {
+      store.dispatch(loadState(JSON.parse(launchArgs.reduxState)));
+    }
+    return <Provider store={store}>{children}</Provider>;
+  },
+});
+```
+
+The wrapper receives `launchArgs` — the props passed to `mount()` — so you can configure per-test state.
+
+### Test-side (import from `@nyby/detox-component-testing/test`)
+
+#### `mount(componentName, props?)`
+
+Mount a registered component on the device. Props are passed as flat key-value pairs (strings, numbers, booleans). Use `spy()` for callback props.
+
+#### `spy(name)`
+
+Create a spy marker for a callback prop. The harness replaces this with a recording function on the app side.
+
+#### `expectSpy(name)`
+
+Returns an assertion object for a spy:
+
+- `.toHaveBeenCalled()` — spy was called at least once
+- `.toHaveBeenCalledTimes(n)` — spy was called exactly `n` times
+- `.lastCalledWith(...args)` — the last call's arguments match
+
+## Limitations
+
+- **No JSX in tests** — Tests run in Node.js, not the React Native runtime. You cannot import components or use JSX in test files. Reference components by their registered name string.
+- **Flat props only** — Props passed through `mount()` must be serializable (strings, numbers, booleans). Nested objects and arrays are not supported. Use `configureHarness({ wrapper })` for complex state like Redux stores.
+- **Callbacks are spies, not real functions** — You can't pass arbitrary callback implementations. Use `spy()` to record calls and assert on them with `expectSpy()`.
+
+## Project Structure
+
+A typical project using `@nyby/detox-component-testing`:
+
+```
+src/
+  components/
+    Stepper.tsx                    # Component source
+    stepper.component.test.ts      # Component test (co-located)
+    LoginForm.tsx
+    loginForm.component.test.ts
+
+component-tests/
+  registry.ts                      # Component registrations
+  jest.config.js                   # Jest config for component tests
+  setup.ts                         # Test setup
+
+app.js                             # Production app entry
+app.component-test.js              # Component test entry (harness)
+index.js                           # Switches entry based on launch args
+detox.config.js                    # Detox config with component test configuration
+```

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@nyby/detox-component-testing",
+  "version": "1.0.0",
+  "description": "Component testing support for Detox and React Native",
+  "main": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./test": "./src/test.ts"
+  },
+  "peerDependencies": {
+    "react": "*",
+    "react-native": "*",
+    "react-native-launch-arguments": "*",
+    "detox": "*"
+  }
+}

package/src/ComponentHarness.tsx

@@ -0,0 +1,117 @@
+import React, { useState, useRef, useCallback } from 'react';
+import { View, Text, TextInput } from 'react-native';
+import { LaunchArguments } from 'react-native-launch-arguments';
+import { getComponent } from './ComponentRegistry';
+import { getWrapper } from './configureHarness';
+
+const PROP_PREFIX = 'detoxProp_';
+const SPY_PREFIX = 'detoxSpy_';
+
+interface MountPayload {
+  id: string;
+  name: string;
+  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]) => {
+    if (key.startsWith(PROP_PREFIX)) {
+      props[key.slice(PROP_PREFIX.length)] = value;
+    } else if (key.startsWith(SPY_PREFIX)) {
+      spies.push(key.slice(SPY_PREFIX.length));
+    }
+  });
+  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) => {
+    try {
+      setMountPayload(JSON.parse(text));
+    } catch (_e) {}
+  }, []);
+
+  let activeMount: MountPayload | null = null;
+  if (mountPayload) {
+    activeMount = mountPayload;
+  } else if (launchArgs.detoxComponentName) {
+    const { props, spies } = parseLaunchArgs(launchArgs);
+    activeMount = {
+      id: '0',
+      name: launchArgs.detoxComponentName as string,
+      props,
+      spies,
+    };
+  }
+
+  return (
+    <View style={{ flex: 1 }}>
+      <TextInput
+        testID="detox-harness-control"
+        onChangeText={handleControl}
+        style={{ height: 1 }}
+      />
+      {activeMount && (
+        <ComponentRenderer key={activeMount.id} mount={activeMount} />
+      )}
+    </View>
+  );
+}
+
+interface SpyData {
+  count: number;
+  lastArgs: any[];
+}
+
+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: [] };
+  });
+
+  const [spyData, setSpyData] = useState(initialData);
+
+  const spyFnsRef = useRef<Record<string, (...args: any[]) => void>>({});
+  const spyProps: Record<string, (...args: any[]) => void> = {};
+  spyNames.forEach(name => {
+    if (!spyFnsRef.current[name]) {
+      spyFnsRef.current[name] = (...callArgs: any[]) => {
+        setSpyData(prev => ({
+          ...prev,
+          [name]: {
+            count: (prev[name]?.count || 0) + 1,
+            lastArgs: callArgs,
+          },
+        }));
+      };
+    }
+    spyProps[name] = spyFnsRef.current[name];
+  });
+
+  const props = { ...defaultProps, ...(mount.props || {}), ...spyProps };
+  const Wrapper = getWrapper();
+
+  return (
+    <Wrapper launchArgs={mount.props || {}}>
+      <View testID="component-harness-root" style={{ flex: 1 }}>
+        <Text testID="detox-mount-id" style={{ height: 1 }}>{mount.id}</Text>
+        <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

@@ -0,0 +1,56 @@
+import { ComponentType } from 'react';
+
+export interface ComponentEntry<P = any> {
+  Component: ComponentType<P>;
+  defaultProps: Partial<P>;
+}
+
+const registry = new Map<string, ComponentEntry>();
+
+export function registerComponent<P>(
+  name: string,
+  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') {
+    registry.set(nameOrComponent, {
+      Component: componentOrProps as ComponentType<P>,
+      defaultProps: (defaultProps || {}) as Partial<P>,
+    });
+  } else {
+    const Component = nameOrComponent;
+    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.',
+      );
+    }
+    registry.set(name, {
+      Component,
+      defaultProps: ((componentOrProps as Partial<P>) || {}) as Partial<P>,
+    });
+  }
+}
+
+export function getComponent(name: string): ComponentEntry {
+  const entry = registry.get(name);
+  if (!entry) {
+    throw new Error(
+      `[detox-component-testing] Component "${name}" not found in registry. Did you call registerComponent()?`,
+    );
+  }
+  return entry;
+}
+
+export function getAll(): Record<string, ComponentEntry> {
+  return Object.fromEntries(registry);
+}

package/src/configureHarness.ts

@@ -0,0 +1,22 @@
+import { ComponentType, ReactNode } from 'react';
+
+export interface WrapperProps {
+  children: ReactNode;
+  launchArgs: Record<string, any>;
+}
+
+export interface HarnessConfig {
+  wrapper: ComponentType<WrapperProps>;
+}
+
+const DefaultWrapper = ({ children }: WrapperProps) => children;
+
+let globalWrapper: ComponentType<WrapperProps> | null = null;
+
+export function configureHarness(config: HarnessConfig): void {
+  globalWrapper = config.wrapper;
+}
+
+export function getWrapper(): ComponentType<WrapperProps> {
+  return globalWrapper || DefaultWrapper;
+}

package/src/index.ts

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

package/src/mount.ts

@@ -0,0 +1,75 @@
+export interface SpyMarker {
+  readonly __detoxSpy__: true;
+  readonly name: string;
+}
+
+export interface SpyExpectation {
+  toHaveBeenCalled(): Promise<void>;
+  toHaveBeenCalledTimes(n: number): Promise<void>;
+  lastCalledWith(...args: any[]): Promise<void>;
+}
+
+const SPY_MARKER = '__detoxSpy__' as const;
+
+let mountCounter = 0;
+let appLaunched = false;
+
+export function spy(name: string): SpyMarker {
+  return { [SPY_MARKER]: true, name };
+}
+
+type MountProps = Record<string, string | number | boolean | SpyMarker>;
+
+export async function mount(componentName: string, props?: MountProps): Promise<void> {
+
+  const payload = {
+    id: String(++mountCounter),
+    name: componentName,
+    props: {} as Record<string, any>,
+    spies: [] as string[],
+  };
+
+  if (props) {
+    Object.entries(props).forEach(([key, value]) => {
+      if (value && typeof value === 'object' && SPY_MARKER in value) {
+        payload.spies.push(key);
+      } else {
+        payload.props[key] = value;
+      }
+    });
+  }
+
+  if (!appLaunched) {
+    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 });
+    appLaunched = true;
+    return;
+  }
+
+  await element(by.id('detox-harness-control')).replaceText(JSON.stringify(payload));
+  await waitFor(element(by.id('detox-mount-id'))).toHaveText(payload.id).withTimeout(5000);
+}
+
+// Detox's expect is injected as a global by the test environment.
+// Cast to any since the library can't import 'detox' directly (peer dep).
+const detoxExpect = expect as unknown as (e: any) => any;
+
+export function expectSpy(name: string): SpyExpectation {
+  return {
+    async toHaveBeenCalled() {
+      await detoxExpect(element(by.id(`spy-${name}-count`))).not.toHaveText('0');
+    },
+    async toHaveBeenCalledTimes(n: number) {
+      await detoxExpect(element(by.id(`spy-${name}-count`))).toHaveText(String(n));
+    },
+    async lastCalledWith(...args: any[]) {
+      await detoxExpect(element(by.id(`spy-${name}-lastArgs`))).toHaveText(JSON.stringify(args));
+    },
+  };
+}

package/src/test.ts

@@ -0,0 +1 @@
+export { mount, spy, expectSpy, SpyMarker, SpyExpectation } from './mount';

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "es2018",
+    "module": "commonjs",
+    "jsx": "react",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "dist",
+    "strict": true,
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src"]
+}