React Native Testing Library

@testing-library/react-native (RNTL) testa componentes da maneira como os usuários interagem com eles - por meio de texto visível, roles de acessibilidade e labels - não por detalhes de implementação como estado interno ou métodos privados.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

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>Sign in</Text>
      </Pressable>
    </View>
  );
}
 
test("submits email on press", 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: "Sign in" }));
 
  await waitFor(() => {
    expect(onSubmit).toHaveBeenCalledWith("alex@example.com");
  });
});

Quando usar isso:

• Componentes de apresentação que recebem props (veja Container/Presenter em Mobile).
• Hooks personalizados via renderHook de @testing-library/react-native.
• Formulários, listas e modais onde o texto visível ao usuário direciona o comportamento.
• Testes de integração do Expo Router com renderRouter de expo-router/testing-library.

Exemplo de Trabalho

// 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="Loading tasks">
        <ActivityIndicator />
      </View>
    );
  }
 
  if (error) {
    return <Text role="alert">{error}</Text>;
  }
 
  if (tasks.length === 0) {
    return <Text>No tasks yet</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: "Ship release", done: false },
  { id: "2", title: "Write tests", done: true },
];
 
describe("<TaskList />", () => {
  test("shows loading state", () => {
    render(<TaskList tasks={[]} loading onToggle={jest.fn()} />);
    expect(screen.getByLabelText("Loading tasks")).toBeOnTheScreen();
  });
 
  test("shows empty state", () => {
    render(<TaskList tasks={[]} loading={false} onToggle={jest.fn()} />);
    expect(screen.getByText("No tasks yet")).toBeOnTheScreen();
  });
 
  test("toggles a task via checkbox role", async () => {
    const onToggle = jest.fn();
    const user = userEvent.setup();
 
    render(<TaskList tasks={TASKS} loading={false} onToggle={onToggle} />);
 
    const shipRelease = screen.getByRole("checkbox", { name: "Ship release" });
    expect(shipRelease).toHaveAccessibilityState({ checked: false });
 
    await user.press(shipRelease);
 
    await waitFor(() => {
      expect(onToggle).toHaveBeenCalledWith("1");
    });
  });
 
  test("lists all task titles", () => {
    render(<TaskList tasks={TASKS} loading={false} onToggle={jest.fn()} />);
    expect(screen.getByText("Ship release")).toBeOnTheScreen();
    expect(screen.getByText("Write tests")).toBeOnTheScreen();
  });
});

O que isso demonstra:

• Prioridade de consulta - getByLabelText para carregamento, getByRole("checkbox") para alternância, getByText para cópia.
• userEvent.setup() - a pressão assíncrona simula a interação real; sempre await.
• waitFor - afirma callbacks após o React processar atualizações em vez de atrasos arbitrários.
• toBeOnTheScreen / toHaveAccessibilityState - matchers RNTL registrados via import (veja Configuração do Jest para Expo).
• Componente apenas com props - sem router, sem fetch, sem store global na unidade sob teste.

Mergulho Profundo

Como Funciona

• RNTL renderiza componentes com Test Renderer - uma árvore do lado do JS que espelha os componentes host do React Native (View, Text, Pressable).
• As consultas percorrem a árvore renderizada procurando por nós que correspondam à acessibilidade e ao texto - os mesmos sinais que a tecnologia assistiva e os usuários confiam.
• screen é um namespace vinculado à chamada render() mais recente - reconsulte após atualizações de estado em vez de armazenar em cache referências de elementos de antes das re-renderizações.
• userEvent agenda interações como um usuário real (pressionar, digitar, rolar) e retorna promessas - fireEvent síncrono ainda existe, mas userEvent é preferido para novos testes.
• Utilitários assíncronos (waitFor, findBy*) consultam até que as asserções passem ou expirem - eles substituem malabarismos manuais com setTimeout + act.

Prioridade de Consulta no React Native

getBy* lança um erro se houver zero ou muitas correspondências. queryBy* retorna null quando ausente (bom para asserções negativas). findBy* envolve waitFor + getBy* para elementos que aparecem após trabalho assíncrono.

Padrões Assíncronos

