jsonassert

README

It's difficult to confirm that a JSON payload, e.g. a HTTP request or response body, does indeed look the way you want using the built-in Go testing package. jsonassert is an easy-to-use Go test assertion library for verifying that two representations of JSON are semantically equal.

Usage

Create a new *jsonassert.Asserter in your test and use this to make assertions against your JSON payloads:

func TestWhatever(t *testing.T) {
	ja := jsonassert.New(t)
	// find some sort of payload
	name := "River Tam"
	age := 16
	ja.Assertf(payload, `
	{
		"name": "%s",
		"age": %d,
		"averageTestScore": "%s",
		"skills": [
			{ "name": "martial arts", "level": 99 },
			{ "name": "intelligence", "level": 100 },
			{ "name": "mental fortitude", "level": 4 }
		]
	}`, name, age, "99%")
}

You may pass in fmt.Sprintf arguments after the expected JSON structure. This feature may be useful for the case when you already have variables in your test with the expected data or when your expected JSON contains a % character which could be misinterpreted as a format directive.

ja.Assertf() supports assertions against strings only.

Check for presence only

Some properties of a JSON payload may be difficult to know in advance. E.g. timestamps, UUIDs, or other randomly assigned values.

For these types of values, place the string "<<PRESENCE>>" as the expected value, and jsonassert will only verify that this key exists (i.e. the actual JSON has the expected key, and its value is not null), but this does not check its value.

For example:

func TestWhatever(t *testing.T) {
	ja := jsonassert.New(t)
	ja.Assertf(`
	{
		"time": "2019-01-28T21:19:42",
		"uuid": "94ae1a31-63b2-4a55-a478-47764b60c56b"
	}`, `
	{
		"time": "<<PRESENCE>>",
		"uuid": "<<PRESENCE>>"
	}`)
}

The above will pass your test, but:

func TestWhatever(t *testing.T) {
	ja := jsonassert.New(t)
	ja.Assertf(`
	{
		"date": "2019-01-28T21:19:42",
		"uuid": null
	}`, `
	{
		"time": "<<PRESENCE>>",
		"uuid": "<<PRESENCE>>"
	}`)
}

The above will fail your tests because the time key was not present in the actual JSON, and the uuid was null.

Ignore ordering in arrays

If your JSON payload contains an array with elements whose ordering is not deterministic, then you can use the "<<UNORDERED>>" directive as the first element of the array in question:

func TestUnorderedArray(t *testing.T) {
	ja := jsonassert.New(t)
	payload := `["bar", "foo", "baz"]`
	ja.Assertf(payload, `["foo", "bar", "baz"]`)                  // Order matters, will fail your test.
	ja.Assertf(payload, `["<<UNORDERED>>", "foo", "bar", "baz"]`) // Order agnostic, will pass your test.
}

Docs

You can find the GoDocs for this package here.

Contributing

Contributions are welcome. Please read the contribution guidelines and discuss feature requests in an issue before opening a PR.

Documentation

Overview

Package jsonassert is a Go test assertion library for verifying that two representations of JSON are semantically equal. Create a new

*jsonassert.Asserter

in your test and use this to make assertions against your JSON payloads:

ja := jsonassert.New(t)

E.g. for the JSON

{"hello": "world"}

you may use an expected JSON of

{"hello": "%s"}

along with the "world" format argument. For example:

ja.Assertf(`{"hello": "world"}`, `{"hello":"%s"}`, "world")

You may wish to make assertions against the *presence* of a value, but not against its value. For example:

ja.Assertf(`{"uuid": "94ae1a31-63b2-4a55-a478-47764b60c56b"}`, `{"uuid":"<<PRESENCE>>"}`)

will verify that the UUID field is present, but does not check its actual value. You may use "<<PRESENCE>>" against any type of value. The only exception is null, which will result in an assertion failure.

If you don't know / care about the order of the elements in an array in your payload, you can ignore the ordering:

payload := `["bar", "foo", "baz"]`
ja.Assertf(payload, `["<<UNORDERED>>", "foo", "bar", "baz"]`)

The above will verify that "foo", "bar", and "baz" are exactly the elements in the payload, but will ignore the order in which they appear.

Index

• type Asserter
  • func New(p Printer) *Asserter
  • func (a *Asserter) Assert(actualJSON, expectedJSON string)
  • func (a *Asserter) Assertf(actualJSON, expectedJSON string, fmtArgs ...interface{})
• type Printer

Examples

• Asserter.Assertf (FormatArguments)
• Asserter.Assertf (PresenceOnly)
• Asserter.Assertf (UnorderedArray)
• New

Types

type Asserter

type Asserter struct {
	// contains filtered or unexported fields
}

Asserter represents the main type within the jsonassert package. See Asserter.Assertf for the main use of this package.

func New

func New(p Printer) *Asserter

New creates a new *jsonassert.Asserter for making assertions against JSON payloads. This type can be reused. I.e. if you are using jsonassert as part of your tests, you only need one *jsonassert.Asseter per (sub)test. In most cases, this will look something like

