testing-fdb

name	testing-fdb
description	Testing and developing fdb (Flutter Debug Bridge). Covers running the smoke test suite, individual command tests, static analysis, and the test app. Use when running fdb tests, adding new commands, verifying fdb behavior, or preparing a release.
metadata	{"internal":true}

Prerequisites

• Dart SDK >= 3.0.0
• Flutter SDK
• Task (brew install go-task)
• A running iOS Simulator or Android emulator

Test App

A minimal Flutter app lives in example/test_app/ and is used as the target for all integration tests.

Setup

task setup    # dart pub get + flutter pub get in test app

Running Tests

Full smoke test

Runs all fdb commands end-to-end: launch, attach, status, reload, restart, logs, tree, screenshot, select, kill.

task smoke                    # auto-detect device
task smoke DEVICE=iPhone-16   # specific device

Individual command tests

The app must already be running (via task test:launch) before running individual tests:

task test:launch DEVICE=iPhone-16
task test:launch-verbose DEVICE=iPhone-16
task test:attach DEVICE=iPhone-16
task test:devices
task test:status
task test:status-after-interrupted-launch
task test:reload
task test:restart
task test:logs
task test:logs-tag
task test:syslog
task test:crash-report
task test:tree
task test:describe
task test:describe-textfield
task test:describe-grid
task test:describe-nested-gestures
task test:describe-router
task test:screenshot
task test:native-view-tap
task test:deeplink
task test:native-tap
task test:grant-permission
task test:simulator
task test:select
task test:tap
task test:double-tap
task test:longpress
task test:tap-at
task test:tap-disappearing-widget
task test:tap-ignore-pointer-wrapper
task test:tap-cupertino-button
task test:input
task test:scroll
task test:scroll-to
task test:mem
task test:mem-native
task test:gc
task test:heap-dump
task test:wait
task test:swipe
task test:swipe-path
task test:back
task test:clean
task test:ext
task test:shared-prefs
task test:app-died
task test:kill
task test:status-stopped
task test:session-dir

Static analysis

task analyze    # dart analyze + dart format --set-exit-if-changed

Unit tests

task test:unit    # dart test

Unit tests cover launch_failure_analyzer.dart — classification of flutter run failures into structured categories (IOS_BUNDLE_ID_CLAIMED, IOS_NO_ACCOUNT_FOR_TEAM, IOS_CODESIGN_PROVISIONING, IOS_DEVICE_LOCKED, IOS_BUILD_SCRIPT, ANDROID_INSTALL_ADB, ANDROID_LICENSE_NOT_ACCEPTED, SDK_TOOLCHAIN, FLUTTER_BUILD, UNKNOWN). Each category has a fixture under test/fixtures/launch_failures/ containing real flutter run output strings.

Cleanup

task cleanup    # kill app, remove .fdb/ session directory

Agent scenarios (semantic regression testing)

task smoke and individual task test:* tasks grep output tokens — binary pass/fail. They cannot catch semantic regressions such as elements leaking from underlying routes, wrong screen names, or incorrect visible text.

Run the scenarios in doc/agent-scenarios.md when making changes to any fdb command. Each scenario describes exact commands to run and a What to verify list you evaluate by reading the actual output. This is the difference between "the right token appeared" and "the right content appeared for the right screen."

# Read the scenarios document
cat doc/agent-scenarios.md

# Run a scenario — example for S1 (home screen baseline)
cd example/test_app
dart run ../../bin/fdb.dart describe
# then evaluate output against the S1 What to verify list

When adding a new command, also add a corresponding scenario to doc/agent-scenarios.md — see the "Adding new scenarios" section at the bottom of that file.

Test output conventions

Each test task prints:

• PASS: fdb <command> on success
• FAIL: fdb <command> - <reason> on failure (to stderr, exits 1)

Adding a new command

1. Create lib/core/commands/<name>/<name>.dart (verb function) and lib/core/commands/<name>/<name>_models.dart (Input typedef + sealed Result).
2. Create lib/cli/adapters/<name>_cli.dart with Future<int> runXxxCli(List<String> args) using runCliAdapter.
3. Add a case to the switch in bin/fdb.dart calling runXxxCli(args).
4. Add the command to the usage string in bin/fdb.dart.
5. Add a test:your-command task to Taskfile.yml following the existing pattern.
6. Add the new task to the smoke task's command sequence.
7. Update README.md commands table.
8. Update doc/README.agents.md commands reference table.
9. Update .agents/skills/testing-fdb/SKILL.md individual test list.