Onboarding: wix/Detox

Generated by RepoPilot · 2026-05-07 · Source

Agent protocol

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/wix/Detox shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

Verdict

GO — Healthy across the board

• Last commit 1d ago
• 8 active contributors
• Distributed ownership (top contributor 41% of recent commits)
• MIT licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

Verify before trusting

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live wix/Detox repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/wix/Detox.

What it runs against: a local clone of wix/Detox — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in wix/Detox | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>wix/Detox</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of wix/Detox. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/wix/Detox.git
#   cd Detox
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of wix/Detox and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "wix/Detox(\\.git)?\\b" \\
  && ok "origin remote is wix/Detox" \\
  || miss "origin remote is not wix/Detox (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "detox-cli/cli.js" \\
  && ok "detox-cli/cli.js" \\
  || miss "missing critical file: detox-cli/cli.js"
test -f "detox/android/detox/src/full/java/com/wix/detox/Detox.java" \\
  && ok "detox/android/detox/src/full/java/com/wix/detox/Detox.java" \\
  || miss "missing critical file: detox/android/detox/src/full/java/com/wix/detox/Detox.java"
test -f "detox/android/detox/src/full/java/com/wix/detox/adapters/server/DetoxServerAdapter.kt" \\
  && ok "detox/android/detox/src/full/java/com/wix/detox/adapters/server/DetoxServerAdapter.kt" \\
  || miss "missing critical file: detox/android/detox/src/full/java/com/wix/detox/adapters/server/DetoxServerAdapter.kt"
test -f "detox/.eslintrc.js" \\
  && ok "detox/.eslintrc.js" \\
  || miss "missing critical file: detox/.eslintrc.js"
test -f "ARCHITECTURE.md" \\
  && ok "ARCHITECTURE.md" \\
  || miss "missing critical file: ARCHITECTURE.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/wix/Detox"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

</details>

TL;DR

Detox is a gray box end-to-end testing framework for React Native and native mobile apps (iOS/Android) that synchronizes with the app's internal state to eliminate flaky tests. Unlike black box testing, it communicates with the app being tested to understand when it's idle and ready for the next action, enabling deterministic automation of user interactions like tapping, typing, and assertion checks. Monorepo using Yarn workspaces. Core structure: detox-cli package (./detox-cli/ with cli.js entry, dependency only on chalk) wraps the main Detox engine (presumably in ./packages/). Native bindings split by platform: Kotlin for Android (336KB), Objective-C/Swift for iOS (440KB combined). Test suite and demo apps per RN version in .buildkite/jobs/. Documentation in MDX format (162KB) under docs/.

Who it's for

Mobile app developers and QA engineers building React Native apps (primary) or native iOS/Android apps who need reliable CI/CD automation without manual testing. Specifically, teams using React Native 77+ on iOS or Android who want to write E2E tests in JavaScript that don't timeout or fail unpredictably.

Maturity & risk

Production-ready and actively maintained. The project shows maturity via NPM version 20.50.3, comprehensive CI/CD setup across .buildkite/ (multiple RN version pipelines), GitHub Actions workflows, and dense monorepo with Kotlin/Swift/Objective-C native bindings. Last commits are recent (indicated by active .buildkite pipelines and CI workflows), with clear versioning discipline.

Low-to-moderate risk for adoption. Detox maintains tight coupling to specific React Native versions (77, 84, 85.2 tested in .buildkite/) which means RN version upgrades can break tests—see the version-specific pipeline files. The mixed-language codebase (JavaScript, Kotlin, Swift, Objective-C) means bugs may require platform-specific expertise. Dependency on Wix's internal infrastructure (Buildkite, .buildkite/) and tooling makes local reproduction of certain CI failures harder.

Active areas of work

Active development targeting React Native compatibility across versions 77, 84, 85.2 (seen in .buildkite/jobs/pipeline.* files). CI infrastructure is robust with separate debug, fast-release, and full-release pipelines. Post-processing pipeline suggests active test result aggregation. GitHub workflows include link scanning, docs deployment to website, and rapid test feedback on PRs.

Get running

git clone https://github.com/wix/Detox.git
cd Detox
yarn install
yarn build

Then see ARCHITECTURE.md for monorepo structure and specific package setup. The .nvmrc specifies Node version to use.

