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

```text
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:

```sh
flutter pub get
```

Run on a connected device or emulator:

```sh
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`](../../packages/messaging_flutter/README.md#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`](../../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`](../../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`](../../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:

```sh
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`:

```sh
./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`](../../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`](../../packages/messaging_flutter/README.md#manual-smoke-checklist).