From a959bfd10137b6f987d1a07f1588265f10da47c2 Mon Sep 17 00:00:00 2001 From: Patrick Bertsch Date: Thu, 2 Apr 2026 09:10:12 -0600 Subject: [PATCH 1/2] docs: add Homebrew as recommended install method in README and pub.dev README --- README.md | 13 +++++++++++-- probe_agent/README.md | 8 ++++++-- 2 files changed, 17 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 2676143..c694447 100644 --- a/README.md +++ b/README.md @@ -59,7 +59,16 @@ The **ProbeAgent** is a Dart package you add to your Flutter app as a dev depend ## Installation -### Option A — Download pre-built binary (recommended for CI/CD) +### Option A — Homebrew (macOS + Linux, recommended) + +```bash +brew tap AlphaWaveSystems/tap +brew install probe +``` + +Upgrades are handled automatically with `brew upgrade probe`. + +### Option B — Download pre-built binary (recommended for CI/CD) Pre-built binaries for Linux, macOS (Intel + Apple Silicon), and Windows are attached to every [GitHub Release](https://github.com/AlphaWaveSystems/flutter-probe/releases). @@ -77,7 +86,7 @@ curl -Lo probe https://github.com/AlphaWaveSystems/flutter-probe/releases/latest chmod +x probe && sudo mv probe /usr/local/bin/ ``` -### Option B — Build from source +### Option C — Build from source ```bash git clone https://github.com/AlphaWaveSystems/flutter-probe.git diff --git a/probe_agent/README.md b/probe_agent/README.md index ab8d4d8..0d3c792 100644 --- a/probe_agent/README.md +++ b/probe_agent/README.md @@ -26,10 +26,14 @@ Both are required. The agent alone does nothing without the CLI to drive it. The `probe` CLI is a Go binary. Install via one of: ```bash -# Option A: Go install +# Option A: Homebrew (macOS + Linux) +brew tap AlphaWaveSystems/tap +brew install probe + +# Option B: Go install go install github.com/AlphaWaveSystems/flutter-probe/cmd/probe@latest -# Option B: Download from GitHub Releases +# Option C: Download from GitHub Releases # https://github.com/AlphaWaveSystems/flutter-probe/releases/latest ``` From 726fd0a5b39c6bc2d97b7893ac664eda34bec28e Mon Sep 17 00:00:00 2001 From: Patrick Bertsch Date: Thu, 2 Apr 2026 09:15:06 -0600 Subject: [PATCH 2/2] =?UTF-8?q?docs:=20sync=20install=20instructions=20?= =?UTF-8?q?=E2=80=94=20add=20Homebrew=20as=20recommended=20install=20metho?= =?UTF-8?q?d?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - installation.md: full rewrite with Homebrew as Option A, pre-built binary as B, go install as C; remove build-from-source as primary method - guide-to-flutter-e2e-testing.md: replace fake curl URL with Homebrew + go install; fix flutterprobe run → probe test; bump agent version to ^0.5.3 - flutter-test-automation.md: replace fake curl URL with go install; fix all flutterprobe run → probe test; add --dart-define=PROBE_AGENT=true to build step --- .../docs/blog/guide-to-flutter-e2e-testing.md | 12 ++- .../comparisons/flutter-test-automation.md | 19 ++-- .../docs/getting-started/installation.md | 93 ++++++++++++------- 3 files changed, 78 insertions(+), 46 deletions(-) diff --git a/website/src/content/docs/blog/guide-to-flutter-e2e-testing.md b/website/src/content/docs/blog/guide-to-flutter-e2e-testing.md index f2a06cf..a43c160 100644 --- a/website/src/content/docs/blog/guide-to-flutter-e2e-testing.md +++ b/website/src/content/docs/blog/guide-to-flutter-e2e-testing.md @@ -35,7 +35,12 @@ Three primary options exist for Flutter E2E testing: Install the FlutterProbe CLI: ```bash -curl -sSL https://flutterprobe.dev/install | sh +# macOS + Linux (recommended) +brew tap AlphaWaveSystems/tap +brew install probe + +# Or via go install (good for CI) +go install github.com/AlphaWaveSystems/flutter-probe/cmd/probe@latest ``` Add the FlutterProbe Dart agent to your app's dev dependencies: @@ -43,8 +48,7 @@ Add the FlutterProbe Dart agent to your app's dev dependencies: ```yaml # pubspec.yaml dev_dependencies: - flutter_probe_agent: - ^0.5.1 + flutter_probe_agent: ^0.5.3 ``` Initialize the agent in your app's main function: @@ -192,7 +196,7 @@ The `wait for` command polls the widget tree until the condition is met or the t Configure FlutterProbe to take screenshots and capture device logs on test failure. This transforms CI failures from "test X failed" into actionable reports with visual context: ```bash -flutterprobe run --suite tests/ --screenshot-on-failure --capture-logs +probe test tests/ --screenshot-on-failure --capture-logs ``` ## Common Pitfalls diff --git a/website/src/content/docs/comparisons/flutter-test-automation.md b/website/src/content/docs/comparisons/flutter-test-automation.md index b55b800..6325b94 100644 --- a/website/src/content/docs/comparisons/flutter-test-automation.md +++ b/website/src/content/docs/comparisons/flutter-test-automation.md @@ -51,12 +51,11 @@ jobs: with: flutter-version: '3.27.0' - name: Install FlutterProbe - run: | - curl -sSL https://flutterprobe.dev/install | sh + run: go install github.com/AlphaWaveSystems/flutter-probe/cmd/probe@latest - name: Build and test run: | - flutter build apk --debug - flutterprobe run --target android --suite tests/ + flutter build apk --debug --dart-define=PROBE_AGENT=true + probe test tests/ -y ``` The key steps are: check out the code, set up Flutter, install FlutterProbe, build the app, and run the test suite. For iOS, replace the build step with `flutter build ios --simulator --debug` and adjust the target flag. @@ -73,10 +72,10 @@ FlutterProbe supports parallel execution via the `--shard` flag: ```bash # Split the suite across 4 parallel shards -flutterprobe run --suite tests/ --shard 1/4 & -flutterprobe run --suite tests/ --shard 2/4 & -flutterprobe run --suite tests/ --shard 3/4 & -flutterprobe run --suite tests/ --shard 4/4 & +probe test tests/ --shard 1/4 & +probe test tests/ --shard 2/4 & +probe test tests/ --shard 3/4 & +probe test tests/ --shard 4/4 & wait ``` @@ -89,7 +88,7 @@ jobs: matrix: shard: [1/4, 2/4, 3/4, 4/4] steps: - - run: flutterprobe run --suite tests/ --shard ${{ matrix.shard }} + - run: probe test tests/ --shard ${{ matrix.shard }} ``` Four shards typically reduce a 12-minute suite to roughly 3 minutes of wall-clock time. The speedup is linear because E2E tests are independent by design — each test starts from a known app state. @@ -137,7 +136,7 @@ Automated tests are only useful if failures are actionable. FlutterProbe generat Reports can be output as JUnit XML for CI integration or as HTML for human review. JUnit XML integrates directly with GitHub Actions, GitLab CI, and most CI dashboards to surface test results in pull request checks. ```bash -flutterprobe run --suite tests/ --report junit --output results.xml +probe test tests/ --report junit --output results.xml ``` When a test fails in CI, the combination of the failure screenshot, the step-level log, and the device log usually provides enough context to diagnose the issue without reproducing it locally. diff --git a/website/src/content/docs/getting-started/installation.md b/website/src/content/docs/getting-started/installation.md index ff08046..14acd1d 100644 --- a/website/src/content/docs/getting-started/installation.md +++ b/website/src/content/docs/getting-started/installation.md @@ -1,47 +1,59 @@ --- title: Installation -description: Build FlutterProbe from source and integrate the Dart agent into your Flutter app. +description: Install the probe CLI and integrate the Dart agent into your Flutter app. --- -## Prerequisites +## Step 1: Install the CLI + +### Option A — Homebrew (macOS + Linux, recommended) + +```bash +brew tap AlphaWaveSystems/tap +brew install probe +``` + +### Option B — Pre-built binary (all platforms, good for CI) -- **Go 1.26+** — for building the probe CLI -- **Dart 3.3+ / Flutter 3.19+** — for the probe_agent package (tested up to Flutter 3.41 / Dart 3.11) -- **Android**: ADB + Android SDK (for Android emulator testing) -- **iOS Simulator**: Xcode + `xcrun simctl` (for iOS simulator testing) -- **iOS Physical Device**: All of the above, plus `iproxy` from `libimobiledevice` for USB port forwarding (`brew install libimobiledevice`) +Download the binary for your platform from [GitHub Releases](https://github.com/AlphaWaveSystems/flutter-probe/releases/latest): -## Build the CLI +| Platform | Binary | +|---|---| +| macOS (Apple Silicon) | `probe-darwin-arm64` | +| macOS (Intel) | `probe-darwin-amd64` | +| Linux (x86-64) | `probe-linux-amd64` | +| Windows (x86-64) | `probe-windows-amd64.exe` | -Clone the repository and build the `probe` binary: +Make the binary executable and place it on your `PATH`: ```bash -git clone https://github.com/AlphaWaveSystems/flutter-probe.git -cd FlutterProbe -make build # outputs bin/probe +chmod +x probe-darwin-arm64 +mv probe-darwin-arm64 /usr/local/bin/probe ``` -To install to your `$GOPATH/bin` (so `probe` is available globally): +### Option C — `go install` (requires Go 1.26+) ```bash -make install +go install github.com/AlphaWaveSystems/flutter-probe/cmd/probe@latest ``` -## Add ProbeAgent to Your Flutter App +This is a good option for CI environments that already have Go set up. -The Dart agent runs inside your Flutter app and provides the WebSocket server that the CLI connects to. +Verify: + +```bash +probe version +``` -### 1. Add the dependency +## Step 2: Add the Agent to Your App -In your Flutter app's `pubspec.yaml`: +Add `flutter_probe_agent` to your Flutter app's `pubspec.yaml`: ```yaml dev_dependencies: - flutter_probe_agent: - path: /path/to/FlutterProbe/probe_agent + flutter_probe_agent: ^0.5.3 ``` -### 2. Initialize in main.dart +Initialize in your `main.dart`: ```dart import 'package:flutter_probe_agent/flutter_probe_agent.dart'; @@ -58,16 +70,16 @@ Future main() async { } ``` -The `PROBE_AGENT` flag is compiled into the binary via `--dart-define`. It must be set at build time — it cannot be toggled at runtime. +The `bool.fromEnvironment` check ensures the agent is only active when built with `--dart-define=PROBE_AGENT=true`. It adds zero overhead to your production app. -### 3. Build with the flag enabled +## Step 3: Build and Run **iOS Simulator:** ```bash -flutter build ios --debug --simulator --dart-define=PROBE_AGENT=true -xcrun simctl install build/ios/iphonesimulator/YourApp.app -xcrun simctl launch com.example.myapp +flutter run --dart-define=PROBE_AGENT=true +# In another terminal: +probe test tests/login.probe --device -v ``` **Android Emulator:** @@ -76,6 +88,17 @@ xcrun simctl launch com.example.myapp flutter build apk --debug --dart-define=PROBE_AGENT=true adb install -r build/app/outputs/flutter-apk/app-debug.apk adb shell am start -n com.example.myapp/.MainActivity +probe test tests/login.probe --device emulator-5554 -v +``` + +**Physical iOS (WiFi mode — recommended):** + +```bash +flutter build ios --profile --dart-define=PROBE_AGENT=true --dart-define=PROBE_WIFI=true +xcrun devicectl device install app --device build/ios/iphoneos/Runner.app +xcrun devicectl device process launch --device +# Find PROBE_TOKEN in app console, then: +probe test tests/ --host --token -v ``` ## Initialize Your Project @@ -90,12 +113,18 @@ This creates: - `probe.yaml` — project configuration - `tests/` — directory for `.probe` test files with samples -## Build the Test Converter (Optional) +## Prerequisites -If you want to migrate tests from other frameworks: +| Requirement | When needed | +|---|---| +| Dart 3.3+ / Flutter 3.19+ | Always (for the agent) | +| Android SDK + ADB | Android emulator/device testing | +| Xcode + `xcrun simctl` | iOS simulator testing | +| `libimobiledevice` (`brew install libimobiledevice`) | Physical iOS device testing via USB | -```bash -make build-convert # outputs bin/probe-convert -``` +## Next Steps -See [probe-convert](/tools/probe-convert/) for details. +- [Write your first test](/probescript/syntax/) +- [ProbeScript Dictionary](/probescript/dictionary/) — all commands and modifiers +- [iOS Integration Guide](/platform/ios/) — physical device setup +- [CI/CD with GitHub Actions](/ci-cd/github-actions/)