# 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
```

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.

## 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).