Flutter Integration Test 가이드

Flutter 테스트의 3단계

Flutter는 테스트를 세 가지 수준으로 나눈다. 아래로 갈수록 범위가 넓고, 실행 비용이 높다.

Integration Test의 특징

• 실제 앱을 빌드하여 실기기/에뮬레이터 위에서 실행한다
• 사용자가 앱을 조작하는 것과 동일한 방식으로 버튼 탭, 텍스트 입력, 화면 전환을 자동으로 수행한다
• 네이티브 플러그인(카메라, 파일 접근, 권한 등)도 실제로 동작한다
• UI 렌더링, 애니메이션, 네비게이션이 포함된 End-to-End(E2E) 테스트이다

수동 테스트의 문제점

• 매 빌드마다 같은 화면을 반복적으로 눌러봐야 한다
• 화면 전환, 버튼 동작, 설정 변경 등 모든 경로를 사람이 일일이 확인하기 어렵다
• 리팩토링 후 기존 기능이 깨졌는지 확인하려면 전체를 다시 돌려봐야 한다
• 야간 빌드, CI/CD 파이프라인에서 자동 검증이 불가능하다

Integration Test가 해결하는 것

• 회귀 방지: 코드 변경 후 기존 기능이 정상인지 자동 확인
• 반복 작업 제거: 한 번 작성하면 수백 번 반복 실행 가능
• 실제 환경 검증: 에뮬레이터/실기기에서 네이티브 기능까지 포함하여 테스트
• 팀 협업: 새 팀원이 합류해도 테스트만 돌리면 기능 정상 여부를 즉시 확인 가능

Step 1: pubspec.yaml에 의존성 추가

integration_test는 Flutter SDK에 내장되어 있다. 별도 버전 지정 없이 sdk: flutter로 추가한다.

# pubspec.yaml
dev_dependencies:
  flutter_test:
    sdk: flutter
  integration_test:
    sdk: flutter

추가 후 flutter pub get을 실행한다.

Step 2: 폴더 구조 생성

프로젝트 루트에 다음 두 폴더를 만든다.

my_app/
  integration_test/       # 통합 테스트 파일
    app_test.dart         # 메인 테스트
  test_driver/            # (선택) 드라이버 설정
    integration_test.dart # 드라이버 엔트리포인트

Step 3: test_driver/integration_test.dart (선택)

웹이 아닌 모바일만 대상이라면 이 파일은 생략 가능하다. 필요 시 다음과 같이 작성한다.

import 'package:integration_test/integration_test_driver.dart';

Future<void> main() => integrationDriver();

기본 구조

통합 테스트 파일은 다음 패턴을 따른다.

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();

  testWidgets('홈 화면이 정상 표시된다', (tester) async {
    app.main();
    await tester.pumpAndSettle();

    expect(find.text('환영합니다'), findsOneWidget);
  });
}

위젯 찾기: find

검증: expect

expect(find.text('출력 설정'), findsOneWidget);
expect(find.text('이전 화면'), findsNothing);

사용자 상호작용: tester

// 버튼 탭 후 화면 전환 대기
await tester.tap(find.text('새로 만들기'));
await tester.pumpAndSettle(const Duration(seconds: 2));

// 텍스트 입력
await tester.enterText(find.byType(TextField), '검색어');
await tester.pumpAndSettle();

비동기 대기 패턴

네트워크 요청, 파일 I/O 등 비동기 작업 후에는 pumpAndSettle()만으로 부족할 수 있다. 이 경우 타임아웃을 주거나, 특정 위젯이 나타날 때까지 폴링한다.

// 방법 1: 타임아웃 지정
await tester.pumpAndSettle(const Duration(seconds: 10));

// 방법 2: 특정 위젯이 나타날 때까지 폴링
bool found = false;
for (int i = 0; i < 30; i++) {
  await tester.pump(const Duration(seconds: 1));
  if (find.text('완료').evaluate().isNotEmpty) {
    found = true;
    break;
  }
}
expect(found, isTrue);

group()으로 테스트 묶기

관련된 테스트를 group()으로 묶어서 구조화할 수 있다.

group('앱 시작', () {
  testWidgets('홈 화면이 정상 표시된다', (tester) async {
    // ...
  });

  testWidgets('출력 설정 카드가 표시된다', (tester) async {
    // ...
  });
});

group('화면 전환', () {
  testWidgets('새로 만들기 탭 시 다음 화면으로 이동', (tester) async {
    // ...
  });
});

기본 실행 명령

# 연결된 기기/에뮬레이터에서 실행
flutter test integration_test/app_test.dart

# 특정 디바이스 지정
flutter test integration_test/app_test.dart -d <device-id>

# 에뮬레이터 예시
flutter test integration_test/app_test.dart -d emulator-5554

# 실기기 예시
flutter test integration_test/app_test.dart -d RFKYC0DKY7J

디바이스 목록 확인

# 연결된 디바이스 목록
flutter devices

# 출력 예시:
# Samsung Galaxy S24 (mobile) - RFKYC0DKY7J - android-arm64
# sdk gphone64 arm64 (mobile) - emulator-5554 - android-arm64

특정 테스트만 실행

현재 Flutter integration test에서는 파일 단위로 실행한다. 특정 testWidgets만 골라서 실행하는 기본 옵션은 없으므로, 필요하면 테스트 파일을 분리하거나 skip: true를 활용한다.

testWidgets('건너뛸 테스트', (tester) async {
  // ...
}, skip: true);  // 이 테스트는 건너뜀

현재 테스트 파일: integration_test/app_test.dart

MotionStitch Lite에는 3개 그룹, 총 6개의 통합 테스트가 작성되어 있다.

그룹 1: 앱 시작

그룹 2: 화면 전환

그룹 3: 출력 설정 인터랙션

한계 및 향후 과제

• 모션포토 필요: 에뮬레이터에는 모션포토 파일이 없어서 "스캔 -> 선택 -> 미리보기 -> 인코딩 -> 완료"의 전체 흐름을 테스트할 수 없다. 실기기에 테스트용 모션포토 데이터가 있어야 한다.
• 권한 다이얼로그: "새로 만들기" 탭 시 사진 접근 권한을 요청하는데, 시스템 다이얼로그는 자동 제어 불가. 사전에 권한을 부여해 두어야 한다.
• 인코딩 시간: 실제 영상 생성 테스트는 수 분이 소요될 수 있어 CI 타임아웃 설정이 필요하다.
• YouTube 업로드: Google Sign-In은 시스템 UI를 사용하므로 Integration Test로 자동화하기 어렵다.

기타 유용한 팁

• Key 활용: 테스트 전용으로 위젯에 Key('test_button')를 부여하면 find.byKey()로 안정적으로 찾을 수 있다. 텍스트가 변경되어도 테스트가 깨지지 않는다.
• 스크린샷 캡처: IntegrationTestWidgetsFlutterBinding의 takeScreenshot()으로 실패 시 스크린샷을 저장할 수 있다.
• 테스트 분리: 테스트 간 상태 공유는 예측 불가능한 결과를 낳는다. 각 testWidgets에서 app.main()을 새로 호출하여 깨끗한 상태에서 시작한다.
• 디버그 출력: debugPrint()로 테스트 중간에 로그를 남길 수 있다.

• Flutter 공식 문서: Integration Testing
• pub.dev: integration_test 패키지
• Flutter 공식 문서: Testing Overview
• Firebase Test Lab