Flutter Testing: Guía Completa de Tests Unitarios, de Widgets e Integración

Introducción al Testing en Flutter

Flutter proporciona un framework de testing integral que permite a los desarrolladores escribir tests confiables y mantenibles en múltiples niveles. A diferencia de los enfoques tradicionales de testing móvil, la arquitectura por capas de Flutter (como se discute en Mobile Testing in 2025: iOS, Android and Beyond) permite probar todo, desde funciones individuales hasta flujos de usuario completos, con velocidad y precisión excepcionales.

El ecosistema de testing de Flutter incluye tres tipos principales de tests:

Tests Unitarios: Verifican lógica de negocio, cálculos y transformaciones de datos
Tests de Widgets: Validan componentes UI e interacciones de usuario
Tests de Integración: Prueban flujos completos de la app en dispositivos reales o simulados

Esta guía cubre técnicas avanzadas de testing, mejores prácticas y ejemplos del mundo real para ayudarte a construir aplicaciones Flutter robustas.

Configuración del Entorno de Testing en Flutter

Configuración de Dependencias

Agrega las dependencias de testing a tu pubspec.yaml:

dev_dependencies:
  flutter_test:
    sdk: flutter
  mockito: ^5.4.4
  build_runner: ^2.4.6
  integration_test:
    sdk: flutter
  flutter_driver:
    sdk: flutter

Estructura del Proyecto

Organiza tus tests siguiendo las convenciones de Flutter:

project/
├── lib/
├── test/              # Tests unitarios y de widgets
│   ├── models/
│   ├── services/
│   └── widgets/
├── integration_test/  # Tests de integración
└── test_driver/       # Scripts de driver

Testing Unitario en Flutter

Probando Lógica de Negocio

Los tests unitarios se enfocan en probar código Dart puro sin dependencias de UI. Aquí hay un ejemplo completo probando un servicio de carrito de compras:

// lib/services/cart_service.dart
class CartService {
  final List<CartItem> _items = [];

  double get totalPrice => _items.fold(
    0.0,
    (sum, item) => sum + (item.price * item.quantity)
  );

  void addItem(CartItem item) {
    final existingIndex = _items.indexWhere(
      (i) => i.productId == item.productId
    );

    if (existingIndex >= 0) {
      _items[existingIndex].quantity += item.quantity;
    } else {
      _items.add(item);
    }
  }

  void removeItem(String productId) {
    _items.removeWhere((item) => item.productId == productId);
  }

  void clearCart() => _items.clear();
}

// test/services/cart_service_test.dart
import 'package:flutter_test/flutter_test.dart';

void main() {
  late CartService cartService;

  setUp(() {
    cartService = CartService();
  });

  group('CartService', () {
    test('debe agregar nuevo item al carrito vacío', () {
      final item = CartItem(
        productId: '1',
        name: 'Producto',
        price: 10.0,
        quantity: 1
      );

      cartService.addItem(item);

      expect(cartService.totalPrice, 10.0);
    });

    test('debe combinar cantidades para items duplicados', () {
      final item = CartItem(
        productId: '1',
        name: 'Producto',
        price: 10.0,
        quantity: 2
      );

      cartService.addItem(item);
      cartService.addItem(item);

      expect(cartService.totalPrice, 40.0);
    });

    test('debe calcular el precio total correctamente', () {
      cartService.addItem(CartItem(
        productId: '1',
        price: 10.0,
        quantity: 2
      ));
      cartService.addItem(CartItem(
        productId: '2',
        price: 15.0,
        quantity: 1
      ));

      expect(cartService.totalPrice, 35.0);
    });
  });
}

Simulación de Dependencias con Mockito

Para probar componentes con dependencias externas, usa Mockito para crear objetos simulados:

// lib/repositories/user_repository.dart
abstract class UserRepository {
  Future<User> fetchUser(String id);
  Future<void> updateUser(User user);
}

// lib/services/user_service.dart
class UserService {
  final UserRepository repository;

  UserService(this.repository);

  Future<User> getUser(String id) async {
    final user = await repository.fetchUser(id);
    if (user.name.isEmpty) {
      throw ValidationException('El nombre de usuario no puede estar vacío');
    }
    return user;
  }
}

// test/services/user_service_test.dart
import 'package:mockito/annotations.dart';
import 'package:mockito/mockito.dart';
import 'package:flutter_test/flutter_test.dart';

@GenerateMocks([UserRepository])
void main() {
  late UserService service;
  late MockUserRepository mockRepository;

  setUp(() {
    mockRepository = MockUserRepository();
    service = UserService(mockRepository);
  });

  test('debe retornar usuario cuando es válido', () async {
    final user = User(id: '1', name: 'Juan Pérez');

    when(mockRepository.fetchUser('1'))
        .thenAnswer((_) async => user);

    final result = await service.getUser('1');

    expect(result.name, 'Juan Pérez');
    verify(mockRepository.fetchUser('1')).called(1);
  });

  test('debe lanzar excepción para usuario inválido', () async {
    final user = User(id: '1', name: '');

    when(mockRepository.fetchUser('1'))
        .thenAnswer((_) async => user);

    expect(
      () => service.getUser('1'),
      throwsA(isA<ValidationException>())
    );
  });
}

