test.format

import test.format

test does not re-export this module, so it is reached only by importing it directly.

Turning any Zuri value into text a person can read in a failure message.

Two shapes are produced. inline() gives one line, abbreviated to fit in a sentence: this is what Expected 3 but received 4 is built from. block() gives a list of lines, indented, with nothing abbreviated away: this is what a diff and a snapshot are built from.

Both are safe on values that contain themselves. A list or a dictionary already being rendered further up the same call is printed as [Circular] rather than followed round again.

Limits

inline() shows at most 8 entries of a list or dictionary, nests at most 3 levels deep, and shortens a string past 60 characters. Anything cut off is marked, never silently dropped. Pass an options dictionary to change any of them:

import test.format

echo format.inline(big_list, { max_items: 40, max_depth: 6 })

block() has no item or depth limit at all, because the reader asked for the whole thing.

Constants

DEFAULT_MAX_ITEMS

test.format.DEFAULT_MAX_ITEMS = 8

DEFAULT_MAX_DEPTH

test.format.DEFAULT_MAX_DEPTH = 3

DEFAULT_MAX_STRING

test.format.DEFAULT_MAX_STRING = 60

Functions

type_name()

test.format.type_name(value) -> string

The name of value’s type: 'nil', 'bool', 'int', 'float', 'bigint', 'string', 'bytes', 'list', 'dict', 'range', 'function', 'class', 'instance', 'module' or 'file'.

Every instance is an 'instance', whatever it was built from. Use type_label() for the form that names the class.

Parameters

• value (any)

Returns string

type_label()

test.format.type_label(value) -> string

How to name value’s type in a sentence a person reads.

The same as type_name(), except that an instance is called by its class: “expected a Point, received a Vector” beats hearing that both of them are instances.

Parameters

• value (any)

Returns string

with_article()

test.format.with_article(word: string) -> string

word with the article that belongs in front of it.

Worth the three lines: “expected a int” is the kind of wording that makes a tool feel unfinished.

Parameters

• word (string)

Returns string

properties_of()

test.format.properties_of(value) -> list

The names of an instance’s own properties, in declaration order.

The single place in the test module that knows how to look inside an instance, so equality, diffing and rendering never disagree about what an object’s contents are.

Parameters

• value (instance)

Returns list

property_of()

test.format.property_of(value, name: string)

Reads one of an instance’s own properties by name.

Parameters

• value (instance)
• name (string)

Returns — any: nil when there is no such property.

class_name()

test.format.class_name(value) -> string

The name of the class value was built from, or nil when it is not an instance.

Parameters

• value (any)

Returns string

inline()

test.format.inline(value, options: ?dict) -> string

value rendered as a single line, abbreviated to stay readable inside a sentence.

import test.format

echo format.inline({ name: 'Ada', tags: ['x', 'y'] })

{ name: 'Ada', tags: ['x', 'y'] }

Parameters

• value (any)
• options (?dict) — any of color, max_items, max_depth, max_string, sort_keys. Anything left out keeps its default.

Returns string

inline_plain()

test.format.inline_plain(value, options: ?dict) -> string

inline() with colour suppressed, whatever the terminal supports.

This is what a machine-readable reporter and a snapshot key are built from, since an escape sequence in either would be a correctness bug rather than a cosmetic one.

Parameters

• value (any)
• options (?dict)

Returns string

block()

test.format.block(value, options: ?dict)

value rendered over as many lines as it takes, with nothing abbreviated away.

A scalar comes back as a single-element list, so the caller never has to special-case it.

import test.format

for line in format.block({ id: 7, tags: ['a', 'b'] }) {
  echo line
}

{
  id: 7,
  tags: [
    'a',
    'b'
  ]
}

Parameters

• value (any)
• options (?dict) — as inline(), except that max_items and max_depth default to unlimited.

Returns — list: the lines, without trailing newlines.

serialize()

test.format.serialize(value)

block() with colour suppressed and dictionary keys sorted, which together make the output stable enough to commit to a repository.

This is the exact text a snapshot file holds.

Parameters

• value (any)

Returns — string: the lines joined with \n, with no trailing one.

duration()

test.format.duration(milliseconds: number) -> string

A duration in milliseconds, rendered the way a reader wants to see it: whole milliseconds below a second, and seconds with one decimal place above.

Parameters

• milliseconds (number)

Returns string

plural()

test.format.plural(count: int, singular: string, plural: ?string) -> string

count followed by singular or plural, whichever the count calls for.

Parameters

• count (int)
• singular (string)
• plural (?string) — singular + 's' by default.

Returns string