Test Helpers

vitest-native ships a small set of helpers for controlling device state inside a test — dimensions, color scheme, safe-area insets, and native modules. Import them from vitest-native/helpers.

import {
  setDimensions,
  setColorScheme,
  setInsets,
  mockNativeModule,
  resetAllMocks,
} from 'vitest-native/helpers'

All helpers work under both engines, with two exceptions: setPlatform and the Keyboard and AppState simulation methods are mock-engine-only (see below).

setPlatform(os)

Mock engine only

Under the default native engine, setPlatform() throws: the platform is baked in when the real React Native module graph loads (Platform.ios/Platform.android and every .ios.ts/.android.ts file have already been selected). Set it in config instead — reactNative({ platform: 'android' }) — or run both platforms as separate Vitest projects.

Switch the platform for a test (mock engine). Affects Platform.OS and platform-specific behavior.

setPlatform('android')

setDimensions(dimensions)

Override the screen dimensions reported by Dimensions and useWindowDimensions.

setDimensions({ width: 768, height: 1024 })

setColorScheme(scheme)

Switch the color scheme reported by Appearance and useColorScheme.

setColorScheme('dark')

setInsets(insets)

Override the safe-area insets reported by the auto-detected react-native-safe-area-context preset. Under the mock engine they reach useSafeAreaInsets, the insets context and initialWindowMetrics. Under the native engine the preset is the library's own Jest mock, and setInsets reaches useSafeAreaInsets only; to give every consumer (SafeAreaInsetsContext, withSafeAreaInsets) the same insets there, render under <SafeAreaProvider initialMetrics={...}>, as the library's testing guide does. No-op when the preset isn't active; undone by resetAllMocks().

setInsets({ top: 59, bottom: 34, left: 0, right: 0 })

mockNativeModule(name, impl)

Provide a mock implementation for a native module. The module becomes present for NativeModules[name], TurboModuleRegistry.get(name) and TurboModuleRegistry.getEnforcing(name). Under the native engine, a module no app registers is otherwise absent from the first two lookups, as on a device — see which native modules exist.

mockNativeModule('MyNativeModule', {
  getValue: () => Promise.resolve(42),
  doSomething: () => {},
})

extendPresetMock(pkg, overrides)

Merge overrides into a preset's module mock (and its default export, when that is an object) — for example to give expo-constants a real expoConfig, or to add an export a library calls that the preset does not model. Returns false when no preset mock exists for the package. Undone by resetAllMocks().

extendPresetMock('expo-constants', {
  expoConfig: { name: 'my-app', scheme: 'my-app' },
})

resetAllMocks()

Reset plugin-controlled state and clear all spies. Under the mock engine that restores the mock's defaults (iOS, 390×844, light mode). Under the native engine it restores the configured platform's initial dimensions and colour scheme. Both engines reset active preset stores and undo mockNativeModule and extendPresetMock calls. Call it in an afterEach to keep tests isolated:

import { afterEach } from 'vitest'
import { resetAllMocks } from 'vitest-native/helpers'

afterEach(() => resetAllMocks())

Under the mock engine this also resets the Keyboard and AppState state described below.

Keyboard & AppState helpers

Mock engine only

These methods exist on the mock engine's Keyboard and AppState. Under the native engine those are React Native's real modules, which have no _show, _hide or _setState.

The Keyboard and AppState mocks include internal helpers for simulating state changes, useful for testing listeners:

import { Keyboard, AppState } from 'react-native'

// Simulate keyboard show/hide (fires keyboardDidShow / keyboardDidHide listeners)
;(Keyboard as any)._show(336) // height in pixels
;(Keyboard as any)._hide()

// Simulate app state change (fires 'change' listeners)
;(AppState as any)._setState('background')

These are reset automatically by resetAllMocks().

Next: jest-compat Layer or the API Coverage reference.