or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

assertions.mdconfiguration.mddevice-management.mdelement-interaction.mdelement-selection.mdindex.mdsynchronization.mdweb-view-testing.md
tile.json

configuration.mddocs/

Configuration

Comprehensive configuration system supporting multiple apps, devices, test runners, and extensive customization options for flexible mobile testing environments across iOS and Android platforms.

Capabilities

Main Configuration Structure

Root configuration object defining all Detox settings and test environment options.

interface DetoxConfig {
  /**
   * Extend configuration from another file or preset
   * @example './base-config.js' or '@my-org/detox-preset'
   */
  extends?: string;
  
  /** Application configurations by name */
  apps?: Record<string, DetoxAppConfig>;
  
  /** Device configurations by name */
  devices?: Record<string, DetoxDeviceConfig>;
  
  /** Default configuration to use when none specified */
  selectedConfiguration?: string;
  
  /** Named test configurations combining apps and devices */
  configurations: Record<string, DetoxConfiguration>;
  
  /** Artifact collection and storage settings */
  artifacts?: DetoxArtifactsConfig;
  
  /** Test execution behavior settings */
  behavior?: DetoxBehaviorConfig;
  
  /** Logging configuration */
  logger?: DetoxLoggerConfig;
  
  /** Session and server settings */
  session?: DetoxSessionConfig;
  
  /** Test runner integration settings */
  testRunner?: DetoxTestRunnerConfig;
  
  /** Global build command (overrides app-specific build commands) */
  build?: string;
  
  /** Global start command (overrides app-specific start commands) */
  start?: string;
}

Usage Example:

// .detoxrc.js
module.exports = {
  selectedConfiguration: 'ios.sim.debug',
  configurations: {
    'ios.sim.debug': {
      device: 'simulator',
      app: 'ios.debug'
    },
    'android.emu.debug': {
      device: 'emulator',
      app: 'android.debug'
    }
  },
  apps: {
    'ios.debug': {
      type: 'ios.app',
      binaryPath: 'ios/build/Build/Products/Debug-iphonesimulator/MyApp.app',
      build: 'xcodebuild -workspace ios/MyApp.xcworkspace -scheme MyApp -configuration Debug -sdk iphonesimulator -derivedDataPath ios/build'
    },
    'android.debug': {
      type: 'android.apk',
      binaryPath: 'android/app/build/outputs/apk/debug/app-debug.apk',
      build: 'cd android && ./gradlew assembleDebug assembleAndroidTest -DtestBuildType=debug'
    }
  },
  devices: {
    simulator: {
      type: 'ios.simulator',
      device: { type: 'iPhone 14' }
    },
    emulator: {
      type: 'android.emulator',
      device: { avdName: 'Pixel_API_33' }
    }
  }
};

App Configuration

Define applications to test with platform-specific build and runtime settings.

interface DetoxAppConfig {
  /** App type identifier */
  type: 'ios.app' | 'android.apk' | string;
  
  /** Path to app binary (relative to project root) */
  binaryPath: string;
  
  /** App bundle identifier (optional, auto-detected if not specified) */
  bundleId?: string;
  
  /** App name for multi-app configurations (used with device.selectApp()) */
  name?: string;
  
  /** Build command executed by 'detox build' */
  build?: string;
  
  /** Development server start command executed by 'detox start' */
  start?: string;
  
  /** Launch arguments passed to app on startup */
  launchArgs?: Record<string, any>;
}

// iOS-specific app configuration
interface DetoxIosAppConfig extends DetoxAppConfig {
  type: 'ios.app';
  binaryPath: string; // Path to .app bundle
  bundleId?: string;  // iOS bundle ID (e.g., com.company.myapp)
  launchArgs?: Record<string, any>;
}

// Android-specific app configuration
interface DetoxAndroidAppConfig extends DetoxAppConfig {
  type: 'android.apk';
  binaryPath: string;     // Path to APK file
  bundleId?: string;      // Android package name
  testBinaryPath?: string; // Path to test APK (for instrumentation tests)
  
