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.

Changelog #

4.1.0 #

First pub.dev release of the 4.x line; includes everything in 4.0.0.

  • Full-screen captures can come from the device itself (--dart-define=SCREENSTACK_DEVICE_SCREENSHOT=true): screenstackDriver() takes them with xcrun simctl io or adb exec-out screencap, so the status bar is included. The in-app screenshot is still used to cut element layers.
  • iPad App Store set: captures from an iPad device feed the 13-inch APP_IPAD_PRO_3GEN_129 screenshots.

4.0.0 #

Breaking rewrite. The SDK is now driven by the screenstack CLI and writes ManifestV2.

  • New API: screenstackCapture(appBuilder:, navigate:, login:, resetSession:) for integration_test, and screenstackDriver() (package:screenstack_sdk/driver.dart) for test_driver/integration_test.dart. PNGs and manifest.json are now written on the host, not inside the device sandbox.
  • Config arrives in --dart-define=SCREENSTACK_CONFIG (base64 ResolvedRunConfig). Removed on-device YAML loading and Platform.environment reads, and the yaml dependency.
  • auth: none screens are captured first in a fresh, logged-out app (after the optional resetSession), before login runs.
  • Android: calls convertFlutterSurfaceToImage() before the first screenshot.
  • Navigation: navigate callback with goRouterNavigate (default, no go_router dependency) and namedRouteNavigate. Removed the awaited pushNamed and the single-Navigator lookup.
  • Locale and light or dark appearance are applied, and (except on Android) the device profile is applied to the test view (size, pixel ratio, safe area). All are reset on teardown.
  • waitFor by key or text with a timeout, endless-animation-safe settling.
  • Element layers: transparent when the keyed widget is a RepaintBoundary, cropped from the screenshot otherwise, with padding and bounds in points. Missing or zero-size elements are warnings, not screen failures.
  • The manifest never contains credentials (the 3.x test-user email is gone).
  • Removed ScreenStackConfig, Screen, FrameTarget, CaptureKind, DeviceProfile, ScreenStackYaml, TestUserCredentials.fromEnv and captureScreenStackScreenshots.
  • Added example/.

3.1.1 #

First pub.dev release from the new in-monorepo location at packages/screenstack_sdk/. Combines the unpublished 3.0.0 + 3.1.0 deltas:

  • DeviceProfile + well-known constants (iphone15ProMax, iphone15Pro, iphoneSE, ipadPro129, pixel9Pro, pixel9, galaxyS25Ultra) and DeviceProfile.lookup(name) / DeviceProfile.wellKnown for string-keyed resolution.
  • TestUserCredentials.fromEnv() reading SCREENSTACK_TEST_USER_EMAIL/PASSWORD/TOKEN/EXPIRES_AT injected by FlightStack at run time. Credentials never appear in manifest.json — only metadata flags.
  • ScreenStackYaml.load() / .parse() reads a screenstack.yml and returns a ScreenStackConfig. Same file the JS SDK reads — one source of truth across both runtimes.
  • captureScreenStackScreenshots now accepts deviceProfile and testUser named args; values flow into a richer manifest.json (sdk, runtime, deviceProfile, testUser metadata blocks at top level).
  • Expired-credential guard refuses to start capture instead of failing mid-run.

3.1.0 #

New #

  • ScreenStackYaml — load a screenstack.yml file and convert it to a ScreenStackConfig so the Flutter SDK accepts the same single source of truth the JS SDK (@voostack/screenstack-sdk) reads. The file lives at the customer's repo root; the integration test calls ScreenStackYaml.load(...) instead of building config in Dart.

    final config = await ScreenStackYaml.load(
      'screenstack.yml',
      appBuilder: () => const MyApp(),
    );
    await captureScreenStackScreenshots(tester, binding, config);
    

    Schema accepts project, deviceProfile (well-known string or literal map), settleDelay, testUser.secretRef (FlightStack swaps for env vars at run time), and screens: with route + name + targets. Targets accept both "canvas/view" short-form strings and { canvas, view } maps. Per-call deviceProfile and testUser args win over what the YAML declares.

  • DeviceProfile.lookup(name) + DeviceProfile.wellKnown — string → profile map keyed by the names the FlightStack mapping table uses (e.g. iphone-15-pro-max). Powers YAML resolution and lets customers thread profile names through env vars without importing the constants in Dart.

  • yaml dependency added.

Repo location #

