ScreenStack Job | FlightStack

ScreenStack Job

Runs your Flutter widget / integration tests in screenshot-capture mode and uploads the resulting images to ScreenStack for visual regression review. ScreenStack is VooStack’s companion product — see the ScreenStack integration guide.

Step ref: flightstack/screen-stack@1.0.0.

Requirements

Any agent that can run flutter test / flutter drive.
A ScreenStack project linked to your FlightStack organization.
Tests instrumented with the screenstack package.

Configuration

Option	Description	Default
Project	ScreenStack project ID (or slug)	from org default
Tests path	Glob pattern of test files to run	`test/screens/**.dart`
Devices	Comma-separated device profile names (e.g. `pixel-7,iphone-15`)	`iphone-15`
Theme variants	`light,dark`, or a list of theme names	`light,dark`
Fail on regression	Fail the job when ScreenStack reports a visual diff above threshold	`true`
Branch baseline	Branch to diff against	repo default branch

How it works

Agent runs the Flutter tests under flutter test --machine with the ScreenStack capture harness enabled.
Each captured screenshot is uploaded via POST /buildagent/{id}/screenstack/upload (or …/upload-by-target for canvas-aware captures).
ScreenStack diffs against the baseline branch and posts results back.
The job exits non-zero if Fail on regression is on and the diff exceeds the project’s threshold.

Outputs

Name	Description
`reviewUrl`	ScreenStack review URL for this run
`changedCount`	Number of screens whose pixel diff exceeds the threshold
`newCount`	Number of new (not in baseline) screens

Example pipeline

┌──────────┐    ┌──────────────┐    ┌──────────────┐
│ On PR    │───▶│ Tests        │───▶│ Screen Stack │
└──────────┘    └──────────────┘    └──────────────┘
                                          │
                                          ▼
                                    ┌──────────────┐
                                    │ Notification │
                                    │ (Slack PR)   │
                                    └──────────────┘

Troubleshooting

Uploads fail with 401 The agent token didn’t pick up your org’s ScreenStack scope. Run flightstack agent doctor and re-register if needed.

Diffs everywhere on the first run The first run becomes the baseline. Approve it in ScreenStack to use it as the reference.