  /** TCP ports to reverse with adb for local development */
  reversePorts?: number[];
  
  launchArgs?: Record<string, any>;
}

Usage Examples:

// iOS app configuration
apps: {
  'ios.debug': {
    type: 'ios.app',
    binaryPath: 'ios/build/Build/Products/Debug-iphonesimulator/MyApp.app',
    bundleId: 'com.company.myapp',
    build: 'xcodebuild -workspace ios/MyApp.xcworkspace -scheme MyApp -configuration Debug -sdk iphonesimulator -derivedDataPath ios/build',
    start: 'react-native start',
    launchArgs: {
      mockServer: 'http://localhost:3000',
      debugMode: true
    }
  }
}

// Android app configuration
apps: {
  'android.debug': {
    type: 'android.apk',
    binaryPath: 'android/app/build/outputs/apk/debug/app-debug.apk',
    testBinaryPath: 'android/app/build/outputs/apk/androidTest/debug/app-debug-androidTest.apk',
    bundleId: 'com.company.myapp',
    build: 'cd android && ./gradlew assembleDebug assembleAndroidTest -DtestBuildType=debug',
    reversePorts: [8081, 3000],
    launchArgs: {
      mockApi: 'staging',
      enableLogging: 'true'
    }
  }
}

// Multi-app configuration
apps: {
  'passenger': {
    name: 'passenger',
    type: 'ios.app',
    binaryPath: 'ios/build/Passenger.app'
  },
  'driver': {
    name: 'driver', 
    type: 'ios.app',
    binaryPath: 'ios/build/Driver.app'
  }
}

Device Configuration

Define target devices and platforms for test execution.

type DetoxDeviceConfig = 
  | DetoxIosSimulatorDriverConfig
  | DetoxAndroidEmulatorDriverConfig
  | DetoxAttachedAndroidDriverConfig
  | DetoxGenymotionCloudDriverConfig
  | DetoxCustomDriverConfig;

// iOS Simulator configuration
interface DetoxIosSimulatorDriverConfig {
  type: 'ios.simulator';
  device: string | IosSimulatorQuery;
  bootArgs?: string; // Additional boot arguments
}

interface IosSimulatorQuery {
  id?: string;    // Specific simulator UDID
  type?: string;  // Device type (e.g., 'iPhone 14')
  name?: string;  // Custom simulator name
  os?: string;    // iOS version (e.g., '16.0')
}

// Android Emulator configuration
interface DetoxAndroidEmulatorDriverConfig {
  type: 'android.emulator';
  device: string | { avdName: string };
  bootArgs?: string;
  gpuMode?: 'auto' | 'host' | 'swiftshader_indirect' | 'angle_indirect' | 'guest' | 'off';
  headless?: boolean;     // Run emulator in headless mode
  readonly?: boolean;     // Use read-only emulator snapshots
  forceAdbInstall?: boolean;
  utilBinaryPaths?: string[];
}

// Android Attached Device configuration
interface DetoxAttachedAndroidDriverConfig {
  type: 'android.attached';
  device: string | { adbName: string };
  forceAdbInstall?: boolean;
  utilBinaryPaths?: string[];
}

// Genymotion Cloud configuration
interface DetoxGenymotionCloudDriverConfig {
  type: 'android.genycloud';
  device: string | { recipeUUID: string } | { recipeName: string };
  forceAdbInstall?: boolean;
  utilBinaryPaths?: string[];
}

Usage Examples:

// iOS Simulator devices
devices: {
  'simulator': {
    type: 'ios.simulator',
    device: { type: 'iPhone 14', os: '16.0' }
  },
  'ipad': {
    type: 'ios.simulator', 
    device: { type: 'iPad Pro (12.9-inch) (6th generation)' },
    bootArgs: '--force-headless'
  }
}

