npm - flutter-skill - Versions diffs - 0.8.0 → 0.8.2 - Mend

flutter-skill 0.8.0 → 0.8.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (2) hide show

package/README.md +197 -227
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -1,67 +1,66 @@
 <p align="center">
-  <img src="assets/social-preview.jpg" alt="flutter-skill" width="640">
+  <a href="https://github.com/ai-dashboad/flutter-skill">
+    <img src="assets/demo-teaser.gif" alt="AI testing a TikTok clone across 8 platforms" width="640">
+  </a>
 </p>
 <h1 align="center">flutter-skill</h1>
 <p align="center">
-  <strong>Give your AI eyes and hands inside any app.</strong><br>
-  E2E testing bridge for Claude, Cursor, Windsurf — across 8 platforms.
+  <strong>Give any AI agent eyes and hands inside any running app.</strong><br>
+  8 platforms. Zero test code. One MCP server.
 </p>
 <p align="center">
+  <a href="https://github.com/ai-dashboad/flutter-skill/stargazers"><img src="https://img.shields.io/github/stars/ai-dashboad/flutter-skill?style=flat&color=yellow" alt="Stars"></a>
   <a href="https://pub.dev/packages/flutter_skill"><img src="https://img.shields.io/pub/v/flutter_skill.svg" alt="pub.dev"></a>
   <a href="https://www.npmjs.com/package/flutter-skill"><img src="https://img.shields.io/npm/v/flutter-skill.svg" alt="npm"></a>
   <a href="https://github.com/ai-dashboad/flutter-skill/actions"><img src="https://img.shields.io/github/actions/workflow/status/ai-dashboad/flutter-skill/ci.yml?label=tests" alt="CI"></a>
-  <a href="https://github.com/ai-dashboad/flutter-skill/stargazers"><img src="https://img.shields.io/github/stars/ai-dashboad/flutter-skill?style=social" alt="Stars"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
-  <a href="https://skills.sh/ai-dashboad/flutter-skill/flutter-skill-testing"><img src="https://img.shields.io/badge/skills.sh-agent%20skill-black" alt="Agent Skill"></a>
 </p>
 <p align="center">
+  <a href="#30-second-demo">Demo</a> •
   <a href="#quick-start">Quick Start</a> •
-  <a href="#platforms">Platforms</a> •
-  <a href="#what-can-it-do">Features</a> •
-  <a href="#install">Install</a> •
+  <a href="#8-platforms-one-tool">Platforms</a> •
+  <a href="#why-not-playwright--appium--detox">vs Others</a> •
   <a href="docs/USAGE_GUIDE.md">Docs</a>
 </p>
 ---
-<p align="center">
-  <strong>🎬 AI tests a full TikTok clone — 28 actions, zero test code</strong>
-</p>
+## 30-Second Demo
 https://github.com/user-attachments/assets/d4617c73-043f-424c-9a9a-1a61d4c2d3c6
