Skip to main content

screenstack_sdk 4.1.0 copy "screenstack_sdk: ^4.1.0" to clipboard
screenstack_sdk: ^4.1.0 copied to clipboard

In-app screenshot and widget-layer capture for Flutter apps, driven by the ScreenStack CLI in CI. Produces store screenshots and showcase layers for ScreenStack canvases.

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:

  1. Reads the run config from --dart-define=SCREENSTACK_CONFIG. Nothing is read from files or environment variables on the device.
  2. 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.
  3. Captures auth: none screens first: calls resetSession, pumps a fresh app, and never logs in.
  4. Pumps a fresh app again, calls login with the run's test user, and captures auth: required screens.
  5. For each screen: calls navigate, settles, waits for waitFor (a ValueKey<String> or visible text) up to its timeout, waits settleMs, 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,
});

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) calls GoRouter.of(context).go(route). go_router is found at runtime, so the SDK does not depend on it.
  • namedRouteNavigate calls Navigator.pushNamed without 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, which integration_test requires 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.

1
likes
160
points
887
downloads

Documentation

Documentation
API reference

Publisher

verified publishervoostack.com

Weekly Downloads

In-app screenshot and widget-layer capture for Flutter apps, driven by the ScreenStack CLI in CI. Produces store screenshots and showcase layers for ScreenStack canvases.

Homepage
Repository (GitHub)
View/report issues

Topics

#screenshots #app-store #testing #ci-cd #automation

Funding

Consider supporting this project:

github.com

License

MIT (license)

Dependencies

flutter, flutter_test, integration_test, vm_service

More

Packages that depend on screenstack_sdk