Ejecuta flutter pub run build_runner build para generar las clases mock.

Testing de Widgets

Probando Componentes UI

Los tests de widgets verifican el renderizado de UI y las interacciones del usuario. Se ejecutan más rápido que los tests de integración mientras proporcionan confianza en el comportamiento de la UI:

// lib/widgets/counter_widget.dart
class CounterWidget extends StatefulWidget {
  @override
  _CounterWidgetState createState() => _CounterWidgetState();
}

class _CounterWidgetState extends State<CounterWidget> {
  int _counter = 0;

  void _increment() => setState(() => _counter++);
  void _decrement() => setState(() => _counter--);

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        Text('Cuenta: $_counter', key: Key('counter_text')),
        ElevatedButton(
          key: Key('increment_button'),
          onPressed: _increment,
          child: Text('Incrementar'),
        ),
        ElevatedButton(
          key: Key('decrement_button'),
          onPressed: _decrement,
          child: Text('Decrementar'),
        ),
      ],
    );
  }
}

// test/widgets/counter_widget_test.dart
import 'package:flutter_test/flutter_test.dart';

void main() {
  testWidgets('CounterWidget incrementa y decrementa',
    (WidgetTester tester) async {

    await tester.pumpWidget(
      MaterialApp(home: Scaffold(body: CounterWidget()))
    );

    // Verificar estado inicial
    expect(find.text('Cuenta: 0'), findsOneWidget);

    // Tocar botón de incremento
    await tester.tap(find.byKey(Key('increment_button')));
    await tester.pump();

    expect(find.text('Cuenta: 1'), findsOneWidget);

    // Tocar botón de decremento
    await tester.tap(find.byKey(Key('decrement_button')));
    await tester.pump();

    expect(find.text('Cuenta: 0'), findsOneWidget);
  });

  testWidgets('CounterWidget maneja múltiples toques',
    (WidgetTester tester) async {

    await tester.pumpWidget(
      MaterialApp(home: Scaffold(body: CounterWidget()))
    );

    // Múltiples incrementos
    for (int i = 0; i < 5; i++) {
      await tester.tap(find.byKey(Key('increment_button')));
      await tester.pump();
    }

    expect(find.text('Cuenta: 5'), findsOneWidget);
  });
}

Probando Widgets Asíncronos

Al probar widgets con operaciones asíncronas, usa pumpAndSettle() para esperar animaciones y operaciones async:

// lib/widgets/user_profile.dart
class UserProfile extends StatelessWidget {
  final Future<User> userFuture;

  UserProfile({required this.userFuture});

  @override
  Widget build(BuildContext context) {
    return FutureBuilder<User>(
      future: userFuture,
      builder: (context, snapshot) {
        if (snapshot.connectionState == ConnectionState.waiting) {
          return CircularProgressIndicator(
            key: Key('loading_indicator')
          );
        }

        if (snapshot.hasError) {
          return Text('Error: ${snapshot.error}',
            key: Key('error_text')
          );
        }

        return Text('Usuario: ${snapshot.data!.name}',
          key: Key('user_name')
        );
      },
    );
  }
}

// test/widgets/user_profile_test.dart
testWidgets('UserProfile muestra carga luego datos',
  (WidgetTester tester) async {

  final userFuture = Future.delayed(
    Duration(milliseconds: 100),
    () => User(name: 'Juan')
  );

  await tester.pumpWidget(
    MaterialApp(home: UserProfile(userFuture: userFuture))
  );

  // Verificar estado de carga
  expect(find.byKey(Key('loading_indicator')), findsOneWidget);

  // Esperar operación async
  await tester.pumpAndSettle();

  // Verificar datos cargados
  expect(find.text('Usuario: Juan'), findsOneWidget);
  expect(find.byKey(Key('loading_indicator')), findsNothing);
});

Testing de Integración

Prueba de Flujos Completos de la App

Los tests de integración verifican recorridos completos del usuario en dispositivos reales o simulados. Similar a los enfoques de testing móvil multiplataforma, el framework de testing de integración de Flutter te permite validar flujos end-to-end con confianza:

// integration_test/app_test.dart
import 'package:flutter_test/flutter_test.dart';
import 'package:integration_test/integration_test.dart';
import 'package:my_app/main.dart' as app;

