@percy/detox

Percy visual testing SDK for Detox — the gray-box E2E framework for React Native apps.

Quick start

npm install --save-dev @percy/cli @percy/detox

Add a screenshot call to any Detox test:

const { device, element, by } = require('detox');
const percyScreenshot = require('@percy/detox');

describe('Login flow', () => {
  it('renders the welcome screen', async () => {
    await expect(element(by.id('welcome'))).toBeVisible();
    await percyScreenshot(device, 'Welcome screen');
  });
});

Run under Percy CLI's app:exec with an App-type project token (app_...):

export PERCY_TOKEN=<app_...>
npx percy app:exec -- npx detox test -c android.emu.debug

A working example app is available at percy/example-percy-detox.

Requirements

• Node ≥ 18
• Detox ≥ 20.32.0
• An App-type Percy project (token starts with app_)

Supported execution targets

Target	Status
Android — local emulator	✅ Fully supported
Android — local USB-attached real device	✅ Same local driver as emulator
iOS — local simulator	✅ Supported
iOS — local real device	⚠️ Works in principle; uncommon

API

await percyScreenshot(deviceOrElement, name, options?)

• deviceOrElement — the Detox device object, or an element handle from element(by.id(...)).
• name — unique snapshot name within the build.
• options (all optional):

Option	Type	Description
fullscreen	boolean	Treat the screenshot as full-screen (no chrome cropping).
fullPage	boolean	Accepted for API parity; produces a single-tile capture (warns once per process).
deviceName	string	Override auto-detected device name.
osVersion	string	Override auto-detected OS version.
orientation	'portrait' | 'landscape'	Override; defaults to 'portrait'.
statusBarHeight	number	Pixel override; default 0.
navigationBarHeight	number	Pixel override; default 0.
ignoreRegionIds	string[]	Mask elements located via by.id(testID).
ignoreRegionElements	DetoxElement[]	Mask pre-matched Detox element handles.
customIgnoreRegions	{top,bottom,left,right}[]	Mask rectangles in point coordinates.
considerRegionIds	string[]	Restrict diff to these elements.
considerRegionElements	DetoxElement[]	Restrict diff to these handles.
customConsiderRegions	{top,bottom,left,right}[]	Restrict diff to these rects (points).
testCase	string	Group snapshot in the Percy review UI.
labels	string	Comma-separated label chips for the snapshot.
sync	boolean	Block until the Percy build finalizes.

Coordinate space: all region options accept point coordinates. The SDK multiplies by the device scale factor automatically. Do not pre-multiply.

Examples

Element-level capture

const hero = element(by.id('hero'));
await expect(hero).toBeVisible();
await percyScreenshot(hero, 'Hero element');

Ignore dynamic regions

await percyScreenshot(device, 'Dashboard', {
  ignoreRegionIds: ['live-clock', 'unread-count'],
  customIgnoreRegions: [{ top: 0, bottom: 100, left: 0, right: 414 }]
});

Group snapshots by test case

await percyScreenshot(device, 'Login screen', { testCase: 'auth-suite' });

Configuration

Environment variable	Effect
PERCY_TOKEN	Required. App-type Percy project token (starts with app_).
PERCY_IGNORE_ERRORS	If 'true', screenshot failures are logged and swallowed instead of failing the test.
PERCY_LOGLEVEL	silent, info, debug. Defaults to info.
PERCY_METRICS	If 'true', collect per-screenshot timing telemetry.

Debugging

If you run into issues, the first place to look is the Debugging SDKs guide — it covers log levels, common setup gotchas, and how to gather logs for a bug report.

To enable verbose output:

PERCY_LOGLEVEL=debug npx percy app:exec -- npx detox test -c android.emu.debug

Migration from @percy/appium-app

@percy/appium-app option	@percy/detox equivalent
ignoreRegionXpaths	Rejected — Detox has no XPath. Use ignoreRegionIds.
ignoreRegionAccessibilityIds	ignoreRegionIds.
ignoreRegionAppiumElements	ignoreRegionElements.
considerRegionXpaths	Rejected — use considerRegionIds.
considerRegionAccessibilityIds	considerRegionIds.
considerRegionAppiumElements	considerRegionElements.
scrollableXpath, scrollableId, screenLengths, topScrollviewOffset, bottomScrollviewOffset, androidScrollAreaPercentage, scrollSpeed, iosOptimizedFullpage	Rejected — fullPage scroll-and-stitch is not supported on Detox.
thTestCaseExecutionId	Rejected — TestHub is not supported.

Passing a rejected key throws TypeError with a migration hint — nothing is silently ignored.

Known limitations

• element.takeScreenshot misses TextureView, GLSurfaceView, Skia canvases, and other hardware-accelerated content on Android (wix/Detox#4489). Use device.takeScreenshot for views backed by these surfaces.
• iOS: atIndex(n).getAttributes() is silently ignored (wix/Detox#4633). When multi-match occurs, @percy/detox uses the first result and logs a warning.
• fullPage is accepted but produces a single-tile capture — Detox has no server-side stitching channel (unlike BrowserStack's Appium executor).
• iOS scale factor is inferred from PNG width: >=1080 → 3x, otherwise 2x. iPad retina at 2x with width 1536+ may be misclassified; override with explicit options or open an issue.

Resources

• Example app + tests
• Percy App Percy docs
• Detox docs

License

MIT