// Android Emulator devices
devices: {
  'emulator': {
    type: 'android.emulator',
    device: { avdName: 'Pixel_API_33' },
    headless: false,
    gpuMode: 'auto'
  },
  'tablet_emulator': {
    type: 'android.emulator',
    device: { avdName: 'Pixel_Tablet_API_33' },
    bootArgs: '-no-window -no-audio'
  }
}

// Physical Android device
devices: {
  'attached': {
    type: 'android.attached',
    device: { adbName: 'emulator-5554' }
  }
}

// Genymotion Cloud
devices: {
  'genycloud': {
    type: 'android.genycloud',
    device: { recipeName: 'Google Pixel 3' }
  }
}

Test Configurations

Combine apps and devices into named test configurations.

interface DetoxConfiguration {
  /** Device configuration (name reference or full config) */
  device: string | DetoxDeviceConfig;
  
  /** App configuration (name reference or full config) for single-app setups */
  app?: string | DetoxAppConfig;
  
  /** Multiple app configurations for multi-app testing */
  apps?: (string | DetoxAppConfig)[];
  
  /** Artifact collection settings for this configuration */
  artifacts?: DetoxArtifactsConfig;
  
  /** Behavior settings for this configuration */
  behavior?: DetoxBehaviorConfig;
  
  /** Logger settings for this configuration */
  logger?: DetoxLoggerConfig;
  
  /** Session settings for this configuration */
  session?: DetoxSessionConfig;
  
  /** Test runner settings for this configuration */
  testRunner?: DetoxTestRunnerConfig;
  
  /** Build command override for this configuration */
  build?: string;
  
  /** Start command override for this configuration */
  start?: string;
}

Usage Examples:

configurations: {
  // Single app configurations
  'ios.sim.debug': {
    device: 'simulator',
    app: 'ios.debug'
  },
  'android.emu.release': {
    device: 'emulator',
    app: 'android.release',
    artifacts: {
      rootDir: './artifacts-release'
    }
  },
  
  // Multi-app configuration
  'ios.multi.debug': {
    device: 'simulator',
    apps: ['passenger', 'driver']
  },
  
  // Inline configuration (not using references)
  'ios.inline': {
    device: {
      type: 'ios.simulator',
      device: { type: 'iPhone 14' }
    },
    app: {
      type: 'ios.app',
      binaryPath: 'ios/build/MyApp.app'
    }
  }
}

Behavior Configuration

Control test execution behavior and app lifecycle management.

interface DetoxBehaviorConfig {
  init?: {
    /** Export global variables (device, element, by, expect, waitFor, web, system, pilot) */
    exposeGlobals?: boolean;
    
    /** Reinstall app before each test suite (default: true) */
    reinstallApp?: boolean;
    
    /** Keep device lock file for parallel test execution (default: false) */
    keepLockFile?: boolean;
  };
  
  /** App launch behavior: 'auto' (default) or 'manual' */
  launchApp?: 'auto' | 'manual';
  
  cleanup?: {
    /** Shutdown device after tests (default: true) */
    shutdownDevice?: boolean;
  };
}

Usage Examples:

behavior: {
  init: {
    exposeGlobals: true,      // Enable global variables
    reinstallApp: true,       // Fresh app install for each test
    keepLockFile: false       // Allow parallel execution
  },
  launchApp: 'auto',          // Automatically launch app
  cleanup: {
    shutdownDevice: true      // Shutdown device after tests
  }
}

// Manual app launch configuration
behavior: {
  launchApp: 'manual',        // Don't auto-launch app
  init: {
    reinstallApp: false       // Keep existing app installation
  }
}

Artifacts Configuration

Configure collection and storage of test artifacts (logs, screenshots, videos).

interface DetoxArtifactsConfig {
  /** Root directory for all artifacts */
  rootDir?: string;
  
