docs: add readme and license files

Author: fiffeek

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Filip Mikina
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,230 @@
+# Teastraw
+
+A Go package for end-to-end testing of Terminal User Interface (TUI) applications.
+
+## Overview
+
+`Teastraw` provides a test runner that can interact with TUI applications by:
+- Starting your TUI application in a pseudo-terminal (PTY)
+- Sending keyboard input and terminal events
+- Capturing and validating screen output
+- Managing application lifecycle and graceful shutdown
+
+## Installation
+
+```bash
+go get github.com/fiffeek/teastraw
+```
+
+## Quick Start
+
+The following example uses `stretchr/testify` for clarity, however, `teastraw` does not make
+any assumptions about the testing library. You get raw errors and can decide yourself what "failing" the test
+means exactly.
+
+Here's a simple example of testing a list-based TUI application:
+
+```go
+package main
+
+import (
+    "bytes"
+    "context"
+    "os"
+    "os/exec"
+    "testing"
+    "time"
+
+    "github.com/fiffeek/teastraw/pkg/exp"
+    "github.com/stretchr/testify/assert"
+    "github.com/stretchr/testify/require"
+)
+
+func TestMyTUIApp(t *testing.T) {
+    ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
+    defer cancel()
+
+    // Create command to run your TUI application
+    cmd := exec.CommandContext(ctx, "./my-tui-app")
+    cmd.Env = append(os.Environ(), "NO_COLOR=1") // Disable colors for consistent testing
+
+    // Create test runner with terminal dimensions
+    runner, err := exp.NewTestRunner(
+        exp.WithInitialTermSize(80, 24), // width, height
+        exp.WithCommand(cmd),
+    )
+    require.NoError(t, err)
+
+    // Start the application
+    require.NoError(t, runner.Start())
+
+    // Wait for initial screen to load
+    err = runner.WaitFor(func(screen []byte) bool {
+        return bytes.Contains(screen, []byte("Welcome"))
+    }, exp.WithCheckInterval(50*time.Millisecond), exp.WithDuration(200*time.Millisecond))
+    assert.NoError(t, err)
+
+    // Send keyboard input
+    assert.NoError(t, runner.Send([]byte("j"))) // Move down
+
+    // Wait for screen to update
+    err = runner.WaitFor(func(screen []byte) bool {
+        return bytes.Contains(screen, []byte("Item 2"))
+    }, exp.WithCheckInterval(50*time.Millisecond), exp.WithDuration(200*time.Millisecond))
+    assert.NoError(t, err)
+
+    // Capture current screen state
+    screen := runner.ScreenNow()
+    // Validate screen content...
+
+    // Send quit command
+    assert.NoError(t, runner.Send([]byte("\x03"))) // Ctrl+C
+
+    // Get final screen before exit
+    finalScreen, err := runner.FinalScreen(exp.WithFinalTimeout(500*time.Millisecond))
+    assert.NoError(t, err)
+
+    // Validate output.
+    // Run the tests with `-update` to create the golden file.
+    exp.RequireEqualSubtest(t, []byte(finalScreen), "__final_screen")
+
+    // Get complete output history
+    output, err := runner.FinalOutput()
+    assert.NoError(t, err)
+    // Validate output...
+}
+```
+
+## Key Features
+
+### Screen Validation
+
+Capture and validate screen content at any point:
+
+```go
+// Get current screen state
+screen := runner.ScreenNow()
+
+// Use golden file testing for screen validation
+exp.RequireEqualSubtest(t, screen, "expected_screen_state")
+```
+
+### Waiting for Conditions
+
+Wait for specific content to appear on screen:
+
+```go
+err := runner.WaitFor(func(screen []byte) bool {
+    return bytes.Contains(screen, []byte("Loading complete"))
+}, exp.WithCheckInterval(10*time.Millisecond), exp.WithDuration(1*time.Second))
+```
+
+### Input Simulation
+
+Send various types of input:
+
+```go
+// Send regular keys
+runner.Send([]byte("hello"))
+
+// Send special keys
+runner.Send([]byte("\x03"))  // Ctrl+C
+runner.Send([]byte("\r"))    // Enter
+runner.Send([]byte("\x1b[A")) // Up arrow
+```
+
+> [!CAUTION]
+> It is recommended to grab output after each key press to let the app process it correctly,
+> see [run_test.go](https://github.com/fiffeek/teastraw/blob/main/test/run_test.go#L140) example.
+
+
+### Graceful Shutdown
+
+Capture final state before application exits:
+
+```go
+// Get the last screen before exit
+finalScreen, err := runner.FinalScreen(exp.WithFinalTimeout(500*time.Millisecond))
+
+// Get complete output history
+allOutput, err := runner.FinalOutput()
+```
+
+## Configuration Options
+
+### Terminal Size
+
+```go
+runner, err := exp.NewTestRunner(
+    exp.WithInitialTermSize(120, 30), // Custom terminal dimensions
+    exp.WithCommand(cmd),
+)
+```
+
+### Exit Sequences
+
+For applications with specific exit sequences:
+
+```go
+runner, err := exp.NewTestRunner(
+    exp.WithExitSequences([]string{"\x1b[?1049l"}), // Clear alternate screen
+    exp.WithCommand(cmd),
+)
+
+[A few common ones](https://github.com/fiffeek/teastraw/blob/main/pkg/exp/const.go#L3) are passed by default, you can also refer to them in your code.
+```
+
+## Testing Patterns
+
+### Golden File Testing
+
+Teastraw includes utilities for golden file testing to validate screen output against known good states:
+
+```go
+// This will create/update golden files in testdata/
+exp.RequireEqualSubtest(t, screenOutput, "test_name")
+```
+
+If you prefer to handle errors yourself (e.g. do not fail a test when it doesn't match),
+you can use `exp.IsEqualToFixture` (`exp.RequireEqualSubtest` is just a wrapper).
+
+### Time-based Testing
+
+Set appropriate timeouts for your application's responsiveness:
+
+```go
+// Quick interactions
+exp.WithDuration(100*time.Millisecond)
+
+// Slower operations
+exp.WithDuration(2*time.Second)
+```
+
+## Examples
+
+See the `test/` directory for complete working examples of testing different types of TUI applications.
+
+## Comparison to Teatest
+
+Bubble Tea provides an experimental test framework called [teatest](https://github.com/charmbracelet/x/tree/main/exp/teatest). While `teastest` is great for testing your Bubble Tea models directly, `teastraw` takes a different approach by testing your complete TUI application end-to-end.
+
+Key differences:
+- **teatest**: Tests your Bubble Tea model in isolation (unit/integration testing)
+- **teastraw**: Tests your compiled binary as a black box (end-to-end testing)
+
+With `teatest`, you interact directly with your model, but external dependencies need to be mocked. With `teastraw`, you can test the real application behavior including CLI arguments, environment variables, file system interactions, and any other external integrations your app uses.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+[See LICENSE](./LICENSE)
+
+## Credits
+
+The code was modeled and adapted from:
+- [charmbracelet's `x/exp/golden`](https://github.com/charmbracelet/x/tree/main/exp/golden)
+- [charmbracelet's `x/exp/teatest`](https://github.com/charmbracelet/x/tree/main/exp/teatest)
+- [bubbletea's examples](https://github.com/charmbracelet/bubbletea/tree/main/examples) in `./bin`