Repolode
Submit
N4darae

N4darae/shrt

A regression testing harness that replays recorded API call chains against a backend, using human-approved baselines to catch changes between releases.

View on GitHub
Stars
2,460
Forks
169
Open issues
6
Last commit
12 days ago

What is it?

shrt tests a backend through chains of API calls defined in YAML, such as logging in, creating an item, adding stock and reading it back. A person approves a passing run as the baseline, and later releases are replayed against it. When a field changes, shrt reports the step, the field and the write it suspects.

A contract file describes what each rpc should require, where values come from, how it refuses bad input and how writes change numeric fields. shrt can generate chains from that contract, probing boundary values, missing or invalid tokens, unknown ids and duplicates. It speaks the Connect protocol over HTTP POST, so it works with servers built on connect-go; plain gRPC-only servers are not supported. Unary and server-streaming rpcs are handled, with streams read up to their first message.

The tool is written in Go and needs buf to compile .proto files. Credentials are read from environment variables and redacted from run records. It only sends requests to localhost unless the target host is listed in the config, and it is designed to be driven by a coding agent while every command also works by hand.

Key features

  • 01Chains of API calls are defined as YAML files and replayed on each release.
  • 02Human-approved baselines record response fields, including ones no assertion checks.
  • 03A contract file can generate probing chains covering boundaries, auth failures and duplicates.
  • 04Failures name the step, the changed field and the suspected write.
  • 05Requests are limited to localhost or explicitly allowed hosts to protect production data.
  • 06A CI gate command exits non-zero on failure.

Use cases

  • Catching regressions in a connect-go backend between releases.
  • Running API regression checks in CI against each new build.
  • Letting a coding agent write and maintain API test contracts under human review.

Quick start

  1. 1

    Install buf (the protobuf build tool shrt needs on PATH)

  2. 2

    Install shrt with Go 1.26 or later

    go install github.com/N4darae/shrt/cmd/shrt@latest
  3. 3

    Check the installed version

    shrt version
  4. 4

    Set up shrt in your backend project and check it

    shrt init

Things to know

  • Requires Go 1.26 or later and buf on PATH.
  • Only works with servers that speak the Connect protocol, not gRPC-only servers.
  • Streaming rpcs are read only up to the first message.
  • shrt init guesses which rpc is the login, so the result must be checked.

In collections

Open-source AI agent frameworks & appsTesting frameworks & test automation toolsMicroservice frameworks & service infrastructure

Topics

#testing#api-testing#regression-testing#go#connect-rpc#grpc#ci-cd#ai-agent

FAQ

What is shrt?
A regression testing harness that replays recorded API call chains against a backend, using human-approved baselines to catch changes between releases. shrt tests a backend through chains of API calls defined in YAML, such as logging in, creating an item, adding stock and reading it back. A person approves a passing run as the baseline, and later releases are replayed against it. When a field changes, shrt reports the step, the field and the write it suspects.
Is shrt free to use? What license does it have?
shrt is open source under the MIT license. Check the license terms before using it in commercial products.
Is shrt still maintained?
Actively maintained. The last commit to shrt was on Oct 26, 2026.
What can I use shrt for?
Catching regressions in a connect-go backend between releases. Running API regression checks in CI against each new build. Letting a coding agent write and maintain API test contracts under human review.
How do I install shrt?
Install buf (the protobuf build tool shrt needs on PATH) Install shrt with Go 1.26 or later: go install github.com/N4darae/shrt/cmd/shrt@latest Check the installed version: shrt version Set up shrt in your backend project and check it: shrt init
Where can I get shrt?
The source code and installation instructions are on GitHub: https://github.com/N4darae/shrt

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects