feat: Dockerized Android integration tests for native ForegroundService lifecycle

.github/workflows/integration-test.yml

@@ -0,0 +1,49 @@
+name: Integration Test
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [ "master", "development" ]
+  # pull_request:
+  #   branches: [ "master", "development" ]
+
+jobs:
+  android-integration:
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+
+    steps:
+      - name: Clone repository
+        uses: actions/checkout@v4
+
+      - name: Free up runner disk space
+        uses: endersonmenezes/free-disk-space@v3
+        with:
+          remove_android: true
+          remove_dotnet: true
+          remove_haskell: true
+          remove_tool_cache: true
+          remove_swap: true
+
+      - name: Enable KVM
+        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: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Build Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          file: scripts/Dockerfile.integration-test
+          tags: fft-integration:latest
+          load: true
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      - name: Run integration tests
+        run: docker run --device /dev/kvm fft-integration:latest

.github/workflows/unit-test.yml

@@ -0,0 +1,45 @@
+name: Unit Test
+
+on:
+  push:
+    branches: [ "master", "development" ]
+  pull_request:
+    branches: [ "master", "development" ]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  unit-test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Clone repository
+        uses: actions/checkout@v4
+
+      - name: Set up Flutter
+        uses: subosito/flutter-action@v2
+        with:
+          channel: stable
+          cache: true
+
+      - name: Install dependencies
+        run: flutter pub get
+
+      - name: Run unit tests with coverage
+        run: flutter test --coverage
+
+      - name: Install lcov
+        run: sudo apt-get install -y lcov
+
+      - name: Generate HTML coverage report
+        run: genhtml coverage/lcov.info -o coverage/html --no-function-coverage
+
+      - name: Upload coverage report
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report
+          path: coverage/html/
+          retention-days: 14

README.md

@@ -654,6 +654,34 @@ Go [here](./documentation/ios_continued_processing_task.md) to set up iOS 26+ `B
 > [!WARNING]
 > `BGContinuedProcessingTask` requires **Xcode 26+** (Swift 6.2+). If you configure `IOSContinuedProcessingTaskOptions` but build with an older Xcode, the plugin will raise a fatal error at runtime. Either upgrade Xcode or leave the `continuedProcessingTask` option as `null`. See the [continued processing task documentation](./documentation/ios_continued_processing_task.md#xcode-version-requirement) for details.
 
+## Running Integration Tests Locally
+
+The repository includes Android instrumented tests that exercise the native `ForegroundService` lifecycle on a real emulator inside a Docker container. KVM hardware acceleration is required, so a **Linux host** (or a VM with nested virtualisation enabled) is needed.
+
+### Prerequisites
+
+* Docker installed and running
+* `/dev/kvm` accessible to the current user (verify with `ls -l /dev/kvm`)
+
+### Build & run
+
+```bash
+# Build the Docker image (first run downloads ~10 GB of SDK/emulator images)
+docker build -t fft-integration -f scripts/Dockerfile.integration-test .
+
+# Run the tests — KVM passthrough is mandatory
+docker run --device /dev/kvm fft-integration
+```
+
+The container boots a headless Android 14 (API 34) emulator, installs the example app + test APK, and executes the Kotlin instrumented tests via `./gradlew :app:connectedAndroidTest`. Test results are printed to stdout; the exit code reflects pass/fail.
+
+### macOS / Windows
+
+KVM is Linux-only. On macOS or Windows you can either:
+
+* Run the Docker command inside a Linux VM that exposes `/dev/kvm` (e.g. using UTM or WSL 2 with nested virtualisation).
+* Skip Docker and run the emulator + tests natively: start an `x86_64` AVD, then execute `cd example && ./gradlew :app:connectedAndroidTest`.
+
 ## Support
 
 If you find any bugs or issues while using the plugin, please register an issues on [GitHub](https://github.com/Dev-hwang/flutter_foreground_task/issues). You can also contact us at <hwj930513@naver.com>.

example/android/.gitignore

@@ -1,8 +1,5 @@
-gradle-wrapper.jar
 /.gradle
 /captures/
-/gradlew
-/gradlew.bat
 /local.properties
 GeneratedPluginRegistrant.java
 

example/android/app/build.gradle

@@ -39,6 +39,7 @@ android {
 
     sourceSets {
         main.java.srcDirs += 'src/main/kotlin'
+        androidTest.java.srcDirs += 'src/androidTest/kotlin'
     }
 
     defaultConfig {
@@ -48,6 +49,7 @@ android {
         targetSdkVersion 35
         versionCode flutterVersionCode.toInteger()
         versionName flutterVersionName
+        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
     }
 
     buildTypes {
@@ -58,11 +60,8 @@ android {
         }
 
         debug {
-            shrinkResources true
-            minifyEnabled true
-            proguardFiles getDefaultProguardFile(
-                    'proguard-android-optimize.txt'),
-                    'proguard-rules.pro'
+            minifyEnabled false
+            shrinkResources false
         }
     }
 }
@@ -71,4 +70,8 @@ flutter {
     source '../..'
 }
 
-dependencies {}
+dependencies {
+    androidTestImplementation 'androidx.test:runner:1.6.2'
+    androidTestImplementation 'androidx.test:rules:1.6.1'
+    androidTestImplementation 'androidx.test.ext:junit:1.2.1'
+}