React Native Testing Library

@testing-library/react-native (RNTL) prueba componentes de la forma en que los usuarios interactúan con ellos - por texto visible, roles de accesibilidad y etiquetas - no por detalles de implementación como estado interno o métodos privados.

Receta

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

import { useState } from "react";
import { render, screen, userEvent, waitFor } from "@testing-library/react-native";
import { Pressable, Text, TextInput, View } from "react-native";
 
function LoginForm({ onSubmit }: { onSubmit: (email: string) => void }) {
  const [email, setEmail] = useState("");
  return (
    <View>
      <TextInput
        accessibilityLabel="Email"
        value={email}
        onChangeText={setEmail}
      />
      <Pressable accessibilityRole="button" onPress={() => onSubmit(email)}>
        <Text>Iniciar sesión</Text>
      </Pressable>
    </View>
  );
}
 
test("envía email al presionar", async () => {
  const onSubmit = jest.fn();
  const user = userEvent.setup();
 
  render(<LoginForm onSubmit={onSubmit} />);
 
  await user.type(screen.getByLabelText("Email"), "alex@example.com");
  await user.press(screen.getByRole("button", { name: "Iniciar sesión" }));
 
  await waitFor(() => {
    expect(onSubmit).toHaveBeenCalledWith("alex@example.com");
  });
});

Cuándo utilizarlo:

• Componentes presentacionales que reciben props (ver Contenedor/Presentador en Móvil).
• Hooks personalizados a través de renderHook desde @testing-library/react-native.
• Formularios, listas y modales donde el texto visible para el usuario controla el comportamiento.
• Pruebas de integración de Expo Router con renderRouter desde expo-router/testing-library.

Ejemplo Funcional

// src/features/tasks/task-list.tsx
import { useCallback, useState } from "react";
import {
  ActivityIndicator,
  FlatList,
  Pressable,
  Text,
  View,
  type ListRenderItem,
} from "react-native";
 
export interface Task {
  id: string;
  title: string;
  done: boolean;
}
 
interface TaskListProps {
  tasks: Task[];
  loading: boolean;
  onToggle: (id: string) => void;
}
 
export function TaskList({ tasks, loading, onToggle }: TaskListProps) {
  const [error, setError] = useState<string | null>(null);
 
  const renderItem: ListRenderItem<Task> = useCallback(
    ({ item }) => (
      <Pressable
        accessibilityRole="checkbox"
        accessibilityState={{ checked: item.done }}
        onPress={() => onToggle(item.id)}
      >
        <Text>{item.title}</Text>
      </Pressable>
    ),
    [onToggle]
  );
 
  if (loading) {
    return (
      <View accessibilityLabel="Cargando tareas">
        <ActivityIndicator />
      </View>
    );
  }
 
  if (error) {
    return <Text role="alert">{error}</Text>;
  }
 
  if (tasks.length === 0) {
    return <Text>Sin tareas aún</Text>;
  }
 
  return (
    <FlatList
      data={tasks}
      keyExtractor={(item) => item.id}
      renderItem={renderItem}
    />
  );
}

// __tests__/task-list-test.tsx
import { render, screen, userEvent, waitFor } from "@testing-library/react-native";
import { TaskList, type Task } from "../src/features/tasks/task-list";
 
const TASKS: Task[] = [
  { id: "1", title: "Lanzar versión", done: false },
  { id: "2", title: "Escribir pruebas", done: true },
];
 
describe("<TaskList />", () => {
  test("muestra estado de carga", () => {
    render(<TaskList tasks={[]} loading onToggle={jest.fn()} />);
    expect(screen.getByLabelText("Cargando tareas")).toBeOnTheScreen();
  });
 
  test("muestra estado vacío", () => {
    render(<TaskList tasks={[]} loading={false} onToggle={jest.fn()} />);
    expect(screen.getByText("Sin tareas aún")).toBeOnTheScreen();
  });
 
  test("alterna una tarea a través del rol de casilla de verificación", async () => {
    const onToggle = jest.fn();
    const user = userEvent.setup();
 
    render(<TaskList tasks={TASKS} loading={false} onToggle={onToggle} />);
 
    const shipRelease = screen.getByRole("checkbox", { name: "Lanzar versión" });
    expect(shipRelease).toHaveAccessibilityState({ checked: false });
 
    await user.press(shipRelease);
 
    await waitFor(() => {
      expect(onToggle).toHaveBeenCalledWith("1");
    });
  });
 
  test("lista todos los títulos de tareas", () => {
    render(<TaskList tasks={TASKS} loading={false} onToggle={jest.fn()} />);
    expect(screen.getByText("Lanzar versión")).toBeOnTheScreen();
    expect(screen.getByText("Escribir pruebas")).toBeOnTheScreen();
  });
});

Lo que esto demuestra:

• Prioridad de consulta - getByLabelText para carga, getByRole("checkbox") para alternadores, getByText para copiar.
• userEvent.setup() - presión asincrona simula interacción real; siempre await.
• waitFor - aserta callbacks después de que React descarga actualizaciones en lugar de retrasos arbitrarios.
• toBeOnTheScreen / toHaveAccessibilityState - matchers RNTL registrados a través de importación (ver Configuración de Jest para Expo).
• Componente solo props - sin router, sin fetch, sin almacén global en la unidad bajo prueba.

Profundización

Cómo Funciona

