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, 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

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

## Running The App

Install dependencies:

```sh
flutter pub get
```

Run on a connected device or emulator:

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

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

```sh
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`](../../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
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`:

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