Skip to main content

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. Set FLET_TEST_GOLDEN=failed to 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) - 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.
  • 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 runs flutter 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) - Seconds start() waits for the Flutter app to connect before it stops the Flutter test process and raises TimeoutError. Defaults to 60 seconds when app_binary is launched, which connects within seconds, and to no limit when flutter test builds the app before it starts, which can take minutes. 0 disables the limit. Env override: FLET_TEST_START_TIMEOUT.

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.
  • FLET_TEST_APP_BINARY: Overrides app_binary.
  • FLET_TEST_START_TIMEOUT: Overrides start_timeout.

Properties

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​

pageproperty​

page: Page

Returns an instance of Flet's app Page.

screenshots_pixel_ratioinstance-attribute​

screenshots_similarity_thresholdinstance-attribute​

test_deviceinstance-attribute​

test_platforminstance-attribute​

testerproperty​

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​

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 behind control, with a 10 pixel margin. If None, the screenshot background is transparent. Pass a light color such as ft.Colors.SURFACE (with a light theme_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 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.

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

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 main or by its first pump_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,
) -> bytes

Takes a screenshot of all controls on the current page.

Parameters:

  • bgcolor (ColorValue | None, default: None) - Background color of the screenshot. If None, 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_binary had 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,
) -> Screenshot

Wraps 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. If None, the screenshot background is transparent.