• RNTL renderiza componentes con Test Renderer - un árbol del lado de JS que refleja componentes host de React Native (View, Text, Pressable).
• Las consultas caminan por el árbol renderizado buscando nodos que coincidan con accesibilidad y texto - las mismas señales en las que se basan la tecnología de asistencia y los usuarios.
• screen es un namespace vinculado al render() más reciente - vuelve a consultar después de actualizaciones de estado en lugar de cachear referencias de elementos de antes de re-renderizados.
• userEvent programa interacciones como un usuario real (presionar, escribir, desplazar) y devuelve promesas - fireEvent sincrónico aún existe pero userEvent es preferido para pruebas nuevas.
• Las utilidades asincronas (waitFor, findBy*) sondean hasta que las aserciones pasen o agoten el tiempo de espera - reemplazan la gimnasia manual de setTimeout + act.

Prioridad de Consulta en React Native

getBy* lanza si hay cero o muchas coincidencias. queryBy* devuelve null cuando está ausente (bueno para aserciones negativas). findBy* envuelve waitFor + getBy* para elementos que aparecen después del trabajo asincrónico.

Patrones Asincronos

// El elemento aparece después de fetch - prefiere findBy*
expect(await screen.findByText("Bienvenido de nuevo")).toBeOnTheScreen();
 
// Callback o mock invocado después de descarga de estado
await waitFor(() => {
  expect(onSubmit).toHaveBeenCalled();
});
 
// Múltiples aserciones después de una interacción
await user.press(screen.getByRole("button", { name: "Actualizar" }));
await waitFor(() => {
  expect(screen.getByText("Actualizado")).toBeOnTheScreen();
});

El tiempo de espera predeterminado de waitFor es 1000 ms - pasa { timeout: 3000 } para redes mocked lentas, no para timing de producción.

Expo Router: renderRouter

import { renderRouter, screen } from "expo-router/testing-library";
import { Text, View } from "react-native";
 
test("llega a la ruta de configuración", async () => {
  const Settings = () => (
    <View>
      <Text>Configuración</Text>
    </View>
  );
 
  renderRouter(
    { index: () => <Text>Inicio</Text>, settings: Settings },
    { initialUrl: "/settings" }
  );
 
  expect(screen).toHavePathname("/settings");
  expect(screen.getByText("Configuración")).toBeOnTheScreen();
});

• Los archivos de prueba deben vivir fuera de app/ - solo rutas y layouts pertenecen allí.
• renderRouter acepta mapas de rutas en línea, matrices de rutas de cadena o directorios de accesorios.
• Matchers personalizados: toHavePathname, toHaveSegments, useLocalSearchParams - ver documentos de prueba de Expo Router.

Notas de TypeScript

import { renderHook, act } from "@testing-library/react-native";
import { useCounter } from "../src/hooks/use-counter";
 
test("incrementa", () => {
  const { result } = renderHook(() => useCounter());
 
  act(() => {
    result.current.increment();
  });
 
  expect(result.current.count).toBe(1);
});

• renderHook escribe result.current desde el tipo de retorno del hook - sin casting manual.
• ListRenderItem<T> en componentes mantiene callbacks renderItem escritos tanto en la aplicación como en las pruebas.
• Habilita eslint-plugin-testing-library en archivos de prueba para detectar abuso de getByTestId y await faltante en userEvent.

Errores Comunes

• Referencias de elementos en caché después de rerender - Nodos obsoletos de antes de una actualización de estado causan fallas de "elemento no encontrado". Solución: Vuelve a consultar con screen.getBy* dentro de waitFor o limita las consultas al render más reciente.

• await faltante en userEvent - Presión y escritura son asincronos; olvidar await compite con aserciones. Solución: await user.press(...) y await user.type(...) en cada prueba.

• getByTestId como predeterminado - testID es invisible para los usuarios y diverge de cambios de copia. Solución: Agrega accessibilityLabel / accessibilityRole en componentes; reserva testID para elementos de lista o casos extremos de driver nativo.

• fireEvent para flujos complejos - fireEvent.press omite la canalización de eventos que userEvent ejercita. Solución: Prefiere userEvent.setup() para interacciones; mantén fireEvent para casos raros de bajo nivel.

• Pruebas de detalles de implementación - Asertir component.state.count o renderizados superficiales al estilo enzyme rompe en refactores. Solución: Aserta resultados visibles: texto, roles, callbacks, estado de accesibilidad.

• Elementos de FlatList no encontrados - Las listas virtualizadas pueden no montar filas fuera de pantalla. Solución: Pasa pequeñas matrices data en pruebas, establece initialNumToRender alto en un envoltorio de prueba o prueba componentes de fila de forma aislada.

• No importar RNTL en la configuración de Jest - Matchers como toBeOnTheScreen lanzan "matcher no encontrado". Solución: import "@testing-library/react-native" en jest.setup.ts (ver Configuración de Jest para Expo).

Alternativas

Preguntas Frecuentes

expect(screen.queryByText("Error")).toBeNull();
// o
expect(screen.queryByText("Error")).not.toBeOnTheScreen();

const user = userEvent.setup();
await user.type(screen.getByLabelText("Email"), "alex@example.com");

renderRouter(routes, { initialUrl: "/profile/42" });
expect(screen).toHavePathname("/profile/42");

import { render, screen, debug } from "@testing-library/react-native";
 
render(<MyComponent />);
screen.debug(); // imprime árbol host a consola

Relacionados

• Configuración de Jest para Expo - preset jest-expo y jest.setup.ts
• Mocking de Módulos Nativos - cuando las pruebas RNTL necesitan comportamiento nativo controlado
• Conceptos Básicos de Pruebas Móviles - donde las pruebas de componentes se sientan en la pirámide
• Contenedor/Presentador en Móvil - presentadores optimizados para RNTL
• Hooks Personalizados para Lógica de Interfaz de Usuario - patrones renderHook
• Maestro E2E - cuando las consultas en Jest no son suficientes

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