jsonhelpers

Documentation

Overview

Package jsonhelpers contains general-purpose functions for manipulating JSON.

These functions are not intended to be highly fast or efficient; they are designed for simplicity of use in test code.

Index

• func CanonicalizeJSON(originalJSON []byte) []byte
• func ToJSON(value interface{}) []byte
• func ToJSONString(value interface{}) string
• type JSONDiffElement
  • func (e JSONDiffElement) Describe(value1Name, value2Name string) string
• type JSONDiffResult
  • func JSONDiff(json1, json2 []byte) (JSONDiffResult, error)
  • func (r JSONDiffResult) Describe(value1Name, value2Name string) []string
• type JSONPath
  • func (p JSONPath) String() string
• type JSONPathComponent

Functions

func CanonicalizeJSON

func CanonicalizeJSON(originalJSON []byte) []byte

CanonicalizeJSON reformats a JSON value so that object properties are alphabetized, making comparisons predictable and making it easier for a human reader to find a property.

func ToJSON

func ToJSON(value interface{}) []byte

ToJSON is just a shortcut for calling json.Marshal and taking only the first result.

func ToJSONString

func ToJSONString(value interface{}) string

ToJSONString calls json.Marshal and returns the result as a string.

Types

type JSONDiffElement

type JSONDiffElement struct {
	// Path represents the location of the data as a path from the root.
	Path JSONPath

	// Value1 is the JSON encoding of the value at that path in the data structure
	// that was passed to JSONDiff as json1. An empty string (as opposed to the JSON
	// representation of an empty string, `""`) means that this property was missing
	// in json1.
	Value1 string

	// Value2 is the JSON encoding of the value at that path in the data structure
	// that was passed to JSONDiff as json2. An empty string (as opposed to the JSON
	// representation of an empty string, `""`) means that this property was missing
	// in json2.
	Value2 string
}

JSONDiffElement describes a point of difference between two JSON data structures.

func (JSONDiffElement) Describe

func (e JSONDiffElement) Describe(value1Name, value2Name string) string

Describe returns a string description of this difference.

type JSONDiffResult

type JSONDiffResult []JSONDiffElement

JSONDiffResult is a list of JSONDiffElement values returned by JSONDiff.

func JSONDiff

func JSONDiff(json1, json2 []byte) (JSONDiffResult, error)

JSONDiff compares two JSON values and returns an explanation of how they differ, if at all, ignoring any differences that do not affect the value semantically (such as whitespace). This is for programmatic use; if you want a human-readable test assertion based on the same logic, see matchers.JSONEqual (which calls this function).

The two values are provided as marshalled JSON data. If they cannot be parsed, the function immediately returns an error.

If the values are deeply equal, the result is nil.

Otherwise, if they are both simple values, the result will contain a single JSONDiffElement.

If they are both JSON objects, JSONDiff will compare their properties. It will produce a JSONDiffElement for each property where they differ. For instance, comparing {"a": 1, "b": 2} with {"a": 1, "b": 3, "c": 4} will produce one element for "b" and one for "c". If a property contains an object value on both sides, the comparison will proceed recursively and may produce elements with subpaths (see JSONPath).

If they are both JSON arrays, and are of the same length, JSONDiff will compare their elements using the same rules as above. For JSON arrays of different lengths, if the shorter one matches every corresponding element of the longer one, it will return a JSONDiffElement pointing to the first element after the shorter one and listing the additional elements starting with a comma (for instance, comparing [10,20] with [10,20,30] will return a string of ",30" at index 2); otherwise it will just return both arrays in their entirety.

Values that are not of the same type will always produce a single JSONDiffElement describing the entire values.

func (JSONDiffResult) Describe

func (r JSONDiffResult) Describe(value1Name, value2Name string) []string

Describe returns a list of string descriptions of the differences.

type JSONPath

type JSONPath []JSONPathComponent

JSONPath represents the location of a node in a JSON data structure.

In a JSON object {"a":{"b":2}}, the nested "b":2 property would be referenced as JSONPath{{Property: "a"}, {Property: "b"}}.

In a JSON array ["a","b",["c"]], the "c" value would be referenced as JSONPath{{Index: 2},{Index: 0}}.

A nil or zero-length slice represents the root of the data.

func (JSONPath) String

func (p JSONPath) String() string

String returns a string representation of the path.

type JSONPathComponent

type JSONPathComponent struct {
	// Property is the name of an object property, or "" if this is in an array.
	Property string

	// Index is the zero-based index of an array element, if this is in an array.
	Index int
}

JSONPathComponent represents a location within the top level of a JSON object or array.