CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-detox

Gray box end-to-end testing and automation framework for mobile applications with advanced synchronization capabilities

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

Detox

Detox is a comprehensive gray box end-to-end testing and automation framework specifically designed for mobile applications, particularly React Native apps on both Android and iOS platforms. It enables developers to write JavaScript-based E2E tests that run on real devices and simulators, providing automated user interaction simulation with advanced synchronization capabilities that eliminate test flakiness by monitoring asynchronous operations.

Package Information

  • Package Name: detox
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install detox

Core Imports

const detox = require('detox');
// Global exports when initialized:
// device, element, by, expect, waitFor, web, system, pilot

ES6 imports:

import detox from 'detox';
// Global exports when initialized:
// device, element, by, expect, waitFor, web, system, pilot

TypeScript:

import detox from 'detox';
import type { Device, ElementFacade, ByFacade } from 'detox';

Basic Usage

const detox = require('detox');

describe('Example Test Suite', () => {
  beforeAll(async () => {
    await detox.init();
  });

  beforeEach(async () => {
    await device.launchApp();
  });

  afterAll(async () => {
    await detox.cleanup();
  });

  it('should have welcome screen', async () => {
    await expect(element(by.text('Welcome'))).toBeVisible();
  });

  it('should show hello screen after tap', async () => {
    await element(by.id('hello_button')).tap();
    await expect(element(by.text('Hello!!!'))).toBeVisible();
  });
});

Main Detox Object

Core Detox initialization and lifecycle management.

const detox: {
  init(config?: DetoxInitOptions): Promise<void>;
  cleanup(): Promise<void>;
  installWorker(options?: DetoxInstallWorkerOptions): Promise<void>;
  uninstallWorker(): Promise<void>;
}

interface DetoxInitOptions {
  configPath?: string;
  override?: Partial<DetoxConfig>;
  workerId?: string;
}

interface DetoxInstallWorkerOptions {
  workerId?: string;
  global?: any;
}

Architecture

Detox is built around several key components:

  • Device Control: Comprehensive device management including app lifecycle, permissions, and hardware simulation
  • Element Interaction: Type-safe element selection, interaction, and assertion system with automatic synchronization
  • Multi-Platform Support: Unified API for both iOS (Simulator/Device) and Android (Emulator/Device) testing
  • Synchronization Engine: Advanced idle/busy monitoring that eliminates test flakiness by waiting for app operations
  • Web View Support: Complete testing capabilities for hybrid apps with web content
  • AI Automation: Pilot system for natural language test automation and debugging

Capabilities

Device Management

Comprehensive device control including app lifecycle management, hardware simulation, permissions, and platform-specific features.

const device: {
  id: string;
  name: string;
  appLaunchArgs: AppLaunchArgs;
  launchApp(config?: DeviceLaunchAppConfig): Promise<void>;
  terminateApp(bundle?: string): Promise<void>;
  getPlatform(): 'ios' | 'android';
  takeScreenshot(name: string): Promise<string>;
}

Device Management

Element Interaction

Type-safe element selection, interaction, and assertion system with automatic synchronization and comprehensive action support.

function element(matcher: NativeMatcher): IndexableNativeElement;

interface IndexableNativeElement {
  atIndex(index: number): NativeElement;
  tap(point?: Point2D): Promise<void>;
  typeText(text: string): Promise<void>;
  swipe(direction: Direction, speed?: Speed): Promise<void>;
}

Element Interaction

Element Selection

Flexible and powerful element selection system supporting multiple matcher types and combination strategies.

const by: {
  id(id: string | RegExp): NativeMatcher;
  text(text: string | RegExp): NativeMatcher;
  label(label: string | RegExp): NativeMatcher;
  type(nativeViewType: string): NativeMatcher;
}

Element Selection

Assertions

Comprehensive assertion system for validating element states, properties, and behaviors with detailed error reporting.

function expect(element: NativeElement): Expect;

interface Expect {
  toBeVisible(pct?: number): Promise<void>;
  toExist(): Promise<void>;
  toHaveText(text: string): Promise<void>;
  toHaveValue(value: any): Promise<void>;
  not: Expect;
}

Assertions

Synchronization

Advanced waiting and synchronization utilities for handling asynchronous operations and ensuring test stability.

function waitFor(element: NativeElement): Expect<WaitFor>;

interface WaitFor {
  withTimeout(millis: number): Promise<void>;
  whileElement(matcher: NativeMatcher): NativeElementWaitableActions & WaitFor;
}

Synchronization

Web View Testing

Complete testing capabilities for hybrid applications with web view content, supporting both regular and secured web elements.

function web(matcher?: NativeMatcher): WebViewElement;

interface WebViewElement {
  element(webMatcher: WebMatcher): WebElement;
  atIndex(index: number): WebViewElement;
}

Web View Testing

Configuration

