Integration Testing and Flutter DevTools: End-to-End on Real Device
Integration tests are the most realistic level of Flutter testing: they run on physical device or emulator, drive the app as a real user would and verify complete flows from UI input to backend response. Unlike test widgets that isolate a single component, integration tests traverse the entire stack application — navigation, state management, HTTP, local storage.
In this article we build a complete integration test pipeline: we write the tests
with the package integration_test, we run them locally on the emulator,
we automate them on GitHub Actions and finally run them on real physical devices
with Firebase Test Lab. We use Flutter DevTools to analyze memory and CPU during
execution, identifying performance regressions before deployment.
What You Will Learn
- Difference between unit tests, widget tests and integration tests in Flutter
- Package setup
integration_testand test file structure - Writing E2E tests with
IntegrationTestWidgetsFlutterBinding - Use of
find,tap,enterTextepumpAndSettle - Flutter DevTools: Memory Profiler, CPU Profiler and Network tab
- GitHub Actions: CI/CD pipeline for integration tests on emulator
- Firebase Test Lab: Running on an array of physical devices
- Mocking strategies for isolating the backend in E2E testing
The Test Pyramid in Flutter
Before writing integration tests, it is essential to understand where they fit in Flutter testing pyramid and what their cost/benefit is compared to the other levels.
| Type | Speed | Loyalty | Maintenance | When to use them |
|---|---|---|---|---|
| Unit Tests | ~1ms per test | Low (isolated logic) | Minimal | Business logic, repository, utils |
| Widget Tests | ~50ms per test | Medium (UI without device) | Average | UI components, interactions |
| Integration Test | ~30s per test | High (real device) | High | Critical flows, E2E regression |
The rule of thumb: 70% unit tests, 20% widget tests, 10% integration tests. The tests of integration are valuable but expensive — use them for critical business flows (login, checkout, onboarding) where a regression causes real harm.
Project Setup
# pubspec.yaml: dipendenze per integration testing
dependencies:
flutter:
sdk: flutter
integration_test:
sdk: flutter # gia incluso nell'SDK Flutter
dev_dependencies:
flutter_test:
sdk: flutter
integration_test:
sdk: flutter
mocktail: ^1.0.4 # per mock degli HTTP client
fake_async: ^1.3.1 # per controllare il tempo nei test
# Struttura directory raccomandata
# test/ unit test e widget test
# integration_test/ integration test
# app_test.dart
# flows/
# auth_flow_test.dart
# checkout_flow_test.dart
# helpers/
# test_helpers.dart
The First Integration Test
The binding for integration tests is different from that of widget tests:
IntegrationTestWidgetsFlutterBinding.ensureInitialized() initialize
the binding that communicates with the native device and enables the collection of performance metrics.
// 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() {
// OBBLIGATORIO: inizializza il binding integration test
final binding = IntegrationTestWidgetsFlutterBinding.ensureInitialized();
group('App Integration Tests', () {
testWidgets('App si avvia e mostra la home page', (tester) async {
// Avvia l'app completa (non un widget isolato)
app.main();
await tester.pumpAndSettle(); // Aspetta che tutte le animazioni finiscano
// Verifica che la home page sia visibile
expect(find.text('Benvenuto'), findsOneWidget);
expect(find.byKey(const Key('home_page')), findsOneWidget);
});
testWidgets('Navigazione tra le tab funziona', (tester) async {
app.main();
await tester.pumpAndSettle();
// Tap sulla tab Profile
await tester.tap(find.byKey(const Key('nav_profile')));
await tester.pumpAndSettle();
// Verifica che la pagina profilo sia caricata
expect(find.byKey(const Key('profile_page')), findsOneWidget);
// Torna alla Home
await tester.tap(find.byKey(const Key('nav_home')));
await tester.pumpAndSettle();
expect(find.byKey(const Key('home_page')), findsOneWidget);
});
});
}
Testing a Complete Authentication Flow
A login flow is the ideal candidate for integration testing: it engages UI, validation, HTTP calling, token storage and post-login navigation.
// integration_test/flows/auth_flow_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('Auth Flow', () {
testWidgets('Login con credenziali valide naviga alla home', (tester) async {
app.main();
await tester.pumpAndSettle();
// Trova e compila il campo email
final emailField = find.byKey(const Key('email_field'));
expect(emailField, findsOneWidget);
await tester.tap(emailField);
await tester.enterText(emailField, 'test@example.com');
// Compila il campo password
final passwordField = find.byKey(const Key('password_field'));
await tester.tap(passwordField);
await tester.enterText(passwordField, 'password123');
// Chiudi la tastiera
await tester.testTextInput.receiveAction(TextInputAction.done);
await tester.pumpAndSettle();
// Tap sul pulsante di login
await tester.tap(find.byKey(const Key('login_button')));
// Aspetta che il login HTTP completi (max 5 secondi)
await tester.pumpAndSettle(const Duration(seconds: 5));
// Verifica redirect alla home page
expect(find.byKey(const Key('home_page')), findsOneWidget);
expect(find.byKey(const Key('login_page')), findsNothing);
});
testWidgets('Login con credenziali errate mostra errore', (tester) async {
app.main();
await tester.pumpAndSettle();
await tester.enterText(
find.byKey(const Key('email_field')),
'wrong@example.com',
);
await tester.enterText(
find.byKey(const Key('password_field')),
'wrongpassword',
);
await tester.tap(find.byKey(const Key('login_button')));
await tester.pumpAndSettle(const Duration(seconds: 5));
// Deve apparire il messaggio di errore
expect(find.text('Credenziali non valide'), findsOneWidget);
// Deve rimanere sulla login page
expect(find.byKey(const Key('login_page')), findsOneWidget);
});
testWidgets('Validazione form: email non valida blocca il submit', (tester) async {
app.main();
await tester.pumpAndSettle();
await tester.enterText(
find.byKey(const Key('email_field')),
'email-non-valida',
);
await tester.tap(find.byKey(const Key('login_button')));
await tester.pumpAndSettle();
// Errore di validazione visibile (no HTTP call effettuata)
expect(find.text('Inserisci un\'email valida'), findsOneWidget);
});
});
}
Collection of Performance Metrics
Integration testing is not just functional correctness: the binding integration test Allows you to collect frame timing, memory and rendering metrics at runtime of the test, producing a JSON report that can be parsed in CI.
// integration_test/performance_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() {
final binding = IntegrationTestWidgetsFlutterBinding.ensureInitialized();
testWidgets('Scrolling della lista prodotti: performance test', (tester) async {
app.main();
await tester.pumpAndSettle();
// Naviga alla lista prodotti
await tester.tap(find.byKey(const Key('nav_products')));
await tester.pumpAndSettle();
// Raccoglie metriche durante il scroll
await binding.watchPerformance(() async {
// Scroll veloce per 5 paginate
for (int i = 0; i < 5; i++) {
await tester.fling(
find.byKey(const Key('products_list')),
const Offset(0, -500),
3000, // velocita pixels/secondo
);
await tester.pumpAndSettle();
}
},
reportKey: 'products_scroll_perf');
// Le metriche vengono salvate automaticamente in un file JSON
// Accessibile via: flutter drive --profile
});
}
// Comando per raccogliere metriche in modalita profile:
// flutter drive \
// --driver=test_driver/integration_test.dart \
// --target=integration_test/performance_test.dart \
// --profile
Flutter DevTools: Deep Profiling
Flutter DevTools is a suite of diagnostic tools accessible via browser while the app is running in debug or profile mode. The most useful tabs to identify performance problems are the Performance tab (frame timing), the Memory tab (heap allocation) and the Network tab (HTTP latency).
# Avviare DevTools durante un integration test
# 1. Lancia l'app in modalita debug su emulatore
flutter run --debug
# 2. Apri DevTools (automaticamente o manualmente)
flutter pub global run devtools
# 3. Oppure direttamente da VS Code / Android Studio
# View > Command Palette > Flutter: Open DevTools
# Performance tab: comandi utili
# - "Record" per catturare una sessione
# - "Enhance Tracing" per shader e build details
# - Filtra per "Janky frames" (rosso = sopra 16ms budget)
# Memory tab: identificare memory leak
# - "GC" button: forza garbage collection
# - "Snapshot" prima e dopo un'operazione
# - Confronta gli heap dump per trovare oggetti non rilasciati
# Network tab
# - Mostra tutte le richieste HTTP/HTTPS
# - Timing breakdown: DNS, connect, send, wait, receive
# - Filtro per URI pattern
Memory Leak Pattern Common in Flutter
The most common memory leak in integration tests (and in production) isAnimationController
not willing: A controller created in initState without the corresponding one
dispose() accumulates listeners and is never released by the garbage collector.
Flutter DevTools Memory tab identifies it as an object with retaining path to the root.
GitHub Actions: CI/CD Pipeline for Integration Testing
Running integration tests in CI requires an Android emulator or an iOS simulator. Here is a complete GitHub Actions setup optimized for fast build times.
# .github/workflows/integration-tests.yml
name: Integration Tests
on:
push:
branches: [main, develop]
pull_request:
branches: [main]
jobs:
integration-tests-android:
runs-on: ubuntu-latest
timeout-minutes: 30
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Setup Java (richiesto per emulatore Android)
uses: actions/setup-java@v4
with:
java-version: '17'
distribution: 'temurin'
- name: Setup Flutter
uses: subosito/flutter-action@v2
with:
flutter-version: '3.27.0'
channel: 'stable'
cache: true # cache delle dipendenze Flutter
- name: Install dependencies
run: flutter pub get
- name: Enable KVM (accelerazione hardware emulatore)
run: |
echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' \
| sudo tee /etc/udev/rules.d/99-kvm4all.rules
sudo udevadm control --reload-rules
sudo udevadm trigger --name-match=kvm
- name: Avvia emulatore Android
uses: reactivecircus/android-emulator-runner@v2
with:
api-level: 33
arch: x86_64
profile: Nexus 6
avd-name: integration_test_avd
emulator-options: -no-snapshot-save -no-window -gpu swiftshader_indirect -noaudio -no-boot-anim
disable-animations: true # disabilita animazioni per test piu veloci
script: |
flutter test integration_test/ \
--flavor development \
-d emulator-5554 \
--dart-define=ENVIRONMENT=test
- name: Upload test results
if: always()
uses: actions/upload-artifact@v4
with:
name: integration-test-results
path: build/integration_test_results/
Firebase Test Lab: Physical Device Matrix
GitHub Actions with Emulators covers basic testing, but physical devices they have real hardware differences (GPU, sensors, OEM Android variants) that the emulator does not play. Firebase Test Lab offers a fleet of devices physical files on which to run the app.
# Preparazione dell'APK per Firebase Test Lab
# 1. Build dell'app e del test APK separati
flutter build apk --debug --target-platform android-arm64
flutter build apk --debug \
--target=integration_test/app_test.dart \
--target-platform android-arm64
# 2. Upload e avvio del test su Firebase Test Lab via gcloud CLI
gcloud firebase test android run \
--type instrumentation \
--app build/app/outputs/apk/debug/app-debug.apk \
--test build/app/outputs/apk/debug/app-debug-androidTest.apk \
--device model=Pixel6,version=33,locale=it,orientation=portrait \
--device model=SamsungS22,version=32,locale=it,orientation=portrait \
--device model=OnePlus9,version=31,locale=it,orientation=portrait \
--timeout 5m \
--results-bucket=gs://my-project-test-results \
--results-dir=integration_tests/$(date +%Y%m%d_%H%M%S)
# Integrazione Firebase Test Lab in GitHub Actions
- name: Authenticate Google Cloud
uses: google-github-actions/auth@v2
with:
credentials_json: ${{ secrets.GCP_CREDENTIALS }}
- name: Setup gcloud CLI
uses: google-github-actions/setup-gcloud@v2
- name: Build test APKs
run: |
flutter build apk --debug
flutter build apk --debug \
--target=integration_test/app_test.dart
- name: Run tests on Firebase Test Lab
run: |
gcloud firebase test android run \
--type instrumentation \
--app build/app/outputs/apk/debug/app-debug.apk \
--test build/app/outputs/apk/debug/app-debug-androidTest.apk \
--device model=Pixel6,version=33,locale=it,orientation=portrait \
--timeout 5m \
--results-bucket=gs://my-app-test-results
Mocking Strategy for Reliable E2E Tests
Tests that depend on a real backend are fragile: the server can be down,
data can change, latency varies. The best strategy for testing
integration and use a mock local server (as mockito
or a fake HTTP server) configurable via --dart-define.
# main.dart: configurazione per ambiente test
// main.dart
void main() {
// Legge la variabile di ambiente iniettata dalla CI
const environment = String.fromEnvironment(
'ENVIRONMENT',
defaultValue: 'production',
);
if (environment == 'test') {
// Usa il mock HTTP client per i test di integrazione
HttpOverrides.global = _MockHttpOverrides();
}
runApp(
ProviderScope(
overrides: environment == 'test'
? [
// Override Riverpod provider con il mock repository
apiClientProvider.overrideWithValue(MockApiClient()),
]
: [],
child: const MyApp(),
),
);
}
class _MockHttpOverrides extends HttpOverrides {
@override
HttpClient createHttpClient(SecurityContext? context) {
// Intercetta tutte le richieste HTTP e restituisce dati fissi
return MockHttpClient();
}
}
Best Practices for Stable Integration Tests
-
Use Explicit Keys: every interactive widget must have a
Keyconstant to make it findable in tests in a stable way. -
You prefer
pumpAndSettleapump:pumpAndSettlewait for all the hanging animations and frames end, reducing flaky tests due to timing. -
Explicit timeouts: USA
pumpAndSettle(Duration(seconds: 5))for asynchronous operations instead of the default infinite timeout. -
Resetting state between tests: USA
tearDownfor clean SharedPreferences, local databases and authentication tokens. -
Disable animations: in US CI pipelines
--no-enable-impellerand disable animations to speed up execution by 40%.
Conclusions
Integration tests are the last line of defense before deployment to production: they capture regressions that escape unit tests because they emerge from interaction between real components on real hardware. The cost is high — 30-60 seconds per test, setup complexity, ongoing maintenance — but for critical business flows the ROI is indisputable.
The combination of GitHub Actions for quick feedback on every PR and Firebase Test Lab for coverage across heterogeneous physical devices creates a safety net solid that allows you to deploy with confidence. Flutter DevTools completes the picture providing visibility into performance at runtime, transforming tests integration from simple correctness checks to monitoring tools quality of user experience.







