@bdayadev/flutter-ultra-mcp 1.11.6 → 1.12.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
     {
       "name": "flutter",
       "description": "Durable cross-platform Flutter automation via 8 specialized MCP servers, in-app mixin binding, and an optional DevTools panel. Replaces marionette_mcp and the official dart mcp-server for Claude Code.",
-      "version": "1.11.6",
+      "version": "1.12.0",
       "author": {
         "name": "Bdaya-Dev",
         "url": "https://github.com/Bdaya-Dev"
@@ -23,5 +23,5 @@
       "tags": ["flutter", "dart", "mcp", "testing", "automation", "patrol", "cross-platform"]
     }
   ],
-  "version": "1.11.6"
+  "version": "1.12.0"
 }

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "flutter",
-  "version": "1.11.6",
+  "version": "1.12.0",
   "description": "Durable cross-platform Flutter automation via 8 specialized MCP servers, in-app mixin binding, and an optional DevTools panel. Replaces marionette_mcp and the official dart mcp-server for Claude Code.",
   "author": {
     "name": "Bdaya-Dev",

package/.mcp.json

@@ -27,7 +27,8 @@
       "args": ["${CLAUDE_PLUGIN_ROOT}/packages/flutter-ultra-browser/dist/bin.cjs"],
       "env": {
         "PLAYWRIGHT_BROWSERS_PATH": "${CLAUDE_PLUGIN_DATA}/browsers",
-        "FLUTTER_ULTRA_STATE_DIR": "${CLAUDE_PLUGIN_DATA}/state"
+        "FLUTTER_ULTRA_STATE_DIR": "${CLAUDE_PLUGIN_DATA}/state",
+        "NODE_PATH": "${CLAUDE_PLUGIN_DATA}/node_modules"
       }
     },
     "flutter-ultra-native-mobile": {

package/dart/ultra_flutter/pubspec.yaml

@@ -4,7 +4,7 @@ description: >-
   extensions (gesture, screenshot, inspector, screencast, log collection)
   for the flutter-ultra-mcp Claude Code plugin. Composable with Sentry and
   other WidgetsFlutterBinding subclasses via the mixin form.
-version: 1.11.6
+version: 1.12.0
 homepage: https://github.com/Bdaya-Dev/flutter-ultra-mcp
 repository: https://github.com/Bdaya-Dev/flutter-ultra-mcp
 issue_tracker: https://github.com/Bdaya-Dev/flutter-ultra-mcp/issues

package/dart/ultra_flutter_devtools/pubspec.yaml

@@ -2,7 +2,7 @@ name: ultra_flutter_devtools
 description: >-
   Flutter DevTools extension showing live MCP activity for the flutter-ultra-mcp
   Claude Code plugin (sessions, recent tool calls, errors, screenshot grid).
-version: 1.11.6
+version: 1.12.0
 homepage: https://github.com/Bdaya-Dev/flutter-ultra-mcp
 repository: https://github.com/Bdaya-Dev/flutter-ultra-mcp
 issue_tracker: https://github.com/Bdaya-Dev/flutter-ultra-mcp/issues

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bdayadev/flutter-ultra-mcp",
-  "version": "1.11.6",
+  "version": "1.12.0",
   "description": "Flutter Ultra MCP plugin monorepo — 8 MCP servers + ultra_flutter Dart packages + skills for Claude Code.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/Bdaya-Dev/flutter-ultra-mcp",

package/skills/UPSTREAM-LICENSES

@@ -0,0 +1,75 @@
+The following vendored skills are sourced from upstream repositories under
+the BSD 3-Clause License. The flutter-ultra plugin itself is Apache-2.0.
+
+================================================================================
+flutter/skills — https://github.com/flutter/skills
+================================================================================
+
+Copyright 2026 The Flutter Authors. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software without
+   specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+Skills vendored:
+  add-integration-test, add-widget-preview, add-widget-test,
+  apply-architecture-best-practices, build-responsive-layout,
+  fix-layout-issues, implement-json-serialization,
+  setup-declarative-routing, setup-localization, use-http-package
+
+================================================================================
+dart-lang/skills — https://github.com/dart-lang/skills
+================================================================================
+
+Copyright 2012, the Dart project authors.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software without
+   specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+Skills vendored:
+  add-unit-test, build-cli-app, collect-coverage, fix-runtime-errors,
+  generate-test-mocks, migrate-to-checks-package, resolve-package-conflicts,
+  run-static-analysis, use-pattern-matching

package/skills/add-integration-test/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: add-integration-test
+description: Configures Flutter Driver for app interaction and converts MCP actions into permanent integration tests. Use when adding integration testing to a project, exploring UI components via MCP, or automating user flows with the integration_test package.
+---
+
+# Implementing Flutter Integration Tests
+
+## Contents
+
+- [Project Setup and Dependencies](#project-setup-and-dependencies)
+- [Interactive Exploration via MCP](#interactive-exploration-via-mcp)
+- [Test Authoring Guidelines](#test-authoring-guidelines)
+- [Execution and Profiling](#execution-and-profiling)
+- [Workflow: End-to-End Integration Testing](#workflow-end-to-end-integration-testing)
+- [Examples](#examples)
+
+## Project Setup and Dependencies
+
+Configure the project to support integration testing and Flutter Driver extensions.
+
+1. Add required development dependencies to `pubspec.yaml`:
+   ```bash
+   flutter pub add 'dev:integration_test:{"sdk":"flutter"}'
+   flutter pub add 'dev:flutter_test:{"sdk":"flutter"}'
+   ```
+2. Enable the Flutter Driver extension in your application entry point (typically `lib/main.dart` or a dedicated `lib/main_test.dart`):
+   - Import `package:flutter_driver/driver_extension.dart`.
+   - Call `enableFlutterDriverExtension();` before `runApp()`.
+3. Add `Key` parameters (e.g., `ValueKey('login_button')`) to critical widgets for reliable targeting.
+
+## Interactive Exploration via MCP
+
+Use MCP tools to interactively explore and manipulate the application state before writing static tests.
+
+- **Launch**: Execute `launch_app` with `target: "lib/main_test.dart"` to start the application and acquire the DTD URI.
+- **Inspect**: Execute `get_widget_tree` to discover available `Key`s, `Text` nodes, and widget `Type`s.
+- **Interact**: Execute `tap`, `enter_text`, and `scroll` to simulate user flows.
+- **Wait**: Always execute `waitFor` or verify state with `get_health` when navigating or triggering animations.
+- **Troubleshoot Unmounted Widgets**: If a widget is not found, it may be lazily loaded. Execute `scroll` or `scrollIntoView` to force the widget to mount.
+
+## Test Authoring Guidelines
+
+Structure integration tests using the `flutter_test` API paradigm.
+
+- Create a dedicated `integration_test/` directory at the project root.
+- Name all test files using the `<name>_test.dart` convention.
+- Initialize the binding: `IntegrationTestWidgetsFlutterBinding.ensureInitialized();`
+- Load the application UI: `await tester.pumpWidget(MyApp());`
+- Trigger frames: `await tester.pumpAndSettle();` after interactions.
+- Assert visibility: `expect(find.byKey(ValueKey('foo')), findsOneWidget);`
+- Scroll to off-screen widgets: `await tester.scrollUntilVisible(itemFinder, 500.0, scrollable: listFinder);`
+
+## Execution and Profiling
+
+Execute tests using the `flutter drive` command. Require a host driver script at `test_driver/integration_test.dart`.
+
+- **Chrome:** Launch `chromedriver --port=4444`, then: `flutter drive --driver=test_driver/integration_test.dart --target=integration_test/app_test.dart -d chrome`
+- **Headless web:** Run with `-d web-server`.
+- **Android (Local):** `flutter drive --driver=test_driver/integration_test.dart --target=integration_test/app_test.dart`
+
+## Workflow: End-to-End Integration Testing
+
+- [ ] **Setup**
+  - [ ] Add `integration_test` and `flutter_test` to `pubspec.yaml`.
+  - [ ] Inject `enableFlutterDriverExtension()` into the app entry point.
+  - [ ] Assign `ValueKey`s to target widgets.
+- [ ] **Exploration**
+  - [ ] Run `launch_app` via MCP.
+  - [ ] Map the widget tree using `get_widget_tree`.
+  - [ ] Validate interaction paths using MCP tools (`tap`, `enter_text`).
+- [ ] **Authoring**
+  - [ ] Create `integration_test/app_test.dart`.
+  - [ ] Write test cases using `WidgetTester` APIs.
+  - [ ] Create `test_driver/integration_test.dart` with `integrationDriver()`.
+- [ ] **Execution & Feedback Loop**
+  - [ ] Run `flutter drive`.
+  - [ ] Review output -> fix `PumpAndSettleTimedOutException` or missing widget issues -> re-run.
+
+## Examples
+
+### Standard Integration Test
+
+```dart
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:integration_test/integration_test.dart';
+import 'package:my_app/main.dart';
+
+void main() {
+  IntegrationTestWidgetsFlutterBinding.ensureInitialized();
+
+  group('End-to-end test', () {
+    testWidgets('tap on the floating action button, verify counter', (tester) async {
+      await tester.pumpWidget(const MyApp());
+      expect(find.text('0'), findsOneWidget);
+
+      final fab = find.byKey(const ValueKey('increment'));
+      await tester.tap(fab);
+      await tester.pumpAndSettle();
+
+      expect(find.text('1'), findsOneWidget);
+    });
+  });
+}
+```
+
+### Host Driver Script
+
+```dart
+import 'package:integration_test/integration_test_driver.dart';
+
+Future<void> main() => integrationDriver();
+```
+
+## Flutter Ultra Integration
+
+After writing the integration test, use these tools to launch the app and verify it:
+
+- `mcp__plugin_flutter_flutter-ultra-runtime__launch_app` — Launch the app with the integration test target
+- `mcp__plugin_flutter_flutter-ultra-runtime__attach` — Attach to the running app's VM Service
+- `mcp__plugin_flutter_flutter-ultra-runtime__screenshot` — Capture screenshots during test verification
+- `mcp__plugin_flutter_flutter-ultra-runtime__get_widget_tree` — Inspect the widget tree to verify test assertions
+
+---
+
+> **Attribution:** This skill is vendored from [flutter/skills](https://github.com/flutter/skills) (BSD-3-Clause).
+> Synced by `scripts/sync-upstream-skills.mjs`. Do not edit manually — changes will be overwritten on next sync.

package/skills/add-unit-test/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: add-unit-test
+description: Write and organize unit tests for functions, methods, and classes using `package:test`. Use when creating new logic or fixing bugs to ensure code remains correct and regression-free.
+---
+
+# Testing Dart and Flutter Applications
+
+## Contents
+
+- [Structuring Test Files](#structuring-test-files)
+- [Writing Tests](#writing-tests)
+- [Executing Tests](#executing-tests)
+- [Test Implementation Workflow](#test-implementation-workflow)
+- [Examples](#examples)
+
+## Structuring Test Files
+
+Organize test files to mirror the `lib` directory structure to maintain predictability.
+
+- Place all test code within the `test` directory at the root of the package.
+- Append `_test.dart` to the end of all test file names (e.g., `lib/src/utils.dart` should be tested in `test/src/utils_test.dart`).
+- If writing integration tests, place them in an `integration_test` directory at the root of the package.
+
+## Writing Tests
+
+Utilize `package:test` as the standard testing library for Dart applications.
+
+- Import `package:test/test.dart` (or `package:flutter_test/flutter_test.dart` for Flutter).
+- Group related tests using the `group()` function to provide shared context.
+- Define individual test cases using the `test()` function.
+- Validate outcomes using the `expect()` function alongside matchers (e.g., `equals()`, `isTrue`, `throwsA()`).
+- Write asynchronous tests using standard `async`/`await` syntax. The test runner automatically waits for the `Future` to complete.
+- Manage test setup and teardown using `setUp()` and `tearDown()` callbacks.
+- If testing code that relies on dependency injection, use `package:mockito` alongside `package:test` to generate mock objects, configure fixed scenarios, and verify interactions.
+
+## Executing Tests
+
+Select the appropriate test runner based on the project type and test location.
+
+- If working on a pure Dart project, execute tests using the `dart test` command.
+- If working on a Flutter project, execute tests using the `flutter test` command.
+- If running integration tests, explicitly specify the directory path, as the default runner ignores it: `dart test integration_test` or `flutter test integration_test`.
+
+## Test Implementation Workflow
+
+Follow this sequential workflow when implementing new test suites. Copy the checklist to track your progress.
+
+### Task Progress
+
+- [ ] 1. Create the test file in the `test/` directory, ensuring the `_test.dart` suffix.
+- [ ] 2. Import `package:test/test.dart` and the target library.
+- [ ] 3. Define a `main()` function.
+- [ ] 4. Initialize shared resources or mocks using `setUp()`.
+- [ ] 5. Write `test()` cases grouped by functionality using `group()`.
+- [ ] 6. Execute the test suite using the appropriate CLI command.
+- [ ] 7. **Feedback Loop**: Run test -> Review stack trace for failures -> Fix implementation or assertions -> Re-run until passing.
+
+## Examples
+
+### Standard Unit Test Suite
+
+Demonstrates grouping, setup, synchronous, and asynchronous testing.
+
+```dart
+import 'package:test/test.dart';
+import 'package:my_package/calculator.dart';
+
+void main() {
+  group('Calculator', () {
+    late Calculator calc;
+
+    setUp(() {
+      calc = Calculator();
+    });
+
+    test('adds two numbers correctly', () {
+      expect(calc.add(2, 3), equals(5));
+    });
+
+    test('handles asynchronous operations', () async {
+      final result = await calc.fetchRemoteValue();
+      expect(result, isNotNull);
+      expect(result, greaterThan(0));
+    });
+  });
+}
+```
+
+### Mocking with Mockito
+
+Demonstrates configuring a mock object for dependency injection testing.
+
+```dart
+import 'package:test/test.dart';
+import 'package:mockito/mockito.dart';
+import 'package:mockito/annotations.dart';
+import 'package:my_package/api_client.dart';
+import 'package:my_package/data_service.dart';
+
+// Generate the mock using build_runner: dart run build_runner build
+@GenerateNiceMocks([MockSpec<ApiClient>()])
+import 'data_service_test.mocks.dart';
+
+void main() {
+  group('DataService', () {
+    late MockApiClient mockApiClient;
+    late DataService dataService;
+
+    setUp(() {
+      mockApiClient = MockApiClient();
+      dataService = DataService(apiClient: mockApiClient);
+    });
+
+    test('returns parsed data on successful API call', () async {
+      // Configure the mock
+      when(mockApiClient.get('/data')).thenAnswer((_) async => '{"id": 1}');
+
+      // Execute the system under test
+      final result = await dataService.fetchData();
+
+      // Verify outcomes and interactions
+      expect(result.id, equals(1));
+      verify(mockApiClient.get('/data')).called(1);
+    });
+  });
+}
+```
+
+## Flutter Ultra Integration
+
+After writing the unit test, run and validate it:
+
+- `mcp__plugin_flutter_flutter-ultra-build__start_run_unit_tests` — Execute unit tests (supports `testNamePattern` and `coverage`)
+- `mcp__plugin_flutter_flutter-ultra-build__poll_run_unit_tests` — Monitor test progress until completion
+- `mcp__plugin_flutter_flutter-ultra-build__get_run_unit_tests_result` — Get detailed results with per-failure info
+
+---
+
+> **Attribution:** This skill is vendored from [dart-lang/skills](https://github.com/dart-lang/skills) (BSD-3-Clause).
+> Synced by `scripts/sync-upstream-skills.mjs`. Do not edit manually — changes will be overwritten on next sync.

package/skills/add-widget-preview/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: add-widget-preview
+description: Adds interactive widget previews to the project using the previews.dart system. Use when creating new UI components or updating existing screens to ensure consistent design and interactive testing.
+---
+
+# Previewing Flutter Widgets
+
+## Contents
+
+- [Preview Guidelines](#preview-guidelines)
+- [Handling Limitations](#handling-limitations)
+- [Workflows](#workflows)
+- [Examples](#examples)
+
+## Preview Guidelines
+
+Use the Flutter Widget Previewer to render widgets in real-time, isolated from the full application context.
+
+- **Target Elements:** Apply the `@Preview` annotation to top-level functions, static methods, or public widget constructors/factories that have no required arguments and return a `Widget` or `WidgetBuilder`.
+- **Imports:** Always import `package:flutter/widget_previews.dart`.
+- **Custom Annotations:** Extend the `Preview` class to create custom annotations that inject common properties (themes, wrappers).
+- **Multiple Configurations:** Apply multiple `@Preview` annotations to generate multiple preview instances. Or extend `MultiPreview`.
+- **Runtime Transformations:** Override `transform()` in custom `Preview` or `MultiPreview` classes for dynamic modification.
+
+## Handling Limitations
+
+The Widget Previewer runs in a web environment:
+
+- **No Native APIs:** Do not use `dart:io` or `dart:ffi`. Use conditional imports to mock or bypass.
+- **Asset Paths:** Use package-based paths (e.g., `packages/my_package_name/assets/my_image.png`).
+- **Public Callbacks:** Ensure all callback arguments are public and constant.
+- **Constraints:** Apply explicit constraints using the `size` parameter if your widget is unconstrained.
+
+## Workflows
+
+### Creating a Widget Preview
+
+- [ ] Import `package:flutter/widget_previews.dart`.
+- [ ] Identify a valid target (top-level function, static method, or parameter-less constructor).
+- [ ] Apply the `@Preview` annotation.
+- [ ] Configure parameters (`name`, `group`, `size`, `theme`, `brightness`).
+- [ ] If applying same config to multiple widgets, extract into a custom class extending `Preview`.
+
+### Interacting with Previews
+
+**If using a supported IDE (Flutter 3.38+):**
+
+1. Launch the IDE. Widget Previewer starts automatically.
+2. Open the "Flutter Widget Preview" tab.
+3. Toggle "Filter previews by selected file" if needed.
+
+**If using the Command Line:**
+
+1. Navigate to the project root.
+2. Run `flutter widget-preview start`.
+3. View in the Chrome environment.
+
+## Examples
+
+### Basic Preview
+
+```dart
+import 'package:flutter/widget_previews.dart';
+import 'package:flutter/material.dart';
+
+@Preview(name: 'My Sample Text', group: 'Typography')
+Widget mySampleText() {
+  return const Text('Hello, World!');
+}
+```
+
+### MultiPreview Implementation
+
+```dart
+import 'package:flutter/widget_previews.dart';
+import 'package:flutter/material.dart';
+
+final class MultiBrightnessPreview extends MultiPreview {
+  const MultiBrightnessPreview({required this.name});
+  final String name;
+
+  @override
+  List<Preview> get previews => const [
+    Preview(brightness: Brightness.light),
+    Preview(brightness: Brightness.dark),
+  ];
+
+  @override
+  List<Preview> transform() {
+    final previews = super.transform();
+    return previews.map((preview) {
+      final builder = preview.toBuilder()
+        ..group = 'Brightness'
+        ..name = '$name - ${preview.brightness!.name}';
+      return builder.toPreview();
+    }).toList();
+  }
+}
+
+@MultiBrightnessPreview(name: 'Primary Card')
+Widget cardPreview() => const Card(
+  child: Padding(padding: EdgeInsets.all(8.0), child: Text('Content')),
+);
+```
+
+## Flutter Ultra Integration
+
+After adding `@Preview` annotations, use these tools to view and capture previews:
+
+- `mcp__plugin_flutter_flutter-ultra-runtime__launch_app` — Launch the app to render previews
+- `mcp__plugin_flutter_flutter-ultra-runtime__screenshot` — Capture preview screenshots for documentation
+- `mcp__plugin_flutter_flutter-ultra-build__analyze` — Verify preview annotations are syntactically correct
+
+---
+
+> **Attribution:** This skill is vendored from [flutter/skills](https://github.com/flutter/skills) (BSD-3-Clause).
+> Synced by `scripts/sync-upstream-skills.mjs`. Do not edit manually — changes will be overwritten on next sync.

package/skills/add-widget-test/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: add-widget-test
+description: Implement a component-level test using `WidgetTester` to verify UI rendering and user interactions (tapping, scrolling, entering text). Use when validating that a specific widget displays correct data and responds to events as expected.
+---
+
+# Writing Flutter Widget Tests
+
+## Contents
+
+- [Setup & Configuration](#setup--configuration)
+- [Core Components](#core-components)
+- [Workflow: Implementing a Widget Test](#workflow-implementing-a-widget-test)
+- [Interaction & State Management](#interaction--state-management)
+- [Examples](#examples)
+
+## Setup & Configuration
+
+1. Add `flutter_test` to `dev_dependencies` in `pubspec.yaml`.
+2. Place all test files in `test/` at the project root.
+3. Suffix all test file names with `_test.dart`.
+
+## Core Components
+
+- **`WidgetTester`**: Primary interface for building and interacting with widgets. Provided by `testWidgets()`.
+- **`Finder`**: Locates widgets (e.g., `find.text('Submit')`, `find.byType(TextField)`, `find.byKey(Key('submit_btn'))`).
+- **`Matcher`**: Verifies presence or state (e.g., `findsOneWidget`, `findsNothing`, `findsNWidgets(2)`).
+
+## Workflow: Implementing a Widget Test
+
+### Task Progress
+
+- [ ] **Step 1:** Define the test with `testWidgets('description', (WidgetTester tester) async { ... })`.
+- [ ] **Step 2:** Build the widget with `await tester.pumpWidget(MyWidget())`. Wrap in `MaterialApp` if needed.
+- [ ] **Step 3:** Locate elements with `Finder` objects.
+- [ ] **Step 4:** Verify initial state with `expect(finder, matcher)`.
+- [ ] **Step 5:** Simulate interactions (e.g., `await tester.tap(buttonFinder)`).
+- [ ] **Step 6:** Rebuild the tree with `await tester.pump()` or `await tester.pumpAndSettle()`.
+- [ ] **Step 7:** Verify updated state with `expect()`.
+- [ ] **Step 8:** Run with `flutter test test/your_test_file_test.dart`.
+- [ ] **Step 9:** Feedback Loop: Review output -> fix assertions -> re-run.
+
+## Interaction & State Management
+
+- **Static rendering:** `pumpWidget()` once, then immediately assert.
+- **Standard state changes (button taps):** `tester.tap()` then `tester.pump()`.
+- **Animations/transitions:** Trigger the action then `tester.pumpAndSettle()`.
+- **Text input:** `await tester.enterText(textFieldFinder, 'Input string')`.
+- **Long lists:** `await tester.scrollUntilVisible(itemFinder, 500.0, scrollable: listFinder)`.
+
+## Examples
+
+### TodoList Widget Test
+
+**Target Widget (`lib/todo_list.dart`):**
+
+```dart
+import 'package:flutter/material.dart';
+
+class TodoList extends StatefulWidget {
+  const TodoList({super.key});
+  @override
+  State<TodoList> createState() => _TodoListState();
+}
+
+class _TodoListState extends State<TodoList> {
+  final todos = <String>[];
+  final controller = TextEditingController();
+
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp(
+      home: Scaffold(
+        body: Column(
+          children: [
+            TextField(controller: controller),
+            Expanded(
+              child: ListView.builder(
+                itemCount: todos.length,
+                itemBuilder: (context, index) {
+                  final todo = todos[index];
+                  return Dismissible(
+                    key: Key('$todo$index'),
+                    onDismissed: (_) => setState(() => todos.removeAt(index)),
+                    child: ListTile(title: Text(todo)),
+                  );
+                },
+              ),
+            ),
+          ],
+        ),
+        floatingActionButton: FloatingActionButton(
+          onPressed: () {
+            setState(() {
+              todos.add(controller.text);
+              controller.clear();
+            });
+          },
+          child: const Icon(Icons.add),
+        ),
+      ),
+    );
+  }
+}
+```
+
+**Test (`test/todo_list_test.dart`):**
+
+```dart
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:my_app/todo_list.dart';
+
+void main() {
+  testWidgets('Add and remove a todo item', (WidgetTester tester) async {
+    await tester.pumpWidget(const TodoList());
+    expect(find.byType(ListTile), findsNothing);
+
+    await tester.enterText(find.byType(TextField), 'Buy groceries');
+    await tester.tap(find.byType(FloatingActionButton));
+    await tester.pump();
+    expect(find.text('Buy groceries'), findsOneWidget);
+
+    await tester.drag(find.byType(Dismissible), const Offset(500, 0));
+    await tester.pumpAndSettle();
+    expect(find.text('Buy groceries'), findsNothing);
+  });
+}
+```
+
+## Flutter Ultra Integration
+
+After writing the widget test, run and validate it with these tools:
+
+- `mcp__plugin_flutter_flutter-ultra-build__start_run_widget_tests` — Execute widget tests (supports `testNamePattern` to scope)
+- `mcp__plugin_flutter_flutter-ultra-build__poll_run_widget_tests` — Monitor test progress until completion
+- `mcp__plugin_flutter_flutter-ultra-build__get_run_widget_tests_result` — Get detailed results: passed, failed, skipped, per-failure info
+- `mcp__plugin_flutter_flutter-ultra-build__analyze` — Static analysis before running tests
+
+---
+
+> **Attribution:** This skill is vendored from [flutter/skills](https://github.com/flutter/skills) (BSD-3-Clause).
+> Synced by `scripts/sync-upstream-skills.mjs`. Do not edit manually — changes will be overwritten on next sync.