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 a Page instance 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) - If True, screenshots taken during tests are stored as golden reference images. Env override: FLET_TEST_GOLDEN=1.
• 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) - If True, use HTTP transport instead of TCP for Flet client-server communication. Env override: FLET_TEST_USE_HTTP=1.
• disable_fvm (bool, default: False) - If True, do not invoke fvm when running the Flutter test process. Env override: FLET_TEST_DISABLE_FVM=1.
• skip_pump_and_settle (bool, default: False) - If True, the initial pump_and_settle after app start is skipped.
• device_mode (bool, default: False) - If True, the app under test runs on-device with embedded Python (over dart_bridge), as produced by flet build. This session then hosts only the Tester over a dedicated channel and does not run flet_app_main. If False (default), the app runs here in-process (host mode) against the dev client shell. Env override: FLET_TEST_DEVICE_MODE=1.

Environment Variables:

• FLET_TEST_PLATFORM: Overrides test_platform.
• FLET_TEST_DEVICE: Overrides test_device.
• FLET_TEST_GOLDEN: Enables golden screenshot capture when set to 1.
• FLET_TEST_SCREENSHOTS_PIXEL_RATIO: Overrides screenshots_pixel_ratio.
• FLET_TEST_SCREENSHOTS_SIMILARITY_THRESHOLD: Overrides screenshots_similarity_threshold.
• FLET_TEST_USE_HTTP: Enables HTTP transport when set to 1.
• FLET_TEST_DISABLE_FVM: Disables fvm usage when set to 1.

Properties

• page - Returns an instance of Flet's app Page.
• screenshots_pixel_ratio
• screenshots_similarity_threshold
• test_device
• test_platform
• tester - 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 if FLET_TEST_GOLDEN=1 environment variable is set.
• assert_gif - Compare an animated GIF built from frames against a golden GIF.
• assert_screenshot - Compares provided screenshot with a golden copy or takes golden screenshot if FLET_TEST_GOLDEN=1 environment 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

buildpageproperty

page: Page

Returns an instance of Flet's app Page.

buildscreenshots_pixel_ratioinstance-attribute

buildscreenshots_similarity_thresholdinstance-attribute

buildtest_deviceinstance-attribute

buildtest_platforminstance-attribute

buildtesterproperty

tester: Tester | RemoteTester

Returns the tester that programmatically interacts with page controls and the test environment. In device mode this is a RemoteTester driving the app over a socket.

Methods

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

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.

deployed_codeassert_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. 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 single int or a per-frame sequence matching the number of frames.
• loop (int, default: 0) - Number of times the GIF should repeat (0 means infinite).
• disposal (DisposalMode, default: DisposalMode.DEFAULT) - Frame disposal mode.
• similarity_threshold (float, default: 0) - Minimum acceptable per-frame SSIM (%). Uses screenshots_similarity_threshold when 0.

deployed_codeassert_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.

deployed_codecreate_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,
) -> Path

Create 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 .gif extension 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 with take_animation.
• duration (int | Sequence[int], default: 1000) - Frame duration in milliseconds. Either a single int applied to every frame, or a sequence of int with one entry per frame. Pass the same list used for take_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 (0 means 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 / frames are given, the input is empty, or a duration sequence has a different length than the frame count.
• FileNotFoundError - If any referenced image file does not exist.

deployed_coderesize_page

resize_page(width: float, height: float)

Resizes the page window to the specified width and height.

deployed_codestartasync

start()

Starts Flet app and Flutter integration test process.

deployed_codetake_page_controls_screenshotasync

take_page_controls_screenshot(
    pixel_ratio: float | None = None,
    pump_times: int = 0,
    pump_duration: DurationValue | None = None,
) -> bytes

Takes a screenshot of all controls on the current page.

deployed_codeteardownasync

teardown()

Teardown Flutter integration test process.

deployed_codewrap_page_controls_in_screenshotasync

wrap_page_controls_in_screenshot(
    margin=10,
    pump_times: int = 0,
    pump_duration: DurationValue | None = None,
) -> Screenshot

Wraps provided controls in a Screenshot control.