Library setup
Both libraries are optional. Dev Scenario drives any app without them. Add them to your debug build when you want:
- app-instrumentation: much faster runs, because Dev Scenario drives the app from inside it instead of from outside. Why it's faster
- Network interceptor: see and mock your app's requests in the Network tab. What it does
You can add one, the other, or both. For each library, follow one of the ways shown — they are alternatives, not steps.
Android
app-instrumentation
Setup
Add the Gradle plugin:
app/build.gradle.ktsplugins {
id("com.android.application")
id("io.github.devscenario.app-instrumentation") version "1.0.3"
}
No code to add: app-instrumentation starts itself when the debug app launches.
That's all for debug builds. The rest of this section is optional.
Advanced
Without the plugin
One line for debug builds. No plugin needed. Don't use the plugin as well. Version on Maven Central: 1.0.3 for app-instrumentation and its Gradle plugin.
dependencies {
debugImplementation(
"io.github.devscenario:app-instrumentation:1.0.3"
)
}
For a release build too, such as an internal QA build, add it to that build as well (releaseImplementation, or that build's own configuration), and let it run there: a build that isn't debuggable doesn't start it unless its manifest says so (or the app calls DevScenarioInstrumentation.start(application)). In the <application> of that build's manifest:
<meta-data
android:name="io.github.devscenario.instrumentation.ALLOW_IN_RELEASE"
android:value="true" />
Release builds
The setup above is for debug builds. What keeps app-instrumentation out of what you ship: the plugin's or debugImplementation's debug-only default.
Testing an optimized staging or QA build on purpose? Turn it on for just that build: see Only some builds.
Turning it on in a release build
Testing a release build on purpose, such as an internal QA build? Keep such builds internal: app-instrumentation lets Dev Scenario drive the app.
Pick the build in the Gradle plugin, and that's all: a build the plugin adds a library to also runs it. Use release = true for every release build, or pick some builds as shown in Only some builds. Added it without the plugin? See Without the plugin.
Only some builds
Needs app-instrumentation 1.0.2 or later. Turn it on for your test builds only, such as a dev or QA app that also goes to Firebase, and keep it off in the build you publish.
Pick the builds one of two ways. A picked release build gets the library and runs it; every other build follows the usual defaults.
By app id
Every build of this application id. Use it when each environment has its own app id.
scenarioInstrumentation {
forApplicationId("com.example.app.dev") {
release = true
}
}
By variant name
Exactly the variants you list. Use it when environments share one app id.
scenarioInstrumentation {
forBuildVariants("appTestRelease") {
release = true
}
}
Network interceptor
Setup
Add the auto plugin. It wires every OkHttpClient in your app and adds the library for you. No code, no dependency line.
plugins {
id("com.android.application") // keep it first
id("io.github.devscenario.httpinterceptor.auto") version "1.1.2"
}
Your app keeps its own OkHttp version. No network security config change is needed.
That's all for debug builds. The rest of this section is optional.
Advanced
Manual setup
Add the library and register the interceptor yourself — useful when you only want it on some clients. Version on Maven Central: 1.1.2 for the network interceptor and its Gradle plugin.
dependencies {
debugImplementation(
"io.github.devscenario:httpinterceptor:1.1.2"
)
}
src/debug/… where you build OkHttpClient
OkHttpClient.Builder()
.addInterceptor(authInterceptor)
.addInterceptor(NetworkLogInterceptor()) // last
.build()
debugImplementation, the class only exists in debug builds, so code in src/main that mentions NetworkLogInterceptor won't compile for release — an if (BuildConfig.DEBUG) check doesn't help. Put that line in src/debug/ (with a no-op version in src/release/), or use the auto plugin.Live streams
Server-sent events and WebSocket messages can show live under their request in the Network tab. Both are off by default: until you turn them on, an event stream shows as one request and a WebSocket only as its upgrade request.
With the auto plugin:
app/build.gradle.ktsscenarioHttpInterceptor {
serverSentEvents = true // server-sent events, live
webSockets = true // WebSocket messages, live
}
With manual setup:
- Server-sent events:
NetworkLogInterceptor(serverSentEvents = true) - WebSocket messages: open sockets with
ScenarioWebSockets.newWebSocket(client, request, listener)
Release builds
The setup above is for debug builds. What keeps the interceptor out of what you ship: auto plugin: only touches the variants you allow (debug by default). Manual: debugImplementation.
Testing an optimized staging or QA build on purpose? Turn it on for just that build: see Only some builds.
Turning it on in a release build
Testing a release build on purpose, such as an internal QA build? Keep such builds internal: the interceptor sends every request, headers included, to Dev Scenario.
Pick the build in the Gradle plugin, and that's all: a build the plugin adds a library to also runs it. Use release = true for every release build, or pick some builds as shown in Only some builds.
Added the interceptor by hand instead of with the plugin? Then also allow it to run: allowInRelease = true on NetworkLogInterceptor and ScenarioWebSockets.newWebSocket.
Only some builds
Needs network interceptor 1.1.1 or later. Turn it on for your test builds only, such as a dev or QA app that also goes to Firebase, and keep it off in the build you publish.
Pick the builds one of two ways. A picked release build gets the library and runs it; every other build follows the usual defaults.
By app id
Every build of this application id. Use it when each environment has its own app id.
scenarioHttpInterceptor {
forApplicationId("com.example.app.dev") {
release = true
}
}
By variant name
Exactly the variants you list. Use it when environments share one app id.
scenarioHttpInterceptor {
forBuildVariants("appTestRelease") {
release = true
}
}
When you need extra Gradle setup
On a standard Android Studio project the snippets above work as they are. Whether you need more depends on how your project is set up — which is why one project needed extra blocks and another didn't. Find your case:
- “Plugin [id: 'io.github.devscenario…'] was not found” Your
settings.gradle(.kts)plugin repositories don't include Maven Central (common when onlygoogle()or a company mirror is listed). Add it — snippet. - “…must include a version number” You applied the plugin without
version, which is common in multi-module projects and version catalogs. Declare the version once — snippet. - Your project uses
buildscript { classpath … }andapply plugin:Older setup style; theplugins { }lines don't apply. Use the classpath form — snippet. - app-instrumentation or the interceptor can't be found The dependency repositories (
dependencyResolutionManagement) don't include Maven Central. AddmavenCentral()there too. - “…requires the Android Application or Library plugin” The interceptor plugin is applied before the Android plugin. Move
com.android.applicationabove it. - Builds fine, but nothing is captured or app-instrumentation never starts Your app has product flavors, so the debug variant is called e.g.
freeDebuganddebug = truematches nothing. List the variants — snippet.
pluginManagement {
repositories {
google()
mavenCentral()
gradlePluginPortal()
}
}
dependencyResolutionManagement {
repositories {
google()
mavenCentral()
}
}
build.gradle.kts (root) — declare versions once
plugins {
id("com.android.application") version "<your AGP version>" apply false
id("io.github.devscenario.app-instrumentation") version "1.0.3" apply false
id("io.github.devscenario.httpinterceptor.auto") version "1.1.2" apply false
}
// then in app/build.gradle.kts: id("io.github.devscenario.httpinterceptor.auto") — no version
Using a version catalog? Add the plugins to gradle/libs.versions.toml and apply them with alias(…):
[plugins]
devscenario-instrumentation = { id = "io.github.devscenario.app-instrumentation", version = "1.0.3" }
devscenario-interceptor = { id = "io.github.devscenario.httpinterceptor.auto", version = "1.1.2" }
Older projects (Groovy, buildscript)
// build.gradle (root)
buildscript {
repositories { google(); mavenCentral() }
dependencies {
classpath "com.android.tools.build:gradle:<your AGP version>"
classpath "io.github.devscenario:app-instrumentation-gradle-plugin:1.0.3"
classpath "io.github.devscenario:httpinterceptor-auto:1.1.2"
}
}
// app/build.gradle
apply plugin: 'com.android.application'
apply plugin: 'io.github.devscenario.app-instrumentation'
apply plugin: 'io.github.devscenario.httpinterceptor.auto'
app/build.gradle.kts — apps with product flavors
scenarioInstrumentation { variants("freeDebug", "paidDebug") }
scenarioHttpInterceptor { variants("freeDebug", "paidDebug") }
iOS
Swift Package Manager, iOS 13 or later. CocoaPods isn't supported.
app-instrumentation
Setup
In Xcode: File → Add Package Dependencies…, enter the URL, and add the product DevScenarioAppInstrumentation to your app target.
https://github.com/devscenario/app-instrumentation-ios.git
Or, if your project declares dependencies in Package.swift:
.package(url: "https://github.com/devscenario/app-instrumentation-ios.git", from: "1.2.1")
// in your target's dependencies:
.product(name: "DevScenarioAppInstrumentation", package: "app-instrumentation-ios")
That's all: app-instrumentation starts when the app finishes launching, in debug builds only (simulator, development signing), and is the default iOS driver in Dev Scenario. Works on simulators and real iPhones.
That's all for debug builds. The rest of this section is optional.
Advanced
Release builds
The setup above is for debug builds. What keeps app-instrumentation out of what you ship: it starts only in debuggable builds (simulator, development signing) unless the app opts in.
Testing an optimized staging or QA build on purpose? Turn it on for just that build: see Only some builds.
Turning it on in a release build
Testing a release build on purpose, such as an internal QA or TestFlight build? Keep such builds internal: app-instrumentation lets Dev Scenario drive the app.
Set its release key in your Info.plist, as shown in Only some builds.
Only some builds
Needs app-instrumentation 1.2.1 or later. Turn it on for your test builds only, such as a dev or QA app that also goes to TestFlight or Firebase, and keep it off in the build you publish.
Set DevScenarioInstrumentationEnabledInRelease in your Info.plist, one of three ways:
Every build
On in all builds of the app.
<key>DevScenarioInstrumentationEnabledInRelease</key>
<true/>
By bundle id
On only for the listed bundle ids. Use it when your test configuration builds its own bundle id.
<key>DevScenarioInstrumentationEnabledInRelease</key>
<array>
<string>com.example.app.dev</string>
</array>
By configuration
On where a build setting says YES. Use it when configurations share one bundle id.
<key>DevScenarioInstrumentationEnabledInRelease</key>
<string>$(DEVSCENARIO_ENABLED)</string>
Then add a user-defined build setting DEVSCENARIO_ENABLED set to YES for your test configuration only.
Info.plist keys
Both optional; add only the ones you need.
Info.plist<!-- Default true. false: start only when you call
DevScenarioAppInstrumentation.start() -->
<key>DevScenarioInstrumentationAutoStart</key>
<true/>
<!-- Default 7756. The port when Dev Scenario didn't launch
the app (it picks one when it does) -->
<key>DevScenarioInstrumentationPort</key>
<integer>7756</integer>
Network interceptor
Setup
Add it the same way: in Xcode, File → Add Package Dependencies…, enter the URL, and add the automatic product DevScenarioHttpInterceptorAuto to your app target.
https://github.com/devscenario/httpinterceptor-ios.git
Or, if your project declares dependencies in Package.swift:
.package(url: "https://github.com/devscenario/httpinterceptor-ios.git", from: "1.0.5")
// in your target's dependencies:
.product(name: "DevScenarioHttpInterceptorAuto", package: "httpinterceptor-ios")
Every URLSession is captured: URLSession.shared, your own configurations, Alamofire, Moya. No code.
Add this to Info.plist so the app may talk to Dev Scenario on your Mac:
<key>NSAppTransportSecurity</key>
<dict>
<key>NSAllowsLocalNetworking</key><true/>
</dict>
On a simulator that's all. On a real iPhone connected to your Mac with a cable, Dev Scenario connects to the app by itself while it's open: network logs and mocks work with nothing to set up.
That's all for debug builds. The rest of this section is optional.
Advanced
Manual setup
Link the DevScenarioHttpInterceptor product instead of DevScenarioHttpInterceptorAuto, and register it yourself, for example to capture only some sessions.
import DevScenarioHttpInterceptor
// At app start. On a real iPhone, Dev Scenario
// then connects to the app over USB.
NetworkLogInterceptor.install()
For your own URLSession configurations, add NetworkLogInterceptor.self to protocolClasses.
Live streams
Server-sent events and WebSocket messages can show live under their request in the Network tab. Both are off by default: until you turn them on, an event stream shows as one request and a WebSocket only as its upgrade request.
With the automatic product, turn them on in Info.plist:
Info.plist<!-- Server-sent events, live -->
<key>DevScenarioInterceptorServerSentEvents</key>
<true/>
<!-- WebSocket messages, live -->
<key>DevScenarioInterceptorWebSockets</key>
<true/>
With the manual product: NetworkLogInterceptor.serverSentEvents = true, and create WebSocket tasks with NetworkLogInterceptor.webSocketTask(session:request:).
Live SSE and WebSocket capture is simulator-only for now.
Release builds
The setup above is for debug builds. What keeps the interceptor out of what you ship: it runs only in debuggable builds (simulator, development signing), automatic and manual alike. App Store, TestFlight and ad hoc builds stay off unless the Info.plist key DevScenarioInterceptorEnabledInRelease turns it on.
Testing an optimized staging or QA build on purpose? Turn it on for just that build: see Only some builds.
Turning it on in a release build
Testing a release build on purpose, such as an internal QA or TestFlight build? Keep such builds internal: the interceptor sends every request, headers included, to Dev Scenario.
Set its release key in your Info.plist, as shown in Only some builds.
Only some builds
Needs network interceptor 1.0.3 or later. Turn it on for your test builds only, such as a dev or QA app that also goes to TestFlight or Firebase, and keep it off in the build you publish.
Set DevScenarioInterceptorEnabledInRelease in your Info.plist, one of three ways:
Every build
On in all builds of the app.
<key>DevScenarioInterceptorEnabledInRelease</key>
<true/>
By bundle id
On only for the listed bundle ids. Use it when your test configuration builds its own bundle id.
<key>DevScenarioInterceptorEnabledInRelease</key>
<array>
<string>com.example.app.dev</string>
</array>
By configuration
On where a build setting says YES. Use it when configurations share one bundle id.
<key>DevScenarioInterceptorEnabledInRelease</key>
<string>$(DEVSCENARIO_ENABLED)</string>
Then add a user-defined build setting DEVSCENARIO_ENABLED set to YES for your test configuration only.
Flutter
Pure Dart packages — no Android or iOS project changes. Flutter 3.16+.
app-instrumentation
Setup
pubspec.yamldependencies:
devscenario_app_instrumentation: ^0.4.1
lib/main.dart
import 'package:devscenario_app_instrumentation/devscenario_app_instrumentation.dart';
import 'package:flutter/foundation.dart';
void main() {
WidgetsFlutterBinding.ensureInitialized();
if (kDebugMode) DevScenarioAppInstrumentation.start();
runApp(const MyApp());
}
That's all for debug builds. The rest of this section is optional.
Advanced
Release builds
The setup above is for debug builds. What keeps app-instrumentation out of what you ship: your kDebugMode check around start().
Turning it on in a release build
Testing a release build on purpose, such as an internal QA build? Keep such builds internal: app-instrumentation lets Dev Scenario drive the app.
Call start(allowInRelease: true) outside kDebugMode, with the package in dependencies.
Network interceptor
Setup
Captures dart:io, package:http and dio traffic with one line, and answers the mocks you set up in the Network tab.
dependencies:
devscenario_httpinterceptor: ^0.2.2
lib/main.dart
import 'package:devscenario_httpinterceptor/devscenario_httpinterceptor.dart';
void main() {
DevScenarioHttpInterceptor.enable(); // debug builds only
runApp(const MyApp());
}
On a real device, pass your computer's IP: DevScenarioHttpInterceptor.enable(host: "<your computer's IP>").
That's all for debug builds. The rest of this section is optional.
Advanced
dio with a custom adapter
dio with a custom adapter (HTTP/2, Cronet, Cupertino) needs DevScenarioDioInterceptor; see the package's README.
Release builds
The setup above is for debug builds. What keeps the interceptor out of what you ship: enable() installs nothing outside a debug build.
Turning it on in a release build
Testing a release build on purpose, such as an internal QA build? Keep such builds internal: the interceptor sends every request, headers included, to Dev Scenario.
Call enable(allowInRelease: true) outside kDebugMode, with the package in dependencies.