Expressive and versatile end-to-end HTTP API testing made easy in Go (golang), built on top of gentleman HTTP client toolkit.

Take a look to the examples to get started.

• Versatile built-in expectations.
• Extensible custom expectations.
• Declarative, expressive, fluent API.
• Response body matching and strict equality expectations.
• Deep JSON comparison.
• JSON Schema validation.
• Full-featured HTTP client built on top of gentleman toolkit.
• Intuitive and semantic HTTP client DSL.
• Easy to configure and use.
• Composable chainable assertions.
• Works with Go's testing package (more test engines might be added in the future).
• Convenient helpers and abstractions over Go's HTTP primitives.
• Middleware-oriented via gentleman's middleware layer.
• Extensible and hackable API.

• v3 - Latest stable version with better JSON assertion. Uses gentleman@v2. Recommended.
• v2 - Stable version. Uses gentleman@v2.
• v1 - First version. Stable. Uses gentleman@v1. Actively maintained.

go get -u gopkg.in/h2non/baloo.v3

• Go 1.7+

See examples directory for featured examples.

package simple

import (
  "testing"

  "gopkg.in/h2non/baloo.v3"
)

// test stores the HTTP testing client preconfigured
var test = baloo.New("http://httpbin.org")

func TestBalooSimple(t *testing.T) {
  test.Get("/get").
    SetHeader("Foo", "Bar").
    Expect(t).
    Status(200).
    Header("Server", "apache").
    Type("json").
    JSON(map[string]string{"bar": "foo"}).
    Done()
}

package custom_assertion

import (
  "errors"
  "net/http"
  "testing"

  "gopkg.in/h2non/baloo.v3"
)

// test stores the HTTP testing client preconfigured
var test = baloo.New("http://httpbin.org")

// assert implements an assertion function with custom validation logic.
// If the assertion fails it should return an error.
func assert(res *http.Response, req *http.Request) error {
  if res.StatusCode >= 400 {
    return errors.New("Invalid server response (> 400)")
  }
  return nil
}

func TestBalooClient(t *testing.T) {
  test.Post("/post").
    SetHeader("Foo", "Bar").
    JSON(map[string]string{"foo": "bar"}).
    Expect(t).
    Status(200).
    Type("json").
    AssertFunc(assert).
    Done()
}

package json_schema

import (
  "testing"

  "gopkg.in/h2non/baloo.v3"
)

const schema = `{
  "title": "Example Schema",
  "type": "object",
  "properties": {
    "origin": {
      "type": "string"
    }
  },
  "required": ["origin"]
}`

// test stores the HTTP testing client preconfigured
var test = baloo.New("http://httpbin.org")

func TestJSONSchema(t *testing.T) {
  test.Get("/ip").
    Expect(t).
    Status(200).
    Type("json").
    JSONSchema(schema).
    Done()
}

package alias_assertion

import (
  "errors"
  "net/http"
  "testing"

  "gopkg.in/h2non/baloo.v3"
)

// test stores the HTTP testing client preconfigured
var test = baloo.New("http://httpbin.org")

func assert(res *http.Response, req *http.Request) error {
  if res.StatusCode >= 400 {
    return errors.New("Invalid server response (> 400)")
  }
  return nil
}

func init() {
  // Register assertion function at global level
  baloo.AddAssertFunc("test", assert)
}

func TestBalooClient(t *testing.T) {
  test.Post("/post").
    SetHeader("Foo", "Bar").
    JSON(map[string]string{"foo": "bar"}).
    Expect(t).
    Status(200).
    Type("json").
    Assert("test").
    Done()
}

See godoc reference for detailed API documentation.

Asserts the response HTTP status code to be equal.

Asserts the response HTTP status to be within the given numeric range.

Asserts the response HTTP status to be a valid server response (>= 200 && < 400).

Asserts the response HTTP status to be a valid clint/server error response (>= 400 && < 600).

Asserts the response HTTP status to be a valid server error response (>= 500 && < 600).

Asserts the response HTTP status to be a valid client error response (>= 400 && < 500).

Asserts the Content-Type header. MIME type aliases can be used as kind argument.

Supported aliases: json, xml, html, form, text and urlencoded.

Asserts a response header field value matches.

Regular expressions can be used as value to perform the specific assertions.

Asserts a response header field with the given value.

Asserts that a response header field is not equal to the given value.

Asserts if a header field is present in the response.

Asserts if a header field is not present in the response.

Asserts a response body as string using strict comparison.

Regular expressions can be used as value to perform the specific assertions.

Asserts a response body matching a string expression.

Regular expressions can be used as value to perform the specific assertions.

Asserts the response body length.

Asserts the response body with the given JSON struct.

Asserts the response body againts the given JSON schema definition.

data argument can be a string containing the JSON schema, a file path or an URL pointing to the JSON schema definition.

Assert adds a new assertion function by alias name.

Assertion function must be previosly registered via baloo.AddAssertFunc("alias", function).

See an example here.

Adds a new custom assertion function who should return an detailed error in case that the assertion fails.

Clone this repository:

git clone https://github.com/h2non/baloo.git && cd baloo

Install dependencies:

go get -u ./...

Run tests:

go test ./...

Lint code:

go test ./...

Run example:

go test ./_examples/simple/simple_test.go

MIT - Tomas Aparicio