vitest-mobile

Run Vitest component tests inside a real React Native app. Tests execute using real native views and real touch events, not mocked renderers or simulated interactions.

The pool boots an emulator/simulator, launches a React Native app, connects over WebSocket, and sends test files to run.

Table of Contents

• Prerequisites
• Quick Start
• Vitest Config
• Writing Tests
• Test API Reference
• CLI Reference
• CI/CD
• Troubleshooting

Prerequisites

Tool	Version	Notes
Node.js	>= 18	LTS recommended
npm	>= 9	Ships with Node 18+
Xcode	>= 15	iOS only — includes xcrun simctl
Android SDK	API 35	Android only — includes adb, avdmanager
Java	17 (Temurin)	Android only
Vitest	^4.0	Peer dependency
React Native	>= 0.81.5	New Architecture (Fabric + TurboModules) required

Quick Start

Install the package:

npm install vitest-mobile

Create a vitest.config.ts at the root of your project with the nativePlugin:

import { defineConfig } from 'vitest/config';
import { nativePlugin } from 'vitest-mobile';

export default defineConfig({
  test: {
    projects: [
      {
        plugins: [nativePlugin({ platform: 'ios' })],
        test: {
          name: 'ios',
          include: ['test-packages/**/tests/**/*.test.tsx'],
        },
      },
      {
        plugins: [nativePlugin({ platform: 'android' })],
        test: {
          name: 'android',
          include: ['test-packages/**/tests/**/*.test.tsx'],
        },
      },
    ],
  },
});

Bootstrap the test harness app and run the tests:

# Generate, build, and install the test harness app (~5 min first build)
npx vitest-mobile bootstrap --platform ios

# Run tests
npx vitest run --project ios

For Android:

# Generate, build, and install the test harness app (~5 min first build)
npx vitest-mobile bootstrap --platform android
npx vitest run --project android

Writing Tests

Tests look like standard Vitest tests, but use vitest-mobile/runtime for rendering into real native views:

import React from 'react';
import { describe, it, expect, afterEach } from 'vitest';
import { render, cleanup, waitFor } from 'vitest-mobile/runtime';
import { CounterModule } from '../CounterModule';

afterEach(async () => {
  await cleanup();
});

describe('CounterModule', () => {
  it('renders initial count of zero', async () => {
    const screen = await render(<CounterModule userId="123" />);
    await expect.element(screen.getByTestId('count-display')).toHaveText('0');
  });

  it('increments on press', async () => {
    const screen = await render(<CounterModule userId="123" />);
    await screen.getByTestId('increment-btn').tap();
    await expect.element(screen.getByTestId('count-display')).toHaveText('1');
  });
});

Test API Reference

Rendering

import { render, cleanup, waitFor, screenshot, pause } from 'vitest-mobile/runtime';

Function	Description
render(<Component />)	Mount a component into the test container. Returns a Screen with locator methods.
cleanup()	Unmount the rendered component and flush the UI queue.
waitFor(fn, opts?)	Retry an assertion until it passes. Default 3s timeout, 50ms interval.
pause({ label?, screenshot? })	Block test execution until resumed.

Screen

Method	Description
screen.getByTestId(id)	Find element by testID. Returns Locator. Throws if not found.
screen.getByText(text)	Find element containing text. Returns Locator.
screen.getAllByTestId(id)	Find all matching elements.
screen.queryByTestId(id)	Returns Locator | null (no throw).
screen.findByTestId(id)	Async — waits until element appears.
screen.findByText(text)	Async — waits until text appears.
screen.dumpTree()	Returns an indented text representation of the view tree.
screen.getTree()	Returns a structured ViewTreeNode object.

Locator

Method	Description
locator.tap()	Dispatch a real native tap event via the TurboModule.
locator.longPress()	Dispatch a real native long press.
locator.type(text)	Type text into a focused input via native text input.
locator.text	Current text content (sync, re-queries on access).
locator.exists	Whether the element is in the tree.

Custom Matchers

Matcher	Description
expect(locator).toBeVisible()	Element exists and is not hidden.
expect(locator).toHaveText('...')	Text content matches exactly.
expect(locator).toContainText('...')	Text content contains the string.

Use expect.element(locator) for automatic retrying:

await expect.element(screen.getByTestId('count')).toHaveText('1');

