Cypress Testing for React Native Apps: What You Need to Know
Cypress cannot run end-to-end tests on native React Native apps. Learn what it can test, which native tools to consider, and how to choose a practical setup.
Short answer: Cypress cannot directly run end-to-end tests on a native React Native app installed on iOS or Android. Cypress runs in a browser. It can test a web surface, a mobile website, or a browser-based app such as Ionic, but changing the browser viewport does not test native app behavior.
If your product has both a web app and a native React Native app, Cypress can cover the web app while a native end-to-end (E2E) tool covers installed-app journeys. React Native’s testing overview names Detox, Appium, and Maestro as options. The right choice depends on your app setup, React Native version, build and CI workflow, and the user journeys you need to verify.
1. What Cypress can and cannot test
| Target | Can Cypress test it? | What that means |
|---|---|---|
| Native React Native app installed on iOS or Android | No | Cypress does not run against the native app UI on a device or simulator. |
| Website with a responsive mobile layout | Yes | Cypress can run browser tests at a narrow viewport. These remain browser tests. |
| Browser-based mobile app, such as an Ionic app | Yes, for browser functionality | The application runs in a browser environment, which is Cypress’s execution target. |
| React web application | Yes | Cypress documents React end-to-end and component testing. |
| React Native Web surface | Potentially, as a web application | Test the browser-rendered output and its web behavior; this does not cover native platform behavior. |
Cypress states in its FAQ that it cannot run on native mobile apps, while describing support for mobile browser behavior and browser-developed mobile apps. Its React component testing documentation covers React 18 and 19 with Vite, Webpack, and Next.js. That React support does not make Cypress a React Native device runner.
2. Why a mobile viewport is not native testing
A call such as cy.viewport() changes the dimensions Cypress uses for a browser test. It can help check responsive layout and browser behavior at a phone-sized viewport. It does not install your app, launch a native view hierarchy, or exercise platform-specific interactions in iOS or Android.
That distinction matters when a bug depends on native behavior: permissions, app lifecycle, deep links into an installed app, native navigation, keyboard handling, or integration with device capabilities. A browser test may cover related web behavior, but it cannot establish that the native flow works.
3. Keep Cypress for the web surface
If your project includes a website, admin console, or browser-rendered React Native Web experience, Cypress can remain part of the test strategy for that surface. Keep its coverage labeled and scoped as web coverage so a passing browser run is not mistaken for evidence that the installed app works.
Cypress documents both React end-to-end and component testing. Use component tests for focused browser-rendered component behavior and E2E tests for important web journeys. For responsive checks, set a suitable viewport and assert the rendered web interface. A small viewport is useful for layout coverage; it is not a substitute for native device coverage.
4. Choose a native React Native E2E option
React Native’s testing overview names Detox, Appium, and Maestro among E2E options. The source documents these as choices, not a universal ranking. Compare them against your actual app and delivery workflow.
| Option | What the cited documentation supports | Check before choosing |
|---|---|---|
| Detox | Purpose-built for React Native E2E testing against a running app on a device or simulator. | Verify your React Native version and architecture against current Detox compatibility docs. Detox v20.x documents full New Architecture compatibility for React Native 0.77.x–0.84.x. Expo support is community-driven; follow the Expo setup guidance if applicable. |
| Appium | Named by React Native’s testing overview as an E2E option. | Check the current driver, platform, CI, and app-build setup against your project’s needs. |
| Maestro | Named by React Native’s testing overview; Expo documents running Maestro flows against Android and iOS development builds through EAS Workflows. | The documented Expo Maestro job type is currently marked alpha. Confirm its current status and whether the workflow fits your release process. |
For an Expo project, Expo’s documented route is to build development apps and run Maestro flows against Android and iOS builds using EAS Workflows. The Expo Maestro E2E workflow guide marks the Maestro job type alpha, so account for that qualification before depending on it in CI.
5. A practical test plan
- List the surfaces. Separate browser-rendered pages from installed iOS and Android apps. Include React Native Web as a browser surface if you ship it.
- Assign the runner by execution target. Use Cypress for the browser surface. Select a native E2E runner for installed-app flows.
- Check compatibility and build integration. Confirm your React Native version, architecture, Expo setup if used, operating systems, simulator or device availability, and CI build path against current tool documentation.
- Start with vital native journeys. React Native’s testing guidance notes that E2E tests are slower and more maintenance-intensive. Prioritize flows such as authentication, core functionality, and payments rather than trying to reproduce every unit or component test at the device level.
- Keep results distinct. Report web and native coverage separately so teams can see which execution environment passed.
6. Cost, performance, and reliability considerations
The research sources do not provide comparable benchmark numbers for Cypress, Detox, Appium, or Maestro, so there is no supported speed ranking here. In general, the practical cost of native E2E coverage includes building the app, provisioning simulator/device environments, running longer journeys, and maintaining tests as screens and flows change. React Native’s overview specifically cautions that E2E tests are slower and more prone to flakiness than lower-level tests, with ongoing running and maintenance costs.
- Keep device-level coverage focused on high-value user journeys.
- Use lower-level tests for logic and component details that do not require a running installed app.
- Validate the CI build and device environment as well as the test script; failures can originate before the test reaches the intended screen.
- Review version support when upgrading React Native, its architecture, Expo, or the chosen runner.
- Do not treat a successful responsive browser run as evidence of native reliability.
7. Troubleshooting common Cypress and React Native questions
| Symptom or question | Cause | What to do |
|---|---|---|
| Cypress cannot find or launch the React Native app | Cypress does not execute native iOS or Android apps. | Run native E2E coverage with a tool intended for that target, such as Detox, Appium, or Maestro; keep Cypress for browser surfaces. |
| The test passes at a phone viewport, but the native app still fails | A narrow browser viewport tests web layout, not the installed app or native platform behavior. | Add a native device/simulator flow for the affected journey. |
| React component tests work, so why do native screens not run? | Cypress’s React testing support targets React rendered for its browser-based test environment. | Distinguish React web components from React Native views and use a native runner for the latter. |
| Detox setup fails after a React Native upgrade | Runner compatibility can depend on React Native version and architecture. | Check the current Detox environment setup and compatibility table for the exact version and architecture; do not assume a prior setup still applies. |
| An Expo Maestro workflow behaves differently than expected | Expo’s documented Maestro job type is marked alpha, and workflow/build configuration matters. | Check the latest Expo workflow documentation and verify the development build, platform, and workflow configuration. |
| Native E2E runs are slow or flaky | Device-level journeys have more setup and maintenance surface than focused lower-level tests. | Reduce coverage to vital flows, keep assertions tied to observable user outcomes, and investigate build/device setup separately from app behavior. |
8. Or skip the browser setup
For screenshots of a website or browser-rendered React surface, ScreenshotNeo provides a screenshot API and MCP server. It does not test native React Native apps or replace native E2E tests. One GET request captures a URL; the API documentation describes its options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
timeout=90,
)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before the shot. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed; response headers report the page verdict and billing status. Its MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 shots. Every feature is on every plan.
Sign up free for 1,000 screenshots a month, with no card required.
9. Frequently asked questions
Does Cypress plan to support native React Native testing?
The authoritative current product guidance is Cypress’s FAQ: it says Cypress cannot run on native mobile apps. Recheck that FAQ when evaluating future capability changes.
Can I use Cypress for React Native Web?
You can use Cypress for the browser-rendered web application surface. That does not cover native iOS or Android behavior.
Should I remove Cypress if my product is React Native?
Not if you also have browser surfaces that benefit from Cypress. Keep the web and installed-app responsibilities clear and select a native runner for native flows.
Which native runner is best?
The cited documentation does not establish a universal winner. Compare platform coverage, version compatibility, Expo/build integration, CI environment, and the flows you need to protect.
