Mockeo de Módulos Nativos

Jest se ejecuta en Node - no hay cámara, GPS o Keychain. jest-expo proporciona stubs para la mayoría de los módulos del Expo SDK con valores por defecto seguros; añades mocks manuales cuando tus tests necesitan resultados de permisos específicos, lecturas de sensores o comportamiento de SDKs nativos de terceros.

Receta

Tarjeta de referencia rápida - lista para copiar y pegar.

// __tests__/location-screen-test.tsx
import { render, screen, waitFor } from "@testing-library/react-native";
import * as Location from "expo-location";
import { LocationScreen } from "../src/screens/location-screen";
 
jest.mock("expo-location");
 
const mockLocation = jest.mocked(Location);
 
beforeEach(() => {
  mockLocation.requestForegroundPermissionsAsync.mockResolvedValue({
    status: "granted",
    granted: true,
    canAskAgain: true,
    expires: "never",
  });
 
  mockLocation.getCurrentPositionAsync.mockResolvedValue({
    coords: { latitude: 37.77, longitude: -122.42, altitude: 0, accuracy: 5, altitudeAccuracy: 5, heading: 0, speed: 0 },
    timestamp: 1_700_000_000_000,
  });
});
 
test("shows coordinates when permission is granted", async () => {
  render(<LocationScreen />);
  expect(await screen.findByText(/37\.77/)).toBeOnTheScreen();
  await waitFor(() => {
    expect(mockLocation.getCurrentPositionAsync).toHaveBeenCalled();
  });
});

Cuándo usarlo:

• Los componentes llaman a expo-location, expo-notifications, expo-secure-store u otros bridges nativos.
• Módulos Expo personalizados o módulos nativos de React Native que tu app importa directamente.
• Simular denegación de permisos, fallos de almacenamiento offline o códigos de error del SDK.
• Espiar llamadas a módulos para afirmar que tu app reacciona correctamente - no para evitar escribir aserciones.

Ejemplo Completo

// src/services/push-token-service.ts
import * as Notifications from "expo-notifications";
import * as Device from "expo-device";
 
export async function registerForPushNotifications(): Promise<string | null> {
  if (!Device.isDevice) {
    return null;
  }
 
  const { status: existing } = await Notifications.getPermissionsAsync();
  let finalStatus = existing;
 
  if (existing !== "granted") {
    const { status } = await Notifications.requestPermissionsAsync();
    finalStatus = status;
  }
 
  if (finalStatus !== "granted") {
    throw new Error("Push permission denied");
  }
 
  const token = await Notifications.getExpoPushTokenAsync();
  return token.data;
}

// __tests__/push-token-service-test.tsx
import * as Notifications from "expo-notifications";
import * as Device from "expo-device";
import { registerForPushNotifications } from "../src/services/push-token-service";
 
jest.mock("expo-notifications");
jest.mock("expo-device");
 
const notifications = jest.mocked(Notifications);
const device = jest.mocked(Device);
 
describe("registerForPushNotifications", () => {
  beforeEach(() => {
    jest.clearAllMocks();
    device.isDevice = true;
  });
 
  test("returns token when permission already granted", async () => {
    notifications.getPermissionsAsync.mockResolvedValue({
      status: "granted",
      granted: true,
      canAskAgain: true,
      expires: "never",
    });
    notifications.getExpoPushTokenAsync.mockResolvedValue({
      data: "ExponentPushToken[abc]",
      type: "expo",
    });
 
    await expect(registerForPushNotifications()).resolves.toBe(
      "ExponentPushToken[abc]"
    );
    expect(notifications.requestPermissionsAsync).not.toHaveBeenCalled();
  });
 
  test("requests permission when not yet granted", async () => {
    notifications.getPermissionsAsync.mockResolvedValue({
      status: "undetermined",
      granted: false,
      canAskAgain: true,
      expires: "never",
    });
    notifications.requestPermissionsAsync.mockResolvedValue({
      status: "granted",
      granted: true,
      canAskAgain: true,
      expires: "never",
    });
    notifications.getExpoPushTokenAsync.mockResolvedValue({
      data: "ExponentPushToken[xyz]",
      type: "expo",
    });
 
    await expect(registerForPushNotifications()).resolves.toBe(
      "ExponentPushToken[xyz]"
    );
    expect(notifications.requestPermissionsAsync).toHaveBeenCalledTimes(1);
  });
 
  test("throws when permission denied", async () => {
    notifications.getPermissionsAsync.mockResolvedValue({
      status: "denied",
      granted: false,
      canAskAgain: false,
      expires: "never",
    });
 
    await expect(registerForPushNotifications()).rejects.toThrow(
      "Push permission denied"
    );
  });
 
  test("returns null on simulator", async () => {
    device.isDevice = false;
 
    await expect(registerForPushNotifications()).resolves.toBeNull();
    expect(notifications.getPermissionsAsync).not.toHaveBeenCalled();
  });
});

Lo que esto demuestra:

• jest.mock("expo-*") - reemplaza el módulo con funciones auto-mockeadas que configuras por test.
• jest.mocked() - acceso tipado a implementaciones mock en TypeScript.
• Tests de capa de servicio - llamadas nativas aisladas en un módulo; los tests de UI mockean el servicio en lugar de tres paquetes Expo.
• Ramas de permisos explícitas - cada estado (granted, denied, undetermined) obtiene su propio test.
• jest.clearAllMocks() en beforeEach - previene fugas de conteo de llamadas entre tests.

Análisis Profundo

Cómo Funciona