void main() {
  IntegrationTestWidgetsFlutterBinding.ensureInitialized();

  group('Test de Integración de Flujo de Login', () {
    testWidgets('flujo completo de login',
      (WidgetTester tester) async {

      app.main();
      await tester.pumpAndSettle();

      // Navegar a login
      await tester.tap(find.text('Iniciar Sesión'));
      await tester.pumpAndSettle();

      // Ingresar credenciales
      await tester.enterText(
        find.byKey(Key('email_field')),
        'test@example.com'
      );
      await tester.enterText(
        find.byKey(Key('password_field')),
        'password123'
      );

      // Enviar login
      await tester.tap(find.byKey(Key('login_button')));
      await tester.pumpAndSettle(Duration(seconds: 5));

      // Verificar navegación a inicio
      expect(find.text('Bienvenido'), findsOneWidget);
    });

    testWidgets('muestra error para credenciales inválidas',
      (WidgetTester tester) async {

      app.main();
      await tester.pumpAndSettle();

      await tester.tap(find.text('Iniciar Sesión'));
      await tester.pumpAndSettle();

      await tester.enterText(
        find.byKey(Key('email_field')),
        'invalid@example.com'
      );
      await tester.enterText(
        find.byKey(Key('password_field')),
        'wrong'
      );

      await tester.tap(find.byKey(Key('login_button')));
      await tester.pumpAndSettle(Duration(seconds: 5));

      expect(find.text('Credenciales inválidas'), findsOneWidget);
    });
  });
}

Ejecutando Tests de Integración

Ejecuta tests de integración en dispositivos o emuladores:

# Ejecutar en dispositivo conectado
flutter test integration_test/app_test.dart

# Ejecutar en dispositivo específico
flutter test integration_test/app_test.dart -d emulator-5554

# Ejecutar con driver para escenarios avanzados
flutter drive \
  --driver=test_driver/integration_test.dart \
  --target=integration_test/app_test.dart

Mejores Prácticas y Estrategias de Testing

Organización de Tests

Tipo de Test	Cantidad	Velocidad	Enfoque de Cobertura
Tests Unitarios	70%	Rápida	Lógica de negocio, utilidades
Tests de Widgets	20%	Media	Componentes UI, interacciones
Tests de Integración	10%	Lenta	Flujos críticos de usuario

Golden Testing para Regresión UI

Captura y compara capturas de pantalla de widgets:

testWidgets('Botón coincide con archivo golden',
  (WidgetTester tester) async {

  await tester.pumpWidget(
    MaterialApp(home: CustomButton(text: 'Enviar'))
  );

  await expectLater(
    find.byType(CustomButton),
    matchesGoldenFile('goldens/custom_button.png')
  );
});

Actualiza archivos golden cuando cambia la UI:

flutter test --update-goldens

Testing de Rendimiento

Monitorea el rendimiento de construcción de widgets:

testWidgets('ListView funciona eficientemente',
  (WidgetTester tester) async {

  await tester.pumpWidget(
    MaterialApp(
      home: ListView.builder(
        itemCount: 1000,
        itemBuilder: (context, index) => ListTile(
          title: Text('Item $index')
        ),
      ),
    ),
  );

  await tester.pumpAndSettle();

  // Medir rendimiento de scroll
  await tester.fling(
    find.byType(ListView),
    Offset(0, -500),
    1000
  );

  await tester.pumpAndSettle();

  // Verificar que no hay caída de frames
  expect(tester.binding.hasScheduledFrame, isFalse);
});

Técnicas Avanzadas de Testing

Probando State Management

Para el testing de gestión de estado basado en Provider, Flutter proporciona herramientas robustas similares a lo que encontrarías en React Native Testing Library:

testWidgets('Counter provider actualiza UI',
  (WidgetTester tester) async {

  await tester.pumpWidget(
    ChangeNotifierProvider(
      create: (_) => CounterProvider(),
      child: MaterialApp(home: CounterScreen()),
    ),
  );

  expect(find.text('0'), findsOneWidget);

  await tester.tap(find.byIcon(Icons.add));
  await tester.pump();

  expect(find.text('1'), findsOneWidget);
});

Probando Navegación

Verifica el comportamiento de enrutamiento:

testWidgets('Navegación a pantalla de detalle',
  (WidgetTester tester) async {

  await tester.pumpWidget(
    MaterialApp(
      routes: {
        '/': (context) => HomeScreen(),
        '/detail': (context) => DetailScreen(),
      },
    ),
  );

  await tester.tap(find.text('Ver Detalles'));
  await tester.pumpAndSettle();

  expect(find.byType(DetailScreen), findsOneWidget);
});

Configuración de Integración Continua

Configuración de GitHub Actions

name: Flutter Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: subosito/flutter-action@v2
        with:
          flutter-version: '3.16.0'

      - name: Instalar dependencias
        run: flutter pub get

      - name: Ejecutar tests unitarios
        run: flutter test --coverage

      - name: Subir cobertura
        uses: codecov/codecov-action@v3
        with:
          file: coverage/lcov.info

Conclusión

El framework de testing de Flutter proporciona herramientas poderosas para asegurar la calidad del código en todas las capas de tu aplicación. Al combinar tests unitarios para lógica de negocio, tests de widgets para componentes UI, y tests de integración para flujos críticos, creas una red de seguridad robusta que permite refactorización confiada y desarrollo rápido de características.

Puntos Clave:

Sigue la pirámide de testing: 70% unitarios, 20% widgets, 10% integración
Usa mockito para aislar dependencias en tests unitarios
Aprovecha WidgetTester para validación UI completa
Implementa golden tests para detección de regresión visual
Automatiza testing en pipelines CI/CD

Comienza con tests de alto valor cubriendo lógica de negocio crítica y flujos de usuario, luego expande la cobertura iterativamente a medida que tu aplicación crece.