mirror of
https://github.com/hanzoai/Detox.git
synced 2026-09-24 16:55:12 +00:00
docs: add internal architecture documentation (#4909)
This commit is contained in:
Yedidya Kennard
+344
@@ -0,0 +1,344 @@
|
|||||||
|
# Detox Architecture
|
||||||
|
|
||||||
|
This document provides an overview of Detox's internal architecture for contributors and maintainers.
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
Detox is a **gray-box end-to-end testing framework** for React Native mobile applications. Unlike black-box testing frameworks, Detox has visibility into the app's internal state, enabling automatic synchronization between tests and the app.
|
||||||
|
|
||||||
|
```text
|
||||||
|
┌───────────────────────────────────────────────────────────┐
|
||||||
|
│ Test Environment (Node.js) │
|
||||||
|
│ │
|
||||||
|
│ ┌─────────────┐ ┌─────────────┐ ┌───────────────────┐ │
|
||||||
|
│ │ Test Runner │ │DetoxContext │ │ ArtifactsManager │ │
|
||||||
|
│ │(Jest/Mocha) │ │ (Realms) │ │ │ │
|
||||||
|
│ └──────┬──────┘ └──────┬──────┘ └─────────┬─────────┘ │
|
||||||
|
│ │ │ │ │
|
||||||
|
│ └────────────────┼───────────────────┘ │
|
||||||
|
│ │ │
|
||||||
|
│ ┌─────────▼─────────┐ │
|
||||||
|
│ │ DetoxWorker │ │
|
||||||
|
│ │ - device │ │
|
||||||
|
│ │ - element/by │ │
|
||||||
|
│ │ - expect │ │
|
||||||
|
│ └─────────┬─────────┘ │
|
||||||
|
│ │ │
|
||||||
|
│ ┌─────────▼─────────┐ │
|
||||||
|
│ │ Client │ │
|
||||||
|
│ │ (WebSocket) │ │
|
||||||
|
│ └─────────┬─────────┘ │
|
||||||
|
└──────────────────────────┼────────────────────────────────┘
|
||||||
|
│
|
||||||
|
┌─────────▼─────────┐
|
||||||
|
│ DetoxServer │
|
||||||
|
│ (WebSocket) │
|
||||||
|
│ localhost:port │
|
||||||
|
└─────────┬─────────┘
|
||||||
|
│
|
||||||
|
┌──────────────────────────┼────────────────────────────────┐
|
||||||
|
│ Mobile Device/Simulator │
|
||||||
|
│ │ │
|
||||||
|
│ ┌─────────▼─────────┐ │
|
||||||
|
│ │ Native Client │ │
|
||||||
|
│ │ (iOS/Android) │ │
|
||||||
|
│ │ │ │
|
||||||
|
│ │ - Synchronizer │ │
|
||||||
|
│ │ - Matchers │ │
|
||||||
|
│ │ - Actions │ │
|
||||||
|
│ └───────────────────┘ │
|
||||||
|
└───────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
## Core Components
|
||||||
|
|
||||||
|
### 1. Realms (`src/realms/`)
|
||||||
|
|
||||||
|
Detox uses a "realm" pattern to manage different execution contexts:
|
||||||
|
|
||||||
|
| Realm | Class | Purpose |
|
||||||
|
|-------|-------|---------|
|
||||||
|
| **Primary** | `DetoxPrimaryContext` | Full-featured context with device allocation, used in test runner process |
|
||||||
|
| **Secondary** | `DetoxSecondaryContext` | Lightweight config-snapshot context for worker processes |
|
||||||
|
|
||||||
|
**Key files:**
|
||||||
|
|
||||||
|
- `DetoxContext.js` - Base class exposing `device`, `element`, `expect`, `by`, `waitFor`, `web`, `system`
|
||||||
|
- `DetoxPrimaryContext.js` - Handles initialization, device allocation, server lifecycle
|
||||||
|
- `DetoxSecondaryContext.js` - Receives config snapshots, no device management
|
||||||
|
|
||||||
|
The base `DetoxContext` uses **funpermaproxy** to lazily delegate API calls to the worker:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
device = funpermaproxy(() => this[symbols.worker].device);
|
||||||
|
element = funpermaproxy.callable(() => this[symbols.worker].element);
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Worker (`src/DetoxWorker.js`)
|
||||||
|
|
||||||
|
Each test worker creates a `DetoxWorker` instance that:
|
||||||
|
|
||||||
|
- Connects to the Detox server via `Client`
|
||||||
|
- Creates the `InvocationManager` for command serialization
|
||||||
|
- Instantiates the `RuntimeDevice` via environment factories
|
||||||
|
- Creates matchers (`by`, `element`, `expect`, `waitFor`)
|
||||||
|
- Manages the `ArtifactsManager`
|
||||||
|
|
||||||
|
**Lifecycle hooks:**
|
||||||
|
|
||||||
|
- `onRunDescribeStart` / `onRunDescribeFinish`
|
||||||
|
- `onTestStart` / `onTestDone`
|
||||||
|
- `onHookFailure` / `onTestFnFailure`
|
||||||
|
|
||||||
|
### 3. Client-Server Communication (`src/client/`, `src/server/`)
|
||||||
|
|
||||||
|
See [docs/architecture/client-server.md](docs/architecture/client-server.md) for details.
|
||||||
|
|
||||||
|
**Key components:**
|
||||||
|
|
||||||
|
- `Client` - WebSocket client connecting to server, sends actions to app
|
||||||
|
- `AsyncWebSocket` - Promise-based WebSocket wrapper
|
||||||
|
- `DetoxServer` - WebSocket server mediating tester ↔ app communication
|
||||||
|
- `DetoxSession` / `DetoxSessionManager` - Per-session state management
|
||||||
|
|
||||||
|
### 4. Device Management (`src/devices/`)
|
||||||
|
|
||||||
|
See [docs/architecture/devices.md](docs/architecture/devices.md) for details.
|
||||||
|
|
||||||
|
**Structure:**
|
||||||
|
|
||||||
|
```text
|
||||||
|
devices/
|
||||||
|
├── allocation/ # Device allocation strategies
|
||||||
|
│ ├── DeviceAllocator.js
|
||||||
|
│ ├── DeviceRegistry.js
|
||||||
|
│ └── drivers/
|
||||||
|
│ ├── ios/ # SimulatorAllocDriver
|
||||||
|
│ └── android/ # Emulator, Attached, Genycloud
|
||||||
|
├── runtime/ # Runtime device abstractions
|
||||||
|
│ ├── RuntimeDevice.js
|
||||||
|
│ └── drivers/
|
||||||
|
│ ├── ios/ # IosDriver, SimulatorDriver
|
||||||
|
│ └── android/ # EmulatorDriver, AttachedAndroidDriver, GenyCloudDriver
|
||||||
|
├── cookies/ # Device state serialization
|
||||||
|
└── validation/ # Environment validators
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5. Artifacts (`src/artifacts/`)
|
||||||
|
|
||||||
|
See [docs/architecture/artifacts.md](docs/architecture/artifacts.md) for details.
|
||||||
|
|
||||||
|
**Plugins:**
|
||||||
|
|
||||||
|
- `screenshot` - Captures screenshots on failure or on-demand
|
||||||
|
- `video` - Records test execution video
|
||||||
|
- `log` - Aggregates device and app logs
|
||||||
|
- `instruments` - iOS performance profiling
|
||||||
|
- `uiHierarchy` - Dumps view hierarchy for debugging (iOS only)
|
||||||
|
|
||||||
|
### 6. Invocation System (`src/invoke.js`, `src/client/actions/`)
|
||||||
|
|
||||||
|
Commands are serialized as JSON and sent to the native app:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// Test code
|
||||||
|
await element(by.id('button')).tap();
|
||||||
|
|
||||||
|
// Serialized to invocation
|
||||||
|
{
|
||||||
|
type: 'invoke',
|
||||||
|
params: {
|
||||||
|
target: { type: 'Class', value: 'com.wix.detox.Detox' },
|
||||||
|
method: 'perform',
|
||||||
|
args: [{ /* matcher */ }, { /* action */ }]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
The `InvocationManager` handles serialization/deserialization and batching.
|
||||||
|
|
||||||
|
### 7. Matchers & Expectations (`src/ios/`, `src/android/`)
|
||||||
|
|
||||||
|
Platform-specific implementations:
|
||||||
|
|
||||||
|
| Component | iOS | Android |
|
||||||
|
|-----------|-----|---------|
|
||||||
|
| Matchers | `src/matchers/` | `src/android/matchers/` |
|
||||||
|
| Actions | `src/ios/` | `src/android/actions/` |
|
||||||
|
| Expectations | `src/ios/expectTwo.js` | `src/android/AndroidExpect.js` |
|
||||||
|
|
||||||
|
Note: Shared matcher factory logic is in `src/matchers/`. iOS-specific expectations and test runner code are in `src/ios/`.
|
||||||
|
|
||||||
|
### 8. Test Runner Integration (`runners/`)
|
||||||
|
|
||||||
|
```text
|
||||||
|
runners/
|
||||||
|
├── jest/
|
||||||
|
│ ├── testEnvironment/ # Jest environment setup
|
||||||
|
│ ├── reporters/ # Custom reporters
|
||||||
|
│ ├── globalSetup.js
|
||||||
|
│ └── globalTeardown.js
|
||||||
|
├── jest-circus/ # Circus event handling
|
||||||
|
└── mocha/ # Mocha adapter
|
||||||
|
```
|
||||||
|
|
||||||
|
## Data Flow
|
||||||
|
|
||||||
|
### Test Execution Flow
|
||||||
|
|
||||||
|
```text
|
||||||
|
1. Jest runs test file
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
2. DetoxEnvironment.setup()
|
||||||
|
└── detox.init()
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
3. DetoxPrimaryContext initializes
|
||||||
|
├── Starts DetoxServer
|
||||||
|
├── Allocates device
|
||||||
|
└── Installs worker
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
4. DetoxWorker.init()
|
||||||
|
├── Connects Client to server
|
||||||
|
├── Creates RuntimeDevice
|
||||||
|
├── Creates matchers
|
||||||
|
└── Installs app (if configured)
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
5. Test executes
|
||||||
|
├── element(by.id('x')).tap()
|
||||||
|
│ └── Client.execute(invocation)
|
||||||
|
│ └── Server relays to app
|
||||||
|
│ └── App executes action
|
||||||
|
│ └── App responds
|
||||||
|
│ └── Client resolves
|
||||||
|
└── expect(element).toBeVisible()
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
6. DetoxEnvironment.teardown()
|
||||||
|
└── detox.cleanup()
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
7. Artifacts collected, device deallocated
|
||||||
|
```
|
||||||
|
|
||||||
|
### Synchronization Flow
|
||||||
|
|
||||||
|
```text
|
||||||
|
Test sends action
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
Native client receives
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
Synchronizer checks app state:
|
||||||
|
├── Pending network requests?
|
||||||
|
├── Main thread busy?
|
||||||
|
├── Animations running?
|
||||||
|
├── React Native bridge busy?
|
||||||
|
└── JavaScript thread idle?
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
When idle: Execute action
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
Return result to test
|
||||||
|
```
|
||||||
|
|
||||||
|
## Key Design Patterns
|
||||||
|
|
||||||
|
### 1. Symbol-Based Privacy
|
||||||
|
|
||||||
|
Internal members use Symbols to prevent accidental access:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
const $worker = Symbol('worker');
|
||||||
|
class DetoxContext {
|
||||||
|
[$worker] = null;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Factory Pattern
|
||||||
|
|
||||||
|
Environment-specific factories create platform-appropriate instances:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
const factories = environmentFactory.createFactories(deviceConfig);
|
||||||
|
// Returns: envValidatorFactory, artifactsManagerFactory,
|
||||||
|
// matchersFactory, runtimeDeviceFactory
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Cancellable Async Flow (CAF)
|
||||||
|
|
||||||
|
Long-running operations use CAF for cancellation:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
this._reinstallAppsOnDevice = CAF(this._reinstallAppsOnDevice.bind(this));
|
||||||
|
// Can be cancelled via: this._initToken.abort('CLEANUP')
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. Event-Driven Architecture
|
||||||
|
|
||||||
|
`ArtifactsManager` and `RuntimeDevice` use event emitters for loose coupling:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
deviceEmitter.on('bootDevice', this.onBootDevice.bind(this));
|
||||||
|
deviceEmitter.on('launchApp', this.onLaunchApp.bind(this));
|
||||||
|
```
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
Configuration flows through composition:
|
||||||
|
|
||||||
|
```text
|
||||||
|
.detoxrc.js / detox.config.js
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
loadExternalConfig()
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
CLI arguments (--configuration, --device-name, etc.)
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
composeDetoxConfig()
|
||||||
|
├── composeAppsConfig()
|
||||||
|
├── composeDeviceConfig()
|
||||||
|
├── composeArtifactsConfig()
|
||||||
|
├── composeBehaviorConfig()
|
||||||
|
└── composeSessionConfig()
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
RuntimeConfig
|
||||||
|
```
|
||||||
|
|
||||||
|
## Directory Structure
|
||||||
|
|
||||||
|
```text
|
||||||
|
detox/
|
||||||
|
├── src/
|
||||||
|
│ ├── realms/ # Context management
|
||||||
|
│ ├── client/ # WebSocket client
|
||||||
|
│ ├── server/ # WebSocket server
|
||||||
|
│ ├── devices/ # Device management
|
||||||
|
│ ├── artifacts/ # Artifact collection
|
||||||
|
│ ├── configuration/ # Config composition
|
||||||
|
│ ├── ios/ # iOS-specific code
|
||||||
|
│ ├── android/ # Android-specific code
|
||||||
|
│ ├── matchers/ # Matcher factories
|
||||||
|
│ ├── invoke.js # Invocation manager
|
||||||
|
│ └── DetoxWorker.js # Per-test worker
|
||||||
|
├── runners/ # Test runner integrations
|
||||||
|
├── local-cli/ # CLI commands
|
||||||
|
├── ios/ # Native iOS SDK
|
||||||
|
└── android/ # Native Android SDK
|
||||||
|
```
|
||||||
|
|
||||||
|
## See Also
|
||||||
|
|
||||||
|
- [docs/architecture/client-server.md](docs/architecture/client-server.md) - Client-server protocol details
|
||||||
|
- [docs/architecture/devices.md](docs/architecture/devices.md) - Device management internals
|
||||||
|
- [docs/architecture/artifacts.md](docs/architecture/artifacts.md) - Artifact collection system
|
||||||
|
- [docs/articles/how-detox-works.md](docs/articles/how-detox-works.md) - User-facing explanation
|
||||||
|
- [docs/articles/design-principles.md](docs/articles/design-principles.md) - Design philosophy
|
||||||
@@ -0,0 +1,560 @@
|
|||||||
|
# Artifacts System
|
||||||
|
|
||||||
|
The artifacts subsystem collects test artifacts like screenshots, videos, logs, and performance data during test execution.
|
||||||
|
|
||||||
|
## Architecture Overview
|
||||||
|
|
||||||
|
```text
|
||||||
|
┌─────────────────────────────────────────────────────────────┐
|
||||||
|
│ Artifacts Subsystem │
|
||||||
|
│ │
|
||||||
|
│ ┌───────────────────────────────────────────────────────┐ │
|
||||||
|
│ │ ArtifactsManager │ │
|
||||||
|
│ │ │ │
|
||||||
|
│ │ - Registers plugins │ │
|
||||||
|
│ │ - Subscribes to device events │ │
|
||||||
|
│ │ - Orchestrates lifecycle callbacks │ │
|
||||||
|
│ │ - Manages idle callback queue │ │
|
||||||
|
│ └────────────────────────┬──────────────────────────────┘ │
|
||||||
|
│ │ │
|
||||||
|
│ ┌───────────────┼───────────────┐ │
|
||||||
|
│ │ │ │ │
|
||||||
|
│ ┌─────▼─────┐ ┌─────▼─────┐ ┌─────▼─────┐ │
|
||||||
|
│ │Screenshot │ │ Video │ │ Log │ │
|
||||||
|
│ │ Plugin │ │ Plugin │ │ Plugin │ │
|
||||||
|
│ └───────────┘ └───────────┘ └───────────┘ │
|
||||||
|
│ │
|
||||||
|
│ ┌───────────┐ ┌───────────┐ │
|
||||||
|
│ │Instruments│ │UIHierarchy│ │
|
||||||
|
│ │ Plugin │ │ (iOS) │ │
|
||||||
|
│ └───────────┘ └───────────┘ │
|
||||||
|
│ │
|
||||||
|
│ ┌───────────────────────────────────────────────────────┐ │
|
||||||
|
│ │ ArtifactPathBuilder │ │
|
||||||
|
│ │ Generates paths: artifacts/{config}/{test}/artifact │ │
|
||||||
|
│ └───────────────────────────────────────────────────────┘ │
|
||||||
|
└─────────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
## Directory Structure
|
||||||
|
|
||||||
|
```text
|
||||||
|
src/artifacts/
|
||||||
|
├── ArtifactsManager.js # Main orchestrator
|
||||||
|
├── providers/
|
||||||
|
│ └── index.js # Exports: AndroidArtifactPluginsProvider,
|
||||||
|
│ # IosArtifactPluginsProvider,
|
||||||
|
│ # IosSimulatorArtifactPluginsProvider
|
||||||
|
├── templates/
|
||||||
|
│ ├── artifact/
|
||||||
|
│ │ ├── Artifact.js # Base artifact class
|
||||||
|
│ │ └── FileArtifact.js # File-based artifact
|
||||||
|
│ └── plugin/
|
||||||
|
│ ├── ArtifactPlugin.js # Base plugin class
|
||||||
|
│ ├── StartupAndTestRecorderPlugin.js
|
||||||
|
│ ├── TwoSnapshotsPerTestPlugin.js
|
||||||
|
│ └── WholeTestRecorderPlugin.js
|
||||||
|
├── screenshot/
|
||||||
|
│ ├── ScreenshotArtifactPlugin.js
|
||||||
|
│ ├── SimulatorScreenshotPlugin.js # iOS
|
||||||
|
│ └── ADBScreencapPlugin.js # Android
|
||||||
|
├── video/
|
||||||
|
│ ├── VideoArtifactPlugin.js
|
||||||
|
│ ├── SimulatorRecordVideoPlugin.js # iOS
|
||||||
|
│ └── ADBScreenrecorderPlugin.js # Android
|
||||||
|
├── log/
|
||||||
|
│ ├── LogArtifactPlugin.js
|
||||||
|
│ ├── ios/
|
||||||
|
│ │ └── SimulatorLogPlugin.js
|
||||||
|
│ └── android/
|
||||||
|
│ └── ADBLogcatPlugin.js
|
||||||
|
├── instruments/
|
||||||
|
│ ├── InstrumentsArtifactPlugin.js
|
||||||
|
│ ├── ios/
|
||||||
|
│ │ └── SimulatorInstrumentsPlugin.js
|
||||||
|
│ └── android/
|
||||||
|
│ └── AndroidInstrumentsPlugin.js
|
||||||
|
├── uiHierarchy/
|
||||||
|
│ └── IosUIHierarchyPlugin.js # iOS only
|
||||||
|
└── utils/
|
||||||
|
├── ArtifactPathBuilder.js
|
||||||
|
└── temporaryPath.js
|
||||||
|
```
|
||||||
|
|
||||||
|
## ArtifactsManager
|
||||||
|
|
||||||
|
### Initialization
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
class ArtifactsManager extends EventEmitter {
|
||||||
|
constructor({ rootDir, pathBuilder, plugins }) {
|
||||||
|
this._pluginConfigs = plugins;
|
||||||
|
this._artifactPlugins = {};
|
||||||
|
this._pathBuilder = new ArtifactPathBuilder({ rootDir });
|
||||||
|
this._idlePromise = Promise.resolve();
|
||||||
|
}
|
||||||
|
|
||||||
|
registerArtifactPlugins(artifactPluginFactoriesMap) {
|
||||||
|
for (const [key, factory] of Object.entries(artifactPluginFactoriesMap)) {
|
||||||
|
const config = this._pluginConfigs[key];
|
||||||
|
this._artifactPlugins[key] = this._instantiateArtifactPlugin(factory, config);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Plugin Instantiation
|
||||||
|
|
||||||
|
Each plugin receives an API object for interacting with the manager:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
_instantiateArtifactPlugin(pluginFactory, pluginUserConfig) {
|
||||||
|
const artifactsApi = {
|
||||||
|
plugin: null,
|
||||||
|
userConfig: { ...pluginUserConfig },
|
||||||
|
|
||||||
|
preparePathForArtifact: async (artifactName, testSummary) => {
|
||||||
|
const artifactPath = this._pathBuilder.buildPathForTestArtifact(artifactName, testSummary);
|
||||||
|
const artifactDir = path.dirname(artifactPath);
|
||||||
|
await fs.ensureDir(artifactDir);
|
||||||
|
return artifactPath;
|
||||||
|
},
|
||||||
|
|
||||||
|
trackArtifact: (artifact) => this.emit('trackArtifact', artifact),
|
||||||
|
untrackArtifact: (artifact) => this.emit('untrackArtifact', artifact),
|
||||||
|
|
||||||
|
requestIdleCallback: (callback) => {
|
||||||
|
// Queue for execution during idle time
|
||||||
|
this._idleCallbackRequests.push({ caller: artifactsApi.plugin, callback });
|
||||||
|
return this._idlePromise;
|
||||||
|
},
|
||||||
|
};
|
||||||
|
|
||||||
|
const plugin = pluginFactory(artifactsApi);
|
||||||
|
artifactsApi.plugin = plugin;
|
||||||
|
return plugin;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Device Event Subscription
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
subscribeToDeviceEvents(deviceEmitter) {
|
||||||
|
deviceEmitter.on('bootDevice', this.onBootDevice.bind(this));
|
||||||
|
deviceEmitter.on('beforeShutdownDevice', this.onBeforeShutdownDevice.bind(this));
|
||||||
|
deviceEmitter.on('shutdownDevice', this.onShutdownDevice.bind(this));
|
||||||
|
deviceEmitter.on('beforeLaunchApp', this.onBeforeLaunchApp.bind(this));
|
||||||
|
deviceEmitter.on('launchApp', this.onLaunchApp.bind(this));
|
||||||
|
deviceEmitter.on('appReady', this.onAppReady.bind(this));
|
||||||
|
deviceEmitter.on('beforeUninstallApp', this.onBeforeUninstallApp.bind(this));
|
||||||
|
deviceEmitter.on('beforeTerminateApp', this.onBeforeTerminateApp.bind(this));
|
||||||
|
deviceEmitter.on('terminateApp', this.onTerminateApp.bind(this));
|
||||||
|
deviceEmitter.on('createExternalArtifact', this.onCreateExternalArtifact.bind(this));
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Lifecycle Events
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// Test lifecycle
|
||||||
|
async onRunDescribeStart(suite) {
|
||||||
|
await this._callPlugins('ascending', 'onRunDescribeStart', suite);
|
||||||
|
}
|
||||||
|
|
||||||
|
async onTestStart(testSummary) {
|
||||||
|
await this._callPlugins('ascending', 'onTestStart', testSummary);
|
||||||
|
}
|
||||||
|
|
||||||
|
async onTestDone(testSummary) {
|
||||||
|
await this._callPlugins('descending', 'onTestDone', testSummary);
|
||||||
|
}
|
||||||
|
|
||||||
|
async onRunDescribeFinish(suite) {
|
||||||
|
await this._callPlugins('descending', 'onRunDescribeFinish', suite);
|
||||||
|
}
|
||||||
|
|
||||||
|
// Failure hooks
|
||||||
|
async onHookFailure(testSummary) {
|
||||||
|
await this._callPlugins('plain', 'onHookFailure', testSummary);
|
||||||
|
}
|
||||||
|
|
||||||
|
async onTestFnFailure(testSummary) {
|
||||||
|
await this._callPlugins('plain', 'onTestFnFailure', testSummary);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Plugin Execution Strategy
|
||||||
|
|
||||||
|
Plugins can be called in different orders based on priority:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
async _callPlugins(strategy, methodName, ...args) {
|
||||||
|
for (const pluginGroup of this._groupPlugins(strategy)) {
|
||||||
|
await Promise.all(pluginGroup.map(async (plugin) => {
|
||||||
|
try {
|
||||||
|
await plugin[methodName](...args);
|
||||||
|
} catch (e) {
|
||||||
|
this._unhandledPluginExceptionHandler(e, { plugin, methodName });
|
||||||
|
}
|
||||||
|
}));
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
_groupPlugins(strategy) {
|
||||||
|
if (strategy === 'plain') {
|
||||||
|
return [_.values(this._artifactPlugins)];
|
||||||
|
}
|
||||||
|
|
||||||
|
const byPriority = _.chain(this._artifactPlugins)
|
||||||
|
.values()
|
||||||
|
.groupBy('priority')
|
||||||
|
.entries()
|
||||||
|
.sortBy(([priority]) => Number(priority))
|
||||||
|
.map(1)
|
||||||
|
.value();
|
||||||
|
|
||||||
|
return strategy === 'descending' ? byPriority.reverse() : byPriority;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Plugin Types
|
||||||
|
|
||||||
|
### Base Plugin (`src/artifacts/templates/plugin/ArtifactPlugin.js`)
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
class ArtifactPlugin {
|
||||||
|
constructor({ api }) {
|
||||||
|
this.api = api;
|
||||||
|
this.enabled = api.userConfig.enabled !== false;
|
||||||
|
this.keepOnlyFailedTestsArtifacts = api.userConfig.keepOnlyFailedTestsArtifacts;
|
||||||
|
}
|
||||||
|
|
||||||
|
// Lifecycle hooks (override in subclasses)
|
||||||
|
async onBootDevice(deviceInfo) {}
|
||||||
|
async onBeforeLaunchApp(appLaunchInfo) {}
|
||||||
|
async onLaunchApp(appLaunchInfo) {}
|
||||||
|
async onTestStart(testSummary) {}
|
||||||
|
async onTestDone(testSummary) {}
|
||||||
|
async onBeforeCleanup() {}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Screenshot Plugin
|
||||||
|
|
||||||
|
Captures screenshots on test failure or on-demand:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
class ScreenshotArtifactPlugin extends TwoSnapshotsPerTestPlugin {
|
||||||
|
async preparePathForSnapshot(testSummary, name) {
|
||||||
|
return this.api.preparePathForArtifact(`${name}.png`, testSummary);
|
||||||
|
}
|
||||||
|
|
||||||
|
async takeSnapshot(name) {
|
||||||
|
// Delegate to device driver
|
||||||
|
return this.driver.takeScreenshot(name);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Configuration:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
{
|
||||||
|
artifacts: {
|
||||||
|
plugins: {
|
||||||
|
screenshot: {
|
||||||
|
enabled: true,
|
||||||
|
shouldTakeAutomaticSnapshots: true,
|
||||||
|
keepOnlyFailedTestsArtifacts: true,
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Video Plugin
|
||||||
|
|
||||||
|
Records test execution:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
class VideoArtifactPlugin extends WholeTestRecorderPlugin {
|
||||||
|
async onTestStart(testSummary) {
|
||||||
|
await this.startRecording();
|
||||||
|
}
|
||||||
|
|
||||||
|
async onTestDone(testSummary) {
|
||||||
|
await this.stopRecording();
|
||||||
|
|
||||||
|
if (testSummary.status === 'passed' && this.keepOnlyFailedTestsArtifacts) {
|
||||||
|
await this.discardRecording();
|
||||||
|
} else {
|
||||||
|
await this.saveRecording(testSummary);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Log Plugin
|
||||||
|
|
||||||
|
Aggregates device and app logs:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
class LogArtifactPlugin extends StartupAndTestRecorderPlugin {
|
||||||
|
async onLaunchApp(appLaunchInfo) {
|
||||||
|
await this.startCapturingLogs(appLaunchInfo);
|
||||||
|
}
|
||||||
|
|
||||||
|
async onTestDone(testSummary) {
|
||||||
|
const logs = await this.stopCapturingLogs();
|
||||||
|
await this.saveLogs(logs, testSummary);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Instruments Plugin (iOS)
|
||||||
|
|
||||||
|
Records performance profiles:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
class InstrumentsArtifactPlugin extends ArtifactPlugin {
|
||||||
|
async startRecording({ recordingPath, samplingInterval }) {
|
||||||
|
await this.client.startInstrumentsRecording({ recordingPath, samplingInterval });
|
||||||
|
}
|
||||||
|
|
||||||
|
async stopRecording() {
|
||||||
|
await this.client.stopInstrumentsRecording();
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### UI Hierarchy Plugin (iOS)
|
||||||
|
|
||||||
|
Captures view hierarchy for debugging (iOS only via `IosUIHierarchyPlugin`):
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
class IosUIHierarchyPlugin extends ArtifactPlugin {
|
||||||
|
async onTestFnFailure(testSummary) {
|
||||||
|
const hierarchy = await this.client.captureViewHierarchy();
|
||||||
|
await this.saveHierarchy(hierarchy, testSummary);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Platform-Specific Implementations
|
||||||
|
|
||||||
|
Each artifact type has platform-specific implementations:
|
||||||
|
|
||||||
|
| Artifact | iOS (Simulator) | Android |
|
||||||
|
|----------|-----------------|---------|
|
||||||
|
| Screenshot | `SimulatorScreenshotPlugin` | `ADBScreencapPlugin` |
|
||||||
|
| Video | `SimulatorRecordVideoPlugin` | `ADBScreenrecorderPlugin` |
|
||||||
|
| Log | `SimulatorLogPlugin` | `ADBLogcatPlugin` |
|
||||||
|
| Instruments | `SimulatorInstrumentsPlugin` | `AndroidInstrumentsPlugin` |
|
||||||
|
| UI Hierarchy | `IosUIHierarchyPlugin` | Not available |
|
||||||
|
|
||||||
|
The appropriate plugin is selected by the provider based on the device type:
|
||||||
|
|
||||||
|
- `IosSimulatorArtifactPluginsProvider` for iOS simulators
|
||||||
|
- `AndroidArtifactPluginsProvider` for Android devices
|
||||||
|
|
||||||
|
## Artifact Templates
|
||||||
|
|
||||||
|
### Two Snapshots Per Test
|
||||||
|
|
||||||
|
Takes snapshots at test start and end:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
class TwoSnapshotsPerTestPlugin extends ArtifactPlugin {
|
||||||
|
async onTestStart(testSummary) {
|
||||||
|
if (this.shouldTakeAutomaticSnapshots) {
|
||||||
|
await this.takeSnapshot('testStart');
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
async onTestDone(testSummary) {
|
||||||
|
if (this.shouldTakeAutomaticSnapshots) {
|
||||||
|
await this.takeSnapshot('testDone');
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Whole Test Recorder
|
||||||
|
|
||||||
|
Records throughout entire test:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
class WholeTestRecorderPlugin extends ArtifactPlugin {
|
||||||
|
async onTestStart(testSummary) {
|
||||||
|
await this.startRecording(testSummary);
|
||||||
|
}
|
||||||
|
|
||||||
|
async onTestDone(testSummary) {
|
||||||
|
await this.stopRecording();
|
||||||
|
await this.saveOrDiscard(testSummary);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Path Building
|
||||||
|
|
||||||
|
### ArtifactPathBuilder
|
||||||
|
|
||||||
|
Generates consistent artifact paths:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
class ArtifactPathBuilder {
|
||||||
|
constructor({ rootDir }) {
|
||||||
|
this._rootDir = rootDir;
|
||||||
|
}
|
||||||
|
|
||||||
|
buildPathForTestArtifact(artifactName, testSummary) {
|
||||||
|
// Path format: rootDir/{statusSign}{fullName}({invocations})/{artifactName}
|
||||||
|
// Example: artifacts/✓ Login should work/screenshot.png
|
||||||
|
// Example: artifacts/✗ Login should work (2)/screenshot.png (on retry)
|
||||||
|
const testDir = this._constructDirectoryNameForCurrentRunningTest(testSummary);
|
||||||
|
return path.join(this._rootDir, testDir, artifactName);
|
||||||
|
}
|
||||||
|
|
||||||
|
_constructDirectoryNameForCurrentRunningTest(testSummary) {
|
||||||
|
const prefix = this._buildTestDirectoryPrefix(testSummary);
|
||||||
|
const suffix = testSummary.invocations > 1 ? ` (${testSummary.invocations})` : '';
|
||||||
|
return constructSafeFilename(prefix, testSummary.fullName, suffix);
|
||||||
|
}
|
||||||
|
|
||||||
|
_buildTestDirectoryPrefix(testSummary) {
|
||||||
|
return testSummary.status === 'passed' ? '✓ ' : '✗ ';
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Custom path builders can be provided:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// detox.config.js
|
||||||
|
module.exports = {
|
||||||
|
artifacts: {
|
||||||
|
rootDir: 'e2e-artifacts',
|
||||||
|
pathBuilder: './my-path-builder.js',
|
||||||
|
}
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
module.exports = {
|
||||||
|
artifacts: {
|
||||||
|
rootDir: 'artifacts',
|
||||||
|
pathBuilder: undefined, // or custom path builder
|
||||||
|
plugins: {
|
||||||
|
screenshot: {
|
||||||
|
enabled: true,
|
||||||
|
shouldTakeAutomaticSnapshots: true,
|
||||||
|
keepOnlyFailedTestsArtifacts: true,
|
||||||
|
},
|
||||||
|
video: {
|
||||||
|
enabled: true,
|
||||||
|
keepOnlyFailedTestsArtifacts: true,
|
||||||
|
},
|
||||||
|
log: {
|
||||||
|
enabled: true,
|
||||||
|
keepOnlyFailedTestsArtifacts: false,
|
||||||
|
},
|
||||||
|
instruments: {
|
||||||
|
enabled: false,
|
||||||
|
},
|
||||||
|
uiHierarchy: { // iOS only
|
||||||
|
enabled: true,
|
||||||
|
keepOnlyFailedTestsArtifacts: true,
|
||||||
|
},
|
||||||
|
},
|
||||||
|
},
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
## Lifecycle Flow
|
||||||
|
|
||||||
|
```text
|
||||||
|
Test Suite Starts
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
onRunDescribeStart(suite)
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌────────────────────────────────┐
|
||||||
|
│ For each test: │
|
||||||
|
│ │
|
||||||
|
│ onTestStart(testSummary) │
|
||||||
|
│ │ │
|
||||||
|
│ ▼ │
|
||||||
|
│ [Test executes] │
|
||||||
|
│ │ │
|
||||||
|
│ ┌────┴────┐ │
|
||||||
|
│ │ Failure │ │
|
||||||
|
│ └────┬────┘ │
|
||||||
|
│ │ │
|
||||||
|
│ onHookFailure() or │
|
||||||
|
│ onTestFnFailure() │
|
||||||
|
│ │ │
|
||||||
|
│ ▼ │
|
||||||
|
│ onTestDone(testSummary) │
|
||||||
|
│ │ │
|
||||||
|
│ [Save or discard artifacts] │
|
||||||
|
│ │
|
||||||
|
└────────────────────────────────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
onRunDescribeFinish(suite)
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
onBeforeCleanup()
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
[Final artifact processing]
|
||||||
|
```
|
||||||
|
|
||||||
|
## Idle Callbacks
|
||||||
|
|
||||||
|
Plugins can defer non-critical work:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// In plugin
|
||||||
|
async onTestDone(testSummary) {
|
||||||
|
// Critical work first
|
||||||
|
await this.stopRecording();
|
||||||
|
|
||||||
|
// Defer compression to idle time
|
||||||
|
this.api.requestIdleCallback(async () => {
|
||||||
|
await this.compressVideo();
|
||||||
|
await this.uploadToCloud();
|
||||||
|
});
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## External Artifacts
|
||||||
|
|
||||||
|
Plugins can create artifacts from external sources:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// During test
|
||||||
|
device.createExternalArtifact({
|
||||||
|
pluginId: 'screenshot',
|
||||||
|
artifactName: 'custom-screenshot',
|
||||||
|
artifactPath: '/tmp/screenshot.png',
|
||||||
|
});
|
||||||
|
|
||||||
|
// In ArtifactsManager
|
||||||
|
async onCreateExternalArtifact({ pluginId, artifactName, artifactPath }) {
|
||||||
|
await this._callSinglePlugin(pluginId, 'onCreateExternalArtifact', {
|
||||||
|
artifact: new FileArtifact({ temporaryPath: artifactPath }),
|
||||||
|
name: artifactName,
|
||||||
|
});
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## See Also
|
||||||
|
|
||||||
|
- [ARCHITECTURE.md](../../ARCHITECTURE.md) - Main architecture overview
|
||||||
|
- [docs/config/artifacts.mdx](../config/artifacts.mdx) - Artifacts configuration
|
||||||
|
- [docs/guide/taking-screenshots.md](../guide/taking-screenshots.md) - Screenshot guide
|
||||||
@@ -0,0 +1,348 @@
|
|||||||
|
# Client-Server Communication
|
||||||
|
|
||||||
|
Detox uses a WebSocket-based client-server architecture for communication between the test process (Node.js) and the mobile app.
|
||||||
|
|
||||||
|
## Architecture Overview
|
||||||
|
|
||||||
|
```text
|
||||||
|
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
|
||||||
|
│ Test Process │ │ DetoxServer │ │ Mobile App │
|
||||||
|
│ (Node.js) │ │ (localhost) │ │ (iOS/Android) │
|
||||||
|
│ │ │ │ │ │
|
||||||
|
│ ┌────────────┐ │ WS │ ┌────────────┐ │ WS │ ┌────────────┐ │
|
||||||
|
│ │ Client │◄─┼───────►│ │ Session │◄─┼───────►│ │ Native │ │
|
||||||
|
│ │ │ │ │ │ Manager │ │ │ │ Client │ │
|
||||||
|
│ └────────────┘ │ │ └────────────┘ │ │ └────────────┘ │
|
||||||
|
└──────────────────┘ └──────────────────┘ └──────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
## Why a Mediator Server?
|
||||||
|
|
||||||
|
The server acts as a mediator rather than having direct client-to-app communication:
|
||||||
|
|
||||||
|
1. **Resilience** - Either side can disconnect (app restart, simulator boot) without losing the other's state
|
||||||
|
2. **Session management** - Multiple test workers can share device sessions
|
||||||
|
3. **Debugging** - Server can log all messages for troubleshooting
|
||||||
|
4. **Flexibility** - Server can run on a different machine for CI/CD
|
||||||
|
|
||||||
|
## Components
|
||||||
|
|
||||||
|
### Client (`src/client/Client.js`)
|
||||||
|
|
||||||
|
The test-side WebSocket client that:
|
||||||
|
|
||||||
|
- Connects to the Detox server
|
||||||
|
- Sends actions to the mobile app
|
||||||
|
- Handles responses and events
|
||||||
|
- Manages synchronization state
|
||||||
|
|
||||||
|
**Key methods:**
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// Connect to server and login to session
|
||||||
|
await client.connect();
|
||||||
|
|
||||||
|
// Send an invocation (tap, type, scroll, etc.)
|
||||||
|
await client.execute(invocation);
|
||||||
|
|
||||||
|
// Wait for app to be ready (synchronized)
|
||||||
|
await client.waitUntilReady();
|
||||||
|
|
||||||
|
// Send action and wait for response
|
||||||
|
await client.sendAction(new actions.Invoke(invocation));
|
||||||
|
```
|
||||||
|
|
||||||
|
**Event handling:**
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
client.setEventCallback('appConnected', this._onAppConnected);
|
||||||
|
client.setEventCallback('ready', this._onAppReady);
|
||||||
|
client.setEventCallback('AppNonresponsiveDetected', this._onAppUnresponsive);
|
||||||
|
client.setEventCallback('AppWillTerminateWithError', this._onBeforeAppCrash);
|
||||||
|
client.setEventCallback('appDisconnected', this._onAppDisconnected);
|
||||||
|
client.setEventCallback('serverError', this._onUnhandledServerError);
|
||||||
|
```
|
||||||
|
|
||||||
|
### AsyncWebSocket (`src/client/AsyncWebSocket.js`)
|
||||||
|
|
||||||
|
Promise-based wrapper around the WebSocket API:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
class AsyncWebSocket {
|
||||||
|
async open() { /* ... */ }
|
||||||
|
async close() { /* ... */ }
|
||||||
|
async send(action, options) { /* ... */ }
|
||||||
|
|
||||||
|
// Track in-flight requests for timeout handling
|
||||||
|
inFlightPromises = {};
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### DetoxServer (`src/server/DetoxServer.js`)
|
||||||
|
|
||||||
|
WebSocket server that mediates all communication:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
class DetoxServer {
|
||||||
|
constructor({ port, standalone }) {
|
||||||
|
this._sessionManager = new DetoxSessionManager();
|
||||||
|
this._wss = new WebSocket.Server({ port });
|
||||||
|
}
|
||||||
|
|
||||||
|
async open() {
|
||||||
|
// Start listening
|
||||||
|
}
|
||||||
|
|
||||||
|
_onConnection(ws, req) {
|
||||||
|
this._sessionManager.registerConnection(ws, req.socket);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### DetoxSession (`src/server/DetoxSession.js`)
|
||||||
|
|
||||||
|
Per-session state management:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
class DetoxSession {
|
||||||
|
constructor(id) {
|
||||||
|
this.id = id;
|
||||||
|
this.tester = null; // Test process connection
|
||||||
|
this.app = null; // Mobile app connection
|
||||||
|
}
|
||||||
|
|
||||||
|
// Route messages between tester and app
|
||||||
|
// Handle connection/disconnection events
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### DetoxSessionManager (`src/server/DetoxSessionManager.js`)
|
||||||
|
|
||||||
|
Manages multiple concurrent sessions:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
class DetoxSessionManager {
|
||||||
|
constructor() {
|
||||||
|
this._sessions = new Map();
|
||||||
|
}
|
||||||
|
|
||||||
|
registerConnection(ws, socket) {
|
||||||
|
// Identify session from login message
|
||||||
|
// Create or join existing session
|
||||||
|
}
|
||||||
|
|
||||||
|
getSession(sessionId) {
|
||||||
|
return this._sessions.get(sessionId);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Message Protocol
|
||||||
|
|
||||||
|
All messages are JSON objects with a standard structure.
|
||||||
|
|
||||||
|
**Platform differences:** iOS and Android implement the protocol quite differently:
|
||||||
|
|
||||||
|
- **Android** is reflection-centric — the `generation/` project maps Java classes to JS invocation objects (see `src/android/espressoapi/`), allowing the test side to call Android APIs via reflection-based dispatch
|
||||||
|
- **iOS** has a more handcrafted and formalized protocol, with explicit message types handled on the native side
|
||||||
|
|
||||||
|
**Note:** Invocation targets vary by operation type:
|
||||||
|
|
||||||
|
- High-level operations use `com.wix.detox.Detox` as the entry point
|
||||||
|
- Action-specific invocations may use `com.wix.detox.espresso.DetoxAction` (Android) or platform-specific targets
|
||||||
|
|
||||||
|
### Request (Test → App)
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"type": "invoke",
|
||||||
|
"messageId": 1,
|
||||||
|
"params": {
|
||||||
|
"target": {
|
||||||
|
"type": "Class",
|
||||||
|
"value": "com.wix.detox.espresso.DetoxAction"
|
||||||
|
},
|
||||||
|
"method": "perform",
|
||||||
|
"args": [
|
||||||
|
{ "matcher": "..." },
|
||||||
|
{ "action": "..." }
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Response (App → Test)
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"type": "invokeResult",
|
||||||
|
"messageId": 1,
|
||||||
|
"params": {
|
||||||
|
"result": "success"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Event (App → Test)
|
||||||
|
|
||||||
|
Events typically use fixed negative `messageId` values (e.g., `-1000`, `-0xc1ea`) rather than the incrementing positive IDs used for request-response pairs.
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"type": "ready",
|
||||||
|
"messageId": -1000
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"type": "AppWillTerminateWithError",
|
||||||
|
"params": {
|
||||||
|
"errorDetails": "..."
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Actions (`src/client/actions/actions.js`)
|
||||||
|
|
||||||
|
Predefined action classes for common operations:
|
||||||
|
|
||||||
|
| Action | Purpose |
|
||||||
|
|--------|---------|
|
||||||
|
| `Login` | Authenticate with session ID |
|
||||||
|
| `Ready` | Query if app is ready |
|
||||||
|
| `Invoke` | Execute a command on the app |
|
||||||
|
| `Cleanup` | Signal test completion |
|
||||||
|
| `ReloadReactNative` | Reload the RN bundle |
|
||||||
|
| `CurrentStatus` | Get app synchronization status |
|
||||||
|
| `Shake` | Trigger device shake |
|
||||||
|
| `SetOrientation` | Change device orientation |
|
||||||
|
| `SetSyncSettings` | Configure synchronization settings |
|
||||||
|
| `DeliverPayload` | Send push notification, deep link |
|
||||||
|
| `CaptureViewHierarchy` | Dump UI hierarchy |
|
||||||
|
| `GenerateViewHierarchyXml` | Generate UI hierarchy as XML (iOS and Android) |
|
||||||
|
| `SetInstrumentsRecordingState` | Control iOS performance profiling |
|
||||||
|
| `WaitForBackground` | Wait for app to background |
|
||||||
|
| `WaitForActive` | Wait for app to foreground |
|
||||||
|
|
||||||
|
## Connection Lifecycle
|
||||||
|
|
||||||
|
```text
|
||||||
|
1. Test starts
|
||||||
|
│
|
||||||
|
├── Client.connect()
|
||||||
|
│ └── WebSocket connects to server
|
||||||
|
│
|
||||||
|
├── Client.sendAction(Login)
|
||||||
|
│ └── Server creates/joins session
|
||||||
|
│
|
||||||
|
└── Server waits for app connection
|
||||||
|
|
||||||
|
2. App launches (with server URL in launch args)
|
||||||
|
│
|
||||||
|
├── Native client connects to server
|
||||||
|
│ └── Server associates with session
|
||||||
|
│
|
||||||
|
└── Server notifies test: 'appConnected'
|
||||||
|
|
||||||
|
3. App becomes ready
|
||||||
|
│
|
||||||
|
└── Native client sends 'ready' event
|
||||||
|
|
||||||
|
4. Test executes
|
||||||
|
│
|
||||||
|
├── Client.execute(invocation)
|
||||||
|
│ ├── Server routes to app
|
||||||
|
│ ├── App executes
|
||||||
|
│ └── App responds via server
|
||||||
|
│
|
||||||
|
└── Client receives result
|
||||||
|
|
||||||
|
5. Test completes
|
||||||
|
│
|
||||||
|
├── Client.cleanup()
|
||||||
|
│ └── Sends Cleanup action
|
||||||
|
│
|
||||||
|
└── Client.close()
|
||||||
|
```
|
||||||
|
|
||||||
|
## Synchronization
|
||||||
|
|
||||||
|
The client monitors app readiness through deferred promises (simplified):
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// Track connection state
|
||||||
|
this._whenAppIsConnected = new Deferred();
|
||||||
|
this._whenAppIsReady = new Deferred();
|
||||||
|
|
||||||
|
// Wait for synchronization (simplified - actual implementation has additional checks)
|
||||||
|
async waitUntilReady() {
|
||||||
|
await this._whenAppIsConnected.promise;
|
||||||
|
await this.sendAction(new actions.Ready());
|
||||||
|
this._whenAppIsReady.resolve();
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Slow Invocation Detection
|
||||||
|
|
||||||
|
When `debugSynchronization` is enabled, the client periodically queries app status during long operations:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
_scheduleSlowInvocationQuery() {
|
||||||
|
this._slowInvocationStatusHandle = setTimeout(async () => {
|
||||||
|
const status = await this.currentStatus();
|
||||||
|
log.info({ event: 'APP_STATUS' }, status);
|
||||||
|
// Reschedule if still waiting
|
||||||
|
}, this._slowInvocationTimeout);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
### App Crash Detection
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
_onBeforeAppCrash({ params }) {
|
||||||
|
this._pendingAppCrash = new DetoxRuntimeError({
|
||||||
|
message: 'The app has crashed',
|
||||||
|
debugInfo: params.errorDetails,
|
||||||
|
});
|
||||||
|
|
||||||
|
// Reject pending promises
|
||||||
|
// Schedule app termination
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Disconnect Handling
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
_onAppDisconnected() {
|
||||||
|
if (this._pendingAppCrash) {
|
||||||
|
this._whenAppDisconnected.reject(this._pendingAppCrash);
|
||||||
|
this._asyncWebSocket.rejectAll(this._pendingAppCrash);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## User Stack Traces
|
||||||
|
|
||||||
|
The client preserves user test stack traces for better error messages:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
async _doSendAction(action, options) {
|
||||||
|
const errorWithUserStack = createErrorWithUserStack();
|
||||||
|
|
||||||
|
try {
|
||||||
|
const response = await this._asyncWebSocket.send(action, options);
|
||||||
|
return await action.handle(response);
|
||||||
|
} catch (err) {
|
||||||
|
throw replaceErrorStack(errorWithUserStack, asError(err));
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## See Also
|
||||||
|
|
||||||
|
- [ARCHITECTURE.md](../../ARCHITECTURE.md) - Main architecture overview
|
||||||
|
- [docs/architecture/devices.md](devices.md) - Device management
|
||||||
|
- [docs/config/session.mdx](../config/session.mdx) - Session configuration
|
||||||
@@ -0,0 +1,426 @@
|
|||||||
|
# Device Management
|
||||||
|
|
||||||
|
The device subsystem handles allocation, lifecycle, and interaction with iOS simulators, Android emulators, and cloud devices.
|
||||||
|
|
||||||
|
## Architecture Overview
|
||||||
|
|
||||||
|
```text
|
||||||
|
┌────────────────────────────────────────────────────────────┐
|
||||||
|
│ Device Subsystem │
|
||||||
|
│ │
|
||||||
|
│ ┌─────────────────┐ ┌─────────────────┐ ┌────────────┐ │
|
||||||
|
│ │ DeviceAllocator │─►│ RuntimeDevice │─►│ Driver │ │
|
||||||
|
│ │ │ │ │ │ │ │
|
||||||
|
│ │ - allocate() │ │ - launchApp() │ │ - boot() │ │
|
||||||
|
│ │ - free() │ │ - terminateApp()│ │ - install()│ │
|
||||||
|
│ │ │ │ - reloadRN() │ │ - execute()│ │
|
||||||
|
│ └────────┬────────┘ └────────┬────────┘ └────────────┘ │
|
||||||
|
│ │ │ │
|
||||||
|
│ ┌────────▼────────┐ ┌────────▼────────┐ │
|
||||||
|
│ │ DeviceRegistry │ │ DeviceCookie │ │
|
||||||
|
│ │ (Lock files) │ │ (Serialization) │ │
|
||||||
|
│ └─────────────────┘ └─────────────────┘ │
|
||||||
|
└────────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
## Directory Structure
|
||||||
|
|
||||||
|
```text
|
||||||
|
src/devices/
|
||||||
|
├── allocation/
|
||||||
|
│ ├── DeviceAllocator.js # Main allocation coordinator
|
||||||
|
│ ├── DeviceList.js # Available devices tracking
|
||||||
|
│ ├── DeviceRegistry.js # Lock-based device registry
|
||||||
|
│ ├── drivers/
|
||||||
|
│ │ ├── ios/
|
||||||
|
│ │ │ └── SimulatorAllocDriver.js
|
||||||
|
│ │ └── android/
|
||||||
|
│ │ ├── emulator/
|
||||||
|
│ │ │ └── EmulatorAllocDriver.js
|
||||||
|
│ │ ├── attached/
|
||||||
|
│ │ │ └── AttachedAndroidAllocDriver.js
|
||||||
|
│ │ └── genycloud/
|
||||||
|
│ │ └── GenyAllocDriver.js
|
||||||
|
│ └── factories/
|
||||||
|
│ ├── ios.js
|
||||||
|
│ ├── android.js
|
||||||
|
│ └── external.js
|
||||||
|
├── runtime/
|
||||||
|
│ ├── RuntimeDevice.js # Main device abstraction
|
||||||
|
│ └── drivers/
|
||||||
|
│ ├── DeviceDriverBase.js
|
||||||
|
│ ├── ios/
|
||||||
|
│ │ ├── IosDriver.js
|
||||||
|
│ │ └── SimulatorDriver.js
|
||||||
|
│ └── android/
|
||||||
|
│ ├── AndroidDriver.js
|
||||||
|
│ ├── emulator/
|
||||||
|
│ │ └── EmulatorDriver.js
|
||||||
|
│ ├── attached/
|
||||||
|
│ │ └── AttachedAndroidDriver.js
|
||||||
|
│ └── genycloud/
|
||||||
|
│ └── GenyCloudDriver.js
|
||||||
|
├── common/
|
||||||
|
│ └── drivers/
|
||||||
|
│ ├── ios/tools/
|
||||||
|
│ │ └── AppleSimUtils.js
|
||||||
|
│ └── android/
|
||||||
|
│ ├── exec/
|
||||||
|
│ │ ├── ADB.js
|
||||||
|
│ │ └── AAPT.js
|
||||||
|
│ └── tools/
|
||||||
|
│ ├── Instrumentation.js
|
||||||
|
│ └── AppInstallHelper.js
|
||||||
|
├── cookies/
|
||||||
|
│ └── index.js # Device state serialization
|
||||||
|
└── validation/
|
||||||
|
└── ... # Environment validators
|
||||||
|
```
|
||||||
|
|
||||||
|
## Device Types
|
||||||
|
|
||||||
|
| Type | Config Value | Platform | Description |
|
||||||
|
|------|--------------|----------|-------------|
|
||||||
|
| iOS Simulator | `ios.simulator` | iOS | Xcode simulators |
|
||||||
|
| Android Emulator | `android.emulator` | Android | AVD emulators |
|
||||||
|
| Android Attached | `android.attached` | Android | USB-connected devices |
|
||||||
|
| Genycloud | `android.genycloud` | Android | Genymotion cloud instances |
|
||||||
|
|
||||||
|
## Allocation System
|
||||||
|
|
||||||
|
### DeviceAllocator (`src/devices/allocation/DeviceAllocator.js`)
|
||||||
|
|
||||||
|
Coordinates device allocation with concurrency control:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
class DeviceAllocator {
|
||||||
|
constructor(allocationDriver, deviceRegistry) {
|
||||||
|
this._driver = allocationDriver;
|
||||||
|
this._registry = deviceRegistry;
|
||||||
|
}
|
||||||
|
|
||||||
|
async allocate(deviceConfig) {
|
||||||
|
// Find or create a device matching the config
|
||||||
|
// Register ownership in the registry
|
||||||
|
// Return a device cookie
|
||||||
|
}
|
||||||
|
|
||||||
|
async postAllocate(deviceCookie, configs) {
|
||||||
|
// Platform-specific device setup after allocation
|
||||||
|
// e.g., boot simulator, disable animations, unlock screen
|
||||||
|
// Returns an enriched device cookie
|
||||||
|
}
|
||||||
|
|
||||||
|
async free(deviceCookie) {
|
||||||
|
// Release the device
|
||||||
|
// Remove from registry
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### DeviceRegistry (`src/devices/allocation/DeviceRegistry.js`)
|
||||||
|
|
||||||
|
Uses lock files for cross-process device ownership:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
class DeviceRegistry {
|
||||||
|
constructor({ lockfilePath }) {
|
||||||
|
this._lockfile = new ExclusiveLockfile(lockfilePath);
|
||||||
|
}
|
||||||
|
|
||||||
|
async allocateDevice(deviceQuery) {
|
||||||
|
return this._lockfile.exclusively(async () => {
|
||||||
|
// Find available device
|
||||||
|
// Mark as allocated
|
||||||
|
// Return device handle
|
||||||
|
});
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Allocation Drivers
|
||||||
|
|
||||||
|
Each device type has a specialized allocation driver:
|
||||||
|
|
||||||
|
**SimulatorAllocDriver** (`src/devices/allocation/drivers/ios/SimulatorAllocDriver.js`):
|
||||||
|
|
||||||
|
- Queries available simulators via `xcrun simctl`
|
||||||
|
- Creates simulators if needed
|
||||||
|
- Handles simulator lifecycle
|
||||||
|
|
||||||
|
**EmulatorAllocDriver** (`src/devices/allocation/drivers/android/emulator/EmulatorAllocDriver.js`):
|
||||||
|
|
||||||
|
- Validates AVD existence
|
||||||
|
- Launches emulators with appropriate flags
|
||||||
|
- Assigns unique ports
|
||||||
|
|
||||||
|
**GenyAllocDriver** (`src/devices/allocation/drivers/android/genycloud/GenyAllocDriver.js`):
|
||||||
|
|
||||||
|
- Communicates with Genymotion cloud API
|
||||||
|
- Provisions cloud instances
|
||||||
|
- Handles instance lifecycle
|
||||||
|
|
||||||
|
## Runtime Device
|
||||||
|
|
||||||
|
### RuntimeDevice (`src/devices/runtime/RuntimeDevice.js`)
|
||||||
|
|
||||||
|
The main device abstraction exposed to tests:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
class RuntimeDevice {
|
||||||
|
constructor(deviceCookie, deps, configs) {
|
||||||
|
this._driver = createDriver(deviceCookie, deps);
|
||||||
|
this._appsConfig = configs.appsConfig;
|
||||||
|
}
|
||||||
|
|
||||||
|
// App management
|
||||||
|
async launchApp(params) { /* ... */ }
|
||||||
|
async terminateApp(bundleId) { /* ... */ }
|
||||||
|
async installApp() { /* ... */ }
|
||||||
|
async uninstallApp() { /* ... */ }
|
||||||
|
|
||||||
|
// React Native specific
|
||||||
|
async reloadReactNative() { /* ... */ }
|
||||||
|
|
||||||
|
// Device control
|
||||||
|
async sendToHome() { /* ... */ }
|
||||||
|
async shake() { /* ... */ }
|
||||||
|
async setLocation(lat, lon) { /* ... */ }
|
||||||
|
async setURLBlacklist(urls) { /* ... */ }
|
||||||
|
|
||||||
|
// State
|
||||||
|
get id() { return this._driver.deviceId; }
|
||||||
|
get name() { return this._driver.deviceName; }
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Driver Hierarchy
|
||||||
|
|
||||||
|
```text
|
||||||
|
DeviceDriverBase
|
||||||
|
├── IosDriver
|
||||||
|
│ └── SimulatorDriver
|
||||||
|
└── AndroidDriver
|
||||||
|
├── EmulatorDriver
|
||||||
|
├── AttachedAndroidDriver
|
||||||
|
└── GenyCloudDriver
|
||||||
|
```
|
||||||
|
|
||||||
|
**DeviceDriverBase** (`src/devices/runtime/drivers/DeviceDriverBase.js`):
|
||||||
|
|
||||||
|
- Abstract base class
|
||||||
|
- Defines common interface
|
||||||
|
- Provides utility methods
|
||||||
|
|
||||||
|
**Platform Drivers**:
|
||||||
|
|
||||||
|
- Implement platform-specific operations
|
||||||
|
- Handle app installation/launch
|
||||||
|
- Manage device state
|
||||||
|
|
||||||
|
## Platform-Specific Tools
|
||||||
|
|
||||||
|
### iOS Tools
|
||||||
|
|
||||||
|
**AppleSimUtils** (`src/devices/common/drivers/ios/tools/AppleSimUtils.js`):
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
class AppleSimUtils {
|
||||||
|
async boot(deviceId) { /* xcrun simctl boot */ }
|
||||||
|
async shutdown(deviceId) { /* xcrun simctl shutdown */ }
|
||||||
|
async install(deviceId, path) { /* xcrun simctl install */ }
|
||||||
|
async launch(deviceId, bundleId, args) { /* xcrun simctl launch */ }
|
||||||
|
async setPermissions(deviceId, bundleId, permissions) { /* ... */ }
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Android Tools
|
||||||
|
|
||||||
|
**ADB** (`src/devices/common/drivers/android/exec/ADB.js`):
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
class ADB {
|
||||||
|
async devices() { /* adb devices */ }
|
||||||
|
async install(deviceId, apkPath) { /* adb install */ }
|
||||||
|
async shell(deviceId, command) { /* adb shell */ }
|
||||||
|
async forward(deviceId, local, remote) { /* adb forward */ }
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Instrumentation** (`src/devices/common/drivers/android/tools/Instrumentation.js`):
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
class Instrumentation {
|
||||||
|
async launch(deviceId, bundleId, testRunner, args) {
|
||||||
|
// am instrument -w -r ...
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Device Lifecycle
|
||||||
|
|
||||||
|
### Allocation Flow
|
||||||
|
|
||||||
|
```text
|
||||||
|
1. Test starts
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
2. DeviceAllocator.allocate(deviceConfig)
|
||||||
|
│
|
||||||
|
├── Query available devices
|
||||||
|
│ └── SimulatorQuery / FreeDeviceFinder
|
||||||
|
│
|
||||||
|
├── Acquire lock
|
||||||
|
│ └── DeviceRegistry.allocateDevice()
|
||||||
|
│
|
||||||
|
└── Return DeviceCookie
|
||||||
|
|
||||||
|
3. DeviceAllocator.postAllocate(cookie, configs)
|
||||||
|
│
|
||||||
|
├── Platform-specific device setup
|
||||||
|
│ ├── iOS: Boot simulator, clean app cache
|
||||||
|
│ └── Android: Wait for boot, disable animations,
|
||||||
|
│ unlock screen, configure System UI
|
||||||
|
│
|
||||||
|
└── Return enriched DeviceCookie
|
||||||
|
|
||||||
|
4. RuntimeDevice created with cookie
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
5. Tests execute
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
6. DeviceAllocator.free(cookie)
|
||||||
|
│
|
||||||
|
├── Shutdown (if configured)
|
||||||
|
│
|
||||||
|
└── Release lock
|
||||||
|
```
|
||||||
|
|
||||||
|
### App Launch Flow
|
||||||
|
|
||||||
|
```text
|
||||||
|
1. device.launchApp(params)
|
||||||
|
│
|
||||||
|
├── Terminate if running
|
||||||
|
│
|
||||||
|
├── Build launch args
|
||||||
|
│ ├── Detox server URL
|
||||||
|
│ ├── Session ID
|
||||||
|
│ └── User-provided args
|
||||||
|
│
|
||||||
|
├── Platform-specific launch
|
||||||
|
│ ├── iOS: xcrun simctl launch
|
||||||
|
│ └── Android: am instrument
|
||||||
|
│
|
||||||
|
└── Wait for app connection
|
||||||
|
└── client.waitUntilReady()
|
||||||
|
```
|
||||||
|
|
||||||
|
## Device Cookie
|
||||||
|
|
||||||
|
Device cookies serialize device state for passing between processes:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// src/devices/cookies/index.js
|
||||||
|
const DeviceCookie = {
|
||||||
|
serialize(device) {
|
||||||
|
return {
|
||||||
|
id: device.id,
|
||||||
|
type: device.type,
|
||||||
|
// Platform-specific data
|
||||||
|
};
|
||||||
|
},
|
||||||
|
|
||||||
|
deserialize(cookie) {
|
||||||
|
// Reconstruct device handle
|
||||||
|
}
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
## Environment Validation
|
||||||
|
|
||||||
|
Validators ensure the environment is properly configured:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// iOS validator
|
||||||
|
class IosSimulatorEnvValidator {
|
||||||
|
async validate() {
|
||||||
|
// Check Xcode installation
|
||||||
|
// Verify xcrun availability
|
||||||
|
// Validate simulator runtime
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// Android validator
|
||||||
|
class AndroidEmulatorEnvValidator {
|
||||||
|
async validate() {
|
||||||
|
// Check ANDROID_HOME
|
||||||
|
// Verify ADB installation
|
||||||
|
// Validate emulator availability
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Event Emission
|
||||||
|
|
||||||
|
RuntimeDevice emits lifecycle events for artifact collection:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
class RuntimeDevice {
|
||||||
|
async launchApp(params) {
|
||||||
|
await this._eventEmitter.emit('beforeLaunchApp', launchInfo);
|
||||||
|
|
||||||
|
// ... launch logic ...
|
||||||
|
|
||||||
|
await this._eventEmitter.emit('launchApp', launchInfo);
|
||||||
|
await this._eventEmitter.emit('appReady', appInfo);
|
||||||
|
}
|
||||||
|
|
||||||
|
async uninstallApp() {
|
||||||
|
await this._eventEmitter.emit('beforeUninstallApp', appInfo);
|
||||||
|
// ... uninstall logic ...
|
||||||
|
}
|
||||||
|
|
||||||
|
async terminateApp() {
|
||||||
|
await this._eventEmitter.emit('beforeTerminateApp', appInfo);
|
||||||
|
// ... terminate logic ...
|
||||||
|
await this._eventEmitter.emit('terminateApp', appInfo);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
Device configuration in `.detoxrc.js`:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
module.exports = {
|
||||||
|
devices: {
|
||||||
|
simulator: {
|
||||||
|
type: 'ios.simulator',
|
||||||
|
device: {
|
||||||
|
type: 'iPhone 15 Pro',
|
||||||
|
},
|
||||||
|
},
|
||||||
|
emulator: {
|
||||||
|
type: 'android.emulator',
|
||||||
|
device: {
|
||||||
|
avdName: 'Pixel_4_API_30',
|
||||||
|
},
|
||||||
|
},
|
||||||
|
genycloud: {
|
||||||
|
type: 'android.genycloud',
|
||||||
|
device: {
|
||||||
|
recipeUUID: '...',
|
||||||
|
},
|
||||||
|
},
|
||||||
|
},
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
## See Also
|
||||||
|
|
||||||
|
- [ARCHITECTURE.md](../../ARCHITECTURE.md) - Main architecture overview
|
||||||
|
- [docs/config/devices.mdx](../config/devices.mdx) - Device configuration reference
|
||||||
|
- [docs/guide/android-dev-env.md](../guide/android-dev-env.md) - Android setup guide
|
||||||
Reference in New Issue
Block a user