The SDK was moved into the ScreenStack monorepo at packages/screenstack_sdk/. Previously at voo_flutter/packages/dev/screenstack_sdk. No code change needed on the consumer side — pub.dev still ships it as screenstack_sdk.

3.0.0 #

New #

  • DeviceProfile — describes the device the captures were taken on. Written into manifest.json so the FlightStack uploader can route captures to the right canvas view automatically. Ships with well-known constants (iphone15ProMax, iphone15Pro, iphoneSE, ipadPro129, pixel9Pro, pixel9, galaxyS25Ultra).
  • TestUserCredentials — credentials the setup callback uses to sign in, sourced from env vars set by FlightStack at run time:
    • SCREENSTACK_TEST_USER_EMAIL
    • SCREENSTACK_TEST_USER_PASSWORD
    • SCREENSTACK_TEST_USER_TOKEN
    • SCREENSTACK_TEST_USER_EXPIRES_AT Use TestUserCredentials.fromEnv() instead of reading the environment directly. Credentials themselves are NEVER serialized into the manifest — only metadata (whether a password / bearer was provided, expiry).
  • captureScreenStackScreenshots(..., DeviceProfile? deviceProfile, TestUserCredentials? testUser) — new optional parameters thread the above through to the manifest.
  • ScreenStackConfig.deviceProfile and .testUser — also accept config-level defaults; per-call args win.
  • Expired-credential guard — capture aborts before pumping the app if TestUserCredentials.isExpired is true, instead of failing mid-capture.

Manifest #

manifest.json now starts with "sdk": "screenstack_sdk", "runtime": "flutter" so a single FlightStack uploader can disambiguate Flutter SDK and JS SDK output. New deviceProfile and testUser (metadata-only) blocks at the top level.

Breaking #

The captureScreenStackScreenshots signature now has the two extra optional named parameters. Existing call sites compile unchanged. The manifest schema is additive — older uploaders that ignore unknown keys keep working.

2.0.3 #

  • Reorder exports and streamline code structure across multiple files
  • Update dependencies and fix formatting issues across multiple packages

2.0.2 #

Documentation #

  • Authentication guide: Comprehensive section on handling auth in screenshots
    • Option 1: Setup/teardown callbacks with Firebase, Supabase, custom examples
    • Option 2: Demo/screenshot mode pattern for bypassing auth
    • Option 3: Test-specific routes (e.g., /preview/dashboard)
  • Environment variables: Guidance on storing secrets in CI/CD pipelines
  • Best practices: Updated auth section with practical examples

2.0.1 #

New Features #

  • setup callback: Run authentication or data seeding before capture starts
  • teardown callback: Run cleanup after capture completes
  • ScreenStackCallback type: Type alias for setup/teardown functions

Example #

await captureScreenStackScreenshots(
  tester,
  binding,
  config,
  setup: (tester, context) async {
    // Authenticate before capturing protected screens
    await AuthService.signIn(email: 'test@example.com', password: 'test');
    await tester.pumpAndSettle();
  },
  teardown: (tester, context) async {
    await AuthService.signOut();
  },
);

2.0.0 #

Breaking Changes #

  • captureScreenStackScreenshots() now returns CaptureSessionResult instead of void

New Features #

  • Multi-canvas support: Upload screenshots to multiple canvases simultaneously
  • FrameTarget class: Type-safe canvas/view targeting with FrameTarget(canvas: 'iOS', view: 'Home')
  • Screen class: Define routes with explicit upload targets
  • ScreenStackConfig.advanced() constructor: For multi-canvas projects
  • Screen.withPaths() factory: Parse targets from "canvas/view" string format
  • FrameTarget.parse() factory: Create targets from path strings
  • JSON manifest generation: manifest.json with capture results and targets
  • CaptureResult class: Detailed results per captured screen
  • CaptureSessionResult class: Session summary with success/failure counts
  • Config validation: config.validate() returns list of configuration errors
  • Per-screen settle delay: Override global delay for specific screens

Improvements #

  • Comprehensive library documentation with examples
  • Better error messages for navigation failures
  • Emoji-enhanced console output for capture progress
  • effectiveName getter auto-generates filename from route if not specified

Documentation #

  • Complete API reference in README
  • ScreenStack hierarchy explanation
  • Workflow diagram
  • Best practices and troubleshooting guide

1.0.0 #

  • Initial release
  • ScreenStackConfig class for type-safe configuration
  • captureScreenStackScreenshots() helper for integration tests
  • Support for go_router and Navigator navigation
  • Configurable settle delay
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