George KarrandLuke Heath
51da3581e6
## 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 --> [](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>
105 lines
3.1 KiB
Markdown
105 lines
3.1 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
cd tools/screencap
|
|
make build
|
|
```
|
|
|
|
This produces a `screencap` binary in the current directory.
|
|
|
|
To remove the binary:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
./screencap https://fleet.example.com
|
|
```
|
|
|
|
Or with authentication:
|
|
|
|
```bash
|
|
./screencap -sso https://fleet.example.com
|
|
./screencap -email admin@example.com -password secret https://fleet.example.com
|
|
```
|
|
|
|
### Run a saved workflow
|
|
|
|
```bash
|
|
./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.
|
|
|
|
```bash
|
|
./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
|
|
|
|
```bash
|
|
./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
|
|
...
|
|
```
|