CLI Reference

All commands are run via npx vitest-mobile <command>.

Device & App Lifecycle

# Boot a simulator / emulator
npx vitest-mobile boot-device --platform ios
npx vitest-mobile boot-device --platform android

# Build the native harness binary (~5 min first time, cached after)
npx vitest-mobile build --platform ios
npx vitest-mobile build --platform android

# Install the built binary onto the device
npx vitest-mobile install --platform ios

# Build + install in one step
npx vitest-mobile bootstrap --platform ios
npx vitest-mobile bootstrap --platform android --headless --api-level 35

Debugging & Inspection

# Evaluate a JS expression in the running app via CDP
npx vitest-mobile debug eval "<expression>"

# Open the JS debugger
npx vitest-mobile debug open

# Take a screenshot of the simulator
npx vitest-mobile screenshot --platform ios

Running Tests

# Run all tests on iOS
npx vitest run --project ios

# Run all tests on Android
npx vitest run --project android

# Watch mode (re-runs on file changes)
npx vitest --project ios

Useful CDP Eval Expressions

# Check test file registry
npx vitest-mobile debug eval "JSON.stringify(Object.keys(globalThis.__TEST_FILES__ || {}))"

# Check if a test module has the babel plugin's __run wrapper
npx vitest-mobile debug eval "(function() { var f = globalThis.__TEST_FILES__; var m = f && f['counter/counter.test.tsx'](); return JSON.stringify({ hasRun: typeof m?.__run, keys: Object.keys(m || {}) }); })()"

CI/CD

To add vitest-mobile E2E tests to your CI pipeline:

Android

name: Native Tests (Android)
on: [push, pull_request]

jobs:
  e2e-android:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: 17

      - run: npm ci

      # Enable KVM for hardware-accelerated Android emulator
      - name: Enable KVM
        run: |
          echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' \
            | sudo tee /etc/udev/rules.d/99-kvm4all.rules
          sudo udevadm control --reload-rules
          sudo udevadm trigger --name-match=kvm

      # Build native binary, boot emulator, install app
      - run: npx vitest-mobile bootstrap --platform android --headless --api-level 35

      # Pre-build the JS bundle for faster test startup
      - run: npx vitest-mobile bundle --platform android

      # Run tests
      - run: npx vitest run --project android

iOS

name: Native Tests (iOS)
on: [push, pull_request]

jobs:
  e2e-ios:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm

      - run: npm ci
      - run: npx vitest-mobile bootstrap --platform ios --headless
      - run: npx vitest-mobile bundle --platform ios
      - run: npx vitest run --project ios

Adding Build Caching

To avoid rebuilding the native binary on every CI run, cache the ~/.cache/vitest-mobile directory. The cache-key command generates a deterministic key:

- name: Compute cache key
  id: cache-key
  run: echo "key=android-e2e-$(npx vitest-mobile cache-key --platform android)" >> "$GITHUB_OUTPUT"

- uses: actions/cache/restore@v4
  with:
    path: ~/.cache/vitest-mobile
    key: ${{ steps.cache-key.outputs.key }}
    restore-keys: android-e2e-

# ... bootstrap + test steps ...

- uses: actions/cache/save@v4
  with:
    path: ~/.cache/vitest-mobile
    key: ${{ steps.cache-key.outputs.key }}

For Android, also cache the system image to avoid re-downloading:

path: |
  ~/.cache/vitest-mobile
  /usr/local/lib/android/sdk/system-images/android-35

Troubleshooting

"Requiring unknown module NNN"

Module code is not in the bundle. Caused by lazy bundling or missing static dependencies. Try clearing the Metro cache:

npx expo start --dev-client --clear

"Vitest failed to find the current suite"

describe()/it() called without runner context. The babel plugin should prevent this. Check:

1. Clear Metro cache
2. Verify the test file is being transformed (check for exports.__run in the bundled output)

App crashes on reload

The dev client sometimes serves a 1-module bundle. Workaround — terminate and relaunch:

xcrun simctl terminate booted com.vitest.mobile.harness
xcrun simctl launch booted com.vitest.mobile.harness --initialUrl "http://127.0.0.1:8081"

"No development build installed"

Rebuild the native binary:

npx vitest-mobile bootstrap --platform ios

License

MIT