ja := jsonassert.New(t)

Example

package main

import (
	"fmt"

	"github.com/kinbiko/jsonassert"
)

type printer struct{}

func (p *printer) Errorf(format string, args ...interface{}) {
	fmt.Println(fmt.Sprintf(format, args...))
}

// using the varible name 't' to mimic a *testing.T variable
//
//nolint:gochecknoglobals // this is global to make the examples look like valid test code
var t *printer

func main() {
	ja := jsonassert.New(t)
	ja.Assertf(`{"hello":"world"}`, `
		{
			"hello": "world"
		}`)
}

func (*Asserter) Assert

func (a *Asserter) Assert(actualJSON, expectedJSON string)

Assert works like Assertf, but does not accept fmt.Sprintf directives. See Assert for details.

func (*Asserter) Assertf

func (a *Asserter) Assertf(actualJSON, expectedJSON string, fmtArgs ...interface{})

Assertf takes two strings, the first being the 'actual' JSON that you wish to make assertions against. The second string is the 'expected' JSON, which can be treated as a template for additional format arguments. If any discrepancies are found, these will be given to the Errorf function in the Printer. E.g. for the JSON

{"hello": "world"}

you may use an expected JSON of

{"hello": "%s"}

along with the "world" format argument. For example:

ja.Assertf(`{"hello": "world"}`, `{"hello":"%s"}`, "world")

You may also use format arguments in the case when your expected JSON contains a percent character, which would otherwise be interpreted as a format-directive.

ja.Assertf(`{"averageTestScore": "99%"}`, `{"averageTestScore":"%s"}`, "99%")

You may wish to make assertions against the *presence* of a value, but not against its value. For example:

ja.Assertf(`{"uuid": "94ae1a31-63b2-4a55-a478-47764b60c56b"}`, `{"uuid":"<<PRESENCE>>"}`)

will verify that the UUID field is present, but does not check its actual value. You may use "<<PRESENCE>>" against any type of value. The only exception is null, which will result in an assertion failure.

If you don't know / care about the order of the elements in an array in your payload, you can ignore the ordering:

payload := `["bar", "foo", "baz"]`
ja.Assertf(payload, `["<<UNORDERED>>", "foo", "bar", "baz"]`)

The above will verify that "foo", "bar", and "baz" are exactly the elements in the payload, but will ignore the order in which they appear.

Example (FormatArguments)

package main

import (
	"fmt"

	"github.com/kinbiko/jsonassert"
)

type printer struct{}

func (p *printer) Errorf(format string, args ...interface{}) {
	fmt.Println(fmt.Sprintf(format, args...))
}

// using the varible name 't' to mimic a *testing.T variable
//
//nolint:gochecknoglobals // this is global to make the examples look like valid test code
var t *printer

func main() {
	ja := jsonassert.New(t)
	expTestScore := "28%"
	ja.Assertf(
		`{ "name": "Jayne Cobb", "age": 36, "averageTestScore": "88%" }`,
		`{ "name": "Jayne Cobb", "age": 36, "averageTestScore": "%s" }`, expTestScore,
	)
}

Output:

expected string at '$.averageTestScore' to be '28%' but was '88%'

Example (PresenceOnly)

package main

import (
	"fmt"

	"github.com/kinbiko/jsonassert"
)

type printer struct{}

func (p *printer) Errorf(format string, args ...interface{}) {
	fmt.Println(fmt.Sprintf(format, args...))
}

// using the varible name 't' to mimic a *testing.T variable
//
//nolint:gochecknoglobals // this is global to make the examples look like valid test code
var t *printer

func main() {
	ja := jsonassert.New(t)
	ja.Assertf(`{"hi":"not the right key name"}`, `
		{
			"hello": "<<PRESENCE>>"
		}`)
}

Output:

unexpected object key(s) ["hi"] found at '$'
expected object key(s) ["hello"] missing at '$'

Example (UnorderedArray)

package main

import (
	"fmt"

	"github.com/kinbiko/jsonassert"
)

type printer struct{}

func (p *printer) Errorf(format string, args ...interface{}) {
	fmt.Println(fmt.Sprintf(format, args...))
}

// using the varible name 't' to mimic a *testing.T variable
//
//nolint:gochecknoglobals // this is global to make the examples look like valid test code
var t *printer

func main() {
	ja := jsonassert.New(t)
	ja.Assertf(
		`["zero", "one", "two"]`,
		`["<<UNORDERED>>", "one", "two", "three"]`,
	)
}

Output:

actual JSON at '$[0]' contained an unexpected element: "zero"
expected JSON at '$[2]': "three" was missing from actual payload

type Printer

type Printer interface {
	Errorf(msg string, args ...interface{})
}

Printer is any type that has a testing.T-like Errorf function. You probably want to pass in a *testing.T instance here if you are using this in your tests.