go-api-test-runner

I wanted a simple way to run API smoke tests without pulling in a full testing framework or clicking through Postman. The goal was to have just a YAML config file and run the tests in CI with a single command.

---

Usage

go run . --file testdata/example.yaml

Flags:

Flag	Default	Description
--file	testdata/example.yaml	Path to your YAML test suite
--parallel	1	How many tests to run concurrently
--verbose	false	Show passing assertions, not just failures

Example:

go run . --file my_suite.yaml --parallel 4 --verbose

Exits 0 if all tests pass, 1 if any fail

---

Writing tests

Create a YAML file with a name for the suite and a list of tests:

name: User API

tests:
  - name: Get user returns 200
    method: GET
    url: https://api.example.com/users/1
    headers:
      Authorization: "Bearer ${API_TOKEN}"
    assert:
      status: 200
      headers:
        Content-Type: application/json
      body_contains:
        - email
      json_path:
        - path: id
          expected: 1
        - path: role
          expected: admin
      max_response_ms: 500

  - name: Create user returns 201
    method: POST
    url: https://api.example.com/users
    headers:
      Content-Type: application/json
    body: |
      {"name": "Alice", "email": "alice@example.com"}
    assert:
      status: 201
      json_path:
        - path: name
          expected: Alice

Supported assertions:

Key	What it checks
status	HTTP status code
headers	Response header key/value pairs
body_contains	List of substrings that must appear in the body
body_matches	List of regexes that must match the body
json_path	Dot-notation path + expected value (e.g. data.items.0.id)
max_response_ms	Response must arrive within this many milliseconds

Environment variables: any ${VAR} in your YAML is substituted from the environment at load time, so you can keep secrets out of the file:

API_TOKEN=my-secret go run . --file suite.yaml

---

Running tests

go test ./...

The unit tests don't make any network calls as the runner tests use a stub executor.

---

Getting started

brew install go       # if you don't have Go
go mod tidy
go test ./...
go run . --verbose