Screen Capture & Terminal Automation Guide

This guide explains how to use ZQK's built-in terminal automator and visual capture engine (pkg/screencap) to record automated terminal sessions, generate visual verification artifacts, and drive interactive CLI testing.

---

1. When to Use

1. Automated Documentation & Walkthroughs: Capture crisp screenshots of terminal commands, dashboards, and TUI outputs directly during CI or script runs.
2. Visual QA Verification: Fulfill visual evidence criteria (verification_matrix) by automating a sequence of user inputs and capturing window or screen state.
3. Animated Terminal Transcripts: Record millisecond-accurate timeline event logs for replay or SVG export.

---

2. Terminal Automation Engine (TerminalAutomator)

The TerminalAutomator wraps standard OS processes with interactive pseudo-terminal controls:

package main

import (
    "context"
    "time"

    "github.com/zqk-os/zqk/pkg/screencap"
)

func main() {
    capturer := screencap.NewMacCapturer()
    automator, err := screencap.NewTerminalAutomator(capturer, "zqk", "tui")
    if err != nil {
        panic(err)
    }

    if err := automator.Start(); err != nil {
        panic(err)
    }

    // Wait for TUI initialization
    ctx := context.Background()
    _ = automator.WaitForOutput("Dashboard", 5*time.Second)

    // Simulate user typing a key
    _ = automator.TypeCommand("q")

    // Snapshot
    _ = capturer.CaptureScreen(ctx, "dashboard.png")
}

---

3. Screen, Window, and Region Capture

The Capturer interface provides three granularity levels:

---

4. Platform Considerations

• macOS: Native implementation uses /usr/sbin/screencapture with -x flag (suppressing audio shutter clicks).
• Linux/X11/Wayland: Extensible via screencap.CommandRunner interface to wrap import (ImageMagick) or grim.
• Headless CI: When running in headless virtualized containers, ensure a virtual framebuffer (like xvfb) is configured if capturing GUI windows.