Replay & verify

bugcapsule CLI

One CLI (Dart, shipped in the Flutter package, version 0.4.0) replays capsules from every runtime. It drives flutter run, an Android instrumentation, an XCUITest or a Playwright browser, and computes verdicts by the same rules everywhere.

Install

# From git
dart pub global activate --source git https://github.com/draz26648/bug_capsule_flutter_sdk --git-path packages/bug_capsule

# From a local checkout (what the onboarding uses)
cd bug_capsule_flutter_sdk && flutter pub get && dart pub global activate --source path packages/bug_capsule

# Inside a Flutter app that already depends on bug_capsule
dart run bug_capsule:bugcapsule <command>

bugcapsule --version        # bugcapsule 0.4.0 (capsule spec v1)

Log in

bugcapsule login --url https://api.bugcapsule.com --secret-key bcs_... --ingest-key bci_...

Credentials go to ~/.bugcapsule/config.json (mode 600; USERPROFILE on Windows). BUGCAPSULE_URL, BUGCAPSULE_SECRET_KEY and BUGCAPSULE_INGEST_KEY override the file, which is what you want in CI. The ingest key is only needed for push.

Commands

Launch options (run, verify, regress run)

Exit codes

How attempts become verdicts: Verdicts & divergences.

Which runtime, which code

1. --runtime, else "runtime" in bugcapsule.json at the project root, else detection: pubspec.yaml → flutter, settings.gradle(.kts) → android, *.xcodeproj/*.xcworkspace → ios, package.json → web.
2. A capsule replays only in the runtime that captured it. Otherwise: INCOMPATIBLE (runtime.mismatch, exit 3) without building anything.
3. run builds manifest.source.gitSha in a temporary git worktree when the project is a git checkout and the commit exists (--no-pin replays the working tree). verify and regress run build the working tree.
4. The build gets the commit it's made from: Flutter --dart-define=BUGCAPSULE_GIT_SHA, Android -PbugcapsuleGitSha, iOS build setting BUGCAPSULE_GIT_SHA, web env BUGCAPSULE_GIT_SHA. A commit other than the capsule's is the expected build.gitSha divergence.

bugcapsule.json

At the project root. Not needed for Flutter apps that use the defaults.

{
  "runtime": "android",
  "android": { "applicationId": "com.example.shop" },
  "timeouts": { "buildSeconds": 1200, "attemptSeconds": 120 }
}

Replay protocol and safety

Protocol v1.1, identical across runtimes:

BUGCAPSULE_REPLAY_URL = http://127.0.0.1:<port>/a/<token>
GET  <base>/settings   → ReplaySettings JSON (attemptId, runtime, strategy, …)
GET  <base>/capsule    → .bugcapsule bytes
POST <base>/result     → ReplayReport JSON  (204; 409 wrong attemptId; 410 attempt closed)

• The server binds 127.0.0.1 on a random port (--lan for physical devices). Android emulators reach it through adb reverse (removed on exit).
• Every attempt gets a new 32-byte token and a new attemptId. Other tokens get 404; a report is accepted once; a late report from a killed attempt can never count for the next one.
• Requests with an Origin header are refused (403), so no web page can talk to the server.
• Fallback result channel: BUGCAPSULE_RESULT::{json} on stdout (Flutter), in instrumentation status (Android) or the XCUITest log (iOS), accepted only from the process launched for the armed attempt.
• Attempt isolation: Flutter relaunches, Android pm clear, iOS uninstall, web fresh browser context. A missing report, crash or timeout is an error attempt, never evidence of a fix.

Environment variables