diff --git a/README.md b/README.md index c75708c..5a1997d 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,8 @@ # crawler -Playwright for TUIs via tmux. +Test TUIs through tmux. -A Go testing library for black-box testing of terminal user interfaces. -Tests run real binaries inside tmux sessions, send keystrokes, capture screen -output, and assert against it -- all through the standard `testing.TB` interface. +A Go testing library for black-box testing of terminal user interfaces. Tests run binaries inside tmux sessions, send keystrokes, capture screen output, and assert against it. Uses the standard `testing.TB` interface. ## Quick start @@ -104,7 +102,7 @@ term.WaitFor(crawler.Text("Done"), crawler.WithWaitPollInterval(100*time.Millise On timeout, `WaitFor` calls `t.Fatal` with a diagnostic message showing what was expected and the most recent screen captures: -``` +```text terminal_test.go:42: crawler: wait-for: timed out after 5s waiting for: screen to contain "Loading complete" recent screen captures (oldest to newest): @@ -130,17 +128,17 @@ terminal_test.go:42: crawler: wait-for: timed out after 5s ### Built-in matchers -| Matcher | Description | -|---------|-------------| -| `Text(s)` | Screen contains substring | -| `Regexp(pattern)` | Screen matches regex | -| `Line(n, s)` | Row n equals s (trailing spaces trimmed) | -| `LineContains(n, s)` | Row n contains substring | -| `Not(m)` | Inverts a matcher | -| `All(m...)` | All matchers must match | -| `Any(m...)` | At least one matcher must match | -| `Empty()` | Screen has no visible content | -| `Cursor(row, col)` | Cursor is at position | +| Matcher | Description | +| -------------------- | ---------------------------------------- | +| `Text(s)` | Screen contains substring | +| `Regexp(pattern)` | Screen matches regex | +| `Line(n, s)` | Row n equals s (trailing spaces trimmed) | +| `LineContains(n, s)` | Row n contains substring | +| `Not(m)` | Inverts a matcher | +| `All(m...)` | All matchers must match | +| `Any(m...)` | At least one matcher must match | +| `Empty()` | Screen has no visible content | +| `Cursor(row, col)` | Cursor is at position | ### Snapshot testing @@ -199,6 +197,7 @@ func TestNavigation(t *testing.T) { ## Documentation +- [Package reference](https://pkg.go.dev/github.com/cboone/crawler) -- full API on pkg.go.dev - [Getting started](docs/GETTING-STARTED.md) -- first-test tutorial - [Matchers in depth](docs/MATCHERS.md) -- all built-in matchers, composition, and custom matchers - [Snapshot testing](docs/SNAPSHOTS.md) -- golden-file testing guide @@ -213,6 +212,7 @@ func TestNavigation(t *testing.T) { - **OS**: Linux, macOS, or any Unix-like system where tmux runs The tmux binary is located by checking, in order: + 1. `WithTmuxPath` option 2. `CRAWLER_TMUX` environment variable 3. `$PATH` lookup @@ -223,7 +223,7 @@ Each test gets its own tmux server via a unique socket path under `os.TempDir()` All operations (`capture-pane`, `send-keys`, `resize-window`) go through the `tmux` CLI. No cgo, no terminfo parsing, no terminal emulator reimplementation. -``` +```text Go test process +-------------------------------------------------+ | func TestFoo(t *testing.T) { | diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 30f60da..a00e538 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -4,7 +4,8 @@ How crawler works internally. This guide is for contributors and users who want to understand what happens behind the API. For API overview and usage examples, see the [README](../README.md). For -detailed function signatures, see `go doc github.com/cboone/crawler`. +detailed function signatures, see the [package documentation on pkg.go.dev](https://pkg.go.dev/github.com/cboone/crawler) +or run `go doc github.com/cboone/crawler`. ## Why tmux diff --git a/docs/GETTING-STARTED.md b/docs/GETTING-STARTED.md index 8435a3b..50affde 100644 --- a/docs/GETTING-STARTED.md +++ b/docs/GETTING-STARTED.md @@ -2,7 +2,8 @@ This guide walks you through writing and running your first crawler test. For a concise API overview, see the [README](../README.md). For detailed function -signatures, see `go doc github.com/cboone/crawler`. +signatures, see the [package documentation on pkg.go.dev](https://pkg.go.dev/github.com/cboone/crawler) +or run `go doc github.com/cboone/crawler`. ## Prerequisites diff --git a/docs/MATCHERS.md b/docs/MATCHERS.md index 3c71f16..b404e4d 100644 --- a/docs/MATCHERS.md +++ b/docs/MATCHERS.md @@ -5,7 +5,8 @@ or `WaitForScreen` takes a matcher that is polled against screen captures until it succeeds or the timeout expires. For the API overview table, see the [README](../README.md). For function -signatures, see `go doc github.com/cboone/crawler`. +signatures, see the [package documentation on pkg.go.dev](https://pkg.go.dev/github.com/cboone/crawler) +or run `go doc github.com/cboone/crawler`. ## How matchers work diff --git a/docs/PATTERNS.md b/docs/PATTERNS.md index 5fe31a9..1191664 100644 --- a/docs/PATTERNS.md +++ b/docs/PATTERNS.md @@ -4,7 +4,8 @@ A cookbook of common TUI testing scenarios with complete examples. Each recipe is self-contained. For API details, see the [README](../README.md) and -`go doc github.com/cboone/crawler`. +the [package documentation on pkg.go.dev](https://pkg.go.dev/github.com/cboone/crawler) +or run `go doc github.com/cboone/crawler`. ## Basic interaction: Type / Press / WaitFor diff --git a/docs/SNAPSHOTS.md b/docs/SNAPSHOTS.md index b8ea64d..c248d46 100644 --- a/docs/SNAPSHOTS.md +++ b/docs/SNAPSHOTS.md @@ -6,7 +6,8 @@ assertions for each piece of text, you capture the entire screen and compare it against a committed file. For API overview and usage examples, see the [README](../README.md). For -detailed function signatures, see `go doc github.com/cboone/crawler`. +detailed function signatures, see the [package documentation on pkg.go.dev](https://pkg.go.dev/github.com/cboone/crawler) +or run `go doc github.com/cboone/crawler`. ## When to use snapshots diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index 7830e2a..60d1ba2 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -3,7 +3,8 @@ Debugging test failures, fixing common problems, and setting up CI. For API overview and usage examples, see the [README](../README.md). For -detailed function signatures, see `go doc github.com/cboone/crawler`. +detailed function signatures, see the [package documentation on pkg.go.dev](https://pkg.go.dev/github.com/cboone/crawler) +or run `go doc github.com/cboone/crawler`. ## tmux not found