create-flet-control-integration-tests— agent skill

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

1. Identify behavior to verify.
2. Build deterministic layout/state:

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

1. Choose file by scope rule before writing tests.
2. Write test using async pytest.
3. Use screenshot assertion for UI behavior, functional assertion for non-visual behavior.
4. Name test so request.node.name can be used as screenshot key.
5. Run target test file.
6. 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