Daily commands: For CLI: npm install -g detox-cli or use local yarn workspace. For development: yarn build compiles native modules. Run tests: exact commands depend on which package (iOS, Android, CLI), but typically yarn test in the target workspace. See specific .buildkite/jobs/*.yml files for full CI test commands per platform.

Map of the codebase

• detox-cli/cli.js — Entry point for the Detox CLI tool; all contributors using Detox from command line depend on this dispatcher
• detox/android/detox/src/full/java/com/wix/detox/Detox.java — Core Android test runtime initialization; handles instrumentation setup and test lifecycle for Android apps
• detox/android/detox/src/full/java/com/wix/detox/adapters/server/DetoxServerAdapter.kt — WebSocket server adapter bridging test client and native Android app; critical communication layer
• detox/.eslintrc.js — Linting configuration enforced across the main Detox package; defines code style standards all PRs must follow
• ARCHITECTURE.md — High-level design document explaining Detox's gray-box testing model and component interactions
• .buildkite/pipeline.sh — Primary CI/CD orchestration script; controls build, test, and release workflows across iOS and Android
• detox/android/detox/src/coreNative/java/com/wix/detox/actions/DetoxViewActions.kt — Native Android view interaction primitives; implements core gesture and UI automation commands

How to make changes

Add a new Android test action (e.g., new gesture)

1. Define the action handler in the action handlers map (detox/android/detox/src/full/java/com/wix/detox/adapters/server/DetoxActionHandlers.kt)
2. Implement the native view action using Espresso or direct Android APIs (detox/android/detox/src/coreNative/java/com/wix/detox/actions/DetoxViewActions.kt)
3. Register the action in the dispatcher to route incoming commands (detox/android/detox/src/full/java/com/wix/detox/adapters/server/DetoxActionsDispatcher.kt)
4. Add test case in Android test suite to verify the action works end-to-end (detox/android/detox/src)

Modify app launch and initialization behavior

1. Update launch argument parsing if adding new CLI flags (detox/android/detox/src/full/java/com/wix/detox/LaunchArgs.java)
2. Adjust intent factory to configure new launch parameters (detox/android/detox/src/full/java/com/wix/detox/LaunchIntentsFactory.kt)
3. Update activity launch logic to apply new configuration (detox/android/detox/src/full/java/com/wix/detox/ActivityLaunchHelper.kt)
4. Initialize new state in the main Detox class (detox/android/detox/src/full/java/com/wix/detox/Detox.java)

Add a new test query matcher (e.g., custom element selection)

1. Implement the matcher logic in DetoxViewActions (detox/android/detox/src/coreNative/java/com/wix/detox/actions/DetoxViewActions.kt)
2. Add handler that uses the matcher in action handlers (detox/android/detox/src/full/java/com/wix/detox/adapters/server/DetoxActionHandlers.kt)
3. Register the matcher in the dispatcher for client requests (detox/android/detox/src/full/java/com/wix/detox/adapters/server/DetoxActionsDispatcher.kt)
4. Add integration test to verify matcher works with real app views (detox/__tests__)

Why these technologies

• WebSocket (Java + Kotlin on Android) — Enables real-time bidirectional communication between test client (Node.js) and native Android app; allows synchronous RPC-style test commands
• Espresso (Android Testing Framework) — Provides gray-box access to Android view hierarchy and built-in synchronization primitives; avoids flaky black-box UI automation
• JUnit Runner Integration — Leverages Android's native test instrumentation infrastructure for reliable app launch, lifecycle management, and permission handling
• Gradle (Android Build System) — Standard Android build tool; integrates Detox as an instrumentation library without requiring custom build steps
• Node.js CLI (detox-cli + chalk) — Cross-platform test orchestration; minimal dependencies for simple command-line argument parsing and colored output

Trade-offs already made

• Gray-box testing (native code access) vs. black-box (UI automation only)

  • Why: Gray-box approach requires native integration but provides stable, synchronizable test execution without flaky timing hacks
  • Consequence: Tests must be written for specific app frameworks (React Native, native); cannot test arbitrary third-party apps

• Synchronous WebSocket RPC vs. asynchronous event streaming

  • Why: Synchronous RPC simplifies test script logic (await pattern) and makes failures deterministic
  • Consequence: undefined

Traps & gotchas

1. React Native version pinning: Tests must match RN version in .buildkite pipelines (77, 84, 85.2); mismatches cause bridge failures. 2. Native build prerequisites: iOS requires Xcode & CocoaPods; Android requires Android SDK. Not all can be installed via package managers. 3. Yarn version lock: Uses Yarn 4.12.0 (.yarn/releases/), not npm; using npm instead breaks workspace resolution. 4. Platform-specific paths: Detox-iOS and Detox-Android have completely different native implementations; changes to matchers may need platform-specific handling. 5. Buildkite-dependent workflows: Some CI logic is in .buildkite/ YAML, not GitHub Actions; local reproduction may require Buildkite agent or custom scripts.

Architecture

Concepts to learn

• Gray box testing — Detox's core differentiator—it syncs with the app's internal state (idle/busy) to eliminate flaky waits, unlike black-box tools; understanding this is essential to writing reliable tests
• React Native bridge synchronization — Detox must communicate with RN's native thread to know when JS and native layers are idle; bugs often stem from bridge lifecycle mismatches across RN versions
• Matcher pattern (by.id(), by.text()) — Detox's fluent API for element selection; matchers compile to efficient native queries, so understanding specificity vs. performance tradeoffs is key to test design
• Flakiness elimination via app state polling — Detox polls app state instead of using arbitrary waits; this requires understanding race conditions, async boundaries, and when the app is truly 'ready'
• Monorepo package linking with Yarn workspaces — Detox uses Yarn 4 workspaces to link native driver packages (iOS, Android) with the CLI; modifying one package requires understanding workspace resolution and build order
• Native module bridging (JNI/Kotlin, Objective-C++) — The framework must communicate bidirectionally with native layers; bugs often occur at the bridge boundary where data marshaling or threading models collide
• CI/CD matrix testing across RN versions — Detox's .buildkite/ setup tests against multiple RN versions (77, 84, 85.2) in parallel; understanding how to extend the matrix is critical for adding new version support

Related repos

• facebook/react-native — Detox targets React Native as its primary platform; understanding RN's bridge and threading model is essential for debugging synchronization issues
• appium/appium — Alternative black-box E2E testing framework for mobile apps; Detox's gray-box approach is a direct response to Appium's flakiness issues
• wix/react-native-template — Wix's own RN starter template that likely includes Detox pre-configured for teams adopting the testing framework
• maestroooo/maestro — Modern competitor for mobile E2E testing with lower friction setup; both target same pain points but Detox emphasizes tighter app integration
• detox/docs — Official Detox documentation repo (deployed via .github/workflows/docs.yml); contains user guides and API reference separate from this monorepo

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for detox-cli/cli.js entry point

The detox-cli package has a test script that does nothing ("test": ":"), yet it's the primary entry point users interact with. There are no visible test files for cli.js in the repo structure, creating a gap in test coverage for a critical user-facing module. This would ensure the CLI argument parsing, help text, and delegation to the main detox package work correctly.

• [ ] Create detox-cli/tests/ directory with test files
• [ ] Add unit tests for cli.js that verify: argument parsing, help/version flags, error handling, and proper delegation to detox package
• [ ] Update detox-cli/package.json test script to run Jest or the repo's test runner
• [ ] Add test cases for edge cases like invalid arguments and missing dependencies

Create GitHub Actions workflow for detox-cli package health checks

The .github/workflows directory has multiple workflows but appears to lack one specifically for the detox-cli package. Since detox-cli is a published npm package with dependencies (chalk), it should have automated checks to verify: package publishing readiness, dependency vulnerabilities, and npm audit compliance. This prevents broken CLI releases.

• [ ] Create .github/workflows/detox-cli-health.yml workflow
• [ ] Add steps to: run npm audit on detox-cli/, verify package.json validity, test the bin entry point (detox-cli/cli.js), and validate it can be installed/executed
• [ ] Configure workflow to run on: pushes to main, PRs modifying detox-cli/*, and pre-release
• [ ] Add status badge to detox-cli/README.md (if exists) or create one

Add missing error handling and integration tests for Android/iOS pipeline configurations

The .buildkite/jobs/ directory contains multiple pipeline YAML files for different React Native versions (RN 77, 84, 85.2) and platforms (iOS, Android), but there's no visible validation or integration test suite. If these pipelines have syntax errors or reference missing jobs, they fail silently in CI. Adding validation ensures pipeline reliability across platform/version combinations.

• [ ] Create .buildkite/tests/ directory with a validation script (Node.js or bash)
• [ ] Add tests to verify: all YAML files parse correctly, all referenced jobs exist, environment variables are defined, and steps reference valid commands
• [ ] Create a GitHub Actions workflow (.github/workflows/buildkite-validation.yml) that runs this validation on changes to .buildkite/
• [ ] Document expected structure in CONTRIBUTING.md for pipeline configuration requirements

Good first issues

• Add TypeScript definitions for detox-cli: The detox-cli/package.json shows TypeScript (37KB) exists in repo but cli.js has no .d.ts file; would help IDE users and reduce issues from missing type hints
• Expand test coverage for detox-cli edge cases: detox-cli/package.json has 'test' script set to ':' (no-op); adding Jest tests for CLI argument parsing, error handling, and help text would catch regressions early
• Document build prerequisites in ARCHITECTURE.md: ARCHITECTURE.md exists but repo has heavy native content (Kotlin, Swift, Objective-C); adding OS-specific setup steps (Xcode versions, Android SDK level, CocoaPods) would reduce contributor friction

Top contributors

• @gosha212 — 41 commits
• @markdevocht — 29 commits
• @noomorph — 12 commits
• @mobileoss — 10 commits
• @d4vidi — 5 commits

Recent commits

• d280e91 — Detox with RN0.85.2 support (#4936) (markdevocht)
• 1b46ddb — 20.50.3 (#4940) (markdevocht)
• 1f672f2 — CI publish script update for correct version handling (#4939) (markdevocht)
• a98929b — fix of screenshots of the navigation bar on iOS 26 (#4938) (markdevocht)
• bb13942 — RN0.84 (#4926) (markdevocht)
• a97e9b4 — fix (#4925) (markdevocht)
• a0cf825 — v20.50.0 (#4924) (markdevocht)
• ffd6f3d — Feat/v20.49.0 (#4923) (markdevocht)
• 0ae2bb7 — version bump (#4922) (markdevocht)
• 924e349 — iOS 26.1 implementation of liquidGlass overlay (#4921) (markdevocht)

Security observations

The detox-cli package has a relatively good security posture with minimal direct dependencies. The primary concern is the use of a caret-pinned dependency (chalk ^4.0.0) which could allow installation of vulnerable versions. The repository structure shows proper use of build pipeline configuration (.buildkite) and GitHub workflows, but the lack of visible lock file commitment and limited dependency audit visibility present moderate concerns. No hardcoded secrets, injection vectors, or exposed credentials were identified in the file structure provided. Recommendation: Implement strict dependency version pinning, automated security scanning in CI/CD, and regular dependency audits.

• Medium · Outdated Dependency: chalk — detox-cli/package.json - dependencies.chalk. The package uses chalk ^4.0.0, which is a caret dependency allowing any version from 4.0.0 to <5.0.0. While chalk is a legitimate library, older versions in the 4.x range may contain security vulnerabilities. The caret range could pull in a vulnerable version if not pinned correctly. Fix: Update chalk to the latest stable version and consider using a more restrictive version range (e.g., ~4.1.2 or a specific pinned version) to reduce supply chain attack surface.
• Low · Missing package-lock or Yarn lock enforcement — detox-cli/package.json and project root. The repository uses Yarn 4.12.0 (.yarn/releases/yarn-4.12.0.cjs present), but there's no indication of a committed lock file in the provided structure. This could lead to non-deterministic builds and potential installation of unexpected dependency versions. Fix: Ensure yarn.lock (or package-lock.json if using npm) is committed to version control and CI/CD pipeline enforces lockfile usage with --frozen-lockfile flag.
• Low · Executable Script Permissions Risk — detox-cli/cli.js. The detox-cli/cli.js file is marked as executable (bin entry in package.json) but without proper security measures documented. Shell scripts with user input can be vulnerable if they execute commands without proper sanitization. Fix: Ensure the CLI script validates all user inputs, avoids shell injection vulnerabilities, and uses proper quoting/escaping for any command execution. Review the actual cli.js implementation.
• Low · Minimal Dependency Security Visibility — detox/package.json (not provided in analysis). The detox-cli package has very few direct dependencies (only chalk), but the main 'detox' package dependencies are not shown in this analysis. This limits visibility into the complete dependency tree security posture. Fix: Run 'npm audit' or 'yarn audit' regularly. Use automated dependency scanning tools in CI/CD pipeline (e.g., Snyk, OWASP Dependency-Check). Consider using npm/yarn audit in pre-commit hooks.

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.