• Preset jest-expo instala mocks por defecto para módulos Expo para que las importaciones no causen crash en Jest. Los valores por defecto devuelven promesas resueltas con formas de "éxito" genéricas - raramente coincidiendo con tus casos edge de producción.
• jest.mock("module-name") se levanta hacia la parte superior del archivo e intercambia el módulo antes de que tus importaciones se evalúen. Funciona para expo-*, @react-native-async-storage/async-storage y módulos locales de la app.
• Mocks manuales en __mocks__/ junto al nombre de paquete de node_modules o archivo de src/ se aplican cuando llamas jest.mock sin una factory.
• Patrón spy - jest.spyOn(module, "fn") envuelve una sola función mientras deja el resto real (cuando no está completamente mockeado).
• Mockeo de límite - mockea src/services/api.ts, no fetch ni cada importación transitiva, a menos que estés testeando el cliente HTTP en sí.

Lo que jest-expo Mockea vs Lo que Debes Mockear

Patrones de Mock Manual

Factory inline (por archivo de test):

jest.mock("expo-secure-store", () => ({
  getItemAsync: jest.fn(),
  setItemAsync: jest.fn(),
  deleteItemAsync: jest.fn(),
}));

Archivo de mock manual compartido:

src/
  services/
    analytics.ts
  __mocks__/
    analytics.ts      # mock manual - jest.mock("../services/analytics") lo recoge

// src/__mocks__/analytics.ts
export const trackEvent = jest.fn();
export const identifyUser = jest.fn();

Re-exportar módulo real con un spy:

jest.mock("expo-linking", () => {
  const actual = jest.requireActual<typeof import("expo-linking")>("expo-linking");
  return {
    ...actual,
    openURL: jest.fn(actual.openURL),
  };
});

Evitar Falsa Confianza

Trata los mocks nativos de Jest como tests de contrato para tu reacción JS - no como prueba de que el bridge nativo funciona. Añade Maestro E2E o QA manual para diálogos de permisos y rutas de hardware.

Notas de TypeScript

import type { LocationObject } from "expo-location";
 
function buildLocation(overrides: Partial<LocationObject> = {}): LocationObject {
  return {
    coords: {
      latitude: 0,
      longitude: 0,
      altitude: 0,
      accuracy: 0,
      altitudeAccuracy: 0,
      heading: 0,
      speed: 0,
    },
    timestamp: Date.now(),
    ...overrides,
  };
}
 
mockLocation.getCurrentPositionAsync.mockResolvedValue(
  buildLocation({ coords: { latitude: 51.5, longitude: -0.12, altitude: 0, accuracy: 1, altitudeAccuracy: 1, heading: 0, speed: 0 } })
);

• Importa tipos del paquete real incluso cuando la implementación está mockeada.
• Usa jest.mocked(fn) en lugar de (fn as jest.Mock) para tipado más estricto.
• Las mocks factory pueden llamar a jest.requireActual para preservar exportaciones unmockeadas y reducir drift.

Errores Comunes

• Asumir que los valores por defecto de jest-expo coinciden con tu test - Los mocks de permisos por defecto frecuentemente devuelven granted. Los tests nunca ejercen rutas de denegación a menos que sobrescribas explícitamente. Solución: Establece mockResolvedValue para cada escenario de permiso/estado explícitamente.

• Mockear demasiado profundo - Mockear internals de react-native o cada importación de expo-* hace tests frágiles cuando cambios del SDK alteran firmas. Solución: Mockea tu límite de servicio; mantén un módulo responsable de llamadas nativas.

• Olvidar jest.clearAllMocks() - Los conteos de llamadas e implementaciones encoladas se filtran entre tests. Solución: afterEach en jest.setup.ts o beforeEach en bloques describe que usan spies.

• jest.requireActual después de mock completo - Esparcir requireActual para módulos nativos puede traer bindings nativos reales a Jest y causar crash. Solución: Mockea solo las funciones que llamas; evita requireActual en módulos que tocan código nativo.

• Falsa confianza de suites verdes - Todo comportamiento nativo es fake; la producción aún falla en un dispositivo real. Solución: Documenta qué flujos necesitan Maestro o chequeos de dispositivo manual en plantillas de PR.

• import() dinámico eludiendo mocks - Las importaciones lazy pueden resolverse antes de que jest.mock se aplique si están mal ordenadas. Solución: Usa importaciones estáticas en código bajo test, o jest.unstable_mockModule para rutas de importación dinámica ESM.

• Duplicar configuración de mock en cada archivo - Los mocks de expo-font copiados-pegados derivan. Solución: Helpers compartidos en test-utils/native-mocks.ts o mocks globales en jest.setup.ts para módulos de app-wide (fonts, pantalla de splash).

Alternativas

FAQs

jest.mock("@react-native-async-storage/async-storage", () =>
  require("@react-native-async-storage/async-storage/jest/async-storage-mock")
);

jest.mock("expo-linking", () => ({
  ...jest.requireActual("expo-linking"),
  openURL: jest.fn(() => Promise.resolve(true)),
}));

mockLocation.requestForegroundPermissionsAsync.mockResolvedValue({
  status: "denied",
  granted: false,
  canAskAgain: false,
  expires: "never",
});

afterEach(() => {
  jest.clearAllMocks(); // limpia historial de llamadas
  // jest.resetAllMocks(); // también reinicia implementaciones - úsalo cuando tests sobrescriben mockResolvedValue
});

Relacionado

• Jest Setup for Expo - preset jest-expo y setup global
• React Native Testing Library - afirma UI después de que los mocks se resuelven
• Mobile Testing Basics - qué pertenece en capas unit vs E2E
• Maestro E2E - flujos de dispositivo real que los mocks no pueden reemplazar
• Expo Modules Core - cómo módulos nativos exponen APIs JS
• Native Modules Basics - bridges personalizados que siempre necesitan mocks manuales

Versiones de Stack: Esta página fue escrita para React 19.2.3, React Native 0.86.0, y Expo SDK 57 (expo ~57.0.4).