screenstack_sdk
In-app capture for Flutter apps. screenstack_sdk runs inside
integration_test on a simulator, emulator or device, opens every screen
from your screenstack.yml, and produces full-screen PNGs, transparent
widget layers and a ManifestV2 manifest.json on the host. The screenstack
CLI runs it in CI and uploads the result to your ScreenStack canvases.
Quick start
1. Add the dependency
dev_dependencies:
integration_test:
sdk: flutter
screenstack_sdk: ^4.0.0
2. Add the integration test
integration_test/screenstack_test.dart:
import 'package:my_app/main.dart';
import 'package:screenstack_sdk/screenstack_sdk.dart';
void main() => screenstackCapture(appBuilder: () => const MyApp());
3. Add the driver
test_driver/integration_test.dart:
import 'package:screenstack_sdk/driver.dart';
Future<void> main() => screenstackDriver();
4. Point screenstack.yml at it
platforms:
flutter: { target: integration_test/screenstack_test.dart, devices: [iphone-16-pro, pixel-9] }
screens:
- id: login
route: /login
auth: none
elements:
- { id: login-card, flutter: login_card }
- id: workout
route: /workouts/strength
waitFor: { key: workout_screen }
elements:
- { id: set-row, flutter: set_row, padding: 12 }
Then run npx @voostack/screenstack-sdk capture --platform flutter.
How the CLI drives it
For every device, locale and appearance in the matrix the CLI runs:
flutter drive \
--driver=test_driver/integration_test.dart \
--target=integration_test/screenstack_test.dart \
-d <device-id> \
--dart-define=SCREENSTACK_CONFIG=<base64 ResolvedRunConfig>
On the device, screenstackCapture:
- Reads the run config from
--dart-define=SCREENSTACK_CONFIG. Nothing is read from files or environment variables on the device. - Applies the locale and the light or dark appearance and, except on Android, the device profile (logical size, pixel ratio, safe-area padding) to the test view. All are reset when the test ends.
- Captures
auth: nonescreens first: callsresetSession, pumps a fresh app, and never logs in. - Pumps a fresh app again, calls
loginwith the run's test user, and capturesauth: requiredscreens. - For each screen: calls
navigate, settles, waits forwaitFor(aValueKey<String>or visible text) up to its timeout, waitssettleMs, then takes the screenshot and renders each element layer.
On the host, screenstackDriver() receives the screenshots and the capture
report and writes <screenId>.png, <screenId>__<elementId>.png and
manifest.json to the run's outDir (override with SCREENSTACK_OUT_DIR
or screenstackDriver(outDir: ...)). Output is written even when some
screens failed, so the CLI can upload what was captured.
To run it by hand, base64 a run config (see
example/tool/sample_run_config.json) and pass it yourself:
flutter drive --driver=test_driver/integration_test.dart \
--target=integration_test/screenstack_test.dart -d <device-id> \
--dart-define=SCREENSTACK_CONFIG=$(base64 < run-config.json | tr -d '\n')
API
void screenstackCapture({
required Widget Function() appBuilder,
ScreenStackNavigate navigate = goRouterNavigate,
ScreenStackLogin? login,
ScreenStackResetSession? resetSession,
ResolvedRunConfig? config,
});
Navigation
navigate receives a BuildContext below your root Navigator and the
screen's route (or deepLink when there is no route). It should request
navigation and return; do not await a pushed route.
goRouterNavigate(default) callsGoRouter.of(context).go(route). go_router is found at runtime, so the SDK does not depend on it.namedRouteNavigatecallsNavigator.pushNamedwithout awaiting it.- Anything else: pass your own callback.
screenstackCapture(
appBuilder: () => const MyApp(),
navigate: (context, route) async => myRouter.navigateTo(route),
);
Signing in
The CLI fetches test-user credentials just in time and passes them in the
run config. They reach only your login callback and are never written to
the manifest, the driver report or logs.
screenstackCapture(
appBuilder: () => const MyApp(),
resetSession: (tester) async => await AuthStore.clear(),
login: (tester, user) async {
await tester.enterText(find.byKey(const ValueKey('email')), user.email);
await tester.enterText(find.byKey(const ValueKey('password')), user.password);
await tester.tap(find.byKey(const ValueKey('sign_in')));
},
);
resetSession runs once before the logged-out phase so auth: none
screens (login, register, onboarding) render signed out even if a previous
run left a session behind.
Element layers
An element is found by ValueKey<String>(key), where key is the YAML
flutter: value (or the element id). Wrap it in a keyed RepaintBoundary
to get a transparent layer of just that widget:
RepaintBoundary(
key: const ValueKey('set_row'),
child: SetRow(set: set),
)
Without a RepaintBoundary, the layer is cropped from the full screenshot
and includes whatever is painted behind the widget. padding (logical
pixels) grows the layer on every side. A missing, zero-size or off-screen
element is reported as a warning by the driver and the screen keeps its
other layers.
Platform notes
- Android: the SDK calls
convertFlutterSurfaceToImage()before the first screenshot, whichintegration_testrequires on Android. The test view is not resized on Android: once the surface is converted, a view whose size differs from the emulator's never delivers a screenshot. Use an emulator that matches the device profile; the manifest records the real viewport. - iOS: the example targets iOS 15.0, the minimum current Xcode accepts for simulator builds.
- Boot a simulator or emulator that matches the device profile. On iOS the SDK lays the app out at the profile's size, but the screenshot is taken from the real screen.
Example
example/ is a two-route go_router app with one keyed layer. See its
README for the flutter drive command.
Migrating from 3.x
4.0.0 is a rewrite around the CLI. ScreenStackConfig, Screen,
FrameTarget, DeviceProfile, ScreenStackYaml and
captureScreenStackScreenshots are gone. Screens, devices and canvases now
live in screenstack.yml, and the CLI hands each run to the SDK.
Libraries
- driver
- Host-side half of the ScreenStack Flutter SDK. Use it as the whole of
test_driver/integration_test.dart: - screenstack_sdk
- In-app capture for ScreenStack. Runs inside
integration_teston a simulator, emulator or device, driven by thescreenstackCLI.