fetch is a Go command-line API testing tool. It reads YAML/TOML/JSON-style case files, builds HTTP requests, runs them through the fetch run Cobra command, and verifies responses with assertions for status, headers, cookies, body content, JSON, HTML, XML, YAML, TOML, redirects, and errors.
The main entrypoint is main.go, CLI commands live in cmd/, and most implementation code lives under pkg/:
pkg/config: case, request, assertion, config-file parsing, and template rendering hooks.pkg/client: HTTP request execution helpers.pkg/assert: primitive assertion operators used by response assertions.pkg/assertion: response-specific assertion implementations.pkg/tpl,pkg/util,pkg/log,pkg/version: shared support packages.examples/: executable case files used as reference material.docs/: Jekyll documentation site.
- Use Go 1.26 or newer for normal development;
go.moddeclaresgo 1.26andtoolchain go1.26.4. - Install formatting tools:
make init
- Download module dependencies without vendoring:
go mod download
- Sync vendored dependencies for the Makefile test command:
go mod vendor
- Full dependency maintenance, when intentionally changing dependencies:
make dep
vendor/ is ignored by git, but make test uses -mod=vendor, so a fresh checkout needs go mod vendor before the canonical test command will run.
- Build the CLI binary:
make build
- Run the CLI directly during development:
go run . --help go run . run examples/http_get.yaml
- Run the built binary against an example:
./fetch run examples/http_get.yaml
- Run with verbose output when inspecting request/response behavior:
./fetch run examples/http_get.yaml -v
- Run multiple cases in parallel:
./fetch run examples/http_*.yaml -p 5
The CLI is built with Cobra. Add or edit commands in cmd/, register them from init(), and keep command behavior close to the existing run, version, bootstrap, and generate files.
- Run the project test target:
make test - If
make testfails with an inconsistent vendoring error before tests run, refresh local vendoring first:go mod vendor make test - Run a focused package test while developing:
go test ./pkg/assert -run TestStartsWith - Run all packages without the Makefile coverage flags:
go test ./...
Most tests are standard Go testing table tests in *_test.go files. pkg/util also has a Ginkgo/Gomega suite. Add focused tests next to the package you change, and prefer behavior-oriented cases that exercise the public package function or CLI behavior being modified.
- Format Go code with the project formatter target:
make fmt
make fmtrunsgolineswith a 120-column limit and thengofumpt.- Keep package names short and aligned with the existing directory names.
- Keep new CLI flags and environment variables documented in
docs/Usage/command-line.mdwhen they affect users. - Do not introduce a new dependency if the standard library or an existing dependency already covers the need.
- If dependencies change, update
go.modandgo.sumwithgo mod tidy; only refreshvendor/locally unless the repository policy changes.
The documentation site is under docs/ and uses Jekyll with github-pages, just-the-docs, and docs/Gemfile.lock.
- Install the Bundler version required by the lockfile if your Ruby environment does not already have it:
gem install bundler:2.3.26
- Install docs dependencies:
bundle install
- Serve docs locally from
docs/:bundle exec jekyll serve
Update README examples, examples/, and docs/Usage/ together when changing user-visible case syntax or CLI behavior.
- Local binary build:
make build
- Docker image build:
docker build -t fetch . - Release automation is tag-driven in
.github/workflows/release.yml. - GoReleaser Homebrew tap settings are in
.goreleaser.yml. - GitHub Pages docs deploy from
.github/workflows/jekyll-gh-pages.ymlon pushes tomaster.
Keep the Dockerfile builder image, release workflow Go version, README, docs, and go.mod aligned when changing the Go version.
- Keep diffs narrow and directly tied to the requested change.
- Run
make fmtfor Go code changes. - Run
make testafter syncing localvendor/withgo mod vendor. - For docs-only changes, verify the relevant Markdown and Jekyll files; a Go test run is not required unless code or examples used by tests changed.
- For CLI behavior changes, update the corresponding docs and add or update an example case when useful.
- Do not fabricate commands, release behavior, or CI coverage. This repo has release and docs workflows, but no ordinary push/PR Go test workflow in
.github/workflows/. - Read existing code before editing; package boundaries are simple and should stay that way.
- Prefer small, direct changes over new abstractions.
- Preserve existing examples unless the requested change specifically updates case-file behavior.
- Treat
bootstrapandgenerateas placeholder Cobra commands unless the task is explicitly about them.