Testing - TUIOS

Auto-generate your docs

Running Tests
Run All Tests
Run Tests in Specific Package
Verbose Output
Run Specific Test
Short Mode
Race Detection
Run Specific Package with Race Detection
Benchmarks
Run Benchmarks
Benchmark Specific Package
Benchmark with Memory Stats
Run Specific Benchmark
Compare Benchmarks
Test Coverage
Generate Coverage Report
Detailed Coverage
Coverage for Specific Package
Writing Tests
Test File Structure
Table-Driven Tests
Subtests
Test Helpers
Example Tests
Tape Script Testing
Validate Tape Files
Run Tape Scripts
List Available Tapes
Create Test Tapes
Manual Testing Checklist
Window Management
Workspaces
Tiling Mode
Copy Mode
Terminal Functionality
Daemon Mode
SSH Server Mode
Tape Recording
Configuration
Performance
Cross-Platform (if applicable)
Debugging Tests
Print Debug Info
Skip Tests
Test Timeout
Parallel Tests
Continuous Integration
CI Runs
Test Locally Like CI
Next Steps

This guide covers testing TUIOS, including running the test suite, writing new tests, and performing manual testing.

Running Tests

Run All Tests

Run the complete test suite:

go test ./...

This runs all tests in all packages under the current directory.

Run Tests in Specific Package

Test a specific package:

# Test tape scripting package
go test ./internal/tape/...

# Test configuration package
go test ./internal/config/...

# Test VT emulation
go test ./internal/vt/...

Verbose Output

See detailed test output:

go test -v ./...

Run Specific Test

Run a single test by name:

go test -v ./internal/tape -run TestLexerBasicTokens

Use regex patterns to match multiple tests:

# Run all lexer tests
go test -v ./internal/tape -run TestLexer

# Run all tests containing "Parser"
go test -v ./... -run Parser

Short Mode

Skip slow tests:

go test -short ./...

Mark slow tests in your code:

func TestSlowOperation(t *testing.T) {
    if testing.Short() {
        t.Skip("skipping slow test in short mode")
    }
    // test code
}

Race Detection

Detect race conditions in concurrent code:

go test -race ./...

Race detection adds significant overhead. Tests run much slower but catch race conditions.

Run Specific Package with Race Detection

go test -race ./internal/terminal/...
go test -race ./internal/app/...

Always run with -race when testing concurrent code (PTY handling, goroutines, channels).

Benchmarks

Run Benchmarks

Run performance benchmarks:

go test -bench=. ./...

Benchmark Specific Package

go test -bench=. ./internal/app/...
go test -bench=. ./internal/vt/...

Benchmark with Memory Stats

See memory allocations:

go test -bench=. -benchmem ./internal/app/...

Run Specific Benchmark

go test -bench=BenchmarkStyleCache ./internal/app/...

Compare Benchmarks

Compare performance before and after changes:

# Save baseline
go test -bench=. ./internal/app/... > old.txt

# Make changes, then compare
go test -bench=. ./internal/app/... > new.txt
go install golang.org/x/perf/cmd/benchstat@latest
benchstat old.txt new.txt

Test Coverage

Generate Coverage Report

go test -cover ./...

Detailed Coverage

Generate HTML coverage report:

go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

This opens a browser showing which lines are covered.

Coverage for Specific Package

go test -coverprofile=coverage.out ./internal/tape/...
go tool cover -html=coverage.out

Writing Tests

Test File Structure

Place test files alongside the code they test:

internal/tape/
├── lexer.go
├── lexer_test.go
├── parser.go
└── parser_test.go

Name test files with _test.go suffix.

Table-Driven Tests

Use table-driven tests for multiple test cases:

package example

import "testing"

func TestAdd(t *testing.T) {
    tests := []struct {
        name     string
        a, b     int
        expected int
    }{
        {"positive", 2, 3, 5},
        {"negative", -1, -2, -3},
        {"zero", 0, 5, 5},
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            result := Add(tt.a, tt.b)
            if result != tt.expected {
                t.Errorf("Add(%d, %d) = %d; want %d",
                    tt.a, tt.b, result, tt.expected)
            }
        })
    }
}

Subtests

Use t.Run() for subtests:

func TestFeature(t *testing.T) {
    t.Run("basic case", func(t *testing.T) {
        // test code
    })

    t.Run("edge case", func(t *testing.T) {
        // test code
    })
}

Test Helpers

Create helper functions for common setup:

func setupTest(t *testing.T) (*State, func()) {
    t.Helper()
    state := NewState()
    cleanup := func() {
        state.Close()
    }
    return state, cleanup
}

func TestSomething(t *testing.T) {
    state, cleanup := setupTest(t)
    defer cleanup()
    // test code
}

Example Tests

Write example tests that appear in godoc:

func ExampleParse() {
    result := Parse("hello")
    fmt.Println(result)
    // Output: hello
}

Tape Script Testing

TUIOS includes tape scripting for automated testing.

Validate Tape Files

Check tape syntax:

tuios tape validate examples/demo.tape

Run Tape Scripts

Execute tape scripts:

# Headless mode (background)
go run ./cmd/tuios tape run examples/demo.tape

# Interactive mode (visible TUI)
go run ./cmd/tuios tape play examples/demo.tape

List Available Tapes

tuios tape list

