create-flet-control-integration-tests

name: create-flet-control-integration-tests description: Use when asked to create or update integration tests for any Flet control in sdk/python/packages/flet/integration_tests, including visual goldens and interactive behavior tests.

When to use

Use this skill when adding, updating, or reviewing integration tests for a Flet control (core, material, cupertino, theme, services, types, or examples).

Use it for:

visual rendering checks with golden screenshots
interaction checks (hover, click, input, keyboard)
control property behavior checks
regression tests for control bugs

Test placement

Pick the closest existing suite first:

Core controls: sdk/python/packages/flet/integration_tests/controls/core
Material controls: sdk/python/packages/flet/integration_tests/controls/material
Cupertino controls: sdk/python/packages/flet/integration_tests/controls/cupertino
Theme tests: sdk/python/packages/flet/integration_tests/controls/theme
Type helpers: sdk/python/packages/flet/integration_tests/controls/types
Services: sdk/python/packages/flet/integration_tests/controls/services
Examples: sdk/python/packages/flet/integration_tests/examples

Prefer adding tests to an existing file for the same control. Create a new test file only when no suitable file exists.

Scope split rule (required)

Do not mix loop_scope="module" and loop_scope="function" tests in the same file.

Naming convention:

test_<control>.py for module-scoped visual/stable tests (uses flet_app)
test_<control>_isolated.py for function-scoped tests that require a fresh app per test (uses flet_app_function)

Fixture choice

Use fixtures from integration_tests/conftest.py:

flet_app (loop_scope="module"): best for stable visual tests and bulk screenshot tests.
flet_app_function (loop_scope="function"): best for tests that mutate state and must run in a separate app each.

Authoring workflow

Identify behavior to verify.
Build deterministic layout/state:

set theme_mode explicitly when visuals matter
set fixed sizes/padding/spacing
avoid random or time-varying content

Choose file by scope rule before writing tests.
Write test using async pytest.
Use screenshot assertion for UI behavior, functional assertion for non-visual behavior.
Name test so request.node.name can be used as screenshot key.
Run target test file.
If expected visuals changed, regenerate goldens with FLET_TEST_GOLDEN=1 and re-run without golden mode.

Assertion patterns

Visual control assertion

await flet_app.assert_control_screenshot(
    request.node.name,
    control,
)

Visual full-page assertion

flet_app_function.assert_screenshot(
    request.node.name,
    await flet_app_function.page.take_screenshot(
        pixel_ratio=flet_app_function.screenshots_pixel_ratio
    ),
)

Functional assertion

finder = await flet_app_function.tester.find_by_tooltip("Info tooltip")
assert finder.count == 1

Minimal templates

Template: module-scope file (`test_<control>.py`)

import pytest

import flet as ft
import flet.testing as ftt


@pytest.mark.asyncio(loop_scope="module")
async def test_<behavior>(flet_app: ftt.FletTestApp, request):
    flet_app.page.theme_mode = ft.ThemeMode.LIGHT
    await flet_app.assert_control_screenshot(
        request.node.name,
        ft.Container(width=240, height=80, alignment=ft.Alignment.CENTER),
    )

Template: function-scope file (`test_<control>_isolated.py`)

import pytest

import flet as ft
import flet.testing as ftt


@pytest.mark.asyncio(loop_scope="function")
async def test_<behavior>(flet_app_function: ftt.FletTestApp):
    flet_app_function.page.add(ft.IconButton(icon=ft.Icons.INFO, tooltip="Info"))
    await flet_app_function.tester.pump_and_settle()

    finder = await flet_app_function.tester.find_by_tooltip("Info")
    assert finder.count == 1

Run commands

Run one test file:

uv run pytest -s -o log_cli=true -o log_cli_level=INFO packages/flet/integration_tests/controls/core/test_control.py

Run a subset:

uv run pytest -s -o log_cli=true -o log_cli_level=INFO packages/flet/integration_tests/controls/core/test_control.py -k test_visible

Generate or update goldens:

FLET_TEST_GOLDEN=1 uv run pytest -s -o log_cli=true -o log_cli_level=INFO packages/flet/integration_tests/controls/core/test_control.py

Quality checklist

Test file location matches control area.
module and function scope tests are in separate files.
Function-scoped files use the test_<control>_isolated.py naming convention.
Fixture scope matches test intent.
Screenshot keys are stable (request.node.name preferred).
Visual tests are deterministic (theme/size/content).
Goldens are updated only for intentional visual changes.
No unrelated formatting or refactors in the same change.

References

sdk/python/packages/flet/integration_tests/README.md
sdk/python/packages/flet/integration_tests/conftest.py
sdk/python/packages/flet/integration_tests/controls/core/test_control.py
sdk/python/packages/flet/integration_tests/controls/core/test_control_isolated.py
sdk/python/packages/flet/integration_tests/controls/core/test_layout_control.py
sdk/python/packages/flet/integration_tests/examples/core/test_control.py
sdk/python/examples/controls/control