ScreenStack SDK

Screenshot capture configuration for ScreenStack integration with FlightStack CI/CD.

Overview

This package provides a type-safe API for configuring automated screenshot capture during FlightStack builds. Screenshots are automatically captured from your Flutter app and uploaded to ScreenStack device frames.

Installation

Add to your pubspec.yaml:

dev_dependencies:
  screenstack_sdk: ^1.0.0

Usage

1. Create Configuration File

Create lib/screenstack_config.dart in your Flutter project:

import 'package:screenstack_sdk/screenstack_sdk.dart';
import 'main.dart';

final screenStackConfig = ScreenStackConfig(
  appBuilder: () => const MyApp(),
  routes: {
    '/': 'home_screen',
    '/settings': 'settings_screen',
    '/profile': 'profile_screen',
  },
);

2. Configure FlightStack Pipeline

In your FlightStack pipeline, add a ScreenStack job with Upload mode:

  1. Set Canvas ID to your ScreenStack canvas
  2. Set Config File to lib/screenstack_config.dart
  3. Map each screenshot name to its device frame layer ID

3. Run Your Build

FlightStack will automatically:

  1. Generate an integration test
  2. Navigate to each route and capture screenshots
  3. Upload screenshots to the corresponding device frames in ScreenStack

Configuration Options

ScreenStackConfig

Property Type Description
appBuilder Widget Function() Function that returns your app's root widget
routes Map<String, String> Map of route paths to screenshot names
settleDelay Duration Delay before capture (default: 500ms)

Routes Map

  • Key: Route path (e.g., /home, /settings)
  • Value: Screenshot filename without extension (e.g., home_screen)

The screenshot name must match the mapping in your FlightStack pipeline configuration.

Advanced Usage

Custom Settle Delay

If your app has complex animations, increase the settle delay:

final screenStackConfig = ScreenStackConfig(
  appBuilder: () => const MyApp(),
  routes: { '/': 'home' },
  settleDelay: const Duration(seconds: 1),
);

Manual Test Integration

You can also run the screenshot capture manually:

import 'package:flutter_test/flutter_test.dart';
import 'package:integration_test/integration_test.dart';
import 'package:screenstack_sdk/screenstack_sdk.dart';
import 'package:my_app/screenstack_config.dart';

void main() {
  final binding = IntegrationTestWidgetsFlutterBinding.ensureInitialized();

  testWidgets('Capture screenshots', (tester) async {
    await captureScreenStackScreenshots(
      tester,
      binding,
      screenStackConfig,
      outputDir: 'build/screenshots',
    );
  });
}

Requirements

  • Flutter 3.10.0 or higher
  • Dart 3.5.0 or higher
  • FlightStack CI/CD (for automated uploads)

License

MIT License - see LICENSE for details.

Libraries

screenstack_sdk
ScreenStack SDK - Screenshot capture configuration for FlightStack CI/CD