FletTestApp
Flet app test controller coordinates running a Python-based Flet app alongside a Flutter integration test.
This class launches the Python Flet app, starts the Flutter test process, and facilitates programmatic interaction with the app's controls for automated UI testing.
Parameters:
- flutter_app_dir (os.PathLike) - Path to the Flutter app directory containing integration tests.
- flet_app_main (AppCallable | None, default:
None) - A callable or coroutine function representing the main entry point of the Flet app under test. This will be invoked with aPageinstance when the app starts. - assets_dir (os.PathLike | None, default:
None) - Path to the directory containing static assets for the Flet app. Defaults to"assets"if not provided. - test_path (str | None, default:
None) - Path to the Python test file. Used to determine the location for golden screenshot comparisons. - tcp_port (int | None, default:
None) - TCP port to run the Flet server on. If not specified, a free port is automatically selected. - test_platform (str | None, default:
None) - Target platform for the Flutter integration test (e.g.,"windows","linux","macos","android","ios"). Env override:FLET_TEST_PLATFORM. - test_device (str | None, default:
None) - Target device ID or name for the Flutter integration test. Env override:FLET_TEST_DEVICE. - capture_golden_screenshots (bool, default:
False) - IfTrue, screenshots taken during tests are stored as golden reference images. Env override:FLET_TEST_GOLDEN=1. SetFLET_TEST_GOLDEN=failedto compare as usual and overwrite only goldens that are missing, below the similarity threshold or changed in color. - screenshots_pixel_ratio (float, default:
2.0) - Device pixel ratio to use when capturing screenshots. Env override:FLET_TEST_SCREENSHOTS_PIXEL_RATIO. - screenshots_similarity_threshold (float, default:
99.0) - Minimum percentage similarity required for screenshot comparisons to pass. Env override:FLET_TEST_SCREENSHOTS_SIMILARITY_THRESHOLD. - use_http (bool, default:
False) - IfTrue, use HTTP transport instead of TCP for Flet client-server communication. Env override:FLET_TEST_USE_HTTP=1. - disable_fvm (bool, default:
False) - IfTrue, do not invokefvmwhen running the Flutter test process. Env override:FLET_TEST_DISABLE_FVM=1. - skip_pump_and_settle (bool, default:
False) - IfTrue, the initialpump_and_settleafter app start is skipped. - device_mode (bool, default:
False) - IfTrue, the app under test runs on-device with embedded Python (over dart_bridge), as produced byflet build. This session then hosts only theTesterover a dedicated channel and does not runflet_app_main. IfFalse(default), the app runs here in-process (host mode) against the devclientshell. Env override:FLET_TEST_DEVICE_MODE=1. - app_binary (os.PathLike | None, default:
None) - Path to the executable of a Flutter app built with the integration test as its entry point. When set,start()launches it directly; otherwise it runsflutter test, which builds the app on every start. Used only when the tests run on the host desktop platform and not in device mode. Env override:FLET_TEST_APP_BINARY. - start_timeout (float | None, default:
None) - Secondsstart()waits for the Flutter app to connect before it stops the Flutter test process and raisesTimeoutError. Defaults to 60 seconds whenapp_binaryis launched, which connects within seconds, and to no limit whenflutter testbuilds the app before it starts, which can take minutes.0disables the limit. Env override:FLET_TEST_START_TIMEOUT.
Environment Variables:
FLET_TEST_PLATFORM: Overridestest_platform.FLET_TEST_DEVICE: Overridestest_device.FLET_TEST_GOLDEN: Enables golden screenshot capture when set to1.FLET_TEST_SCREENSHOTS_PIXEL_RATIO: Overridesscreenshots_pixel_ratio.FLET_TEST_SCREENSHOTS_SIMILARITY_THRESHOLD: Overridesscreenshots_similarity_threshold.FLET_TEST_USE_HTTP: Enables HTTP transport when set to1.FLET_TEST_DISABLE_FVM: Disablesfvmusage when set to1.FLET_TEST_APP_BINARY: Overridesapp_binary.FLET_TEST_START_TIMEOUT: Overridesstart_timeout.
Properties
page- Returns an instance of Flet's appPage.screenshots_pixel_ratioscreenshots_similarity_thresholdtest_devicetest_platformtester- Returns the tester that programmatically interacts with page controls and the test environment.
Methods
assert_control_screenshot- Adds control to a clean page, takes a screenshot and compares it with a golden copy or takes golden screenshot ifFLET_TEST_GOLDEN=1environment variable is set.assert_gif- Compare an animated GIF built fromframesagainst a golden GIF.assert_screenshot- Compares provided screenshot with a golden copy or takes golden screenshot ifFLET_TEST_GOLDEN=1environment variable is set.create_gif- Create an animated GIF from a sequence of PNG frames.resize_page- Resizes the page window to the specified width and height.start- Starts Flet app and Flutter integration test process.take_page_controls_screenshot- Takes a screenshot of all controls on the current page.teardown- Teardown Flutter integration test process.wrap_page_controls_in_screenshot- Wraps provided controls in a Screenshot control.
Properties
screenshots_pixel_ratioinstance-attribute
screenshots_similarity_thresholdinstance-attribute
test_deviceinstance-attribute
test_platforminstance-attribute
Methods
assert_control_screenshotasync
assert_control_screenshot(
name: str,
control: Control,
pump_times: int = 0,
pump_duration: DurationValue | None = None,
expand_screenshot: bool = False,
similarity_threshold: float = 0,
bgcolor: ColorValue | None = None,
)Adds control to a clean page, takes a screenshot and compares it with a golden copy or takes golden screenshot if FLET_TEST_GOLDEN=1 environment variable is set.
Parameters:
- name (str) - Screenshot name - will be used as a base for a screenshot filename.
- control (Control) - Control to take a screenshot of.
- bgcolor (ColorValue | None, default:
None) - Background color painted behindcontrol, with a 10 pixel margin. IfNone, the screenshot background is transparent. Pass a light color such asft.Colors.SURFACE(with a lighttheme_mode) for images used in the docs.
assert_gif
assert_gif(
name: str,
frames: Iterable[bytes],
duration: int | Sequence[int] = 1000,
loop: int = 0,
disposal: DisposalMode = DisposalMode.DEFAULT,
similarity_threshold: float = 0,
)Compare an animated GIF built from frames against a golden GIF.
Builds the GIF in memory from the provided frames. If the
FLET_TEST_GOLDEN=1 environment variable is set, writes the GIF as
the golden reference. With FLET_TEST_GOLDEN=failed, the golden is
overwritten only when it is missing or doesn't match. Otherwise loads
the existing golden GIF from disk and compares frame-by-frame via
structural similarity, saving an <name>_actual.gif next to the
golden on mismatch.
Parameters:
- name (str) - GIF name - will be used as a base for the GIF file name.
- frames (Iterable[bytes]) - Iterable of PNG-encoded frame bytes. Typically the result of
Page.take_animation(...). - duration (int | Sequence[int], default:
1000) - Frame duration in milliseconds. Either a singleintor a per-frame sequence matching the number of frames. - loop (int, default:
0) - Number of times the GIF should repeat (0means infinite). - disposal (DisposalMode, default:
DisposalMode.DEFAULT) - Frame disposal mode. - similarity_threshold (float, default:
0) - Minimum acceptable per-frame SSIM (%). Usesscreenshots_similarity_thresholdwhen0.
assert_screenshot
assert_screenshot(
name: str,
screenshot: bytes,
similarity_threshold: float = 0,
)Compares provided screenshot with a golden copy or takes golden screenshot if FLET_TEST_GOLDEN=1 environment variable is set.
Parameters:
- name (str) - Screenshot name - will be used as a base for a screenshot filename.
- screenshot (bytes) - Screenshot contents in PNG format.
create_gif
create_gif(
image_names: Iterable[str] | None = None,
output_name: str = "",
frames: Iterable[bytes] | None = None,
duration: int | Sequence[int] = 1000,
loop: int = 0,
disposal: DisposalMode = DisposalMode.DEFAULT,
) -> PathCreate an animated GIF from a sequence of PNG frames.
Exactly one of image_names or frames must be provided. Unlike
assert_gif, this method only writes the GIF and returns its
path; it does not compare against a golden file.
Parameters:
- image_names (Iterable[str] | None, default:
None) - Iterable of file name stems (without.png) in the order they should appear in the animation. Frames are read from disk under the test's golden directory. - output_name (str, default:
'') - Base name for the resulting animation. The.gifextension is added automatically and the file is stored in the same directory as the source frames. - frames (Iterable[bytes] | None, default:
None) - Iterable of PNG-encoded frame bytes to use directly, in the order they should appear in the animation. Typically paired withtake_animation. - duration (int | Sequence[int], default:
1000) - Frame duration in milliseconds. Either a singleintapplied to every frame, or a sequence ofintwith one entry per frame. Pass the same list used fortake_animation(frame_delays_ms=...)to have the GIF play at the same pace it was captured. - loop (int, default:
0) - Number of times the GIF should repeat (0means infinite). - disposal (DisposalMode, default:
DisposalMode.DEFAULT) - Frame disposal mode.
Returns:
- Path - Path to the generated GIF file.
Raises:
- ValueError - If neither or both of
image_names/framesare given, the input is empty, or adurationsequence has a different length than the frame count. - FileNotFoundError - If any referenced image file does not exist.
resize_page
resize_page(width: float, height: float)Resizes the page window to the specified width and height.
startasync
start()Starts Flet app and Flutter integration test process.
Raises:
- TimeoutError - If the Flutter app has not connected within
start_timeout. - RuntimeError - If the Flutter process exits, or the Flet app server stops, before the app has started.
- Exception - The exception raised by the app's
mainor by its firstpump_and_settle.
take_page_controls_screenshotasync
take_page_controls_screenshot(
pixel_ratio: float | None = None,
pump_times: int = 0,
pump_duration: DurationValue | None = None,
bgcolor: ColorValue | None = None,
) -> bytesTakes a screenshot of all controls on the current page.
Parameters:
- bgcolor (ColorValue | None, default:
None) - Background color of the screenshot. IfNone, it is transparent.
teardownasync
teardown()Teardown Flutter integration test process.
The process gets 10 seconds to exit after the tester's teardown and is
terminated when it does not. An app launched from app_binary ends its
own process with the test result as exit code, so its result is
unknown when it has to be terminated, and when it did not acknowledge
the tester's teardown: it ended before its test completed, and exit
code 0 then comes from the app closing, not from a passed test.
Raises:
- RuntimeError - If the Flutter test process exited with a non-zero code, or an app launched from
app_binaryhad to be terminated or did not acknowledge teardown.
wrap_page_controls_in_screenshotasync
wrap_page_controls_in_screenshot(
margin=10,
pump_times: int = 0,
pump_duration: DurationValue | None = None,
bgcolor: ColorValue | None = None,
) -> ScreenshotWraps provided controls in a Screenshot control.
Parameters:
- margin (default:
10) - Space around the controls included in the screenshot. - bgcolor (ColorValue | None, default:
None) - Background color painted behind the controls and margin. IfNone, the screenshot background is transparent.