nexo/apps/flutter-test

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, routing callback state, and web notification smoke controls for permission/display checks. test/widget_test.dart protects this contract by asserting the status lines and web smoke controls remain present without adding product-style input flows.

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
  web/                    # Web test host scaffold for browser smoke checks

Running The App

Install dependencies:

flutter pub get

Run on a connected device or emulator:

flutter run

This harness does not own default host, port, credential, or forwarding values. Android/iOS/device smoke tests and browser previews should receive runtime URLs from the invoking shell or ignored local profiles.

For Flutter Web browser notification smoke, load the ignored local preview profile before starting the remote web server. Keep the actual host, port, container, and forwarded URL values in agent-test/local/web-smoke.env or the invoking shell.

set -a
source ../../agent-test/local/web-smoke.env
set +a

ssh "$NEXO_REMOTE_SSH" "zsh -lc 'docker exec ${NEXO_PREVIEW_CONTAINER} sh -lc \"cd ${NEXO_CONTAINER_REPO}/apps/flutter-test && flutter build web\"'"
ssh "$NEXO_REMOTE_SSH" "zsh -lc 'docker exec ${NEXO_PREVIEW_CONTAINER} sh -lc \"cd ${NEXO_CONTAINER_REPO}/apps/flutter-test && flutter run -d web-server --web-hostname ${NEXO_WEB_HOSTNAME} --web-port ${NEXO_CONTAINER_WEB_PORT}\"'"

In a separate shell, verify the forwarded preview URL responds:

set -a
source ../../agent-test/local/web-smoke.env
set +a

ssh "$NEXO_REMOTE_SSH" "zsh -lc 'curl -fsS ${NEXO_BROWSER_PREVIEW_URL} >/dev/null'"

Open the forwarded localhost URL in a browser and use the web smoke controls to verify:

• Refresh web permission reports browser notification support and the current permission state.
• Request web permission triggers the browser permission prompt and updates the permission status.
• Show web smoke notification updates Last web display to shown when permission is granted and a visible browser notification appears.
• Clicking the browser notification updates Last opened and Last navigation for the smoke channel payload.

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
flutter build web

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. Use flutter build web to verify that the web host scaffold remains buildable before browser notification smoke checks run on the remote runner.

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.