Create Test Tapes

Write .tape files for automated testing:

# Test window creation
NewWindow
Sleep 100ms

# Test typing
Type "echo test"
Enter
Sleep 200ms

# Test workspace switching
Ctrl+B
Type "w"
Type "2"
Sleep 100ms

# Close window
Ctrl+B
Type "x"

Place test tapes in examples/ or testdata/ directories.

Manual Testing Checklist

When making changes to TUIOS, test these core features:

Window Management

Workspaces

Switch workspace (Alt+1 through Alt+9)
Move window to workspace (Ctrl+B w then workspace number)
Create windows in different workspaces
Workspace indicator shows current workspace

Tiling Mode

Toggle tiling (t key in window management mode)
Windows tile automatically
Create horizontal split (Ctrl+B -)
Create vertical split (Ctrl+B |)
Rotate split direction (Ctrl+B t r)
Equalize splits (Ctrl+B t e)
BSP preselection (Ctrl+B p + direction)

Copy Mode

Terminal Functionality

Daemon Mode

Create session (tuios new session1)
List sessions (tuios ls)
Attach to session (tuios attach session1)
Detach from session (Ctrl+B d)
Kill session (tuios kill-session session1)
State persists across detach/attach

SSH Server Mode

Start SSH server (tuios ssh)
Connect from client (ssh -p 2222 localhost)
Per-connection isolation works
Multiple clients can connect
Clean disconnect

Tape Recording

Configuration

Edit config (tuios config edit)
Custom keybindings work
Config reload without restart
Invalid config shows error

Performance

Create 10+ windows - smooth rendering
Switch workspaces - no lag
Fast output (cat large file) - stays responsive
Memory usage stays reasonable
No memory leaks over time

Cross-Platform (if applicable)

Linux - works correctly
macOS - works correctly
Windows - works correctly (WSL or native)
FreeBSD - works correctly

Debugging Tests

Print Debug Info

Add debug output:

t.Logf("value: %v", value)

Only prints when test fails or with -v flag.

Skip Tests

Temporarily skip a test:

t.Skip("temporarily disabled")

Test Timeout

Set test timeout:

go test -timeout 30s ./...

Default is 10 minutes.

Parallel Tests

Run tests in parallel:

func TestParallel(t *testing.T) {
    t.Parallel()
    // test code
}

Control parallelism:

go test -parallel 4 ./...

Continuous Integration

TUIOS uses GitHub Actions for CI:

CI Runs

All tests (go test ./...)
Race detection (go test -race ./...)
Linting (golangci-lint)
Build verification

Test Locally Like CI

Run the same checks CI runs:

# Run tests
go test ./...

# Run with race detection
go test -race ./...

# Check formatting
test -z "$(gofmt -s -l .)"

# Run linter (if installed)
golangci-lint run

Next Steps

Contributing Guide - Submit your changes
Building from Source - Build TUIOS locally
Architecture Guide - Understand the codebase

Building from Source

⌘I

Build docs developers (and LLMs) love

Get started for free Talk to us

Architecture

Contributing

Documentation Index

​Running Tests

​Run All Tests

​Run Tests in Specific Package

​Verbose Output

​Run Specific Test

​Short Mode

​Race Detection

​Run Specific Package with Race Detection

​Benchmarks

​Run Benchmarks

​Benchmark Specific Package

​Benchmark with Memory Stats

​Run Specific Benchmark

​Compare Benchmarks

​Test Coverage

​Generate Coverage Report

​Detailed Coverage

​Coverage for Specific Package

​Writing Tests

​Test File Structure

​Table-Driven Tests

​Subtests

​Test Helpers

​Example Tests

​Tape Script Testing

​Validate Tape Files

​Run Tape Scripts

​List Available Tapes

​Create Test Tapes

​Manual Testing Checklist

​Window Management

​Workspaces

​Tiling Mode

​Copy Mode

​Terminal Functionality

​Daemon Mode

​SSH Server Mode

​Tape Recording

​Configuration

​Performance

​Cross-Platform (if applicable)

​Debugging Tests

​Print Debug Info

​Skip Tests

​Test Timeout

​Parallel Tests

​Continuous Integration

​CI Runs

​Test Locally Like CI

​Next Steps

Build docs developers (and LLMs) love

Running Tests

Run All Tests

Run Tests in Specific Package

Verbose Output

Run Specific Test

Short Mode

Race Detection

Run Specific Package with Race Detection

Benchmarks

Run Benchmarks

Benchmark Specific Package

Benchmark with Memory Stats

Run Specific Benchmark

Compare Benchmarks

Test Coverage

Generate Coverage Report

Detailed Coverage

Coverage for Specific Package

Writing Tests

Test File Structure

Table-Driven Tests

Subtests

Test Helpers

Example Tests

Tape Script Testing

Validate Tape Files

Run Tape Scripts

List Available Tapes

Create Test Tapes

Manual Testing Checklist

Window Management

Workspaces

Tiling Mode

Copy Mode

Terminal Functionality

Daemon Mode

SSH Server Mode

Tape Recording

Configuration

Performance

Cross-Platform (if applicable)

Debugging Tests

Print Debug Info

Skip Tests

Test Timeout

Parallel Tests

Continuous Integration

CI Runs

Test Locally Like CI

Next Steps