· Flutter 개발 · 7 min read
Flutter 단위 테스트 GitHub Actions CI 자동화 — 커밋마다 커버리지 측정하기
flutter test --coverage를 GitHub Actions에 연동해 PR마다 커버리지 리포트를 자동 생성하는 방법. ubuntu 러너 Flutter 세팅, lcov 리포트 아티팩트 업로드, generated 파일 제외까지 실제 workflow 파일로 정리했다.
지금까지 Repository 테스트, Controller 비동기 테스트, BLE 격리, MQTT 격리까지 작성했다. 근데 문제가 있다. 로컬에서만 flutter test를 돌리면 팀원이 PR 올릴 때 테스트를 안 돌려도 아무도 모른다. 실제로 한 번은 BLE Wrapper를 리팩터하면서 테스트를 깨뜨렸는데, 머지 직전에야 알았다.
GitHub Actions로 연동하면 커밋마다 테스트가 자동으로 돌고, 커버리지까지 숫자로 확인할 수 있다.
왜 로컬 테스트만으로는 부족한가
혼자 작업할 때도 문제가 생긴다. mqtt5_client FakeMqttService를 수정하다가 인터페이스 시그니처를 바꿨는데, 관련 Controller 테스트가 컴파일 에러 없이 그냥 통과했다. 이유가 뭔지 추적하다 보니 테스트 파일이 오래된 버전의 Fake를 임포트하고 있었다.
CI가 있었으면 PR 체크 단계에서 걸렸을 문제다. 로컬에선 “방금 고친 거니까 되겠지”하고 넘기게 된다.
기본 워크플로 구조
.github/workflows/test.yml 파일 하나로 시작한다. 핵심은 세 단계다: Flutter 세팅 → 테스트 실행 → 커버리지 업로드.
name: Flutter Test
on:
push:
branches: [master, main, develop]
pull_request:
branches: [master, main]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: subosito/flutter-action@v2
with:
flutter-version: '3.32.0'
channel: 'stable'
cache: true
- name: Install dependencies
run: flutter pub get
- name: Generate mocks
run: dart run build_runner build --delete-conflicting-outputs
- name: Run tests with coverage
run: flutter test --coverage
- name: Upload coverage artifact
uses: actions/upload-artifact@v4
with:
name: coverage-report
path: coverage/lcov.info
subosito/flutter-action@v2가 Flutter SDK 설치를 처리해준다. cache: true를 빼먹으면 매번 SDK 다운로드로 2~3분이 추가된다.
Mockito 코드 생성 처리
Controller 테스트에서 Mockito를 쓴다면 build_runner가 필수다. CI에서 .g.dart 파일을 생성하지 않으면 컴파일 에러로 테스트 자체가 안 돌아간다.
- name: Generate mocks
run: dart run build_runner build --delete-conflicting-outputs
--delete-conflicting-outputs는 로컬에서 생성한 .g.dart와 충돌을 막는다. 이게 없으면 CI에서 “output already exists” 에러가 난다. 처음에 이거 빠뜨리고 30분 날렸다.
lcov 리포트로 커버리지 시각화
flutter test --coverage 실행 후 coverage/lcov.info 파일이 생긴다. 이걸 HTML로 변환하면 어떤 줄이 테스트됐는지 라인별로 볼 수 있다.
- name: Install lcov
run: sudo apt-get install -y lcov
- name: Remove generated files from coverage
run: |
lcov --remove coverage/lcov.info \
'*/lib/*.g.dart' \
'*/lib/*.freezed.dart' \
'**/*.gen.dart' \
-o coverage/lcov.info
- name: Generate HTML report
run: genhtml coverage/lcov.info -o coverage/html
- name: Upload HTML report
uses: actions/upload-artifact@v4
with:
name: coverage-html
path: coverage/html
lcov --remove로 자동생성 파일을 제외하는 단계가 중요하다. .g.dart, .freezed.dart는 테스트하지 않아도 되는 코드인데, 커버리지 숫자를 깎아먹는다. 이걸 안 빼면 커버리지가 실제보다 20~30% 낮게 나온다.
커버리지 임계값 설정
PR을 머지할 때 커버리지가 특정 수치 이하면 실패시키고 싶다면 추가한다.
- name: Check coverage threshold
run: |
COVERAGE=$(lcov --summary coverage/lcov.info 2>&1 | grep "lines" | grep -oP '\d+\.\d+(?=%)')
echo "Coverage: ${COVERAGE}%"
if (( $(echo "$COVERAGE < 70" | bc -l) )); then
echo "Coverage ${COVERAGE}% is below threshold 70%"
exit 1
fi
숫자는 프로젝트 상황에 맞게 잡는다. IoT 앱처럼 외부 하드웨어 의존도가 높으면 70~75%가 현실적이다. 100%를 목표로 하면 의미 없는 테스트만 늘어난다.
PR 코멘트에 커버리지 표시
PR마다 커버리지 숫자를 코멘트로 달아주면 편하다.
- name: Report LCOV
uses: zgosalvez/github-actions-report-lcov@v4
with:
coverage-files: coverage/lcov.info
minimum-coverage: 70
github-token: ${{ secrets.GITHUB_TOKEN }}
update-comment: true
이 액션이 PR에 커버리지 변화 (+2.3% / -1.1%)를 자동으로 코멘트로 달아준다. update-comment: true를 쓰면 새 커밋마다 코멘트를 새로 쓰지 않고 기존 코멘트를 업데이트한다.
삽질 포인트
ubuntu에서 BLE 테스트가 있을 때: ubuntu 러너에는 Bluetooth 스택이 없다. BLE Wrapper 패턴으로 격리한 테스트는 ubuntu에서도 돌아가지만, flutter_blue_plus를 직접 호출하는 코드가 테스트에 남아있으면 플랫폼 채널 에러가 난다. 격리가 잘 돼 있는지 CI에서 먼저 검증되는 셈이다.
dart run build_runner가 느릴 때: CI 캐시를 활용한다.
- name: Cache build_runner output
uses: actions/cache@v4
with:
path: |
.dart_tool/build
**/*.g.dart
key: ${{ runner.os }}-build-${{ hashFiles('pubspec.lock') }}
flutter test가 특정 디바이스 없이 실패할 때: flutter test는 기본적으로 VM에서 실행된다. -d 옵션 없이 실행하면 된다. 위젯 테스트가 있으면 --platform chrome이 필요한 경우도 있다.
완성된 workflow 파일
name: Flutter Test & Coverage
on:
push:
branches: [master, main, develop]
pull_request:
branches: [master, main]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: subosito/flutter-action@v2
with:
flutter-version: '3.32.0'
channel: 'stable'
cache: true
- name: Install dependencies
run: flutter pub get
- name: Generate mocks
run: dart run build_runner build --delete-conflicting-outputs
- name: Run tests with coverage
run: flutter test --coverage
- name: Install lcov
run: sudo apt-get install -y lcov
- name: Remove generated files from coverage
run: |
lcov --remove coverage/lcov.info \
'*/lib/*.g.dart' \
'*/lib/*.freezed.dart' \
'**/*.gen.dart' \
-o coverage/lcov.info
- name: Generate HTML report
run: genhtml coverage/lcov.info -o coverage/html
- name: Report LCOV
uses: zgosalvez/github-actions-report-lcov@v4
with:
coverage-files: coverage/lcov.info
minimum-coverage: 70
github-token: ${{ secrets.GITHUB_TOKEN }}
update-comment: true
- name: Upload HTML report
uses: actions/upload-artifact@v4
with:
name: coverage-html
path: coverage/html
이 파일 하나를 .github/workflows/test.yml에 넣으면 PR마다 테스트가 돌고 커버리지가 코멘트로 달린다.
다음 편은 Widget Test — 화면 단위 UI 테스트를 실제 IoT 제어 화면에 적용하는 내용이다.
참고 링크