+> **One prompt. 28 AI-driven actions. Zero test code.** The AI explores a TikTok clone, navigates tabs, scrolls feeds, tests search, fills forms — all autonomously.
+---
+## Why This Exists
+Writing E2E tests is painful. Maintaining them is worse.
+**flutter-skill** connects your AI agent (Claude, Cursor, Windsurf, Copilot, OpenClaw) directly to your running app via [MCP](https://modelcontextprotocol.io/). The agent can see the screen, tap buttons, type text, scroll — like a human tester who never sleeps.
 ```
-You: "Test the login flow — enter test@example.com and password123, tap Login, verify Dashboard"
-AI Agent:
-  1. screenshot()        → sees the login screen
-  2. enter_text("email") → types the email
-  3. enter_text("pass")  → types the password
-  4. tap("Login")         → taps the button
-  5. wait_for_element("Dashboard") → confirms navigation
-  ✅ Login flow verified!
-```
+You: "Test the checkout flow with an empty cart, then add 3 items and complete purchase"
-**No test code. No selectors. Just tell the AI what to test.**
+Your AI agent handles the rest — screenshots, taps, text entry, assertions, navigation.
+No Page Objects. No XPath. No brittle selectors. Just plain English.
+```
 ---
 ## Quick Start
-**1. Install**
+**1. Install** (30 seconds)
 ```bash
-npm install -g flutter-skill        # npm (recommended)
-# or: brew install ai-dashboad/flutter-skill/flutter-skill
-# or: dart pub global activate flutter_skill
-# or: npx skills add ai-dashboad/flutter-skill  # Agent Skill (Claude Code, Cursor, Copilot, Cline, etc.)
+npm install -g flutter-skill
 ```
-**2. Add to your MCP config** (Claude Code / Cursor / Windsurf)
+**2. Add to your AI** (copy-paste into MCP config)
 ```json
 {
@@ -74,7 +73,9 @@ npm install -g flutter-skill        # npm (recommended)
 }
 ```
-**3. Add to your app** (2 lines)
+> Works with **Claude Desktop, Cursor, Windsurf, Copilot, Cline, OpenClaw** — any MCP-compatible agent.
+**3. Add to your app** (2 lines for Flutter)
 ```dart
 import 'package:flutter_skill/flutter_skill.dart';
@@ -87,162 +88,118 @@ void main() {
 **4. Test** — just talk to your AI:
-> *"Launch my app, tap Sign Up, fill the form, and verify the success screen"*
+> *"Launch my app, explore every screen, and report any bugs"*
-That's it. Zero configuration.
+That's it. **Zero configuration. Zero test code.**
 <details>
-<summary><strong>📦 More install methods</strong> (Windows, Docker, IDE extensions)</summary>
-| Method | Command | Platform |
-|--------|---------|----------|
-| npm | `npm install -g flutter-skill` | All |
-| Homebrew | `brew install ai-dashboad/flutter-skill/flutter-skill` | macOS/Linux |
-| Scoop | `scoop install flutter-skill` | Windows |
-| One-click | `curl -fsSL .../install.sh \| bash` | macOS/Linux |
-| Windows | `iwr .../install.ps1 -useb \| iex` | Windows |
-| Docker | `docker pull ghcr.io/ai-dashboad/flutter-skill` | All |
-| pub.dev | `dart pub global activate flutter_skill` | All |
-| VSCode | Extensions → "Flutter Skill" | All |
-| IntelliJ | Plugins → "Flutter Skill" | All |
-| Agent Skill | `npx skills add ai-dashboad/flutter-skill` | All (28+ agents) |
-</details>
-<details>
-<summary><strong>🔧 Zero-config onboarding</strong> (auto-detect & patch your app)</summary>
-```bash
-cd your-app/
-flutter-skill init    # Detects platform, patches entry point, configures MCP
-flutter-skill demo    # Launches built-in demo app to try it out
-```
-`init` auto-detects Flutter, iOS, Android, React Native, or Web projects and patches them automatically.
+<summary>📦 More install methods (Homebrew, Scoop, Docker, IDE, Agent Skill)</summary>
+| Method | Command |
+|--------|---------|
+| npm | `npm install -g flutter-skill` |
+| Homebrew | `brew install ai-dashboad/flutter-skill/flutter-skill` |
+| Scoop | `scoop install flutter-skill` |
+| Docker | `docker pull ghcr.io/ai-dashboad/flutter-skill` |
+| pub.dev | `dart pub global activate flutter_skill` |
+| VSCode | Extensions → "Flutter Skill" |
+| JetBrains | Plugins → "Flutter Skill" |
+| Agent Skill | `npx skills add ai-dashboad/flutter-skill` |
+| Zero-config | `flutter-skill init` (auto-detects & patches your app) |
 </details>
 ---
-## Platforms
-flutter-skill works across **8 platforms** with a unified bridge protocol:
-| Platform | SDK | Tests | Status |
-|----------|-----|-------|--------|
-| **Electron** | [`sdks/electron`](sdks/electron/) | 75/75 ✅ | Stable |
-| **KMP Desktop** | [`sdks/kmp`](sdks/kmp/) | 75/75 ✅ | Stable |
-| **Tauri** (Rust) | [`sdks/tauri`](sdks/tauri/) | 75/75 ✅ | Stable |
-| **.NET MAUI** | [`sdks/dotnet-maui`](sdks/dotnet-maui/) | 75/75 ✅ | Stable |
-| **React Native** | [`sdks/react-native`](sdks/react-native/) | 75/75 ✅ | Stable |
-| **Android** (Kotlin) | [`sdks/android`](sdks/android/) | 74/75 ✅ | Stable |
-| **Flutter iOS** | `flutter_skill` (pub.dev) | 60/65 ✅ | Stable |
-| **Flutter Web** | `flutter_skill` (pub.dev) | 63/65 ✅ | Stable |
+## 8 Platforms, One Tool
-> **582/590 tests passing** across all platforms (98.6% pass rate)
+Most testing tools work on 1-2 platforms. flutter-skill works on **8**.
-Each platform is tested against a complex social media app (tabs, feeds, forms, modals, 50+ elements) with 75 E2E tests covering:
-inspect, tap, enter_text, get_text, find_element, wait_for_element, scroll, swipe, screenshot, go_back, press_key, inspect_interactive, eval, and error handling.
+| Platform | SDK | Test Score |
+|----------|-----|:----------:|
+| **Flutter** (iOS/Android/Web) | [`flutter_skill`](https://pub.dev/packages/flutter_skill) | ✅ 188/195 |
+| **React Native** | [`sdks/react-native`](sdks/react-native/) | ✅ 75/75 |
+| **Electron** | [`sdks/electron`](sdks/electron/) | ✅ 75/75 |
+| **Tauri** (Rust) | [`sdks/tauri`](sdks/tauri/) | ✅ 75/75 |
+| **Android** (Kotlin) | [`sdks/android`](sdks/android/) | ✅ 74/75 |
+| **KMP Desktop** | [`sdks/kmp`](sdks/kmp/) | ✅ 75/75 |
+| **.NET MAUI** | [`sdks/dotnet-maui`](sdks/dotnet-maui/) | ✅ 75/75 |
+| **iOS** (Swift/UIKit) | [`sdks/ios`](sdks/ios/) | ✅ 19/19 |
-Each SDK README has platform-specific setup instructions. The same CLI and MCP tools work for all platforms.
+**Total: 656/664 tests passing (98.8%)** — each platform tested against a complex social media app with 50+ elements.
-<details>
-<summary><strong>Platform setup examples</strong></summary>
-**Web** — add one script tag:
-```html
-<script src="flutter-skill.js"></script>
-<script>FlutterSkill.start({ port: 50000 });</script>
-```
-**React Native** — npm install:
-```bash
-npm install flutter-skill
-```
-```js
-import FlutterSkill from 'flutter-skill';
-FlutterSkill.start();
-```
-**iOS (Swift/SwiftUI)** — Swift Package Manager:
-```swift
-import FlutterSkill
-FlutterSkillBridge.shared.start()
-Text("Hello").flutterSkillId("greeting")
-Button("Submit") { submit() }.flutterSkillButton("submitBtn")
-```
+---
-**Android (Kotlin)** — Gradle:
-```kotlin
-implementation("com.flutterskill:flutter-skill:0.7.5")
-FlutterSkillBridge.start(this)
-```
+## Why Not Playwright / Appium / Detox?
-**Electron / Tauri / KMP / .NET** — see each SDK's README for details.
+| | flutter-skill | Playwright | Appium | Detox |
+|---|:---:|:---:|:---:|:---:|
+| **Setup time** | 30 sec | Minutes | Hours | Hours |
+| **Test code needed** | ❌ None | ✅ Yes | ✅ Yes | ✅ Yes |
+| **AI-native (MCP)** | ✅ | ❌ | ❌ | ❌ |
+| **Platforms** | 8 | 3 (web) | Mobile | React Native |
+| **Natural language** | ✅ | ❌ | ❌ | ❌ |
+| **Maintenance** | Zero | High | High | Medium |
+| **Flutter support** | ✅ Native | Partial | Partial | ❌ |
+| **Desktop apps** | ✅ | ✅ | ❌ | ❌ |
-</details>
+**flutter-skill is the only AI-native E2E testing tool that works across mobile, web, and desktop.**
 ---
-## What Can It Do?
-**40+ MCP tools** organized in 4 categories:
+## What It Can Do
 <table>
 <tr>
 <td width="50%" valign="top">
-### 👀 See the Screen
-- `screenshot` — full app screenshot
-- `inspect` — list all interactive elements
-- `get_widget_tree` — full widget hierarchy
-- `find_by_type` — find by widget type
-- `get_text_content` — extract all text
+### 👀 See
+- `screenshot` — capture the screen
+- `inspect_interactive` — all tappable/typeable elements with semantic refs
+- `find_element` / `wait_for_element`
+- `get_elements` — full element tree
 </td>
 <td width="50%" valign="top">
-### 👆 Interact Like a User
-- `tap` / `double_tap` / `long_press`
-- `enter_text` — type into fields
-- `swipe` / `scroll_to` / `drag`
-- `go_back` — navigate back
-- Native: `native_tap`, `native_swipe`
+### 👆 Interact
+- `tap` / `long_press` / `swipe` / `drag`
+- `enter_text` / `set_text` / `clear_text`
+- `scroll` — all directions
+- `go_back` / `press_key`
 </td>
 </tr>
 <tr>
 <td valign="top">
-### ✅ Verify & Assert
-- `assert_text` / `assert_visible`
-- `wait_for_element` / `wait_for_gone`
-- `get_checkbox_state` / `get_slider_value`
-- `assert_element_count`
+### 🔍 Inspect (v0.8.0)
+- **Semantic refs**: `button:Login`, `input:Email`
+- Stable across UI changes
+- `tap(ref: "button:Submit")`
+- 7 roles: button, input, toggle, slider, select, link, item
 </td>
 <td valign="top">
-### 🚀 Launch & Control
-- `launch_app` — launch with flavors/defines
-- `scan_and_connect` — find running apps
+### 🚀 Control
+- `launch_app` — launch with flavors
 - `hot_reload` / `hot_restart`
-- `list_sessions` / `switch_session`
+- `get_logs` / `get_errors`
+- `scan_and_connect` — auto-find apps
 </td>
 </tr>
 </table>
 <details>
-<summary><strong>Full tool reference (40+ tools)</strong></summary>
+<summary><strong>40+ tools — full reference</strong></summary>
 **Launch & Connect:** `launch_app`, `scan_and_connect`, `hot_reload`, `hot_restart`, `list_sessions`, `switch_session`, `close_session`
-**Screen:** `screenshot`, `screenshot_region`, `screenshot_element`, `native_screenshot`, `inspect`, `get_widget_tree`, `find_by_type`, `get_text_content`
+**Screen:** `screenshot`, `screenshot_region`, `screenshot_element`, `native_screenshot`, `inspect`, `inspect_interactive`, `get_widget_tree`, `find_by_type`, `get_text_content`
-**Interaction:** `tap`, `double_tap`, `long_press`, `enter_text`, `swipe`, `scroll_to`, `drag`, `go_back`, `native_tap`, `native_input_text`, `native_swipe`
+**Interaction:** `tap`, `double_tap`, `long_press`, `enter_text`, `set_text`, `clear_text`, `swipe`, `scroll_to`, `drag`, `go_back`, `press_key`, `native_tap`, `native_input_text`, `native_swipe`
 **Assertions:** `assert_text`, `assert_visible`, `assert_not_visible`, `assert_element_count`, `wait_for_element`, `wait_for_gone`, `get_checkbox_state`, `get_slider_value`, `get_text_value`
@@ -252,132 +209,145 @@ FlutterSkillBridge.start(this)
 ---
-## Example Workflows
+## Platform Setup
+<details>
+<summary><strong>Flutter</strong> (iOS / Android / Web)</summary>
+```yaml
+dependencies:
+  flutter_skill: ^0.8.2
+```
+```dart
+import 'package:flutter_skill/flutter_skill.dart';
+void main() {
+  if (kDebugMode) FlutterSkillBinding.ensureInitialized();
+  runApp(MyApp());
+}
+```
+</details>
+<details>
+<summary><strong>React Native</strong></summary>
+```bash
+npm install flutter-skill-react-native
 ```
-"Test login with test@example.com / password123, verify it reaches the dashboard"
-"Submit the registration form empty and check that all validation errors appear"
+```js
+import FlutterSkill from 'flutter-skill-react-native';
+FlutterSkill.start();
+```
-"Navigate through all tabs, screenshot each one, verify back button works"
+</details>
+<details>
+<summary><strong>Electron</strong></summary>
-"Take screenshots of home, profile, and settings — compare with last time"
+```bash
+npm install flutter-skill-electron
 ```
-The AI agent figures out the steps. No test code needed.
+```js
+const { FlutterSkillBridge } = require('flutter-skill-electron');
+FlutterSkillBridge.start(mainWindow);
+```
----
+</details>
-## Native Platform Support
+<details>
+<summary><strong>iOS (Swift)</strong></summary>
-Flutter Skill sees through native dialogs that Flutter can't — permission popups, photo pickers, share sheets:
+```swift
+// Swift Package Manager: FlutterSkillSDK
+import FlutterSkill
+FlutterSkillBridge.shared.start()
-| Capability | iOS Simulator | Android Emulator |
-|-----------|--------------|-----------------|
-| Screenshot | `xcrun simctl` | `adb screencap` |
-| Tap | macOS Accessibility | `adb input tap` |
-| Text input | Pasteboard + Cmd+V | `adb input text` |
-| Swipe | Accessibility scroll | `adb input swipe` |
+Text("Hello").flutterSkillId("greeting")
+```
-No external tools needed — uses built-in OS capabilities.
+</details>
----
+<details>
+<summary><strong>Android (Kotlin)</strong></summary>
-## Test Results
+```kotlin
+implementation("com.flutterskill:flutter-skill:0.8.0")
-Every platform is tested against a **complex social media app** (4-tab navigation, 50+ scrollable items, forms, modals, search) with a comprehensive 75-test E2E suite.
+FlutterSkillBridge.start(this)
+```
+</details>
 <details>
-<summary><strong>75 tests per platform — full breakdown</strong></summary>
-| Category | Tests | What's tested |
-|----------|-------|---------------|
-| Initialize | 1 | Protocol handshake |
-| Inspect | 5 | Element tree, bounds, types, state changes |
-| Inspect Interactive | 5 | Semantic refs, actions, bounds, cross-page |
-| Tap | 6 | By key, text, coordinates, ref, invalid key/ref |
-| Enter Text | 6 | Basic, empty, emoji/unicode 🌍世界, overwrite, long (500+ chars), error handling |
-| Get Text | 4 | Counter, input readback, missing key, button label |
-| Find Element | 5 | By key, missing, by text, partial text, bounds |
-| Wait For Element | 4 | By key, by text, timeout, fast resolution |
-| Press Key | 10 | Enter, Tab, Escape, Backspace, arrows, Ctrl+A, Delete, Home/End, invalid key |
-| Scroll | 6 | Up, down, left, right, large distance, zero |
-| Swipe | 4 | Up, down, left, right |
-| Screenshot | 2 | Base64 encoding, image format (PNG/JPEG) |
-| Navigation | 8 | Detail page, inspect after nav, interactive elements, go_back, round-trip |
-| Logs | 3 | Get, clear, verify empty |
-| Eval | 2 | Expression evaluation, return values |
-| Error Handling | 3 | Unknown method, missing params, malformed request |
-| **Total** | **75** | |
-**Test apps per platform:**
-| Platform | Test App | Elements |
-|----------|----------|----------|
-| Electron | Social media app (HTML/JS) | 60+ items, dark theme |
-| Android | Native Kotlin app with Fragments | 50+ items, Material Design |
-| KMP | Compose Desktop app | 50+ items, tab navigation |
-| Tauri | Web frontend (Rust backend) | 55+ feed cards |
-| .NET MAUI | Simulated bridge with 6 screens | 114 elements |
-| React Native | Real RN app on iOS simulator | Self-registering components |
-| Flutter iOS | TikTok clone (10 feature modules) | Full social media app |
-| Flutter Web | TikTok clone via bridge proxy | Full social media app |
+<summary><strong>Tauri (Rust)</strong></summary>
+```toml
+[dependencies]
+flutter-skill-tauri = "0.8.0"
+```
 </details>
----
+<details>
+<summary><strong>KMP Desktop</strong></summary>
-## Troubleshooting
+Add Gradle dependency — see [`sdks/kmp`](sdks/kmp/) for details.
-| Problem | Fix |
-|---------|-----|
-| "Not connected" | `flutter-skill scan_and_connect` to auto-find apps |
-| "Unknown method" | `flutter pub add flutter_skill` then restart (not hot reload) |
-| No VM Service URI | Add `--vm-service-port=50000` to launch args |
-| Claude Code priority | Run `flutter_skill setup` for priority rules |
+</details>
-📖 **Full docs:** [Usage Guide](docs/USAGE_GUIDE.md) · [Architecture](docs/ARCHITECTURE.md) · [Troubleshooting](docs/TROUBLESHOOTING.md) · [Flutter 3.x Fix](docs/FLUTTER_3X_FIX.md)
+<details>
+<summary><strong>.NET MAUI</strong></summary>
----
+Add NuGet package — see [`sdks/dotnet-maui`](sdks/dotnet-maui/) for details.
-## Links
+</details>
-<table>
-<tr>
-<td>
+---
-📦 **Install**
-- [pub.dev](https://pub.dev/packages/flutter_skill)
-- [npm](https://www.npmjs.com/package/flutter-skill)
-- [Homebrew](https://github.com/ai-dashboad/homebrew-flutter-skill)
+## Example Prompts
-</td>
-<td>
+Just tell your AI what to test:
-🔌 **IDE Extensions**
-- [VSCode Marketplace](https://marketplace.visualstudio.com/items?itemName=ai-dashboad.flutter-skill)
-- [JetBrains Marketplace](https://plugins.jetbrains.com/plugin/29991-flutter-skill)
+| Prompt | What happens |
+|--------|-------------|
+| *"Test login with wrong password"* | Screenshots → enters creds → taps login → verifies error |
+| *"Explore every screen and report bugs"* | Systematically navigates all screens, tests all elements |
+| *"Fill registration with edge cases"* | Tests emoji 🌍, long strings, empty fields, special chars |
+| *"Compare checkout flow on iOS and Android"* | Runs same test on both platforms, compares screenshots |
+| *"Take screenshots of all 5 tabs"* | Taps each tab, captures state |
-</td>
-<td>
+---
-📖 **Docs**
-- [Roadmap](docs/ROADMAP.md)
-- [Changelog](CHANGELOG.md)
-- [Architecture](docs/ARCHITECTURE.md)
+## Contributing
-</td>
-</tr>
-</table>
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+```bash
+git clone https://github.com/ai-dashboad/flutter-skill
+cd flutter-skill
+dart pub get
+dart run bin/flutter_skill.dart server  # Start MCP server
+```
 ---
-<p align="center">
-  <strong>If flutter-skill saves you time, <a href="https://github.com/ai-dashboad/flutter-skill">⭐ star it on GitHub</a>!</strong>
-</p>
+## Links
+| | |
+|---|---|
+| 📦 [pub.dev](https://pub.dev/packages/flutter_skill) | 🧩 [VSCode](https://marketplace.visualstudio.com/items?itemName=AIDashboard.flutter-skill) |
+| 📦 [npm](https://www.npmjs.com/package/flutter-skill) | 🧩 [JetBrains](https://plugins.jetbrains.com/plugin/29991-flutter-skill) |
+| 🍺 [Homebrew](https://github.com/ai-dashboad/homebrew-flutter-skill) | 📖 [Docs](docs/USAGE_GUIDE.md) |
+| 🤖 [Agent Skill](https://skills.sh/ai-dashboad/flutter-skill) | 📋 [Changelog](CHANGELOG.md) |
+---
 <p align="center">
-  <a href="https://github.com/sponsors/ai-dashboad">GitHub Sponsors</a> · <a href="https://buymeacoffee.com/ai-dashboad">Buy Me a Coffee</a>
+  <strong>⭐ If flutter-skill saves you time, star it so others can find it too!</strong>
 </p>
-<p align="center">MIT License</p>
+<p align="center">MIT License © 2025</p>

package/package.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
   "name": "flutter-skill",
   "mcpName": "io.github.ai-dashboad/flutter-skill",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "MCP Server for app automation - Give your AI Agent eyes and hands inside any app (Flutter, React, Web, Native)",
   "main": "index.js",
   "bin": {