native-desktop-ui-testing

name	native-desktop-ui-testing
description	Run and verify Flutter desktop behavior on Windows/macOS/Linux native clients. Invoke when developing, fixing, or testing PC features, user flows, interaction results, Dart MCP scenarios, or testability anchors like ValueKey.
metadata	{"author":"SOLO","version":"1.0.0","domain":"desktop-ui-testing","role":"specialist","scope":"execution"}

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

Step 5. Verify user-visible evidence

Do not treat a successful command response as enough.

Always verify with one or more of:

• another waitFor
• screenshot evidence
• visible text change
• page title change
• widget tree state change
• runtime logs when relevant

If screenshots are captured for testing:

• use them only as temporary verification artifacts
• delete them immediately after the verification result is confirmed
• do not leave test screenshots in the repository or workspace after the task is done

Step 6. Check runtime issues

After important actions:

• inspect mcp_dart.get_runtime_errors
• inspect app logs if behavior is suspicious

Project-Specific Lessons

Successful patterns from this repository

• navigation items already work well when they have stable keys
• desktop native startup can be verified with mcp_dart.launch_app
• flutter_driver works better when critical controls have ValueKey
• screenshots are useful to confirm whether the app is on the home page, detail page, or player page
• player flow often benefits from using ByType for custom composed widgets when text finders are not stable enough

Known caution points

• this project is a desktop client, so web verification is not an acceptable substitute
• some mcp_dart.flutter_driver commands may behave inconsistently with certain parameter combinations; avoid assuming the tool is wrong until you verify with widget tree and screenshots
• a successful desktop launch may still fail if the Windows build artifacts are locked by a stale process; clear stale native processes before retrying

Implementation Guidance For New Code

When adding or updating desktop UI features:

• add ValueKey as part of the initial implementation, not as a late testing patch
• add keys only to meaningful interaction points, not every widget
• keep key names stable and intention-revealing

Suggested naming style:

• nav-home
• settings-logout
• login-submit
• player-play-pause
• player-speed-control
• player-volume-control

Avoid:

• random key names
• unstable index-based names when a semantic name is possible
• renaming keys casually without updating tests

Decision Rules For Automation vs Manual Testing

Automate when:

• the interaction can be controlled without changing product behavior
• a stable ValueKey or reliable runtime finder exists
• the result can be verified with visible evidence

Escalate to manual testing when:

• the interaction depends on real hover behavior or complex OS-level input that MCP cannot reproduce reliably
• automating it would require changing the intended UX
• the interaction is blocked by tool limitations rather than code quality

When escalating, report clearly:

• what was automated successfully
• what could not be automated
• why it should remain manual
• what manual verification steps the user should perform

Output Expectations

When using this skill, provide:

• the native target used
• the entrypoint used
• what flows were automated
• what evidence confirmed success
• what required manual verification, if any
• whether new ValueKey were added and why
• whether any proposed change was rejected because it would alter real product behavior
• whether temporary test screenshots were cleaned up

Short Checklist

• Native desktop target selected
• Web target avoided
• Driver-enabled entrypoint used when needed
• Widget tree inspected before interaction
• ByValueKey preferred for key actions
• Critical UI already has ValueKey, or a minimal product-safe key was added
• No UX behavior was changed just for test convenience
• Manual verification requested when MCP could not reproduce the real interaction
• Runtime errors checked
• Evidence captured with screenshots or visible state changes
• Temporary test screenshots deleted immediately after verification