Dev Scenario Docs
Set up your app / Library setup

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.

Tip: the desktop app shows copy-ready snippets with the current versions under Network → Setup.

Android

app-instrumentation

Setup

Add the Gradle plugin:

app/build.gradle.kts
plugins {
    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.

app/build.gradle.kts
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:

AndroidManifest.xml
<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.

app/build.gradle.kts
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.

app/build.gradle.kts
dependencies {
    debugImplementation(
        "io.github.devscenario:httpinterceptor:1.1.2"
    )
}
src/debug/… where you build OkHttpClient
OkHttpClient.Builder()
    .addInterceptor(authInterceptor)
    .addInterceptor(NetworkLogInterceptor()) // last
    .build()
Manual setup and release builds: with 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.kts
scenarioHttpInterceptor {
    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 only google() 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 … } and apply plugin: Older setup style; the plugins { } 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. Add mavenCentral() there too.
  • “…requires the Android Application or Library plugin” The interceptor plugin is applied before the Android plugin. Move com.android.application above 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. freeDebug and debug = true matches nothing. List the variants — snippet.
settings.gradle.kts — repositories
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.

Package URL
https://github.com/devscenario/app-instrumentation-ios.git

Or, if your project declares dependencies in Package.swift:

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.

Package URL
https://github.com/devscenario/httpinterceptor-ios.git

Or, if your project declares dependencies in Package.swift:

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.yaml
dependencies:
  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.

pubspec.yaml
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.