@bdayadev/flutter-ultra-mcp 1.3.2 → 1.4.0

package/skills/test/SKILL.md

@@ -1,19 +1,170 @@
 ---
-name: test
+name: flutter-test
 description: Orchestrating Flutter unit, widget, and patrol E2E tests with focused reporting. Use when the user asks to run tests, validate a fix, or check coverage on a Flutter project.
 ---
 
-# Test (stub)
+# flutter-test — Test Orchestration
 
-**Status:** scaffold stub. Implementation owner: wave-3 skills worker (see plan §8.5, §12).
+## When to use
+
+Use this skill when the user asks to run tests, validate that a fix works, check coverage, or triage a failing CI test suite locally. This skill covers all three Flutter test layers: unit, widget, and patrol E2E. For ad-hoc interactive flow verification without a written test, use `flutter-drive` instead.
+
+## Prerequisites
+
+- A Flutter project is available and identifiable (pubspec.yaml present).
+- For patrol E2E: the app must be buildable for the target device/web. A connected device or emulator is required for mobile E2E.
+- For coverage reports: `lcov` must be available on the host, or the skill produces the raw `lcov.info` path for the user.
 
 ## Workflow
 
-- `mcp__flutter-ultra-build__analyze` first; fail fast on lint errors.
-- `mcp__flutter-ultra-build__run_unit_tests` / `run_widget_tests` per the input pattern.
-- `mcp__flutter-ultra-patrol__*` for E2E.
-- Report failures with file:line + a screenshot snapshot when available.
+### 1. Identify the project and test scope
+
+- Call `mcp__plugin_flutter_flutter-ultra-build__list_projects` to find available projects.
+- Call `mcp__plugin_flutter_flutter-ultra-build__project_info` for the target project to confirm the project path and available flavors.
+- Determine the test scope from the user's request:
+  - **Unit/widget only** → sections 2–3
+  - **Patrol E2E only** → section 4
+  - **Full suite** → sections 2–4 in order
+  - **Coverage** → section 2 with coverage flag, then section 5
+
+### 2. Static analysis first (fail fast)
+
+Before running any tests, call `mcp__plugin_flutter_flutter-ultra-build__analyze` on the project.
+
+- If analysis returns errors (not warnings): report them and stop — tests will fail to compile anyway.
+- If analysis returns only warnings: continue but include the warning count in the final report.
+
+### 3. Unit and widget tests
+
+**Start the test run:**
+
+- Unit tests: `mcp__plugin_flutter_flutter-ultra-build__start_run_unit_tests`
+  - Pass `testNamePattern` to scope to a specific test file or test name regex (e.g. `invoice_bloc_test`, `.*BlocTest.*`).
+  - Pass `coverage: true` when the user requests coverage.
+- Widget tests: `mcp__plugin_flutter_flutter-ultra-build__start_run_widget_tests`
+  - Same pattern filtering applies.
+
+**Poll until complete:**
+
+- Call `mcp__plugin_flutter_flutter-ultra-build__poll_run_unit_tests` (or `poll_run_widget_tests`) in a loop until status is `completed` or `failed`.
+- Poll interval: respect the tool's natural response time; do not sleep artificially.
+
+**Get results:**
+
+- Call `mcp__plugin_flutter_flutter-ultra-build__get_run_unit_tests_result` (or `get_run_widget_tests_result`).
+- Parse: total tests, passed, failed, skipped, duration.
+- For each failure: extract test name, file path, line number, and failure message.
+
+**Cancellation:** if the user interrupts, call `mcp__plugin_flutter_flutter-ultra-build__cancel_run_unit_tests` (or `cancel_run_widget_tests`).
+
+### 4. Patrol E2E tests
+
+**Discover available tests:**
+
+- Call `mcp__plugin_flutter_flutter-ultra-patrol__list_tests` to enumerate test files and individual test names in `integration_test/`.
+
+**Start a patrol run:**
+
+- Call `mcp__plugin_flutter_flutter-ultra-patrol__start_patrol_test` with:
+  - `testFilePath` or `testName` to scope the run.
+  - `device` for the target (web, emulator ID, or physical device ID from `mcp__plugin_flutter_flutter-ultra-runtime__list_devices`).
+  - `flavor` if the project uses flavors.
+
+**Poll until complete:**
+
+- Call `mcp__plugin_flutter_flutter-ultra-patrol__poll_patrol_job` in a loop until done.
+- While polling, optionally call `mcp__plugin_flutter_flutter-ultra-patrol__take_patrol_screenshot` at key intervals to capture mid-test state.
+
+**Get enriched results:**
+
+- Call `mcp__plugin_flutter_flutter-ultra-patrol__get_patrol_result`.
+- The result includes:
+  - Pass/fail per test step
+  - `logContext`: log lines captured around the failure point
+  - Screenshot paths captured during the test
+  - Browser console errors (for web): call `mcp__plugin_flutter_flutter-ultra-patrol__get_patrol_browser_errors` for additional detail.
+
+**For web E2E failures**: also call `mcp__plugin_flutter_flutter-ultra-patrol__get_patrol_web_debugger_port` to get the Chrome DevTools port, then use `mcp__plugin_flutter_flutter-ultra-browser__connect_over_cdp` for deeper inspection.
+
+**Cancellation:** call `mcp__plugin_flutter_flutter-ultra-patrol__cancel_patrol_job` if interrupted.
+
+### 5. Coverage report (when requested)
+
+After unit tests complete with `coverage: true`:
+
+- The build server writes `coverage/lcov.info` relative to the project root.
+- Call `mcp__plugin_flutter_flutter-ultra-build__get_run_unit_tests_result` — the result includes the coverage file path.
+- Report the top-level line coverage percentage if parseable.
+- If the user wants an HTML report: note that they can run `genhtml coverage/lcov.info -o coverage/html` locally.
+- Do not attempt to parse `lcov.info` manually — report the file path and overall percentage only.
+
+### 6. Golden test handling
+
+When the user asks to update or validate golden screenshots:
+
+- **Validate**: `mcp__plugin_flutter_flutter-ultra-build__start_run_golden_tests` → `poll_run_golden_tests` → `get_run_golden_tests_result`.
+- **Update**: `mcp__plugin_flutter_flutter-ultra-build__start_update_goldens` → `poll_update_goldens` → `get_update_goldens_result`.
+- After updating, note that the changed `.png` files in `test/goldens/` must be committed.
+
+## Failure triage
+
+When tests fail, apply this triage sequence:
+
+1. **Compilation errors** (test file won't load): surface the exact error from the result — usually a missing import or type mismatch. Fix the test file if asked.
+2. **Assertion failures** (expected ≠ actual): show the test name, expected value, actual value, and file:line. Do not auto-fix unless asked.
+3. **Timeout failures**: check if the test awaits a Future that never resolves. Suggest checking if `pumpAndSettle` is waiting on an infinite animation.
+4. **Patrol E2E failures**: read `logContext` from `get_patrol_result` — it contains the log lines immediately before the failure. Cross-reference with `get_patrol_browser_errors` for web.
+5. **Screenshot on failure**: patrol captures screenshots automatically on failure; report the path. For unit/widget failures, call `mcp__plugin_flutter_flutter-ultra-runtime__screenshot` if the app is running in debug mode.
+
+## Output format
+
+After all test layers complete, produce a structured summary:
+
+```
+## Test Results
+
+| Layer | Total | Passed | Failed | Skipped | Duration |
+|-------|-------|--------|--------|---------|----------|
+| Unit  | 42    | 41     | 1      | 0       | 3.2s     |
+| Widget| 18    | 18     | 0      | 0       | 8.1s     |
+| E2E   | 5     | 4      | 1      | 0       | 47s      |
+
+### Failures
+
+**Unit: invoice_bloc_test.dart:87** — `InvoiceListBloc`
+Expected: `InvoiceListLoaded` with 3 items
+Got: `InvoiceListLoaded` with 0 items
+
+**E2E: login_flow_test.dart — "should redirect to dashboard after login"**
+Log context: [ERROR] ZitadelException: invalid_client at 14:23:01.332
+Screenshot: .omc/research/patrol-2026-05-19/login_flow_failure.png
+```
+
+Include the coverage percentage at the bottom if coverage was requested.
+
+## Example
+
+```
+User: "Run the full test suite for the Invora Flutter app and show me what's failing."
+
+1. list_projects → project: clients/invora/invora-flutter
+2. analyze → 0 errors, 3 warnings (continue)
+3. start_run_unit_tests(project: "invora-flutter") → jobId: "unit-001"
+4. poll_run_unit_tests(jobId: "unit-001") → completed
+5. get_run_unit_tests_result → 42 total, 1 failed: invoice_bloc_test.dart:87
+6. start_run_widget_tests(project: "invora-flutter") → jobId: "widget-001"
+7. poll_run_widget_tests → completed, 18/18 passed
+8. list_tests(project: "invora-flutter") → 5 patrol tests
+9. start_patrol_test(testFilePath: "integration_test/", device: "web") → jobId: "patrol-001"
+10. poll_patrol_job → completed, 1 failed: login_flow_test.dart
+11. get_patrol_result → logContext: "ZitadelException: invalid_client", screenshot path
+12. get_patrol_browser_errors → CORS error on /oauth/v2/token
+→ Report table + failure details
+```
 
 ## See also
 
-- Plan §8.5
+- Sibling skill: `flutter-drive` for ad-hoc interactive flow automation without a written test
+- Sibling skill: `flutter-debug` for live runtime triage after a test exposes a bug
+- `mcp__plugin_flutter_flutter-ultra-patrol__get_patrol_result` — enriched E2E failure context
+- `mcp__plugin_flutter_flutter-ultra-build__test_filter` — narrow test scope by name or file pattern

package/skills/tour/SKILL.md

@@ -1,22 +1,101 @@
 ---
-name: tour
+name: flutter-tour
 description: Running route-by-route screenshot tours of a Flutter app. Use when capturing visual state across many app routes, doing pre-release visual regression sweeps, or documenting a feature's UI for review.
 ---
 
-# Route Tour (stub)
+# flutter-tour — Route Screenshot Tour
 
-**Status:** scaffold stub. Implementation owner: wave-3 skills worker (see plan §8.1, §12).
+## When to use
 
-## Quick start
+Use this skill when the user asks to visually document the app, capture all screens for review, or perform a pre-release sweep of the UI. Also use it when producing a screenshot inventory for a design QA pass.
 
-1. Identify the active session via `mcp__flutter-ultra-runtime__discover_sessions`.
-2. For each route in the input list:
-   - Navigate (web: browser navigate, mobile/desktop: GoRouter evaluate)
-   - Wait for the root widget key
-   - Take a screenshot, save to `.omc/research/tour-<date>/<route-slug>.png`
-3. Write `tour-report.md` summarizing route to screenshot mapping.
+## Prerequisites
+
+- A Flutter app is already running in debug mode (or can be launched via `mcp__plugin_flutter_flutter-ultra-runtime__launch_app`).
+- For web tours: a browser context is available or can be created via `mcp__plugin_flutter_flutter-ultra-browser__launch_browser`.
+- The app uses GoRouter or Navigator 2.0 (route list can be discovered via `evaluate`).
+
+## Workflow
+
+1. **Attach to the running session**
+   - Call `mcp__plugin_flutter_flutter-ultra-runtime__discover_sessions` to find active sessions.
+   - If none, call `mcp__plugin_flutter_flutter-ultra-runtime__launch_app` with the target project/flavor.
+   - Call `mcp__plugin_flutter_flutter-ultra-runtime__attach` with the chosen `sessionId`.
+
+2. **Discover routes**
+   - Call `mcp__plugin_flutter_flutter-ultra-runtime__evaluate` with:
+     ```dart
+     import 'package:go_router/go_router.dart';
+     final router = GoRouter.of(context);
+     router.configuration.routes.map((r) => r.path).toList().toString()
+     ```
+   - If GoRouter is not used, call `mcp__plugin_flutter_flutter-ultra-runtime__get_widget_tree` and look for `Navigator` or `MaterialApp` `routes` keys.
+   - If the user supplied a route list explicitly, use that directly.
+
+3. **For each route** (iterate in order):
+   a. Navigate via evaluate:
+
+   ```dart
+   context.go('/your-route');
+   ```
+
+   Or for named routes: `context.goNamed('routeName')`.
+   b. Wait for the UI to settle — call `mcp__plugin_flutter_flutter-ultra-runtime__evaluate` with `SchedulerBinding.instance.endOfFrame` to await the next frame.
+   c. Take a screenshot: `mcp__plugin_flutter_flutter-ultra-runtime__screenshot` — save path as `.omc/research/tour-<YYYY-MM-DD>/<route-slug>.png` where `route-slug` replaces `/` with `-` and strips leading `-`.
+   d. For **web targets**: also call `mcp__plugin_flutter_flutter-ultra-browser__screenshot` for a pixel-perfect browser-rendered capture alongside the VM-service capture.
+   e. Record the mapping `{ route, file, timestamp, title }` for the report.
+
+4. **Handle auth-gated routes**
+   - If a route redirects to a login screen, detect it by checking the widget tree for a login form key or `LoginPage` widget type.
+   - Perform login via `mcp__plugin_flutter_flutter-ultra-runtime__evaluate` (inject credentials into state) or via gesture tools.
+   - Retry the navigation after authentication.
+
+5. **Compile the report**
+   - Write `.omc/research/tour-<date>/tour-report.md` with a markdown table:
+     ```markdown
+     | Route | Screenshot             | Notes |
+     | ----- | ---------------------- | ----- |
+     | /home | [home.png](./home.png) |       |
+     ```
+   - List any routes that could not be captured and the reason (auth wall, crash, async timeout).
+
+## Handling edge cases
+
+- **Auth-gated routes**: detect redirect to login by calling `mcp__plugin_flutter_flutter-ultra-runtime__get_widget_tree` after navigation and checking top-level widget type. Authenticate first, then retry.
+- **Routes with async data**: after `context.go(...)`, await `SchedulerBinding.instance.endOfFrame` and optionally call `evaluate` to check if a loading indicator is still present (`find.byType(CircularProgressIndicator).evaluate().isNotEmpty`). Wait up to 5 seconds in 500 ms increments.
+- **Routes that cause errors**: catch exceptions from `evaluate`; log the error in the report and continue to the next route.
+- **Parameterized routes** (e.g. `/item/:id`): substitute a known test ID, e.g. `/item/1`. Ask the user for sample IDs if none are obvious from context.
+- **Bottom sheets / dialogs**: these are not routes in GoRouter. Capture them by triggering them via `evaluate` after navigating to the parent route, screenshot, then dismiss.
+
+## Output format
+
+At the end of the tour, produce:
+
+1. A summary message listing how many routes were captured successfully vs. skipped.
+2. The path to `tour-report.md`.
+3. Inline markdown image links for any screenshots already visible in context (first 3 max to avoid flooding).
+
+## Example
+
+```
+User: "Take a screenshot tour of the Invora app — all routes."
+
+1. discover_sessions → sessionId: "flutter-1"
+2. attach(sessionId: "flutter-1")
+3. evaluate → routes: ["/", "/login", "/dashboard", "/invoices", "/invoices/:id", "/settings"]
+4. For "/":
+   - evaluate: context.go('/')
+   - evaluate: await SchedulerBinding.instance.endOfFrame
+   - screenshot → .omc/research/tour-2026-05-19/-home.png
+5. For "/login":
+   - evaluate: context.go('/login')
+   - screenshot → .omc/research/tour-2026-05-19/-login.png
+... (repeat for each route)
+6. Write tour-report.md with table of all routes + image links.
+```
 
 ## See also
 
-- Plan §8.1
-- Sibling skill: `drive` for multi-step interaction flows
+- Sibling skill: `flutter-drive` for multi-step interaction flows
+- `mcp__plugin_flutter_flutter-ultra-runtime__evaluate` — arbitrary Dart expression evaluation in app context
+- `mcp__plugin_flutter_flutter-ultra-browser__screenshot` — browser-level screenshot for web targets