screenstack_sdk 4.1.0
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 withxcrun simctl iooradb 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_129screenshots.
4.0.0 #
Breaking rewrite. The SDK is now driven by the screenstack CLI and writes
ManifestV2.
- New API:
screenstackCapture(appBuilder:, navigate:, login:, resetSession:)forintegration_test, andscreenstackDriver()(package:screenstack_sdk/driver.dart) fortest_driver/integration_test.dart. PNGs andmanifest.jsonare now written on the host, not inside the device sandbox. - Config arrives in
--dart-define=SCREENSTACK_CONFIG(base64 ResolvedRunConfig). Removed on-device YAML loading andPlatform.environmentreads, and theyamldependency. auth: nonescreens are captured first in a fresh, logged-out app (after the optionalresetSession), beforeloginruns.- Android: calls
convertFlutterSurfaceToImage()before the first screenshot. - Navigation:
navigatecallback withgoRouterNavigate(default, no go_router dependency) andnamedRouteNavigate. Removed the awaitedpushNamedand 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.
waitForby 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.fromEnvandcaptureScreenStackScreenshots. - 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) andDeviceProfile.lookup(name)/DeviceProfile.wellKnownfor string-keyed resolution.TestUserCredentials.fromEnv()readingSCREENSTACK_TEST_USER_EMAIL/PASSWORD/TOKEN/EXPIRES_ATinjected by FlightStack at run time. Credentials never appear inmanifest.json— only metadata flags.ScreenStackYaml.load()/.parse()reads ascreenstack.ymland returns aScreenStackConfig. Same file the JS SDK reads — one source of truth across both runtimes.captureScreenStackScreenshotsnow acceptsdeviceProfileandtestUsernamed args; values flow into a richermanifest.json(sdk,runtime,deviceProfile,testUsermetadata blocks at top level).- Expired-credential guard refuses to start capture instead of failing mid-run.
3.1.0 #
New #
-
ScreenStackYaml— load ascreenstack.ymlfile and convert it to aScreenStackConfigso 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 callsScreenStackYaml.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), andscreens:with route + name + targets. Targets accept both"canvas/view"short-form strings and{ canvas, view }maps. Per-calldeviceProfileandtestUserargs 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. -
yamldependency 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 intomanifest.jsonso 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 thesetupcallback uses to sign in, sourced from env vars set by FlightStack at run time:SCREENSTACK_TEST_USER_EMAILSCREENSTACK_TEST_USER_PASSWORDSCREENSTACK_TEST_USER_TOKENSCREENSTACK_TEST_USER_EXPIRES_ATUseTestUserCredentials.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.deviceProfileand.testUser— also accept config-level defaults; per-call args win.- Expired-credential guard — capture aborts before pumping the app if
TestUserCredentials.isExpiredis 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 #
setupcallback: Run authentication or data seeding before capture startsteardowncallback: Run cleanup after capture completesScreenStackCallbacktype: 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 returnsCaptureSessionResultinstead ofvoid
New Features #
- Multi-canvas support: Upload screenshots to multiple canvases simultaneously
FrameTargetclass: Type-safe canvas/view targeting withFrameTarget(canvas: 'iOS', view: 'Home')Screenclass: Define routes with explicit upload targetsScreenStackConfig.advanced()constructor: For multi-canvas projectsScreen.withPaths()factory: Parse targets from"canvas/view"string formatFrameTarget.parse()factory: Create targets from path strings- JSON manifest generation:
manifest.jsonwith capture results and targets CaptureResultclass: Detailed results per captured screenCaptureSessionResultclass: 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
effectiveNamegetter 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
ScreenStackConfigclass for type-safe configurationcaptureScreenStackScreenshots()helper for integration tests- Support for go_router and Navigator navigation
- Configurable settle delay