Add Semantics.identifier and Tester.find_by_semantics_identifier

[mccre110]

Description

Flet's Semantics control had no identifier property, so Flutter 3.19+ resource-id / accessibilityIdentifier treatment was unavailable. Tests and native automation had to match on labels (or on widget keys, which never appear in the native accessibility tree).

This adds:

• Semantics.identifier — maps to Flutter's Semantics.identifier
• Tester.find_by_semantics_identifier() (host + remote tester)

Setting identifier implicitly creates a dedicated semantics node (equivalent to container=True), matching Flutter.

find_by_key remains the right default for Flet's own integration tests. Identifier is the right tool when you need a native accessibility ID, a match that survives copy/i18n changes, or one ID shared by widget tests and Appium/XCUITest/UIAutomator.

Test code

import flet as ft

page.add(
    ft.Semantics(
        identifier="save_btn",
        label="Submit",
        content=ft.Button("Save"),
    )
)

finder = await tester.find_by_semantics_identifier("save_btn")
assert finder.count == 1
await tester.tap(finder)

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

Checklist

• I signed the CLA.
• I have performed a self-review of my own code.
• My code follows the style guidelines of this project.
• I have commented my code, particularly in hard-to-understand areas.
• My changes generate no new warnings.
• New and existing tests pass locally with my changes.
• I have made corresponding documentation changes, if applicable.
• I have added changelog entries for user-facing changes, if applicable.
• I have updated release guide pages and website/sidebars.yml for breaking changes, removals, and deprecations, if applicable.

Screenshots

N/A — API / testing change; no visual UI change.

Additional details

Python unit tests for Semantics.identifier pass (pytest packages/flet/tests/test_semantics.py). Integration coverage is in test_finders.py and test_semantics_isolated.py.

Summary by Sourcery

Add stable semantics identifiers and tester finders for reliable widget and native accessibility automation.

New Features:

• Add a stable identifier property to Semantics for native accessibility IDs and widget-test matching.
• Add host and remote tester support for finding controls by semantics identifier.

Enhancements:

• Ensure semantics identifiers create dedicated semantics nodes and remain independent of visible labels.

Documentation:

• Document Semantics.identifier and identifier-based tester matching, including native accessibility mappings.

Tests:

• Add unit and integration coverage for semantics identifiers, matching, and interaction.

Chores:

• Update changelogs and semantics examples to expose the new API.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[sourcery-ai]

Hey - I've reviewed your changes and they look great!

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook