How to capture screenshots in Detox tests

Capturing screenshots in Detox tests preserves the screen state from a mobile end-to-end run as a .png artifact. This is useful when a passing test needs a visual baseline or a failed CI run needs evidence of what the simulator or emulator displayed.

The manual screenshot path uses device.takeScreenshot() inside the test. Detox returns a temporary readable file path while the test is still running, then moves the named image into the artifacts directory when the test finishes.

Artifact retention depends on the screenshot plugin mode used for the run. Keep --take-screenshots set to manual or all for passing manual screenshots, and choose an --artifacts-location directory that the local shell or CI job can inspect after detox test exits.

1. Add a named screenshot call after the screen reaches the state worth saving.

   e2e/profile-screenshot.test.js

   const fs = require('node:fs');
    
   describe('Profile', () => {
     it('loads profile details', async () => {
       await device.launchApp({newInstance: true});
       await element(by.id('profileTab')).tap();
       await expect(element(by.id('profileName'))).toBeVisible();
    
       const screenshotPath = await device.takeScreenshot('profile-ready');
       expect(fs.existsSync(screenshotPath)).toBe(true);
     });
   });

   The path returned by device.takeScreenshot() is only guaranteed while the test is still running. Use the final artifact directory after detox test exits.

2. Use an element screenshot only when one native view is the visual target.

   const screenshotPath = await element(by.id('profileCard')).takeScreenshot('profile-card');

   Element screenshots follow the same temporary-file and final-artifact behavior as device.takeScreenshot().
   Related: How to stabilize selectors in Detox tests

3. Run the target spec with manual screenshot artifacts enabled.

   $ npx detox test --configuration ios.sim.debug --take-screenshots manual --artifacts-location artifacts/detox/ e2e/profile-screenshot.test.js
   PASS e2e/profile-screenshot.test.js
     Profile
       loads profile details (9.2 s)
   
   Test Suites: 1 passed, 1 total
   Tests:       1 passed, 1 total

   manual is the default screenshot artifact mode, but setting it explicitly prevents a shared CI wrapper from disabling manual screenshot artifacts.

4. List the artifact files saved by the run.

   $ find artifacts/detox -type f
   artifacts/detox/Profile loads profile details/profile-ready.png

   A trailing slash in --artifacts-location tells Detox to write directly under that directory. Without the trailing slash, Detox adds a configuration-and-timestamp child directory.

5. Open the saved PNG from the artifact path and confirm it shows the intended screen state.

   If --take-screenshots is none, the manual screenshot can still be taken during the test, but Detox does not save it into the artifacts directory after the test finishes.