Comprehensive configuration system supporting multiple apps, devices, test runners, and extensive customization options.

interface DetoxConfig {
  apps?: Record<string, DetoxAppConfig>;
  devices?: Record<string, DetoxDeviceConfig>;
  configurations: Record<string, DetoxConfiguration>;
  artifacts?: DetoxArtifactsConfig;
  behavior?: DetoxBehaviorConfig;
}

Configuration

System-Level Interactions

Handle system-level UI elements like permission dialogs, system alerts, and OS-specific controls outside the app context.

const system: {
  element(systemMatcher: SystemMatcher): IndexableSystemElement;
}

interface SystemMatcher {
  __system__: any;
}

interface IndexableSystemElement extends SystemElement {
  atIndex(index: number): SystemElement;
}

interface SystemElement {
  tap(): Promise<void>;
}

System matchers available via by.system.label(text) and by.system.type(type).

AI-Powered Automation

Natural language test automation and debugging capabilities through the Pilot system.

const pilot: {
  init(promptHandler: PromptHandler): void;
  perform: Function;
  autopilot: Function;
  extendAPICatalog: Function;
  setDefaults(defaults: Partial<PilotConfig>): void;
}

// Deprecated alias for pilot
const copilot: typeof pilot;

type PromptHandler = (prompt: string) => Promise<string>;

Constants and Utilities

Global constants, logging, and utility functions available throughout the testing session.

const DetoxConstants: {
  userNotificationTriggers: {
    push: 'push';
    calendar: 'calendar';
    timeInterval: 'timeInterval';
    location: 'location';
  };
  userActivityTypes: {
    searchableItem: string;
    browsingWeb: string;
  };
  searchableItemActivityIdentifier: string;
}

const log: Logger;

interface Logger {
  level: DetoxLogLevel;
  fatal: LogMethod;
  error: LogMethod;
  warn: LogMethod;
  info: LogMethod;
  debug: LogMethod;
  trace: LogMethod;
  child(context?: Partial<LogEvent>): Logger;
}

interface LogMethod {
  (...args: unknown[]): void;
  (event: LogEvent, ...args: unknown[]): void;
  begin: LogMethod;
  complete: <T>(message: string, action: T | (() => T)) => T;
  end: LogMethod;
}

type DetoxLogLevel = 'fatal' | 'error' | 'warn' | 'info' | 'debug' | 'trace';

interface LogEvent {
  id?: string | number;
  cat?: string | string[];
  cname?: string;
  [customProperty: string]: unknown;
}

// Interactive REPL mode for debugging
function REPL(context?: object): Promise<void>;

// Deprecated tracing utilities
const trace: {
  startSection: (name: string) => void;
  endSection: (name: string) => void;
};

function traceCall<T>(event: string, action: () => Promise<T>, args?: Record<string, unknown>): Promise<T>;

Command Line Interface

The detox CLI provides commands for app building, testing, and project management.

# Build app for testing
detox build

# Run tests
detox test

# Start development server
detox start

# Initialize Detox configuration
detox init

# Clean framework cache
detox clean-framework-cache

# Build framework cache
detox build-framework-cache

# Rebuild framework cache
detox rebuild-framework-cache

# Reset device lock file
detox reset-lock-file

# Run Detox server
detox run-server

Global Types

interface Point2D {
  x: number;
  y: number;
}

type Direction = 'left' | 'right' | 'top' | 'bottom' | 'up' | 'down';
type Orientation = 'portrait' | 'landscape';
type Speed = 'fast' | 'slow';

interface AppLaunchArgs {
  shared: ScopedAppLaunchArgs;
  modify(modifier: object): this;
  reset(): this;
  get(): object;
}

interface DeviceLaunchAppConfig {
  newInstance?: boolean;
  permissions?: DevicePermissions;
  url?: string;
  delete?: boolean;
  launchArgs?: Record<string, any>;
}

interface ScopedAppLaunchArgs {
  modify(modifier: object): this;
  reset(): this;
  get(): object;
}

// Platform-specific types
type PinchDirection = 'outward' | 'inward';

// Element matcher interfaces
interface NativeMatcher {
  and(matcher: NativeMatcher): NativeMatcher;
  withAncestor(parentMatcher: NativeMatcher): NativeMatcher;
  withDescendant(childMatcher: NativeMatcher): NativeMatcher;
}

interface WebMatcher {
  __web__: any;
}

interface SystemMatcher {
  __system__: any;
}

// Element interfaces
interface NativeElement {
  // All interaction methods as documented in element-interaction.md
}

interface WebElement {
  // All web interaction methods as documented in web-view-testing.md
}

interface SystemElement {
  tap(): Promise<void>;
}

Install with Tessl CLI

npx tessl i tessl/npm-detox
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/detox@20.41.x
Publish Source
CLI
Badge
tessl/npm-detox badge