  /** Custom path builder for artifact organization */
  pathBuilder?: string;
  
  plugins?: {
    /** Log collection settings */
    log?: 'none' | 'failing' | 'all' | DetoxLogArtifactsPluginConfig;
    
    /** Screenshot collection settings */
    screenshot?: 'none' | 'manual' | 'failing' | 'all' | DetoxScreenshotArtifactsPluginConfig;
    
    /** Video recording settings */
    video?: 'none' | 'failing' | 'all' | DetoxVideoArtifactsPluginConfig;
    
    /** Instruments profiling settings (iOS) */
    instruments?: 'none' | 'all' | DetoxInstrumentsArtifactsPluginConfig;
    
    /** UI hierarchy capture settings */
    uiHierarchy?: 'disabled' | 'enabled' | DetoxUIHierarchyArtifactsPluginConfig;
    
    /** Custom artifact plugins */
    [pluginId: string]: unknown;
  };
}

interface DetoxLogArtifactsPluginConfig {
  enabled?: boolean;
  keepOnlyFailedTestsArtifacts?: boolean;
}

interface DetoxScreenshotArtifactsPluginConfig {
  enabled?: boolean;
  keepOnlyFailedTestsArtifacts?: boolean;
  shouldTakeAutomaticSnapshots?: boolean;
  takeWhen?: {
    testStart?: boolean;
    testFailure?: boolean;
    testDone?: boolean;
    appNotReady?: boolean;
  };
}

interface DetoxVideoArtifactsPluginConfig {
  enabled?: boolean;
  keepOnlyFailedTestsArtifacts?: boolean;
  android?: {
    size?: [number, number];
    bitRate?: number;
    timeLimit?: number;
    verbose?: boolean;
  };
  simulator?: {
    codec?: string;
  };
}

Usage Examples:

artifacts: {
  rootDir: './artifacts',
  pathBuilder: './custom-path-builder.js',
  plugins: {
    log: 'failing',           // Collect logs only for failed tests
    screenshot: {
      enabled: true,
      takeWhen: {
        testStart: true,      // Screenshot at test start
        testFailure: true,    // Screenshot on failure
        testDone: false       // No screenshot on completion
      },
      keepOnlyFailedTestsArtifacts: true
    },
    video: {
      enabled: true,
      keepOnlyFailedTestsArtifacts: false,
      android: {
        size: [1280, 720],
        bitRate: 4000000
      }
    },
    instruments: 'none',      // Disable instruments profiling
    uiHierarchy: 'enabled'    // Enable UI hierarchy capture
  }
}

Logger Configuration

Configure logging levels, output format, and console integration.

interface DetoxLoggerConfig {
  /** Log level filter for terminal output */
  level?: 'fatal' | 'error' | 'warn' | 'info' | 'debug' | 'trace';
  
  /** Hijack console methods to format as Detox logs */
  overrideConsole?: boolean;
  
  /** Additional options for log formatting */
  options?: BunyanDebugStreamOptions | ((config: Partial<DetoxLoggerConfig>) => BunyanDebugStreamOptions);
}

Usage Examples:

logger: {
  level: 'info',              // Show info level and above
  overrideConsole: true,      // Format console.log as Detox logs
  options: {
    colors: true,             // Enable colored output
    showProcess: false,       // Hide process info
    showLevel: true,          // Show log levels
    showMetadata: false       // Hide metadata
  }
}

// Dynamic logger configuration
logger: {
  level: 'debug',
  options: (config) => ({
    colors: process.env.CI !== 'true',  // Colors only in non-CI
    showMetadata: config.level === 'trace'
  })
}

Session Configuration

Configure Detox server and session management settings.

interface DetoxSessionConfig {
  /** Automatically start Detox server */
  autoStart?: boolean;
  
  /** Debug synchronization timing (milliseconds) */
  debugSynchronization?: number;
  
