initial wip

Author: gangleri

.github/workflows/release.yml

@@ -0,0 +1,28 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+
+      - uses: goreleaser/goreleaser-action@v6
+        with:
+          version: latest
+          args: release --clean
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.goreleaser.yaml

@@ -0,0 +1,53 @@
+version: 2
+
+before:
+  hooks:
+    - go mod tidy
+
+builds:
+  - id: httpsuite
+    main: .
+    binary: httpsuite
+    ldflags:
+      - -s -w
+      - -X main.version={{.Version}}
+      - -X main.commit={{.Commit}}
+      - -X main.date={{.Date}}
+    env:
+      - CGO_ENABLED=0
+    goos:
+      - linux
+      - darwin
+    goarch:
+      - amd64
+      - arm64
+
+archives:
+  - formats: [tar.gz]
+    name_template: "httpsuite_{{ .Version }}_{{ .Os }}_{{ .Arch }}"
+    files:
+      - README.md
+      - LICENSE
+
+checksum:
+  name_template: "httpsuite_{{ .Version }}_checksums.txt"
+  algorithm: sha256
+
+brews:
+  - name: httpsuite
+    repository:
+      owner: uradical
+      name: homebrew-tap
+    homepage: https://httpsuite.dev
+    description: "JetBrains HTTP Client compatible test runner for CI pipelines"
+    license: MIT
+    test: |
+      system "#{bin}/httpsuite --version"
+
+release:
+  github:
+    owner: uradical
+    name: httpsuite
+  draft: false
+  prerelease: auto
+  name_template: "httpsuite v{{.Version}}"

README.md

@@ -0,0 +1,181 @@
+# httpsuite
+
+Run `.http` files as API tests, for local development and CI. A single binary
+with no runtime dependencies beyond the Go standard library and two uRadical
+modules ([httpparser](../httpparser) for parsing, [webbrowser](../webbrowser)
+for the forthcoming `--ui`).
+
+httpsuite executes the requests in your `.http` files, checks any `# @expect`
+assertions you attach, and reports pass/fail with the right output for where
+it's running — coloured and aligned on a terminal, plain and diffable in CI.
+
+## Install
+
+```sh
+go install github.com/uradical/httpsuite@latest
+```
+
+Requires Go 1.21 or later.
+
+## Usage
+
+```
+httpsuite [--var key=value]... [--ui] [path]
+```
+
+- `path` is optional and defaults to the current directory.
+- `--var key=value` overrides a `{{placeholder}}`. Repeatable.
+- `--ui` is reserved for a results UI and currently prints a notice and exits.
+
+```sh
+httpsuite                          # discover and run in the current directory
+httpsuite ./api                    # run a directory
+httpsuite ./api/users.http         # run a single file
+httpsuite --var token=abc ./api    # override {{token}}
+```
+
+Exit code is **0** when everything passes, **1** when any request or assertion
+fails, and **2** on a usage or setup error.
+
+## Discovery
+
+When `path` is a directory (or omitted), httpsuite decides what to run:
+
+1. If a **`httpsuite.yaml`** exists in the directory, it is used as the suite
+   definition.
+2. Otherwise every **`*.http`** file in the directory is run serially, in
+   sorted order.
+
+When `path` is a single file, only that file is run.
+
+## Suite definition (`httpsuite.yaml`)
+
+```yaml
+parallel: true          # run groups concurrently (default false)
+timeout: 30s            # global per-request timeout (default 10s)
+groups:
+  - name: auth
+    serial: true        # opt this group out of parallel execution
+    files:
+      - auth/login.http
+      - auth/refresh.http
+  - name: users
+    timeout: 5s         # override the timeout for this group
+    files:
+      - users/list.http
+      - users/create.http
+```
+
+- Files within a group always run serially, in order.
+- `serial: true` keeps a group off the parallel path even when `parallel` is on.
+- `timeout` may be set globally and overridden per group.
+
+## Variables
+
+`{{placeholder}}` tokens in a request's URL, headers, and body are resolved at
+execution time. Resolution order, from lowest to highest precedence:
+
+1. File-level `@key = value` declarations inside the `.http` file
+2. OS environment variables
+3. `--var key=value` flags
+
+A placeholder that is still unresolved at execution time fails that request.
+
+## Assertions (`# @expect`)
+
+Attach checks to a request with `# @expect` comments. All assertions on a
+request are evaluated — evaluation never stops at the first failure — and a
+request fails if **any** assertion fails. A request with no assertions passes as
+long as it returns any HTTP response.
+
+```http
+# @name createUser
+POST {{baseUrl}}/users
+Content-Type: application/json
+# @expect status == 201
+# @expect header Location exists
+# @expect body.id number
+# @expect body.name == "Ada Lovelace"
+# @expect body.roles length > 0
+# @expect duration < 500
+
+{ "name": "Ada Lovelace" }
+```
+
+### Status
+
+```http
+# @expect status == 201        # == != < > <= >=
+# @expect status 2xx           # 2xx 3xx 4xx 5xx range match
+```
+
+### Headers
+
+```http
+# @expect header X-Request-Id exists
+# @expect header Content-Type == application/json   # case-insensitive contains
+```
+
+### Body
+
+The response body is parsed as JSON. Paths use dot notation with array indexing,
+e.g. `body.items[0].id`.
+
+```http
+# @expect body.id exists
+# @expect body.id == 10                 # numeric compare: == != < > <= >=
+# @expect body.name == "Alan Bradley"   # quoted string
+# @expect body.active == true           # boolean
+# @expect body.items[0].name == "Alan"  # array indexing
+
+# type checks
+# @expect body.count number             # integer, no decimal point
+# @expect body.price double             # number with a decimal point
+# @expect body.name string
+# @expect body.active boolean
+# @expect body.address object
+# @expect body.items array
+
+# length of an array or string
+# @expect body.items length 3
+# @expect body.items length > 0
+
+# dates
+# @expect body.created date                        # ISO 8601 by default
+# @expect body.created date "YYYY-MM-DD"
+# @expect body.timestamp date "YYYY-MM-DD HH:mm"
+```
+
+Date format tokens: `YYYY MM DD` (date) and `HH mm ss` (time).
+
+### Duration
+
+```http
+# @expect duration < 500        # milliseconds elapsed for the request
+```
+
+> JetBrains `> {% ... %}` response-handler scripts are not executed. When one is
+> found, httpsuite prints a warning and continues — use `# @expect` instead.
+
+## Output
+
+On a terminal, results are coloured (green pass, red fail, bold summary) with
+`✓`/`✗` marks on assertion lines. With no TTY (CI), the same layout is printed
+without ANSI codes and with `PASS`/`FAIL` words instead of glyphs:
+
+```
+FAIL  POST  https://api.example.com/users    422  89ms
+  PASS  status 2xx
+  FAIL  status == 201          expected 201, got 422
+  FAIL  body.id exists         field not present in response
+  PASS  body.name == "Alan"
+
+1 requests  0 passed  1 failed  89ms
+```
+
+## Development
+
+```sh
+go test ./...     # unit tests
+go vet ./...
+```

