OpenParable
Skip to content
← Back to skills

Create Flet Control Integration Tests

Testing & Quality
create-flet-control-integration-tests

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

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
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>.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