// Elemento aparece após o fetch - prefira findBy*
expect(await screen.findByText("Welcome back")).toBeOnTheScreen();
 
// Callback ou mock invocado após o processamento do estado
await waitFor(() => {
  expect(onSubmit).toHaveBeenCalled();
});
 
// Múltiplas asserções após uma interação
await user.press(screen.getByRole("button", { name: "Refresh" }));
await waitFor(() => {
  expect(screen.getByText("Updated")).toBeOnTheScreen();
});

O tempo limite padrão de waitFor é de 1000 ms - passe { timeout: 3000 } para redes simuladas lentas, não para tempo de produção.

Expo Router: renderRouter

import { renderRouter, screen } from "expo-router/testing-library";
import { Text, View } from "react-native";
 
test("lands on settings route", async () => {
  const Settings = () => (
    <View>
      <Text>Settings</Text>
    </View>
  );
 
  renderRouter(
    { index: () => <Text>Home</Text>, settings: Settings },
    { initialUrl: "/settings" }
  );
 
  expect(screen).toHavePathname("/settings");
  expect(screen.getByText("Settings")).toBeOnTheScreen();
});

• Arquivos de teste devem viver fora de app/ - apenas rotas e layouts pertencem lá.
• renderRouter aceita mapas de rotas inline, arrays de caminhos de string ou diretórios de fixtures.
• Matchers personalizados: toHavePathname, toHaveSegments, useLocalSearchParams - veja documentação de teste do Expo Router.

Notas TypeScript

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

• renderHook tipa result.current a partir do tipo de retorno do hook - sem casts manuais.
• ListRenderItem<T> em componentes mantém os callbacks de renderItem tipados tanto no aplicativo quanto nos testes.
• Habilite eslint-plugin-testing-library em arquivos de teste para capturar o uso excessivo de getByTestId e a falta de await em userEvent.

Armadilhas

• Referências de elementos em cache após re-renderização - Nós obsoletos de antes de uma atualização de estado causam inconsistências de "elemento não encontrado". Correção: Reconsulte com screen.getBy* dentro de waitFor, ou escopo as consultas para a renderização mais recente.

• Falta de await em userEvent - Pressionar e digitar são assíncronos; esquecer await causa corridas nas asserções. Correção: await user.press(...) e await user.type(...) em todos os testes.

• getByTestId como padrão - testID é invisível para os usuários e se desvia das alterações de cópia. Correção: Adicione accessibilityLabel / accessibilityRole nos componentes; reserve testID para itens de lista ou casos extremos de driver nativo.

• fireEvent para fluxos complexos - fireEvent.press ignora o pipeline de eventos que userEvent exercita. Correção: Prefira userEvent.setup() para interações; mantenha fireEvent para casos raros de baixo nível.

• Testando detalhes de implementação - Afirmar component.state.count ou renderizações rasas no estilo enzyme quebram em refatorações. Correção: Afirme resultados visíveis: texto, roles, callbacks, estado de acessibilidade.

• Itens FlatList não encontrados - Listas virtualizadas podem não montar linhas fora da tela. Correção: Passe pequenos arrays data em testes, defina initialNumToRender alto em um wrapper de teste ou teste componentes de linha isoladamente.

• Não importar RNTL na configuração do Jest - Matchers como toBeOnTheScreen lançam "matcher não encontrado". Correção: import "@testing-library/react-native" em jest.setup.ts (veja Configuração do Jest para Expo).

Alternativas

FAQs

expect(screen.queryByText("Error")).toBeNull();
// ou
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 a árvore de host no console

Relacionados

• Configuração do Jest para Expo - preset jest-expo e jest.setup.ts
• Mocking de Módulos Nativos - quando testes RNTL precisam de comportamento nativo controlado
• Noções Básicas de Teste Mobile - onde os testes de componentes se encaixam na pirâmide
• Container/Presenter em Mobile - apresentadores otimizados para RNTL
• Hooks Personalizados para Lógica de UI - padrões renderHook
• Maestro E2E - quando consultas em Jest não são suficientes

Versões da Stack: Esta página foi escrita para React 19.2.3, React Native 0.86.0 e Expo SDK 57 (expo ~57.0.4).