nexo/apps/flutter-test/README.md

flutter-test

Test-only Flutter app for the Nexo messaging package.

Purpose

This app is the workspace test harness for packages/messaging_flutter. Keep it small and focused on proving the messaging/notification package contract:

• plugin registration in a real Flutter application
• method-channel calls from Dart to the native plugin
• event-channel delivery from native code to Dart
• notification-open routing callbacks
• Android manifest merge behavior
• manual Firebase FCM and nexo server ACK smoke testing

This app is not a nexo product app and is not the original Mattermost app. The original Mattermost app belongs under apps/mattermost/; app-specific product UI and business logic belong in consuming apps outside this repository.

The app is a plugin API consumer and verification host. Native push handling, ACK delivery, token/key storage, notification rendering, inline reply, and dismiss handling remain owned by packages/messaging_flutter.

Thin Host Contract

The host UI should expose only the plugin integration state needed by tests: device token, raw notification event, opened notification event, and routing callback state. test/widget_test.dart protects this contract by asserting the four status lines remain present and product-style controls are not added.

The host app also proves the required SDK integration hooks stay wired without becoming product logic:

• startup calls NexoMessagingPlugin.instance.initialize() when the harness is not in test-only mode
• smoke login values can be bridged to setAuthToken
• device token state is received from onDeviceTokenReady
• notification opens update onNotificationOpened, onNavigateToChannel, and onNavigateToThread output

Logout/session cleanup remains a consuming-app responsibility; this harness only keeps the callback and token handoff surface visible for tests.

Structure

apps/flutter-test/
  lib/                    # Small test harness UI
  test/                   # Widget tests for the harness
  integration_test/       # Device/emulator plugin integration tests
  android/                # Android test host used to load the plugin
  ios/                    # iOS host scaffold
  macos/                  # macOS host scaffold

Running The App

Install dependencies:

flutter pub get

Run on a connected device or emulator:

flutter run

This harness does not own a default host HTTP port. Android/iOS/device smoke tests should receive runtime URLs from the invoking shell or ignored local profiles. If a browser preview is added later, use the workspace frontend slot 13040 unless a later migration plan changes the baseline.

For Android FCM smoke testing, make sure the Android app has the required Firebase configuration, including android/app/google-services.json. Use the plugin-owned Manual Smoke Checklist for FCM delivery, ACK, inline reply, dismiss, and routing evidence.

For iOS notification preparation, keep real Firebase and Apple files out of git. The user must provide the Apple Team/signing path, Bundle ID, APNs credential choice, Firebase iOS app, local GoogleService-Info.plist, physical device path, and smoke send path before an agent can complete a real APNs/FCM smoke. Use ios/Runner/GoogleService-Info.example.plist and ios/Runner/Runner.example.entitlements only as placeholder references. See ../../docs/ios-notification-test-guide.md.

For macOS notification preparation, keep real signing, provisioning, notarization, Firebase, APNs, device token, and private host values out of git. The user must provide the macOS runner, signing mode, Bundle ID if needed, APNs/Firebase scope, UI prompt responsibility, and evidence destination before an agent can complete visible notification smoke. See ../../docs/macos-notification-test-guide.md.

For Windows notification preparation, keep real Microsoft account, package identity, signing, push credentials, device token, and private host values out of git. The user must provide the Windows runner, packaging mode, notification API path, package identity/signing details if needed, UI prompt responsibility, and evidence destination before an agent can complete visible notification smoke. See ../../docs/windows-notification-test-guide.md.

Verification

The integration test uses the plugin's test/debug event injection path for method-channel, event-channel, and opened-routing checks, including channel and CRT thread routing. Real FCM delivery, ACK, inline reply, and dismiss behavior remain manual smoke checks.

Run checks from this directory:

flutter analyze
flutter test
flutter test integration_test

Use flutter test for the thin-host contract and flutter test integration_test for real Flutter host registration, method-channel, event-channel, and opened-routing coverage.

Run Android native unit tests from apps/flutter-test/android:

./gradlew testDebugUnitTest

Android Gradle tests require a configured Android SDK through ANDROID_HOME, ANDROID_SDK_ROOT, or apps/flutter-test/android/local.properties.

When the local machine does not have a usable Android SDK, device, or emulator, the expected local result is an environment failure rather than a product failure. Use the repository-level remote environment guide for Android integration and native unit verification: ../../packages/messaging_flutter/docs/android-test-environment.md.

Maintenance Rules

• Keep the app thin.
• Prefer deterministic test controls over product-like UI.
• Do not add consuming-app business logic here.
• Do not grow this host into a nexo product app.
• Do not use this path for the original Mattermost app; that belongs under apps/mattermost/.
• Add integration tests here when a plugin behavior needs a real Flutter host.
• Keep manual FCM and server checks documented with the owning module: Manual Smoke Checklist.