// Use when testing or debugging Flet apps in maintainer/contributor development mode with local Python package sources and the local Flutter client, including web, desktop, browser, and computer-use verification workflows.
| name | test-flet-apps-dev |
| description | Use when testing or debugging Flet apps in maintainer/contributor development mode with local Python package sources and the local Flutter client, including web, desktop, browser, and computer-use verification workflows. |
Use this skill when validating a Flet app, example, feature, or bug fix against this repo's local Python packages and/or local Flutter client during maintainer or contributor work.
Flet dev-mode testing usually has one or two processes:
sdk/python.client, when Dart/client or extension code
must be tested.If only Python code changed, uv run flet run ... is often enough. If Dart,
Flutter, extension, or transport code changed, run the local Flutter client so
the changed Dart code is actually used.
The local Flutter client debug build uses a fixed app-server URL from
client/lib/main.dart:
if (kDebugMode) {
pageUrl = "http://localhost:8550";
}
Therefore, when using the local Flutter client without extra URL arguments,
start the Python app on port 8550.
Run from {repo}/sdk/python:
uv run flet run -w -p 8550 examples/controls/core/interactive_viewer/handling_events/main.py
Adjust the sample path as needed. Use port 8550 when the local Flutter client
will connect with its default debug URL. Keep this process running and watch its
stdout for Python callback output, tracebacks, and event payloads.
For web-only checks with the packaged web client, open:
http://127.0.0.1:8550
Run these from {repo}/client.
Use when validating native desktop behavior on the current host OS:
fvm flutter run -d macos # macOS
fvm flutter run -d windows # Windows
fvm flutter run -d linux # Linux
The debug client defaults to http://localhost:8550 when no app URL argument is
provided. Use the platform target that exists on the current machine. Use
Computer Use or the relevant platform automation to navigate and interact with
the app window.
Use when Dart web behavior must be validated in Flutter's default web debug browser:
fvm flutter run -d chrome
This opens a fresh browser connected to the Python app server on port 8550.
If the requested browser is not listed by flutter devices, prefer the web
server target and open the served URL in that browser:
fvm flutter run -d web-server --web-hostname 127.0.0.1 --web-port 8660
open -a "Brave Browser" http://127.0.0.1:8660
Using CHROME_EXECUTABLE can work, but Flutter may fail to attach its debug
websocket in non-default Chromium browsers. Fall back to web-server if that
happens.
localhost, 127.0.0.1, file://), prefer the
in-app browser or the Browser Use plugin when explicitly requested.Always inspect both sides:
print() calls, Python tracebacks.For client/server protocol bugs, compare the raw outgoing Dart event in Flutter logs with the decoded Python event object in Python logs.
For Flutter client sessions:
r for hot reload after many Dart-only edits.R for hot restart if state, initialization, or extension registration
may be stale.q before final response unless the user explicitly wants the app
left running.h for help on other Flutter run key commands.For Python app sessions, restart uv run flet run ... after Python source or
sample changes if the running process does not pick them up.
engine.stamp, rerun the same command with escalation.flutter devices does not list Brave/Edge/etc., use flutter run -d web-server
and open the URL in the target browser.8550 or pass an explicit app URL when the client path supports it.Use when adding or changing deprecations for Python controls/APIs in sdk/python/packages/, including V.deprecated fields, deprecated decorators, version lifecycle, and docs admonitions/labels.
Use when asked to prepare new Flet release by bumping versions and author release notes.
Use when writing or reviewing Flet documentation, including Python docstrings (Google style, reST roles, admonitions), Markdown docs (cross-references, images, code examples), and sidebar navigation.
Use when asked to add, revise, or review a changelog or release-notes entry in this repo. Inspect the existing changelog section style and the relevant PR, issue, and commit context first, then write a focused entry in the correct release section without overstating docs, tests, or chores unless they are the primary user-facing change.
Use whenever editing validation for Python controls in sdk/python/packages/: adding/changing constrained properties, `Raises: ValueError` docstrings, `before_update()` checks, `raise ValueError`, Annotated/V rules, or __validation_rules__.
Create or update Flet control screenshots and GIFs that are generated from integration tests and shown in docs. Use when working on `sdk/python/packages/flet/integration_tests/examples`, refreshing static or interactive golden screenshots, or replacing old example media images or GIFs with generated test assets.
