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 get from your BugCapsule team
| Item | Looks like | Where it goes |
|---|---|---|
| API URL | https://api.bugcapsule.com | SDK config and bugcapsule login |
| Ingest key | bci_… | Inside your app. Treat it as public. |
| Secret key | bcs_… | The CLI and CI secrets only. Never ship it in an app. |
| Dashboard sign-in | user name + password | The web dashboard |
How an integration goes
Add the SDK and initialize it first
Init must run before your app reads storage, because during replay it restores the recorded state there. 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 your project keys 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.