# Detox MCP

An MCP (Model Context Protocol) server for integrating the [Detox](https://github.com/wix/Detox) mobile testing framework with Claude Code.

## Features

- **Test Execution**: Build and run Detox E2E tests with full options
- **Configuration Management**: Read, validate, and generate Detox configurations
- **Code Generation**: Generate test code, matchers, actions, and expectations
- **Device Management**: List iOS simulators and Android emulators
- **Resources**: Access configuration, devices, tests, and API reference
- **Prompts**: Slash commands for common workflows

## Installation

```bash
npm install -g detox-mcp
```

Or install locally in your project:

```bash
npm install detox-mcp
```

## Usage with Claude Code

### Add to Claude Code

```bash
# Add globally
claude mcp add detox-mcp

# Or with npx
claude mcp add --transport stdio detox-mcp -- npx detox-mcp
```

### Project Configuration

Create `.mcp.json` in your project root:

```json
{
  "mcpServers": {
    "detox": {
      "command": "npx",
      "args": ["detox-mcp"],
      "env": {
        "DETOX_PROJECT_PATH": "/path/to/your/react-native/project"
      }
    }
  }
}
```

## Available Tools

### Test Execution

| Tool | Description |
|------|-------------|
| `detox_build` | Build app for Detox testing |
| `detox_test` | Run E2E tests with full options |
| `detox_init` | Initialize Detox in a project |

### Configuration

| Tool | Description |
|------|-------------|
| `detox_read_config` | Read and parse .detoxrc.js |
| `detox_list_configurations` | List available configurations |
| `detox_validate_config` | Validate configuration |
| `detox_create_config` | Generate new configuration |

### Code Generation

| Tool | Description |
|------|-------------|
| `detox_generate_test` | Generate complete test file |
| `detox_generate_matcher` | Generate element matcher code |
| `detox_generate_action` | Generate action code |
| `detox_generate_expectation` | Generate expectation code |

### Devices

| Tool | Description |
|------|-------------|
| `detox_list_devices` | List iOS simulators and Android emulators |

## Resources

Access contextual data via the resource URIs:

| URI | Description |
|-----|-------------|
| `detox://config` | Current Detox configuration |
| `detox://devices` | Available simulators/emulators |
| `detox://tests` | Test file listings |
| `detox://api/matchers` | Matchers API reference |
| `detox://api/actions` | Actions API reference |
| `detox://api/expectations` | Expectations API reference |
| `detox://api/device` | Device API reference |

## Prompts (Slash Commands)

Use these prompts in Claude Code for common workflows:

| Prompt | Description |
|--------|-------------|
| `/detox-test` | Run tests with smart defaults |
| `/detox-generate` | Generate test from description |
| `/detox-setup` | Initialize Detox in project |
| `/detox-debug` | Debug failing tests |

## Examples

### Run Tests

```
Ask Claude: "Run my Detox tests on iOS simulator"
```

Claude will use `detox_build` and `detox_test` tools to execute your tests.

### Generate Test Code

```
Ask Claude: "Generate a Detox test for the login flow"
```

Claude will use `detox_generate_test` to create test code.

### Check Configuration

```
Ask Claude: "What Detox configurations are available?"
```

Claude will use `detox_list_configurations` to show available configs.

## Requirements

- Node.js 18+
- Detox installed in your React Native project
- For iOS: Xcode and applesimutils
- For Android: Android SDK and emulator

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `DETOX_PROJECT_PATH` | Path to React Native project | Current directory |

## Development

```bash
# Clone the repo
git clone https://github.com/your-username/detox-mcp

# Install dependencies
npm install

# Build
npm run build

# Run in development
npm run dev
```

## License

MIT