ci(android): add Firebase Test Lab workflow for integration tests

Adds .github/workflows/integration-tests-firebase.yml that builds the
example app and instrumented test APKs via flutter/Gradle and runs the
full integration test suite on real hardware via Firebase Test Lab.

Changes from initial version:
- Switch debug APK build to `flutter build apk --debug` so the output
  path is unambiguous (always build/app/outputs/apk/debug/app-debug.apk)
- Gate the job on same-repo PRs only to avoid auth failures from forks
  (secrets are unavailable for fork pull requests)

Triggers on pull_request to develop/main (same-repo) and workflow_dispatch
for manual runs. Built APKs are uploaded as artifacts on every run
(if: always()), retained 14 days.

Adds an Integration Tests section to README.md documenting local run
instructions, CI trigger, and required secrets.

Author: SERDUN

.github/workflows/integration-tests-firebase.yml

@@ -0,0 +1,77 @@
+name: Integration Tests (Firebase Test Lab)
+
+on:
+  workflow_dispatch:
+  pull_request:
+    branches:
+      - develop
+      - main
+    paths:
+      - "webtrit_callkeep/**"
+      - "webtrit_callkeep_android/**"
+      - "webtrit_callkeep_platform_interface/**"
+      - ".github/workflows/integration-tests-firebase.yml"
+
+jobs:
+  integration-tests:
+    name: Integration Tests (Firebase Test Lab)
+    runs-on: ubuntu-latest
+    # Skip fork PRs: secrets are not available for forks, so auth steps would fail.
+    # workflow_dispatch always runs (no fork context).
+    if: github.event_name == 'workflow_dispatch' || github.event.pull_request.head.repo.full_name == github.repository
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up JDK 17
+        uses: actions/setup-java@v4
+        with:
+          java-version: "17"
+          distribution: temurin
+
+      - name: Set up Flutter
+        uses: subosito/flutter-action@v2
+        with:
+          flutter-version: "3.32.0"
+          channel: stable
+
+      - name: Install Flutter dependencies
+        run: flutter pub get
+        working-directory: webtrit_callkeep/example
+
+      - name: Authenticate with Google Cloud
+        uses: google-github-actions/auth@v2
+        with:
+          credentials_json: ${{ secrets.FIREBASE_SERVICE_ACCOUNT }}
+
+      - name: Set up Google Cloud SDK
+        uses: google-github-actions/setup-gcloud@v2
+
+      - name: Build debug APK
+        run: flutter build apk --debug
+        working-directory: webtrit_callkeep/example
+
+      - name: Build instrumented test APK
+        run: ./gradlew :app:assembleAndroidTest
+        working-directory: webtrit_callkeep/example/android
+
+      - name: Run tests on Firebase Test Lab
+        run: |
+          gcloud firebase test android run \
+            --type instrumentation \
+            --app webtrit_callkeep/example/build/app/outputs/apk/debug/app-debug.apk \
+            --test webtrit_callkeep/example/build/app/outputs/apk/androidTest/debug/app-debug-androidTest.apk \
+            --device model=Pixel6,version=33,locale=en,orientation=portrait \
+            --timeout 10m \
+            --project ${{ secrets.FIREBASE_PROJECT_ID }}
+
+      - name: Upload build artifacts and test APKs
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: firebase-test-apks-${{ github.run_number }}
+          path: |
+            webtrit_callkeep/example/build/app/outputs/apk/debug/app-debug.apk
+            webtrit_callkeep/example/build/app/outputs/apk/androidTest/debug/app-debug-androidTest.apk
+          retention-days: 14

README.md

@@ -482,6 +482,39 @@ Feel free to explore it, fork it, and use it as a starting point for your own ap
 
 ---
 
+## Integration Tests (Android)
+
+Integration tests live in
+[`webtrit_callkeep/example/integration_test/`](webtrit_callkeep/example/integration_test/)
+and cover lifecycle, call scenarios, state machine, foreground service timing, background service
+paths, and stress/concurrency scenarios.
+
+Android emulators cannot run these tests reliably — `ConnectionService`, foreground service
+lifecycle, and dual-process (`main` + `:callkeep_core`) teardown require real hardware behaviour.
+
+### Run locally
+
+```bash
+cd webtrit_callkeep/example
+./run_integration_tests.sh                 # auto-detect connected device
+./run_integration_tests.sh -d <device-id>  # explicit device
+```
+
+### Run on Firebase Test Lab (CI)
+
+The workflow `.github/workflows/integration-tests-firebase.yml` runs the full suite on real
+hardware. It triggers on PRs to `develop`/`main` (same-repo only) and can be started manually
+from the Actions tab via `workflow_dispatch`.
+
+Required secrets (configure in GitHub repo settings):
+
+| Secret | Description |
+| --- | --- |
+| `FIREBASE_SERVICE_ACCOUNT` | JSON key for a GCP service account with Firebase Test Lab permissions |
+| `FIREBASE_PROJECT_ID` | GCP project ID linked to your Firebase project |
+
+---
+
 ## 📃 More Resources
 
 - [CallKit Documentation (Apple)](https://developer.apple.com/documentation/callkit)