tapir

README

Tapir – Test API Runner

Automated API tests in a single YAML file, executed from a sleek terminal UI.

---

Table of Contents

• Tapir – Test API Runner
  • Table of Contents
  • Overview
  • Features
  • Installation
  • Quick Start
  • Command Reference
  • YAML Suite Format
  • Interactive TUI Shortcuts
  • Building from Source
  • Contributing
  • License

---

Overview

Tapir is a Go‑based CLI that reads a YAML test‑suite file, fires HTTP requests in sequence, checks the responses (status, headers, body, timing …) and displays the results in a Bubble Tea terminal UI. Results can be exported to Markdown or refreshed on demand – perfect for CI pipelines and local development.

---

Features

• YAML‑driven tests – no code required; edit & commit your specs.
• Assertions engine – validate status code, JSON fields, headers and response time.
• Interactive TUI – coloured table of results with keyboard shortcuts.
• One‑key export – press p to save a styled Markdown report.
• Hot reload – press r to rerun the whole suite and update the table (1‑second cool‑down).
• Schema validation – tapir validate <file> ensures your YAML matches the expected format.
• Sample generator – tapir generate example.yaml creates a starter suite.
• Configurable HTTP client – shared transport, global timeout flag.

---

Installation

# Requires Go 1.22+

# Install the latest released binary
go install github.com/IsmailCLN/tapir/cmd/tapir@latest

# Or clone and build from source
 git clone https://github.com/IsmailCLN/tapir.git
 cd tapir && go build -o tapir ./cmd

The resulting tapir binary can be copied anywhere in your $PATH.

---

Quick Start

# Run a suite and open the TUI
 tapir run test-data/test.yaml

# Validate a file without executing requests
 tapir validate my-suite.yaml

# Generate a starter file
 tapir generate example.yaml

While the TUI is open you can press p to export a Markdown report, r to reload, c to copy and q to quit.

---

Command Reference

Command	Description
tapir run <file>	Execute the test suite in file and show the interactive report.
tapir validate <file>	Check file against Tapir schema – returns non‑zero on error.
tapir generate <file>	Write a minimal example suite to file.

Global flags:

--timeout   HTTP timeout per request (default 10s)
--verbose   Print request/response details to stdout while running

---

YAML Suite Format

- suite_name: finance
  requests:
    - name: btcusdt_price
      request:
        method: GET
        url: https://api.binance.com/api/v3/ticker/price?symbol=BTCUSDT
      expect:
        - expectation_type: expect_number_to_be_between
          kwargs: { column: price, min: 100, max: 20000 }        
        - expectation_type: expect_number_to_be_between
          kwargs: { column: price, min: 100 }
        - expectation_type: expect_status_code_between
          kwargs:
            min: 300
            max: 499        
        - expectation_type: expect_status_code_equals
          kwargs:
            code: 200

See test-data/test.yaml for a complete example.

---

Interactive TUI Shortcuts

Key	Action
q	Quit Tapir
p	Print report to tapir-report-YYYYMMDD.md
c	Copy report to clipboard (if OS supported)
r	Reload the entire suite (blocked if pressed again within 1 second → "Refresh requests too frequent.")

---

Building from Source

# Clone repository
 git clone https://github.com/IsmailCLN/tapir.git
 cd tapir

# Run tests
 go test ./...

# Build for your platform
 go build -o tapir ./cmd

To cross‑compile:

GOOS=linux  GOARCH=amd64 go build -o tapir-linux  ./cmd
GOOS=darwin GOARCH=arm64 go build -o tapir-mac    ./cmd

---

Contributing

Pull requests are welcome – please open an issue first to discuss what you would like to change. Make sure go vet ./... and go test ./... pass before submitting.

---

License

Tapir is released under the MIT License. See LICENSE for details.