How to debug Detox tests with the REPL

Detox REPL mode pauses a Jest-backed end-to-end test at a chosen line so a developer can inspect the running app before the next automated action. It is useful when a test reaches the right screen but the next matcher, tap, or wait still fails.

The pause requires starting detox test with --repl and adding await detox.REPL() in the test or lifecycle hook where execution should stop. --repl=auto is better for entering the prompt after a failure, while --repl gives manual control at a planned stop point.

REPL mode is currently tied to the Jest test runner and still needs a normal Detox configuration, built app, and simulator or emulator. Keep the pause temporary, run only the affected spec while debugging, and remove the REPL call before the test returns to a pull request or CI job.

1. Add a temporary REPL pause at the point where the app state becomes uncertain.

   e2e/login.e2e.js

   it('opens the dashboard after login', async () => {
     await device.launchApp();
     await element(by.id('signIn')).tap();
    
     await detox.REPL();
    
     await expect(element(by.id('dashboardTitle'))).toBeVisible();
   });

   Pass a scope object such as await detox.REPL({ testUser, login }) only when the prompt needs project helpers or test data.

2. Run the selected spec in manual REPL mode.

   $ detox test -c ios.sim.debug e2e/login.e2e.js --testNamePattern "opens the dashboard after login" --repl
   detox[61012] i login opens the dashboard after login
   .detox>

   Use --repl=auto when the prompt should open automatically after a test or lifecycle hook fails.

3. Check the available REPL commands.

   .detox> .help
   .break     Sometimes you get stuck, this gets you out
   .clear     Alias for .break
   .dumpxml   Print view hierarchy XML
   .editor    Enter editor mode
   .exit      Exit the REPL
   .help      Print this help message
   .load      Load JS from a file into the REPL session
   .pilot     Execute natural language command
   .save      Save all evaluated commands in this REPL session to a file

4. Inspect the current view hierarchy from the paused app.

   .detox> .dumpxml
   <XCUIElementTypeApplication name="Example">
   ##### snipped #####
   <XCUIElementTypeStaticText name="Dashboard" label="Dashboard"/>
   </XCUIElementTypeApplication>

   The hierarchy output is long by design. Use it to confirm the current screen, visible labels, and test IDs before changing selectors.

   Related: How to wait for UI elements in Detox

5. Run the matcher or action that was failing.

   .detox> await expect(element(by.id('dashboardTitle'))).toBeVisible()
   undefined

   A successful awaited Detox assertion returns to the prompt without throwing. If it throws, inspect the hierarchy again and adjust the selector, wait condition, or app state before resuming.

6. Exit the REPL prompt after the inspection is complete.

   .detox> .exit

   Press Ctrl+C twice if the prompt does not return from an unfinished expression.

7. Remove the temporary await detox.REPL() call from the test.
8. Re-run the selected spec without REPL mode.

   $ detox test -c ios.sim.debug e2e/login.e2e.js --testNamePattern "opens the dashboard after login"
   PASS e2e/login.e2e.js
     PASS opens the dashboard after login (6420 ms)