Native Desktop UI Testing

Native Desktop UI Testing

Overview

This skill is for this Flutter PC client project when running or preparing UI tests for the native desktop app.

Supported target forms:

• Windows desktop app
• macOS desktop app
• Linux desktop app

This skill is not for web UI verification in this project.

When To Use

Default to this skill for this project's desktop client work: whenever you are developing, fixing, or verifying features that affect native user flows, visible state, interaction results, session behavior, navigation outcomes, or other behavior that should be validated through the real desktop client, invoke this skill unless the task is clearly isolated from client-side behavior.

• the user asks to run or verify desktop UI flows
• the task involves mcp_dart UI control
• the task involves player controls, navigation, login/logout, settings, or other desktop client interactions
• the task changes logic that may not alter UI code directly but does affect desktop client behavior or user-visible outcomes
• the task requires adding or reviewing ValueKey for stable UI automation
• the task requires deciding whether a UI interaction should be automated or left for manual verification
• the task is developing or modifying a feature that is suitable for desktop UI testing in this project

Do not use this skill when:

• the task is isolated logic that cannot affect desktop client behavior, native user flows, or visible outcomes
• the task is only a web app verification request
• the task is a simple static code review unrelated to desktop UI execution

Hard Rules

1. Always test the native desktop client

For this repository, UI testing must target the native desktop app, not the web build.

Required behavior:

• prefer native device targets such as windows, macos, or linux
• use mcp_dart.list_devices first, then choose a native desktop device
• launch the app with mcp_dart.launch_app
• if UI control is needed, use a driver-enabled native entrypoint such as lib/driver_main.dart

Forbidden behavior:

• do not use chrome
• do not use edge
• do not switch to web just because web is easier to automate
• do not claim desktop UI is verified if only the web version was tested

Additional expectation:

• when implementing features that are suitable for desktop UI testing, proactively use this skill to run native-client UI verification instead of waiting for the user to explicitly remind you

2. Build testability in during implementation

Do not wait until the testing phase to discover that the UI is hard to control.

When writing or modifying UI code, proactively add stable automation anchors to key interactive widgets.

Priority targets for ValueKey:

• primary navigation items
• login / logout buttons
• primary submit buttons
• critical toggles and switches
• player controls
• detail-page primary actions such as play / continue play
• list items or cards that are expected to be clicked in tests
• dialog confirm / cancel actions when they are important to flows

Good rule of thumb:

• if a widget is critical to a main user path and may be used in automation, give it a stable ValueKey

Avoid weak selectors:

• text-only selectors for frequently changing copy
• structure-based assumptions about widget nesting
• selectors that depend on hover-only state if a stable key can be added without changing product behavior

3. Never change product behavior just to satisfy automation

Do not modify the real interaction design merely because MCP or automation has difficulty operating it.

Examples of unacceptable changes:

• changing a hover-only control to tap-open only for easier testing
• simplifying real interaction flows just to make automation pass
• adding non-product behavior that users do not actually have

Correct fallback:

• if the real interaction is hard to automate with MCP and should remain as designed, keep the product behavior unchanged
• explain the automation limitation clearly
• ask the user to perform that part manually
• report which steps were automated and which steps require manual verification

Manual-test escalation is preferred over changing requirements.

Recommended Execution Workflow

Step 1. Confirm native target

• run mcp_dart.list_devices
• choose windows, macos, or linux
• do not choose browser targets

Step 2. Confirm entrypoint

• use the normal entrypoint when only launching is required
• use a driver-enabled entrypoint when flutter_driver commands are required
• keep the app logic the same; only add a dedicated driver entrypoint when needed

Recommended pattern:

• extract shared bootstrap logic into a reusable entrypoint like lib/app.dart
• keep lib/main.dart for normal startup
• keep lib/driver_main.dart for driver-enabled startup

Step 3. Connect runtime tooling

• launch with mcp_dart.launch_app
• connect using mcp_dart.connect_dart_tooling_daemon
• confirm the app instance with mcp_dart.list_running_apps

Step 4. Inspect before acting

Before trying to tap anything:

• inspect with mcp_dart.get_widget_tree
• use actual runtime tree data to decide finders
• prefer ByValueKey for stable interactions
• use ByText, ByTooltipMessage, or ByType only when appropriate

Recommended finder priority:

1. ByValueKey
2. ByTooltipMessage
3. ByText
4. ByType