Files

T

George KarrandLuke Heath 51da3581e6 Adding new screencap tool to help with automated testing (#42437 )

## Summary

Adds `tools/screencap`, a CLI for automated screenshots of the Fleet UI
via headless Chrome (CDP).

- **Built-in full workflow** captures all major pages and their
modals/tabs (dashboard, hosts, queries, policies, software, controls,
settings, account) in one command.
- **Record custom workflows** in a visible browser — clicks, tabs,
radios, checkboxes, and tooltip hovers are recorded automatically and
saved as replayable JSON under `tools/screencap/workflows/`.
- **Auth options** for SSO, email/password, or session cookie; the
Chrome profile is persisted at `~/.fleet/screencap-profile/` so sessions
survive across runs.
- **Output** is written to `screenshots/<timestamp>-<workflow>-<host>/`
as numbered PNGs, with multi-viewport pages split into separate images.

See `tools/screencap/README.md` for full usage.

## Test plan

- [ ] `cd tools/screencap && make build` produces the binary
- [ ] `./screencap -sso https://<fleet-host>` captures the full built-in
workflow
- [ ] `./screencap -record demo https://<fleet-host>` records a workflow
and saves it under `workflows/demo.json`
- [ ] `./screencap -workflow demo https://<fleet-host>` replays the
recorded workflow
- [ ] `./screencap -list` shows saved workflows

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added a screenshot automation tool that records and replays UI
workflows, captures full-page and modal screenshots, restores scroll
positions, and supports session persistence and multiple login methods.

* **Chores**
* Added a minimal build/clean workflow for the tool and updated ignore
rules to avoid committing generated screenshots.

* **Documentation / Templates**
* Included example workflow templates demonstrating common navigation
and interaction sequences.

<!-- review_stack_entry_start -->

[![Review Change
Stack](https://storage.googleapis.com/coderabbit_public_assets/review-stack-in-coderabbit-ui.svg)](https://app.coderabbit.ai/change-stack/fleetdm/fleet/pull/42437?utm_source=github_walkthrough&utm_medium=github&utm_campaign=change_stack)

<!-- review_stack_entry_end -->
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Luke Heath <luke@fleetdm.com>

2026-05-21 13:49:56 -05:00

workflows

…

go.mod

…

go.sum

…

main.go

…

Makefile

…

README.md

…

workflow.go

…

README.md

screencap

A CLI tool that automatically captures screenshots of Fleet UI pages using a headless Chrome browser. It supports a built-in workflow that covers all major pages and modals, as well as custom recorded workflows that can be saved and replayed.

Prerequisites

Go (1.25+)
Google Chrome installed (the tool uses Chrome via the Chrome DevTools Protocol)
A running Fleet instance to capture

Building

cd tools/screencap
make build

This produces a screencap binary in the current directory.

To remove the binary:

make clean

Authentication

The tool persists a Chrome profile at ~/.fleet/screencap-profile/, so sessions survive across runs. On the first run (or when your session expires), authenticate using one of these methods:

Flag	Description
`-sso`	Opens a visible browser for SSO login. Complete the flow, then press ENTER.
`-email` / `-password`	Logs in with email and password.
`-cookie` / `-cookie-name`	Sets a session cookie directly (cookie name defaults to `Fleet-Session`).
`-login`	Re-authenticate interactively (opens a visible browser).
(no auth flag)	Reuses the saved session from a previous run.

Usage

Run the built-in full workflow

Captures all major Fleet pages (dashboard, hosts, queries, policies, software, controls, settings, account) including modals and tabs:

./screencap https://fleet.example.com

Or with authentication:

./screencap -sso https://fleet.example.com
./screencap -email admin@example.com -password secret https://fleet.example.com

Run a saved workflow

./screencap -workflow my-flow https://fleet.example.com

Record a custom workflow

Opens a visible browser where you click through the pages you want to capture. Clicks, radio buttons, checkboxes, tabs, and tooltip hovers are recorded automatically.

./screencap -record my-flow https://fleet.example.com

During recording:

Browse around in the browser window
Press ENTER to save a screenshot step (optionally type a name first)
Type done to finish and save the workflow

Workflow files are saved as JSON in the workflows/ directory and can be committed to the repo.

List saved workflows

./screencap -list

Additional flags

Flag	Default	Description
`-wait-time-seconds`	`6`	Seconds to wait for each page to load before capturing.
`-workflows-dir`	(repo `tools/screencap/workflows/`)	Override the directory used to read/write workflows.
`-insecure`	`false`	Ignore TLS certificate errors (use only for self-signed/dev certs).

Output

Screenshots are saved to screenshots/<timestamp>-<workflow>-<host>/ as numbered PNG files. Each page produces one or more images (one per viewport height if the page scrolls), and modals/tabs get their own files.

Example output structure:

screenshots/2026-03-11_113840-full-fleet.example.com/
  dashboard-1.png
  dashboard-modal-add-hosts-1.png
  dashboard-modal-add-hosts-macos-1.png
  hosts-manage-1.png
  hosts-manage-2.png
  ...