Create Flet Control Integration Tests
Testing & Qualitycreate-flet-control-integration-testsCreate Flet Control Integration Tests is an Agent Skill for testing & quality published in the flet-dev/flet repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
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.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/flet-dev/flet/blob/HEAD/.agents/skills/create-flet-control-integration-tests/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/create-flet-control-integration-tests, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
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>.pyfor module-scoped visual/stable tests (usesflet_app)test_<control>_isolated.pyfor function-scoped tests that require a fresh app per test (usesflet_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_modeexplicitly 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.namecan be used as screenshot key. - Run target test file.
- If expected visuals changed, regenerate goldens with
FLET_TEST_GOLDEN=1and 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.
moduleandfunctionscope tests are in separate files.- Function-scoped files use the
test_<control>_isolated.pynaming convention. - Fixture scope matches test intent.
- Screenshot keys are stable (
request.node.namepreferred). - 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.mdsdk/python/packages/flet/integration_tests/conftest.pysdk/python/packages/flet/integration_tests/controls/core/test_control.pysdk/python/packages/flet/integration_tests/controls/core/test_control_isolated.pysdk/python/packages/flet/integration_tests/controls/core/test_layout_control.pysdk/python/packages/flet/integration_tests/examples/core/test_control.pysdk/python/examples/controls/control