  /** Detox server URL (defaults to auto-generated local server) */
  server?: string;
  
  /** Custom session identifier */
  sessionId?: string;
}

Usage Examples:

session: {
  autoStart: true,                    // Auto-start server
  server: 'ws://localhost:8099',      // Custom server URL
  debugSynchronization: 10000,        // 10 second sync debug
  sessionId: 'my-test-session'        // Custom session ID
}

Test Runner Configuration

Configure integration with Jest and other test runners.

interface DetoxTestRunnerConfig {
  /** Command line arguments for test runner */
  args?: {
    $0: string;           // Runner command (e.g., 'jest')
    _?: string[];         // Positional arguments
    [prop: string]: unknown;
  };
  
  /** Jest-specific configuration */
  jest?: {
    setupTimeout?: number;        // Environment setup timeout (default: 300000)
    teardownTimeout?: number;     // Environment teardown timeout (default: 30000)
    retryAfterCircusRetries?: boolean; // Allow both Jest and Detox retries
    reportSpecs?: boolean;        // Report individual test progress
    reportWorkerAssign?: boolean; // Report worker-device assignments
  };
  
  /** Retry configuration */
  retries?: number;               // Number of retry attempts
  noRetryArgs?: string[];         // Arguments to exclude from retries
  bail?: boolean;                 // Stop retries on permanent failure
  detached?: boolean;             // Run in detached mode for CI
  
  /** Custom inspect handler for debugging */
  inspectBrk?: (config: DetoxTestRunnerConfig) => void;
  
  /** Forward environment variables to test runner */
  forwardEnv?: boolean;
}

Usage Examples:

testRunner: {
  args: {
    $0: 'jest',
    _: ['e2e'],
    maxWorkers: 1,
    verbose: true
  },
  jest: {
    setupTimeout: 120000,          // 2 minute setup timeout
    teardownTimeout: 30000,        // 30 second teardown
    reportSpecs: true,             // Show individual test progress
    reportWorkerAssign: true       // Show device assignments
  },
  retries: 2,                      // Retry failed tests twice
  bail: false,                     // Continue retries even on permanent failures
  detached: true                   // Use detached mode for CI
}

Configuration Best Practices

Environment-Specific Configurations

// Use environment variables for flexibility
const config = {
  selectedConfiguration: process.env.DETOX_CONFIGURATION || 'ios.sim.debug',
  configurations: {
    'ios.sim.debug': {
      device: 'simulator',
      app: 'ios.debug'
    },
    'ios.sim.release': {
      device: 'simulator', 
      app: 'ios.release'
    }
  }
};

// CI-specific overrides
if (process.env.CI) {
  config.logger = { level: 'error' };
  config.artifacts = {
    plugins: {
      video: 'failing',
      screenshot: 'failing'
    }
  };
}

Configuration Inheritance

// Base configuration
// detox.base.js
module.exports = {
  logger: { level: 'info' },
  behavior: {
    init: { reinstallApp: true },
    launchApp: 'auto'
  },
  artifacts: {
    plugins: {
      log: 'failing',
      screenshots: 'failing'
    }
  }
};

// Extended configuration
// .detoxrc.js
module.exports = {
  extends: './detox.base.js',
  selectedConfiguration: 'ios.sim.debug',
  configurations: {
    // Configuration-specific settings
  }
};

Types

interface DetoxConfig {
  extends?: string;
  apps?: Record<string, DetoxAppConfig>;
  devices?: Record<string, DetoxDeviceConfig>;
  selectedConfiguration?: string;
  configurations: Record<string, DetoxConfiguration>;
  artifacts?: DetoxArtifactsConfig;
  behavior?: DetoxBehaviorConfig;
  logger?: DetoxLoggerConfig;
  session?: DetoxSessionConfig;
  testRunner?: DetoxTestRunnerConfig;
  build?: string;
  start?: string;
}

// Additional detailed type interfaces as documented above...