example/README.md

@@ -0,0 +1,74 @@
+# httpsuite example
+
+A self-contained demo: a tiny in-memory REST API (stdlib `net/http` only) and a
+`.http` suite that exercises it with httpsuite.
+
+```
+example/
+  server/main.go   # users API — GET/POST/PUT/PATCH/DELETE over an in-memory map
+  api/             # the .http suite that tests it
+    httpsuite.yaml
+    list.http  get.http  create.http  put.http  patch.http  delete.http  not-found.http
+```
+
+## The API
+
+`server` exposes a `users` resource backed by a mutex-guarded map, seeded with
+two users (id `1` and `2`) on startup:
+
+| Method | Path          | Behaviour                                   |
+| ------ | ------------- | ------------------------------------------- |
+| GET    | `/users`      | `200` — `{ "count", "users": [...] }`       |
+| POST   | `/users`      | `201` — created user + `Location` header    |
+| GET    | `/users/{id}` | `200` or `404`                              |
+| PUT    | `/users/{id}` | `200` (full replace) or `404`               |
+| PATCH  | `/users/{id}` | `200` (partial update) or `404`             |
+| DELETE | `/users/{id}` | `204` or `404`                              |
+
+## Run the demo
+
+Start the server:
+
+```sh
+go run ./example/server            # listens on :8080
+# or choose a port: go run ./example/server --addr 127.0.0.1:9000
+```
+
+In another terminal, run the suite:
+
+```sh
+go run . ./example/api             # or: httpsuite ./example/api
+```
+
+You should see every request pass:
+
+```
+PASS  GET    http://127.0.0.1:8080/users     200  1ms
+  PASS  status == 200
+  PASS  body.users[0].name == "Alan Bradley"
+  ...
+7 requests  7 passed  0 failed  3ms
+```
+
+The requests default to `http://127.0.0.1:8080` via a file-level
+`@baseUrl` variable. Point the suite elsewhere without editing the files:
+
+```sh
+go run . --var baseUrl=http://127.0.0.1:9000 ./example/api
+```
+
+## A note on ordering and state
+
+The suite runs as a single `serial` group in a deliberate order — list, read,
+create, replace, update, delete, then confirm the delete returns `404`. Because
+the requests mutate shared server state, **run them against a freshly started
+server**. Running the suite a second time against the same process will fail
+(e.g. `PUT /users/2` returns `404` because the earlier run deleted it) — which
+is exactly httpsuite doing its job:
+
+```
+FAIL  PUT    http://127.0.0.1:8080/users/2   404  0ms
+  FAIL  status == 200          expected 200, got 404
+```
+
+Restart the server to reset the seed data.

example/api/create.http

@@ -0,0 +1,20 @@
+@baseUrl = http://127.0.0.1:8080
+
+# @name createUser
+POST {{baseUrl}}/users
+Content-Type: application/json
+# @expect status == 201
+# @expect status 2xx
+# @expect header Location exists
+# @expect header Content-Type == application/json
+# @expect body.id exists
+# @expect body.id number
+# @expect body.name == "Grace Hopper"
+# @expect body.email == "grace@example.com"
+# @expect body.active == false
+
+{
+  "name": "Grace Hopper",
+  "email": "grace@example.com",
+  "active": false
+}

example/api/delete.http

@@ -0,0 +1,7 @@
+@baseUrl = http://127.0.0.1:8080
+
+# @name deleteUser
+DELETE {{baseUrl}}/users/2
+# @expect status == 204
+# @expect status 2xx
+# @expect duration < 2000

example/api/get.http

@@ -0,0 +1,10 @@
+@baseUrl = http://127.0.0.1:8080
+
+# @name getUser
+GET {{baseUrl}}/users/1
+# @expect status == 200
+# @expect header Content-Type == application/json
+# @expect body.id == 1
+# @expect body.name == "Alan Bradley"
+# @expect body.email == "alan@uradical.io"
+# @expect body.active == true

example/api/httpsuite.code-workspace

@@ -0,0 +1,14 @@
+{
+	"folders": [
+		{
+			"path": "../../../httpparser"
+		},
+		{
+			"path": "../.."
+		},
+		{
+			"path": "../../../webbrowser"
+		}
+	],
+	"settings": {}
+}