BugCapsule developer docs
Stop reproducing bugs. Replay them.
BugCapsule turns a failure QA saw into a portable .bugcapsule file. You replay it against your real app code on a simulator, emulator or browser, verify your fix, and keep it as a regression test. This guide shows how to add the SDK to your app and how to use the bugcapsule CLI and the dashboard.
Pick your platform
Flutter
One package, bug_capsule. BLoC, Riverpod, Provider, GetX, MobX, Dio, package:http, GoRouter.
Android
Kotlin SDK with a Java-friendly API. Views, Compose, Jetpack Navigation, OkHttp, DataStore.
iOS
Swift package with no dependencies. UIKit, SwiftUI, URLSession, UserDefaults, XCUITest replay.
Web & React
Framework-neutral SDK plus React helpers. fetch, XHR, History API, web storage, Playwright replay.
How it fits together
What you need
| Item | Looks like | Where it goes |
|---|---|---|
| SDK token | bcsdk.v1.… | Inside your app: the one value init needs. It carries the BugCapsule address and can only send data. Project Settings › Keys › SDK tokens. |
| CLI token | personal or service token | The CLI and CI secrets only. Never ship it in an app. |
| API URL | https://api.bugcapsule.com | bugcapsule login, and the advanced explicit setup (with a bci_… ingest key) for self-hosted or existing apps |
| Dashboard sign-in | user name + password | The web dashboard |
How an integration goes
Connect with one line, then add adapters
Initialize with your SDK token, first thing, and wait for the two confirmations: configuration fetched, then first event or Capsule received. Init must run before your app reads storage, because during replay it restores the recorded state there. Then add the integrations for your HTTP client, router, storage and state.
Build with the git commit pinned
Pass
BUGCAPSULE_GIT_SHAat build time. Without it a capsule ispartialandbugcapsule runcan't check out the code that failed.Name actions, track text, write assertions
Semantic action ids, tracked text fields and
check/failassertions make more bugs replayable. Wrong behaviour that doesn't throw becomes a checkable failure.Hand the build to QA
When something breaks, a capsule is captured, redacted on the device and uploaded automatically. QA can also press the capture button.
Replay, fix, verify, keep
bugcapsule runexpectsREPRODUCED; after your fixbugcapsule verifyexpectsFIXED;bugcapsule regress addkeeps it for CI. See verdicts.
New here? The quickstart takes you from an SDK token to a first REPRODUCED and a first FIXED.
Ground rules for every platform
- Replay runs your real app code. Network responses come from the capsule with their recorded latency, so races and data-dependent bugs come back. Requests the recording never saw fail by default, so replay never reaches your real services.
- Redaction happens on the device, before anything is written. It is pattern based and best effort; personal data that isn't a credential is not removed automatically. Read Privacy & redaction before a production rollout.
- Production builds can't be driven into replay. Each platform gates replay behind a debug or test-only path.
- A capsule replays only on the platform that captured it. An Android capsule replays on Android, a web capsule in Chromium, and so on.
- The SDK never breaks your app. If storage or setup fails, the app starts without capture, and SDK errors never reach your error handlers.
Choose your next step
- New integration: install approved artifacts, run the demo, then complete the integration checklist.
- Production diagnostics: configure monitoring, upload release symbols, review data collection and the rollout checklist.
- Maintaining an integration: follow upgrade guidance and keep regressions in CI.