feature/build crawler #3
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Owner
cboone
commented
Feb 6, 2026
cboone
commented
- feat: implement crawler library (Phases 1-3)
- docs: add README with usage guide and CLAUDE.md with project context
- feat: complete phase 3 polish
- docs: add plan for comprehensive documentation guides
- docs: complete plan
- docs: refine comprehensive docs plan
- docs: add comprehensive documentation guides
- docs: rename guide files to all caps
- docs: sync comprehensive guides with current behavior
Implement the full crawler TUI testing library as specified in PLAN.md. Zero third-party Go dependencies; uses only the standard library and the tmux CLI for terminal session management. Core API: Open, Terminal, Screen, SendKeys, Type, Press, WaitFor, WaitForScreen, WaitExit, Resize, Scrollback, MatchSnapshot. Matchers: Text, Regexp, Line, LineContains, Not, All, Any, Empty, Cursor. Options: WithArgs, WithSize, WithEnv, WithDir, WithTimeout, WithPollInterval, WithTmuxPath, WithHistoryLimit. Includes 35 integration tests with a 25-subtest parallel stress test validating complete session isolation.
Create 6 standalone guides in docs/ covering getting started, matchers, snapshot testing, recipes/patterns, troubleshooting, and architecture. Link them from a new Documentation section in the root README.
There was a problem hiding this comment.
Pull request overview
This PR introduces the initial implementation of the crawler Go library for black-box TUI testing via tmux, plus extensive documentation and CI setup to support usage and ongoing development.
Changes:
- Implement core
crawlerAPI (Open, input, waits, screen capture, scrollback, snapshots) backed by tmux + an internal tmux CLI runner. - Add integration tests + a fixture TUI binary for end-to-end verification.
- Add README, godoc, and comprehensive guides under
docs/, plus GitHub Actions CI.
Reviewed changes
Copilot reviewed 25 out of 26 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
crawler.go |
Core public API: session lifecycle, waits, capture, resize, scrollback, diagnostics. |
tmux.go |
tmux adapter utilities: path/version resolution, socket path generation, pane operations. |
options.go |
Functional options / wait options and defaults. |
screen.go |
Immutable Screen capture type and helpers. |
match.go |
Built-in matchers and composition helpers. |
keys.go |
Key constants and Ctrl/Alt helpers. |
snapshot.go |
Golden-file snapshot testing + update workflow (CRAWLER_UPDATE). |
internal/tmuxcli/tmuxcli.go |
Internal tmux command runner abstraction + version + session readiness polling. |
internal/tmuxcli/tmuxcli_test.go |
Tests for the internal tmux CLI runner. |
internal/testbin/main.go |
Fixture TUI program used by integration tests. |
crawler_test.go |
End-to-end integration tests for the library. |
example_test.go |
Package examples for godoc. |
doc.go |
Package-level documentation describing behavior and requirements. |
README.md |
User-facing overview, API guide, and links to docs. |
docs/GETTING-STARTED.md |
Tutorial-style onboarding guide. |
docs/MATCHERS.md |
Detailed matcher documentation and custom matcher examples. |
docs/SNAPSHOTS.md |
Snapshot testing guide and update workflow. |
docs/PATTERNS.md |
Common recipes/patterns for TUI testing. |
docs/TROUBLESHOOTING.md |
Troubleshooting + CI setup guidance. |
docs/ARCHITECTURE.md |
Internal architecture explanation for contributors. |
docs/plans/todo/add-comprehensive-docs.md |
Planning doc for docs expansion (todo). |
docs/plans/done/PLAN.md |
Updated implementation plan checklist (done). |
.github/workflows/ci.yml |
CI workflow running tests on Linux/macOS and installing tmux. |
go.mod |
Initializes module and sets Go version. |
go.sum |
Dependency checksum file (currently empty). |
CLAUDE.md |
Project context, structure, and conventions for contributors. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Fix WithEnv to actually append environment variables as documented instead of overwriting on each call. Refactor waitForInternal to reuse captureScreenRaw, eliminating duplicated screen capture logic.
Document project-specific patterns that Copilot should not flag: internal API defensive checks, tmux format string output parsing, and functional option validation timing.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 26 out of 27 changed files in this pull request and generated 5 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Remove unused setSessionEnv helper, fix Windows docs wording, and update Copilot instructions for incorrect feedback.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 26 out of 27 changed files in this pull request and generated 5 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- README: clarify that Open starts a dedicated tmux server, not just a session - crawler_test: remove unnecessary time.Sleep in TestResize; WaitFor handles timing - tmuxcli: fix doc comments to say "standard output" not "combined stdout" - screen/match: use sentinel values (-1) for cursor position so Cursor(0,0) does not false-positive when display-message fails - CLAUDE.md: document cursor position as best-effort, matching implementation
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 26 out of 27 changed files in this pull request and generated 5 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Clarify doc.go: clamping/validation applies to per-call overrides only - Fix generateSocketPath to surface non-IsNotExist os.Stat errors - Replace fixed sleep with polling loop in TestScrollback - Update Copilot instructions for terminal-level option validation
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 26 out of 27 changed files in this pull request and generated no new comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.