test(cli): cover browse screenshot default-path reservation and cleanup

[yawbtng]

why

browse screenshot's default-path behavior (added in #2246 — write a file by default, advance a collision counter instead of overwriting, clean up the reserved placeholder if capture fails) shipped without any tests. driver-commands.test.ts only asserts the command name is registered.

what changed

Adds tests/screenshot-default-path.test.ts covering the three helpers in src/commands/screenshot.ts:

• getDefaultPathFromFlags — --path and --base64 both opt out of a reserved default; a bare invocation reserves a .png (and .jpeg with --type jpeg).
• reserveDefaultScreenshotPath — advances the -N collision counter instead of overwriting an existing file (fake-timer-pinned timestamp so the collision is deterministic).
• removeIfEmpty — deletes the zero-byte placeholder from a failed capture, keeps a file that already has bytes, and no-ops when the path is already gone.

Test-only, plus a one-line export on each of the three helpers so they can be unit-tested directly. This matches the existing convention of importing pure driver functions from src/ in tests (e.g. driver-commands.test.ts imports resolveSelector, formatSnapshotTree, runtimeHandlers). Happy to relocate the helpers into src/lib/ instead if you'd prefer them out of the command file.

testing

vitest run tests/screenshot-default-path.test.ts → 8 passing. Adjacent suites (driver-commands, cli-surface) still green; tsc -p tsconfig.json clean.

---

Summary by cubic

Add tests for the browse screenshot default-path behavior: reserve a file by default, increment -N on collisions, and clean up empty placeholders on failure. Exported helpers to allow direct unit testing.

• Refactors
  • Exported getDefaultPathFromFlags, reserveDefaultScreenshotPath, and removeIfEmpty from src/commands/screenshot.ts for testability.

^{Written for commit 3042188. Summary will update on new commits.}

[changeset-bot]

⚠️ No Changeset found

Latest commit: 3042188

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[github-actions]

This PR is from an external contributor and must be approved by a stagehand team member with write access before CI can run.
Approving the latest commit mirrors it into an internal PR owned by the approver.
If new commits are pushed later, the internal PR stays open but is marked stale until someone approves the latest external commit and refreshes it.

[cubic-dev-ai]

No issues found across 2 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Architecture diagram

sequenceDiagram
    participant User as CLI User
    participant Cmd as Screenshot Command
    participant Flags as getDefaultPathFromFlags
    participant Reserve as reserveDefaultScreenshotPath
    participant FS as File System
    participant Clean as removeIfEmpty

    User->>Cmd: stagehand browse screenshot
    Cmd->>Flags: call with flags object

    alt No --path, no --base64 (default path needed)
        Flags->>Flags: pick extension (.png / .jpeg) from --type
        Flags->>Reserve: get unique default path
        Reserve->>FS: O_EXCL open(timestamped-name)
        alt File exists (collision)
            Reserve->>Reserve: increment counter, try "-N" variant
            Reserve->>FS: O_EXCL open(next name)
        end
        FS-->>Reserve: placeholder file created (0 bytes)
        Reserve-->>Flags: reserved path string
        Flags-->>Cmd: default path
    else --path or --base64 set
        Flags-->>Cmd: undefined (no default needed)
    end

    Cmd->>FS: driver captures screenshot (writes file)
    alt Capture succeeds
        FS-->>Cmd: file has non-zero bytes → keep
    else Capture fails
        Cmd->>Clean: call removeIfEmpty(path)
        Clean->>FS: statSync(path)
        alt File exists and size === 0
            Clean->>FS: unlinkSync(path)
        else File has bytes or missing
            Clean->>Clean: no‑op
        end
        FS-->>Clean: placeholder removed (if empty)
        Clean-->>Cmd: done
    end

Loading

_{Re-trigger cubic}