golden

README

Golden

The golden package provides methods for producing and comparing golden files.

Golden files are described in the testfiles repository.

Documentation

Overview

The golden package provides methods for producing and comparing golden files.

Golden files are described in the testfiles repository:

https://github.com/RobloxAPI/testfiles

Index

• func Equal(x, y io.Reader) (equal bool, err error)
• type Array
• type Config
• type Encoder
  • func (e *Encoder) Array(v Array)
  • func (e *Encoder) Byte(c byte)
  • func (e *Encoder) Literal(s string)
  • func (e *Encoder) Newline()
  • func (e *Encoder) Object(v Object)
  • func (e *Encoder) Pop()
  • func (e *Encoder) Push()
  • func (e *Encoder) String(s string)
  • func (e *Encoder) Value(v interface{})
• type Field
• type Golden
  • func NewGolden(w io.Writer, config Config) *Golden
  • func (g *Golden) Array(name string, v ...interface{})
  • func (g *Golden) Close() error
  • func (g *Golden) Object(name string, v ...Field)
  • func (g *Golden) SetHandler(handler Handler)
  • func (g *Golden) Value(name string, value interface{})
• type Group
  • func GroupOf(f fs.FS, file string) (group Group)
  • func Groups(f fs.FS, dir string) (groups []Group, err error)
• type Handler
• type Literal
• type Object

Functions

func Equal

func Equal(x, y io.Reader) (equal bool, err error)

Equal returns whether JSON data parsed from two readers are equal. Stops reading once equality is known. Returns an error if either of the readers returned an unexpected error.

Types

type Array

type Array []interface{}

Array represents a JSON array.

type Config

type Config struct {
	// The format of the input file.
	Format string `json:",omitempty"`
	// The structure of the output file.
	Struct string `json:",omitempty"`
}

Config contains options that configure a group.

type Encoder

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

Encoder is a low-level encoder for values. An initialized Encoder is received by a Handler.

func (*Encoder) Array

func (e *Encoder) Array(v Array)

Array writes a JSON array.

func (*Encoder) Byte

func (e *Encoder) Byte(c byte)

Byte writes the given Byte.

func (*Encoder) Literal

func (e *Encoder) Literal(s string)

Literal writes the given string.

func (*Encoder) Newline

func (e *Encoder) Newline()

Newline writes a newline character followed by the current indentation.

func (*Encoder) Object

func (e *Encoder) Object(v Object)

Object writes a JSON object.

func (*Encoder) Pop

func (e *Encoder) Pop()

Pop decreases the indentation by one.

func (*Encoder) Push

func (e *Encoder) Push()

Push increases the indentation by one.

func (*Encoder) String

func (e *Encoder) String(s string)

String writes a JSON string.

func (*Encoder) Value

func (e *Encoder) Value(v interface{})

Value writes an arbitrary value. The types detected by default are described by the Golden.Value method. Other types are handled by the Handler function.

type Field

type Field struct {
	Name  string
	Value interface{}
}

Field represents the field of a JSON object.

type Golden

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

Golden is an encoder that writes the golden format.

func NewGolden

func NewGolden(w io.Writer, config Config) *Golden

NewGolden returns a Golden that writes to w. It is initialized by writing the fields in config. For correctly formatted data, Golden must be closed once all data has been written.

func (*Golden) Array

func (g *Golden) Array(name string, v ...interface{})

Array writes a Data field as a JSON array. Each argument is an element in the array.

No attempt is made to ensure that the field name is unique.

Does nothing if the encoder is closed.

func (*Golden) Close

func (g *Golden) Close() error

Close finishes encoding the root object, flushes any remaining data to be written, and closes the encoder.

func (*Golden) Object

func (g *Golden) Object(name string, v ...Field)

Object writes a Data field as a JSON object. Each argument is a field in the object.

No attempt is made to ensure that the field name is unique.

Does nothing if the encoder is closed.

func (*Golden) SetHandler

func (g *Golden) SetHandler(handler Handler)

SetHandler sets a function to call when Value does not match any types. If the handler returns false, then an error value is written instead.

func (*Golden) Value

func (g *Golden) Value(name string, value interface{})

Value writes a Data field as an arbitrary value. The following types are detected by default:

• nil is written as a JSON null.
• bool is written as a JSON bool.
• primitive numeric types are written as a JSON number.
• Infinity and NaN are written as a JSON string.
• Literal and json.Number are written as-is. Note that an improperly formatted value can cause the resulting JSON to become invalid.
• []byte is written as a JSON array of human-readable strings.
• string is written as a JSON string, or according to []byte if the string contains non-graphic characters.
• error is written according to string.
• Array and []interface{} are written as a JSON array.
• Object is written as a JSON object with ordered fields. No attempt is made to make fields unique.
• map[string]interface{} is written as a JSON object with fields ordered lexicographically.

If the type is not known, then the function set by SetHandler is called. If the handler returns false, or no handler is set, then `<UNKNOWN:type>` is emitted, causing the resulting JSON to be invalid.

No attempt is made to ensure that the field name is unique.

Does nothing if the encoder is closed.

type Group

type Group struct {
	Input  string
	Config string
	Golden string
}

func GroupOf

func GroupOf(f fs.FS, file string) (group Group)

GroupOf returns the group corresponding to the given file. The resulting group will be empty if the file does not exist or cannot be a part of a group.

func Groups

func Groups(f fs.FS, dir string) (groups []Group, err error)

Groups returns a list of file groups produced by walking the given directory.

Sibling files form a group when their names match. The part of the name used to match depends on the type:

• An input file uses its full name.
• A golden file uses its name without the `.golden` extension.
• A config file uses its name without the `.golden-config` extension.

Each resulting Group will have an Input, file other fields are set only if the file exists. Paths in each Group are relative to the input directory.

type Handler

type Handler func(e *Encoder, v interface{}) bool

Handler receives an arbitrary value for customized encoding. v is the value to be encoded. e provides low-level methods for encoding the value. Must return whether the value was handled.

type Literal

type Literal string

Literal represents a raw fragment of JSON data.

type Object

type Object []Field

Object represents a JSON object.