widget-finders

Maps Flutter widget keys and semantic labels to selectors for integration and Playwright E2E tests.

Updated Mar 9, 2026
One-click install
npx skills add https://github.com/yunior123/origna_gta_firebase --skill widget-finders-yunior123
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: widget-finders
Source: https://github.com/yunior123/origna_gta_firebase/tree/main/.claude/skills/widget-finders
Command: npx skills add https://github.com/yunior123/origna_gta_firebase --skill widget-finders-yunior123

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Writing Flutter integration tests and Playwright E2E tests requires knowing the exact keys, finder expressions, and ARIA semantic labels for every interactive widget, which are otherwise scattered across the codebase and easy to get wrong. ## Core Features & Use Cases - Flutter Key Reference: Provides a lookup table of widget keys (e.g., login_email_field, home_add_product_button) with their underlying widget types for integration_test finders. - Playwright Selector Map: Documents the kebab-case semantic label convention (btn-*, input-*, chk-*, link-*) and maps every screen widget to its Playwright selector via getByRole and aria-label locators. - Testing Conventions: Captures project-specific rules such as using pump loops instead of pumpAndSettle(), one testWidgets per file, and force-enabled semantics in main.dart. - Use Case: When writing an E2E test for the checkout flow, look up btn-place-order and chk-terms-accepted to interact with the Place Order button and terms checkbox without inspecting the Flutter source. ## Quick Start Ask the AI to write a Playwright E2E test that logs in, adds a product to the cart, and completes checkout using the widget-finders selectors.

Frequently Asked Questions about widget-finders

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I find Flutter widgets in integration tests?▼

Use key-based finders like find.byKey with the documented keys such as login_email_field or home_add_product_button. Note that buttons are ModernButton wrapping InkWell, not ElevatedButton, and use pump loops instead of pumpAndSettle.

How do I test Flutter Web apps with Playwright?▼

Enable semantics in main.dart via SemanticsBinding.instance.ensureSemantics(), which generates flt-semantics DOM elements with ARIA attributes. Then use Playwright getByRole, getByLabel, or aria-label locators to interact with widgets.

What semantic label convention should Flutter widgets use for E2E tests?▼

Use kebab-case labels with prefixes: btn-* for buttons, input-* for text fields, chk-* for checkboxes, link-* for links, nav-* for navigation, and product-card-{id} for product cards. Wrap widgets in Semantics or use tooltip on IconButton.

Why does pumpAndSettle fail in Flutter integration tests?▼

pumpAndSettle hangs when the app has continuous animations or timers. This project uses pump loops of 10 iterations at 1 second each instead, and limits each test file to a single testWidgets call.

Does Playwright Flutter testing work with CanvasKit and Skwasm?▼

Yes, semantics-based selectors work with both CanvasKit and Skwasm renderers because they rely on the generated flt-semantics DOM tree rather than canvas pixels. No Tab-key workaround is needed since semantics is force-enabled.