dusk:screenshot

Capture a screenshot of the running Flutter app to a file. The VM Service handler walks the render tree to find the RepaintBoundary that DuskPlugin.install() wrapped around the app root, calls toImage, and returns a base64-encoded PNG or JPEG. The CLI decodes the base64 and writes the bytes to the path supplied by --output.

JPEG is the default for size: a typical Flutter web screen renders in ~30 KB at quality 70. Switch to PNG when the agent needs lossless pixels for a diff comparison.

Synopsis
Arguments
Returns
Format and quality
Examples
See also

Synopsis

dart run fluttersdk_dusk dusk:screenshot --output=
                                          [--format=jpeg|png]
                                          [--quality=<1-100>]

dusk:screenshot requires a running Flutter session (CommandBoot.connected). It dials the VM Service URI, calls ext.dusk.screenshot, decodes the base64 payload, and writes the resulting bytes to the supplied output path.

Arguments

Option	Abbr	Type	Default	Required	Description
`--output`	`-o`	string (path)	(none)	yes (`mandatory: true`)	Output file path. Resolved relative to the CWD. The directory must already exist.
`--format`	none	enum	`jpeg`	no	One of `jpeg`, `png`. Constrained by `allowed: ['jpeg', 'png']` so any other value errors out at parse time.
`--quality`	none	int (string-parsed)	`70`	no	JPEG quality, range 1-100. Ignored for PNG. Falls back to `70` when the value fails `int.tryParse`.

The --output guard fires before the VM Service call; an empty or missing path returns exit code 1 with Missing --output=..

Returns

dusk:screenshot returns an integer exit code via Future:

Exit code	Meaning
`0`	Screenshot captured and written. The handler emits `Wrote base64 chars to` where is the length of the base64 string before decoding (useful for spotting empty buffers without inspecting the file).
`1`	`--output` was missing or empty (CLI-side guard); OR the VM Service handler returned a response without a `base64` field.

Success envelope (CLI side):

[ok]      Wrote 41268 base64 chars to /tmp/dashboard.jpeg

VM Service envelope (handler side):

{ "base64": "" }

The CLI calls base64Decode(base64Str) and writes the resulting bytes to output. No additional metadata (width, height, mime) is returned today; the agent infers shape from the file on disk if needed.

Format and quality

jpeg (default): the VM Service handler encodes via the image package's JPEG encoder at the supplied quality. Quality 70 is a Playwright-aligned default; bump to 90 for visual-regression diffs, drop to 40 for quick sanity checks.
png: lossless, larger files (typically 5x JPEG at quality 70). The --quality value is ignored.

The handler never resizes the screenshot; the captured image matches the running viewport's pixel dimensions (logical size times DPR). To capture at a controlled viewport, run dusk:resize or dusk:device first.

Examples

1. Capture the current screen as JPEG

dart run fluttersdk_dusk dusk:screenshot --output=/tmp/screen.jpeg

Expected output (illustrative):

[ok]      Wrote 41268 base64 chars to /tmp/screen.jpeg

2. Capture losslessly for a visual diff

dart run fluttersdk_dusk dusk:screenshot --output=/tmp/screen.png --format=png

Useful when the agent compares against a baseline PNG via image_diff or pixelmatch.

3. Capture at high quality JPEG

dart run fluttersdk_dusk dusk:screenshot --output=/tmp/hifi.jpeg --quality=92

4. Capture after a controlled resize

dart run fluttersdk_dusk dusk:resize --width=1440 --height=900
dart run fluttersdk_dusk dusk:screenshot --output=/tmp/desktop.jpeg