test.source

import test.source

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

Working out where a failure came from, and showing the code that was there.

Every Zuri error carries a stacktrace: a list of strings shaped like /path/to/file.zu:12 -> divide(). That is enough to point a reader at the exact line, provided the frames belonging to the test module itself are dropped first. Nobody needs to be told that the failure passed through _check() on its way out.

Functions

parse_frame()

test.source.parse_frame(line: string)

Splits one stack trace line into a Frame.

Parameters

• line (string)

Returns — Frame: nil when the line is not shaped like a frame, which is what a trace from a future runtime might well look like.

user_frames()

test.source.user_frames(stacktrace: list)

Every frame of stacktrace that belongs to the code under test, innermost first.

The test module’s own frames are dropped, because a failure is never interesting for having gone through a matcher.

Parameters

• stacktrace (list) — an error’s stacktrace.

Returns — list: a list of Frame.

origin()

test.source.origin(stacktrace: list)

The innermost frame of stacktrace outside the test module: where the failing line actually is.

Parameters

• stacktrace (list)

Returns — Frame: nil when every frame belongs to the framework, which happens when a matcher is misused rather than failing.

short_path()

test.source.short_path(path: string) -> string

A path written relative to the working directory when it is under it, and left alone when it is not.

Parameters

• path (string)

Returns string

code_frame()

test.source.code_frame(frame, context: ?int)

The source around a failure, with the offending line marked.

  10 |   var total = 0
  11 |
> 12 |   expect(total).to_be(1)
  13 | })

Parameters

• frame (Frame)
• context (?int) — lines of surrounding code either side, 2 by default.

Returns — list: the lines, already coloured. Empty when the file cannot be read, which is the normal answer for a frame from somewhere that no longer exists.

clear_cache()

test.source.clear_cache()

Forgets every file read for a code frame.

Only matters to a long-lived process that edits the files it is testing between runs.

Classes

Frame

class test.source.Frame

One frame of a stack trace, pulled apart.

Fields

Constructor

test.source.Frame(file, line, name, raw)

Frame.to_string()

test.source.Frame.to_string() -> string

The frame written for a report: a path relative to the working directory, since an absolute one is mostly noise the reader already knows.

Returns string