Mis à jour en octobre 2026 · Lecture : 25 min · React Native 0.88, React 19, TypeScript
Un écran de connexion qui valide l'e-mail, appelle l'API, range le jeton et formate le nom de l'utilisateur fonctionne très bien… jusqu'au jour où l'API change, où il faut le tester sans simulateur, ou où une deuxième application doit réutiliser la même logique. La Clean Architecture répond à ce problème en séparant le code en couches dont les dépendances vont toutes dans le même sens.
Cet article construit pas à pas une fonctionnalité de connexion complète en React Native et TypeScript : entités, cas d'utilisation, repository, injection des dépendances, hook, écran et tests. Le code de l'exemple, hors l'écran du début (incomplet par nature), a été compilé et testé avec React Native 0.88, React 19.3, TypeScript 7 et React Native Testing Library 14.
Points essentiels à retenir :
- Le code se range en cercles : entités au centre, puis cas d'utilisation, adaptateurs, et frameworks à l'extérieur.
- Les dépendances pointent toujours vers le centre : le domaine n'importe ni React Native, ni
fetch, ni une bibliothèque de stockage. - Le domaine déclare des interfaces (ports) ; la couche data les implémente (inversion de dépendance).
- Une racine de composition est le seul endroit qui assemble les classes concrètes.
- Chaque couche se teste isolément, du cas d'utilisation (Jest seul) à l'écran (React Native Testing Library).
1. Le problème : l'écran qui fait tout
L'essentiel : quand un écran mélange règles métier, réseau et stockage, chaque changement technique touche le métier, et rien ne se teste sans tout le reste.
Voici un écran de connexion typique d'un premier projet. Il fonctionne, mais chaque ligne commentée appartient à un sujet différent :
// LoginScreen.tsx – tout au même endroit
export function LoginScreen() {
const [email, setEmail] = useState('');
const [password, setPassword] = useState('');
const [error, setError] = useState('');
async function onSubmit() {
if (!email.includes('@')) return setError('E-mail invalide'); // règle métier
const res = await fetch('https://api.example.com/auth/login', { // réseau
method: 'POST',
body: JSON.stringify({ email, password }),
});
if (res.status === 401) return setError('Identifiants incorrects'); // détail HTTP
const json = await res.json();
await AsyncStorage.setItem('token', json.access_token); // stockage
navigation.navigate('Home', { name: json.user.full_name }); // format de l'API
}
// … puis le JSX
}
Les conséquences sont concrètes :
- Tester la règle « e-mail valide » oblige à rendre un écran et à simuler
fetchet AsyncStorage. - Renommer
full_namecôté API modifie un écran, alors que rien n'a changé pour l'utilisateur. - Le jeton est stocké en clair : AsyncStorage n'est pas chiffré, et ce choix est enfoui dans l'interface.
- Une deuxième application (web, tablette, back-office) ne peut rien réutiliser.
2. La règle de dépendance
L'essentiel : un cercle intérieur ne connaît jamais le nom d'un élément d'un cercle extérieur. Le métier est au centre ; les outils sont à la périphérie et peuvent changer sans le toucher.
Robert C. Martin a formalisé la Clean Architecture en 2012, en synthèse de l'architecture hexagonale (Alistair Cockburn) et de l'architecture en oignon (Jeffrey Palermo). Son schéma représente le code en cercles concentriques, ici dessinés en cadres imbriqués. Appliqué à une application React Native, il donne ceci :
Chaque cercle a un rôle précis :
| Cercle | Contenu dans l'exemple | Peut importer |
|---|---|---|
| Entités | User, règles comme canManageUsers, erreurs métier | Rien d'autre que du TypeScript |
| Cas d'utilisation | LoginUseCase, ports comme AuthRepository | Les entités |
| Adaptateurs | AuthRepositoryImpl, userMapper, useLogin | Cas d'utilisation et entités |
| Frameworks et pilotes | Composants React Native, fetch, expo-secure-store | Tout |
Dans la pratique, on regroupe souvent ces cercles en trois couches de dossiers : domain (entités et cas d'utilisation), data (accès aux données) et presentation (hooks et écrans). C'est le découpage utilisé dans la suite.
L'inversion de dépendance, le mécanisme central
À l'exécution, l'appel descend de l'écran jusqu'au réseau. Pourtant, dans le code, la couche data dépend du domaine, et pas l'inverse. Le domaine déclare une interface (un port) qui décrit ce dont il a besoin ; la couche data fournit une classe qui la respecte (un adaptateur). C'est comparable à une prise électrique normalisée : l'appareil impose la forme de la prise, et n'importe quel adaptateur conforme peut s'y brancher sans que l'appareil change.
La flèche pointillée remonte : AuthRepositoryImpl connaît AuthRepository, mais LoginUseCase ignore tout de AuthRepositoryImpl. Remplacer l'API REST par GraphQL ou par un cache local ne change donc aucune ligne du domaine.
3. Organiser les dossiers
L'essentiel : découpez d'abord par fonctionnalité, puis par couche à l'intérieur de chaque fonctionnalité. Le découpage par couche seul convient aux petites applications.
Le découpage le plus simple sépare les couches à la racine :
src/
├── domain/ # entités, erreurs, ports, cas d'utilisation
├── data/ # API, stockage, repositories, mappers
├── presentation/ # écrans, composants, hooks
└── di/ # racine de composition
Il devient pénible au-delà de quelques fonctionnalités : modifier la connexion fait ouvrir trois dossiers éloignés. Le découpage par fonctionnalité regroupe ce qui change ensemble :
src/
├── features/
│ ├── auth/
│ │ ├── domain/
│ │ │ ├── User.ts
│ │ │ ├── errors.ts
│ │ │ ├── AuthRepository.ts
│ │ │ └── LoginUseCase.ts
│ │ ├── data/
│ │ │ ├── AuthApi.ts
│ │ │ ├── userMapper.ts
│ │ │ ├── TokenStorage.ts
│ │ │ └── AuthRepositoryImpl.ts
│ │ └── presentation/
│ │ ├── useLogin.ts
│ │ └── LoginScreen.tsx
│ └── profile/ # même découpage
├── shared/ # code commun (client HTTP, UI de base)
└── di/
├── DependenciesContext.tsx
└── createDependencies.ts
| Situation | Découpage conseillé |
|---|---|
| Prototype, moins de 5 écrans | Par couche, voire sans Clean Architecture |
| Application qui grandit, plusieurs développeurs | Par fonctionnalité, couches à l'intérieur |
| Logique partagée avec un site web | Domaine dans un paquet séparé d'un monorepo |
Avec Expo Router, les routes vivent dans src/app/ (ou app/). Gardez ces fichiers minces : ils ne font que désigner l'écran à afficher. C'est aussi pour cette raison que la racine de composition est rangée dans src/di/ et non dans src/app/, réservé aux routes.
// src/app/login.tsx – fichier de route Expo Router, sans aucune logique
// (alias « @/ » → « src/ » déclaré dans tsconfig.json)
export { LoginScreen as default } from '@/features/auth/presentation/LoginScreen';
4. La couche domain
L'essentiel : du TypeScript pur. Les entités portent les règles métier, les ports décrivent les besoins, les cas d'utilisation orchestrent une action. Aucun import de React, React Native ou bibliothèque réseau.
Les entités
Une entité n'est pas qu'une forme de données : elle porte les règles qui restent vraies quelle que soit l'interface. readonly empêche une couche extérieure de modifier un utilisateur par erreur.
export type Role = 'admin' | 'user';
export interface User {
readonly id: string;
readonly email: string;
readonly name: string;
readonly role: Role;
}
// Règle métier : elle vit avec l'entité, pas dans un écran
export function canManageUsers(user: User): boolean {
return user.role === 'admin';
}
Les erreurs métier
Le domaine définit ses propres erreurs. Les couches extérieures traduiront les erreurs techniques (HTTP 401, coupure réseau) en ces erreurs-là.
export class InvalidEmailError extends Error {
name = 'InvalidEmailError';
}
export class InvalidCredentialsError extends Error {
name = 'InvalidCredentialsError';
}
export class NetworkError extends Error {
name = 'NetworkError';
}
Le port AuthRepository
import type { User } from './User';
export interface Credentials {
email: string;
password: string;
}
// Port : le domaine dit ce dont il a besoin, la couche data dit comment
export interface AuthRepository {
login(credentials: Credentials): Promise<User>;
logout(): Promise<void>;
getCurrentUser(): Promise<User | null>;
}
Le cas d'utilisation
Un cas d'utilisation représente une action de l'utilisateur. Il reçoit ses dépendances par le constructeur, ce qui permet de lui donner une fausse implémentation dans les tests.
import type { AuthRepository, Credentials } from './AuthRepository';
import type { User } from './User';
import { InvalidEmailError } from './errors';
const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
export class LoginUseCase {
constructor(private readonly authRepository: AuthRepository) {}
async execute({ email, password }: Credentials): Promise<User> {
const normalizedEmail = email.trim().toLowerCase();
if (!EMAIL_PATTERN.test(normalizedEmail)) {
throw new InvalidEmailError();
}
return this.authRepository.login({ email: normalizedEmail, password });
}
}
La normalisation de l'e-mail est une règle métier : elle doit s'appliquer que la connexion vienne de l'écran, d'un lien magique ou d'un test. Sa place est donc ici, pas dans le composant.
5. La couche data
L'essentiel : elle parle à l'API et au stockage, convertit les données de l'API en entités (mapper) et traduit les erreurs techniques en erreurs métier. Rien de ce qui est propre à HTTP ne la dépasse.
La source de données
Les DTO (Data Transfer Objects) décrivent exactement ce que renvoie l'API, avec ses noms (full_name) et ses types (id numérique). Ils restent dans cette couche. L'exemple utilise fetch, intégré à React Native ; avec axios, seul ce fichier changerait.
// Forme des données renvoyées par l'API (et non forme du métier)
export interface UserDto {
id: number;
email: string;
full_name: string;
role: string;
}
export interface LoginResponseDto {
access_token: string;
user: UserDto;
}
export class HttpError extends Error {
name = 'HttpError';
constructor(readonly status: number) {
super(`HTTP ${status}`);
}
}
export class AuthApi {
constructor(private readonly baseUrl: string) {}
async login(email: string, password: string): Promise<LoginResponseDto> {
const response = await fetch(`${this.baseUrl}/auth/login`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ email, password }),
});
if (!response.ok) throw new HttpError(response.status);
return (await response.json()) as LoginResponseDto;
}
async me(token: string): Promise<UserDto> {
const response = await fetch(`${this.baseUrl}/auth/me`, {
headers: { Authorization: `Bearer ${token}` },
});
if (!response.ok) throw new HttpError(response.status);
return (await response.json()) as UserDto;
}
}
Le mapper
import type { User } from '../domain/User';
import type { UserDto } from './AuthApi';
export function toUser(dto: UserDto): User {
return {
id: String(dto.id),
email: dto.email,
name: dto.full_name,
role: dto.role === 'admin' ? 'admin' : 'user', // rôle inconnu : droits minimaux
};
}
Le mapper est le seul endroit qui connaît les deux formes. Si l'API renomme un champ, c'est le seul fichier à modifier avec le DTO. Pour une API que vous ne maîtrisez pas, un schéma Zod à cet endroit vérifie aussi les données à l'exécution : as LoginResponseDto ne vérifie rien, il fait confiance au serveur.
Le stockage du jeton
import * as SecureStore from 'expo-secure-store';
export interface TokenStorage {
save(token: string): Promise<void>;
read(): Promise<string | null>;
clear(): Promise<void>;
}
const KEY = 'auth.accessToken';
// Trousseau iOS / Keystore Android, et non AsyncStorage (stockage en clair)
export class SecureTokenStorage implements TokenStorage {
save(token: string) {
return SecureStore.setItemAsync(KEY, token);
}
read() {
return SecureStore.getItemAsync(KEY);
}
clear() {
return SecureStore.deleteItemAsync(KEY);
}
}
L'implémentation du repository
import type { AuthRepository, Credentials } from '../domain/AuthRepository';
import type { User } from '../domain/User';
import { InvalidCredentialsError, NetworkError } from '../domain/errors';
import { AuthApi, HttpError } from './AuthApi';
import type { TokenStorage } from './TokenStorage';
import { toUser } from './userMapper';
export class AuthRepositoryImpl implements AuthRepository {
constructor(
private readonly api: AuthApi,
private readonly tokens: TokenStorage,
) {}
async login({ email, password }: Credentials): Promise<User> {
try {
const { access_token, user } = await this.api.login(email, password);
await this.tokens.save(access_token);
return toUser(user);
} catch (error) {
throw toDomainError(error);
}
}
async logout(): Promise<void> {
await this.tokens.clear();
}
async getCurrentUser(): Promise<User | null> {
const token = await this.tokens.read();
if (!token) return null;
try {
return toUser(await this.api.me(token));
} catch (error) {
if (error instanceof HttpError && error.status === 401) {
await this.tokens.clear(); // jeton expiré : on repart déconnecté
return null;
}
throw toDomainError(error);
}
}
}
// Les détails HTTP s'arrêtent ici : au-delà, seules les erreurs du domaine circulent
function toDomainError(error: unknown): Error {
if (error instanceof HttpError && error.status === 401) return new InvalidCredentialsError();
if (error instanceof TypeError) return new NetworkError(); // fetch hors ligne
return error instanceof Error ? error : new Error(String(error));
}
Dans React Native, fetch rejette avec un TypeError (« Network request failed ») quand il n'y a pas de réseau, d'où la conversion en NetworkError. Une réponse HTTP d'erreur, elle, ne rejette pas : il faut tester response.ok, ce que fait AuthApi.
6. Assembler : la racine de composition
L'essentiel : un seul fichier crée les classes concrètes et les relie. Le reste de l'application reçoit ses dépendances par un contexte React, ce qui permet de les remplacer dans les tests.
import { AuthApi } from '../features/auth/data/AuthApi';
import { AuthRepositoryImpl } from '../features/auth/data/AuthRepositoryImpl';
import { SecureTokenStorage } from '../features/auth/data/TokenStorage';
import { LoginUseCase } from '../features/auth/domain/LoginUseCase';
import type { Dependencies } from './DependenciesContext';
// Racine de composition : le seul fichier qui connaît les classes concrètes
export function createDependencies(apiUrl: string): Dependencies {
const authRepository = new AuthRepositoryImpl(new AuthApi(apiUrl), new SecureTokenStorage());
return {
loginUseCase: new LoginUseCase(authRepository),
};
}
import { createContext, use, type ReactNode } from 'react';
import type { LoginUseCase } from '../features/auth/domain/LoginUseCase';
export interface Dependencies {
loginUseCase: Pick<LoginUseCase, 'execute'>;
}
const DependenciesContext = createContext<Dependencies | null>(null);
export function DependenciesProvider(props: { value: Dependencies; children: ReactNode }) {
return <DependenciesContext value={props.value}>{props.children}</DependenciesContext>;
}
export function useDependencies(): Dependencies {
const dependencies = use(DependenciesContext);
if (!dependencies) {
throw new Error('useDependencies() doit être appelé sous <DependenciesProvider>');
}
return dependencies;
}
Ce fichier utilise deux nouveautés de React 19 : <DependenciesContext value={…}> remplace <DependenciesContext.Provider>, et use(Context) peut remplacer useContext. Avec React 18, gardez .Provider et useContext.
Les deux fichiers sont volontairement séparés : DependenciesContext.tsx ne contient qu'un type et un contexte. Les hooks l'importent sans tirer avec eux les classes de la couche data. Le point d'entrée fait l'assemblage une seule fois :
import { DependenciesProvider } from './DependenciesContext';
import { createDependencies } from './createDependencies';
import { LoginScreen } from '../features/auth/presentation/LoginScreen';
const dependencies = createDependencies('https://api.example.com');
export default function App() {
return (
<DependenciesProvider value={dependencies}>
<LoginScreen />
</DependenciesProvider>
);
}
Des bibliothèques d'injection comme InversifyJS ou tsyringe existent, mais elles reposent sur des décorateurs et reflect-metadata, qui demandent une configuration Babel supplémentaire en React Native. Pour la plupart des applications, une fonction comme createDependencies suffit et reste lisible.
7. La couche presentation
L'essentiel : le hook transforme le cas d'utilisation en état d'écran (chargement, succès, erreur) et les erreurs métier en messages. L'écran ne fait qu'afficher cet état.
Le hook
Le hook joue un rôle comparable à celui d'un ViewModel dans le modèle MVVM : il prépare l'état que l'écran affiche. L'état est une union discriminée : impossible d'avoir à la fois loading et un message d'erreur.
import { useState } from 'react';
import { useDependencies } from '../../../di/DependenciesContext';
import type { User } from '../domain/User';
import { InvalidCredentialsError, InvalidEmailError, NetworkError } from '../domain/errors';
export type LoginState =
| { status: 'idle' }
| { status: 'loading' }
| { status: 'success'; user: User }
| { status: 'error'; message: string };
export function useLogin() {
const { loginUseCase } = useDependencies();
const [state, setState] = useState<LoginState>({ status: 'idle' });
async function login(email: string, password: string) {
setState({ status: 'loading' });
try {
const user = await loginUseCase.execute({ email, password });
setState({ status: 'success', user });
} catch (error) {
setState({ status: 'error', message: toMessage(error) });
}
}
return { state, login };
}
function toMessage(error: unknown): string {
if (error instanceof InvalidEmailError) return 'Vérifiez le format de votre adresse e-mail.';
if (error instanceof InvalidCredentialsError) return 'E-mail ou mot de passe incorrect.';
if (error instanceof NetworkError) return 'Pas de connexion. Réessayez dans un instant.';
return 'Une erreur inattendue est survenue.';
}
L'écran
import { useState } from 'react';
import { ActivityIndicator, Pressable, Text, TextInput, View } from 'react-native';
import { useLogin } from './useLogin';
export function LoginScreen() {
const { state, login } = useLogin();
const [email, setEmail] = useState('');
const [password, setPassword] = useState('');
const loading = state.status === 'loading';
return (
<View>
<TextInput
placeholder="E-mail"
value={email}
onChangeText={setEmail}
autoCapitalize="none"
keyboardType="email-address"
/>
<TextInput
placeholder="Mot de passe"
value={password}
onChangeText={setPassword}
secureTextEntry
/>
<Pressable role="button" disabled={loading} onPress={() => login(email, password)}>
<Text>Se connecter</Text>
</Pressable>
{loading && <ActivityIndicator />}
{state.status === 'error' && <Text role="alert">{state.message}</Text>}
{state.status === 'success' && <Text>Bonjour {state.user.name}</Text>}
</View>
);
}
Les props role="button" et role="alert" (disponibles depuis React Native 0.71) servent aux lecteurs d'écran et permettent aussi aux tests de trouver les éléments par leur rôle.
Et TanStack Query, Redux ou Zustand ?
Ces outils restent dans la couche presentation. Ils gèrent l'état de l'écran ou le cache, pas les règles métier. Avec TanStack Query, le cas d'utilisation devient simplement la fonction de mutation :
import { useMutation } from '@tanstack/react-query';
import { useDependencies } from '../../../di/DependenciesContext';
import type { Credentials } from '../domain/AuthRepository';
export function useLoginMutation() {
const { loginUseCase } = useDependencies();
return useMutation({
mutationFn: (credentials: Credentials) => loginUseCase.execute(credentials),
});
}
Même principe pour une lecture : useQuery({ queryKey: ['currentUser'], queryFn: () => getCurrentUserUseCase.execute() }). Le cache, les nouvelles tentatives et le rafraîchissement viennent de TanStack Query ; la logique, du domaine.
8. Tester chaque couche
L'essentiel : beaucoup de tests rapides sur le domaine, quelques tests sur la conversion des données, et des tests d'écran centrés sur ce que voit l'utilisateur. Avec React Native Testing Library 14, render, renderHook et act s'attendent avec await.
| Couche | Outil | Ce qu'on vérifie | Doublure |
|---|---|---|---|
| Domain | Jest seul | Règles métier, orchestration | Fake du port |
| Data | Jest seul | Conversion des données, traduction des erreurs | Fausse API, stockage en mémoire |
| Hook | renderHook | Transitions d'état, messages | Faux cas d'utilisation |
| Écran | render, userEvent | Ce que l'utilisateur voit et fait | Faux cas d'utilisation |
Le cas d'utilisation
Un fake est une vraie implémentation simplifiée du port, ici en mémoire. Il rend le test plus lisible qu'une suite de jest.fn() et garantit, grâce à implements, que le faux respecte l'interface.
import type { AuthRepository, Credentials } from './AuthRepository';
import { LoginUseCase } from './LoginUseCase';
import type { User } from './User';
import { InvalidCredentialsError, InvalidEmailError } from './errors';
const ADA: User = { id: '1', email: 'ada@example.com', name: 'Ada', role: 'user' };
// Fake : une vraie implémentation, en mémoire, du port AuthRepository
class FakeAuthRepository implements AuthRepository {
calls: Credentials[] = [];
constructor(private readonly result: User | Error) {}
async login(credentials: Credentials) {
this.calls.push(credentials);
if (this.result instanceof Error) throw this.result;
return this.result;
}
async logout() {}
async getCurrentUser() {
return null;
}
}
describe('LoginUseCase', () => {
it("normalise l'e-mail avant d'appeler le repository", async () => {
const repository = new FakeAuthRepository(ADA);
const user = await new LoginUseCase(repository).execute({
email: ' Ada@Example.com ',
password: 'secret',
});
expect(user).toEqual(ADA);
expect(repository.calls).toEqual([{ email: 'ada@example.com', password: 'secret' }]);
});
it('refuse un e-mail invalide sans appeler le repository', async () => {
const repository = new FakeAuthRepository(ADA);
await expect(
new LoginUseCase(repository).execute({ email: 'ada', password: 'secret' }),
).rejects.toBeInstanceOf(InvalidEmailError);
expect(repository.calls).toHaveLength(0);
});
it('laisse remonter les erreurs du domaine', async () => {
const repository = new FakeAuthRepository(new InvalidCredentialsError());
await expect(
new LoginUseCase(repository).execute({ email: 'ada@example.com', password: 'faux' }),
).rejects.toBeInstanceOf(InvalidCredentialsError);
});
});
Le repository
Le test vérifie ce que la couche data ajoute : la conversion du DTO, l'enregistrement du jeton, la traduction des erreurs et le cas du jeton expiré. TypeScript étant structurel, un simple objet suffit à remplacer AuthApi.
import { InvalidCredentialsError, NetworkError } from '../domain/errors';
import { AuthApi, HttpError } from './AuthApi';
import { AuthRepositoryImpl } from './AuthRepositoryImpl';
import type { TokenStorage } from './TokenStorage';
class MemoryTokenStorage implements TokenStorage {
token: string | null = null;
async save(token: string) {
this.token = token;
}
async read() {
return this.token;
}
async clear() {
this.token = null;
}
}
function fakeApi(overrides: Partial<AuthApi>): AuthApi {
return { login: jest.fn(), me: jest.fn(), ...overrides } as unknown as AuthApi;
}
describe('AuthRepositoryImpl', () => {
it("enregistre le jeton et convertit l'utilisateur de l'API", async () => {
const tokens = new MemoryTokenStorage();
const api = fakeApi({
login: async () => ({
access_token: 'abc',
user: { id: 7, email: 'ada@example.com', full_name: 'Ada Lovelace', role: 'superuser' },
}),
});
const user = await new AuthRepositoryImpl(api, tokens).login({ email: 'ada@example.com', password: 'x' });
expect(tokens.token).toBe('abc');
expect(user).toEqual({ id: '7', email: 'ada@example.com', name: 'Ada Lovelace', role: 'user' });
});
it('traduit un 401 en InvalidCredentialsError', async () => {
const api = fakeApi({ login: async () => { throw new HttpError(401); } });
await expect(
new AuthRepositoryImpl(api, new MemoryTokenStorage()).login({ email: 'a@b.co', password: 'x' }),
).rejects.toBeInstanceOf(InvalidCredentialsError);
});
it('traduit une coupure réseau en NetworkError', async () => {
const api = fakeApi({ login: async () => { throw new TypeError('Network request failed'); } });
await expect(
new AuthRepositoryImpl(api, new MemoryTokenStorage()).login({ email: 'a@b.co', password: 'x' }),
).rejects.toBeInstanceOf(NetworkError);
});
it('efface un jeton expiré et renvoie null', async () => {
const tokens = new MemoryTokenStorage();
tokens.token = 'expired';
const api = fakeApi({ me: async () => { throw new HttpError(401); } });
expect(await new AuthRepositoryImpl(api, tokens).getCurrentUser()).toBeNull();
expect(tokens.token).toBeNull();
});
});
Le hook, avec renderHook
@testing-library/react-hooks n'est plus maintenu depuis 2022 et ne prend en charge que React 16 et 17. renderHook fait désormais partie de @testing-library/react-native. Depuis la version 14, il renvoie une promesse, comme rerender, unmount et act.
import type { ReactNode } from 'react';
import { act, renderHook } from '@testing-library/react-native';
import { DependenciesProvider, type Dependencies } from '../../../di/DependenciesContext';
import type { User } from '../domain/User';
import { InvalidCredentialsError } from '../domain/errors';
import { useLogin } from './useLogin';
const ADA: User = { id: '1', email: 'ada@example.com', name: 'Ada', role: 'user' };
function renderUseLogin(execute: Dependencies['loginUseCase']['execute']) {
const dependencies: Dependencies = { loginUseCase: { execute } };
const wrapper = ({ children }: { children: ReactNode }) => (
<DependenciesProvider value={dependencies}>{children}</DependenciesProvider>
);
return renderHook(() => useLogin(), { wrapper }); // RNTL 14 : renvoie une Promise
}
describe('useLogin', () => {
it("passe en succès avec l'utilisateur connecté", async () => {
const { result } = await renderUseLogin(async () => ADA);
await act(() => result.current.login('ada@example.com', 'secret'));
expect(result.current.state).toEqual({ status: 'success', user: ADA });
});
it('traduit une erreur du domaine en message', async () => {
const { result } = await renderUseLogin(async () => {
throw new InvalidCredentialsError();
});
await act(() => result.current.login('ada@example.com', 'faux'));
expect(result.current.state).toEqual({
status: 'error',
message: 'E-mail ou mot de passe incorrect.',
});
});
});
L'option wrapper place le hook sous le DependenciesProvider, avec un faux cas d'utilisation. C'est tout l'intérêt de la racine de composition : aucun jest.mock() de module n'est nécessaire.
L'écran
import { render, screen, userEvent } from '@testing-library/react-native';
import { DependenciesProvider } from '../../../di/DependenciesContext';
import { InvalidCredentialsError } from '../domain/errors';
import { LoginScreen } from './LoginScreen';
it("affiche l'erreur renvoyée par le cas d'utilisation", async () => {
const user = userEvent.setup();
const execute = async () => {
throw new InvalidCredentialsError();
};
await render(
<DependenciesProvider value={{ loginUseCase: { execute } }}>
<LoginScreen />
</DependenciesProvider>,
);
await user.type(screen.getByPlaceholderText('E-mail'), 'ada@example.com');
await user.type(screen.getByPlaceholderText('Mot de passe'), 'faux');
await user.press(screen.getByRole('button', { name: 'Se connecter' }));
expect(await screen.findByRole('alert')).toHaveTextContent('E-mail ou mot de passe incorrect.');
});
userEvent reproduit la séquence réelle d'événements (appui, saisie caractère par caractère), là où fireEvent appelle seulement le gestionnaire. Préférez-le quand il couvre l'interaction. user.press prend au moins 130 ms : sur une grosse suite de tests, activez les faux minuteurs de Jest.
Version 14 : il faut aussi le paquet test-renderer (qui remplace react-test-renderer), React 19 et React Native 0.78 ou plus. Les codemods rntl-v14-update-deps et rntl-v14-async-functions automatisent la migration depuis la version 13.
9. Erreurs fréquentes et corrections
L'essentiel : la plupart des erreurs reviennent à laisser un détail technique traverser une frontière, ou à ajouter des couches qui n'apportent rien.
| Erreur | Pourquoi c'est un problème | Correction |
|---|---|---|
Le domaine importe react-native, axios ou un stockage | La règle de dépendance est rompue ; le domaine ne se teste plus seul | Déclarer un port dans le domaine, l'implémenter dans data |
| Les DTO de l'API arrivent jusqu'aux écrans | Un renommage côté serveur casse l'interface | Un mapper dans data, des entités au-delà |
new AuthRepositoryImpl() dans un hook | Impossible de remplacer la dépendance en test | Créer les instances dans la racine de composition |
Afficher error.message d'une réponse HTTP | Messages techniques ou en anglais pour l'utilisateur | Erreurs métier traduites en messages dans le hook |
| Jeton dans AsyncStorage | Stockage non chiffré, lisible sur un appareil compromis | expo-secure-store ou react-native-keychain |
| Une interface pour chaque classe | Du code en plus sans second usage | Des ports seulement aux frontières : réseau, stockage, capteurs, horloge |
jest.mock('fetch') dans les tests de cas d'utilisation | Le test dépend d'un détail que le cas d'utilisation ne connaît pas | Un fake du port |
Tests de hook sans await avec RNTL 14 | result est undefined : la promesse n'est pas résolue | await renderHook(…) et await act(…) |
10. Cas limites
L'essentiel : une bonne architecture se juge sur les cas qui sortent du chemin heureux : jeton expiré, absence de réseau, données inattendues, écran fermé pendant une requête.
- Jeton expiré au démarrage :
getCurrentUserreçoit un 401, efface le jeton et renvoienull. L'application affiche l'écran de connexion au lieu d'une erreur. - Rôle inconnu : si l'API ajoute un rôle
superuser, le mapper retombe suruser, les droits minimaux. Le choix inverse donnerait des droits d'administration par accident. - Écran fermé pendant la requête : depuis React 18, appeler
setStateaprès démontage ne provoque plus d'avertissement ni de fuite. Pour annuler réellement la requête, faites passer unAbortSignaldu hook jusqu'àfetch, à travers le port. - Action qui touche plusieurs sources : se connecter puis charger les préférences. C'est le rôle d'un cas d'utilisation qui reçoit deux ports ; ni l'écran ni un repository ne doit appeler l'autre.
- Mode hors ligne : le repository décide entre cache et réseau. Le domaine ne sait pas d'où viennent les données, donc ajouter un cache ne le modifie pas.
- Sous-classes d'
Error:instanceoffonctionne avec le preset Babel de React Native (vérifié pour cet article). En revanche, du code compilé vers ES5 casseinstanceofsur ces sous-classes (vérifié avec TypeScript 5.9 ; TypeScript 7 a retiré cette cible) ; dans ce cas, comparezerror.name.
11. Questions d'entretien
L'essentiel : on attend surtout que vous expliquiez le sens des dépendances, la place de chaque responsabilité et les compromis, pas une liste de dossiers.
Qu'est-ce que la règle de dépendance ?
Le code source d'un cercle intérieur ne mentionne jamais un élément d'un cercle extérieur : ni import, ni nom de classe, ni format de données. Les dépendances pointent toutes vers les entités. C'est ce qui permet de changer de framework, d'API ou de stockage sans toucher au métier.
Pourquoi l'interface du repository est-elle dans le domaine et non dans data ?
Parce que c'est le domaine qui exprime son besoin. Si l'interface était dans data, le cas d'utilisation importerait data, et la dépendance irait vers l'extérieur. C'est le principe d'inversion des dépendances (le « D » de SOLID) : les modules de haut niveau et de bas niveau dépendent tous deux d'une abstraction possédée par le haut niveau.
Quelle différence avec l'architecture hexagonale et l'architecture en oignon ?
Le même objectif, isoler le métier, avec des vocabulaires différents. L'hexagonale (Cockburn, 2005) parle de ports et d'adaptateurs, sans imposer de couches internes. L'oignon (Palermo, 2008) ajoute des couches concentriques autour du modèle de domaine. La Clean Architecture (Martin, 2012) en fait la synthèse et nomme précisément les cercles et la règle de dépendance.
Un cas d'utilisation qui ne fait qu'appeler le repository est-il utile ?
Il apporte peu au départ, mais il donne un endroit évident pour la règle suivante (normalisation, droits, journalisation) et un point d'entrée unique pour l'écran. Certaines équipes autorisent le hook à appeler directement le repository pour les lectures simples. Les deux choix se défendent si l'équipe les applique de façon cohérente.
Où placer la validation d'un formulaire ?
À trois niveaux, pour trois raisons. Dans l'écran, pour un retour immédiat (champ vide). Dans le domaine, pour les règles qui doivent toujours être vraies (format d'e-mail, montant positif). Dans data, pour vérifier que l'API renvoie bien ce qu'on attend (schéma Zod, par exemple). Seule la validation du domaine est obligatoire.
Comment testez-vous un hook qui dépend d'un cas d'utilisation ?
Avec renderHook de React Native Testing Library, en passant un wrapper qui fournit un faux cas d'utilisation par contexte. Avec la version 14, on attend renderHook et chaque act. Pas besoin de jest.mock() de module.
Quand ne faut-il pas utiliser la Clean Architecture ?
Pour un prototype, une application de quelques écrans sans logique métier, ou un projet jetable. Les couches ont un coût : plus de fichiers, plus d'indirection. Elles se rentabilisent quand la logique grandit, que l'équipe s'agrandit ou que le code doit vivre plusieurs années.
12. Notions voisines
- SOLID : l'inversion des dépendances (D) est le cœur du mécanisme ; la responsabilité unique (S) guide le découpage en cas d'utilisation.
- Architecture hexagonale : le vocabulaire « port » et « adaptateur » utilisé dans cet article vient d'elle.
- Domain-Driven Design : il aide à bien modéliser les entités et le langage métier. La Clean Architecture ne l'impose pas.
- MVVM : dans la couche presentation, le hook tient un rôle comparable à celui du ViewModel.
- Feature-Sliced Design : une méthode d'organisation par fonctionnalités, venue du front-end web, compatible avec ce découpage.
13. Et quand c'est une IA qui code ?
L'essentiel : les frontières qui guident une équipe guident aussi un agent de code, si elles sont écrites et vérifiées automatiquement.
Une personne devine qu'un cas d'utilisation ne doit pas appeler fetch ; un agent de code, non. Les frontières explicites de la Clean Architecture lui servent de garde-fous : chaque couche dit ce qu'il a le droit d'importer (NimblePros, juin 2026).
Écrivez la règle de dépendance dans le fichier d'instructions que l'agent lit à chaque session (CLAUDE.md pour Claude Code), puis faites-la respecter par un test d'architecture qui échoue dès qu'un fichier de domain importe React Native ou data. La revue reste utile, mais le test bloque chaque écart.
Un code propre aide l'agent sans le rendre infaillible. Dans une étude cosignée par SonarSource (660 essais avec Claude Code), le taux de réussite ne change pas, mais sur du code plus propre l'agent consomme 7 à 8 % de jetons en moins et revient 34 % moins souvent sur les mêmes fichiers (arXiv 2605.20049, mai 2026).
La nuance de la section 11 tient : plus de couches coûte au début, et devient rentable lors des gros changements, quand l'agent modifie beaucoup de code sans franchir les frontières.
Testez-vous
1. Pour gagner du temps, un développeur importe expo-secure-store dans LoginUseCase.ts afin de lire le jeton. Qu'est-ce qui ne va pas, et comment corriger ?
La règle de dépendance est rompue : le domaine dépend d'un module natif. Le cas d'utilisation ne peut plus être testé avec Jest seul, et changer de stockage modifie le métier. Correction : passer par le port (AuthRepository.getCurrentUser()), dont l'implémentation dans data utilise TokenStorage.
2. L'API renvoie désormais fullName au lieu de full_name. Quels fichiers modifiez-vous ?
Seulement le DTO UserDto dans AuthApi.ts et la ligne correspondante de userMapper.ts, dans la couche data. L'entité User, le cas d'utilisation, le hook et l'écran ne changent pas.
3. Avec React Native Testing Library 14, ce test échoue. Pourquoi ?
import { renderHook } from '@testing-library/react-native';
it('démarre au repos', () => {
const { result } = renderHook(() => useLogin());
expect(result.current.state.status).toBe('idle');
});
Deux raisons. renderHook renvoie une promesse : sans await, result n'existe pas encore. Et le hook appelle useDependencies() sans DependenciesProvider autour : il lève une erreur. Correction, avec l'utilitaire renderUseLogin de la section 8 :
it('démarre au repos', async () => {
const { result } = await renderUseLogin(async () => ADA);
expect(result.current.state.status).toBe('idle');
});
À retenir
- Règle de dépendance : les imports pointent toujours vers le centre ; les entités ne connaissent rien d'autre.
- Domain : entités avec leurs règles, erreurs métier, ports et cas d'utilisation, en TypeScript pur.
- Data : DTO, mappers, stockage sécurisé, et traduction des erreurs techniques en erreurs métier.
- Presentation : un hook transforme le cas d'utilisation en état d'écran ; l'écran affiche.
- Racine de composition : un seul endroit crée les classes concrètes, un contexte les distribue.
- Tests : fakes pour le domaine,
await renderHooketuserEventpour la présentation avec RNTL 14. - Mesure : la Clean Architecture se justifie quand la logique et l'équipe grandissent, pas pour un prototype.
Pour aller plus loin
- Robert C. Martin – The Clean Architecture (2012) : l'article d'origine et le schéma des cercles.
- Alistair Cockburn – Hexagonal Architecture : les ports et adaptateurs, par leur auteur.
- React Native Testing Library – renderHook : la référence de l'API, et le guide de migration vers la version 14.