Module "telescope"

Telescope is a test library for Lua that allows for flexible, declarative tests. The documentation produced here is intended largely for developers working on Telescope. For information on using Telescope, please visit the project homepage at: http://github.com/norman/telescope.

Release: 0.5

Functions

ancestors (i, contexts)	(local) Finds the value in the contexts table indexed with i, and returns a table of i's ancestor contexts.
error_report (contexts, results)	Return a table of stack traces for tests which produced a failure or an error.
filter (t, f)	(local) Filter a table's values by function.
invert_table (t)	(local) Return a table with table t's values as keys and keys as values.
load_contexts (target, contexts)	Build a contexts table from the test file or function given in `target`.
make_assertion (name, message, func)	Create a custom assertion.
run (contexts, callbacks, test_filter)	Run all tests.
summary_report (contexts, results)	Get a one-line report and a summary table with the status counts.
test_report (contexts, results)	Return a detailed report for each context, with the status of each test.

Tables

after_aliases	The default names for "after" blocks.
assertions	The default assertions.
before_aliases	The default names for "before" blocks.
context_aliases	The default names for context blocks.
status_codes	The status codes that can be returned by an invoked test.
status_labels	Labels used to show the various `status_codes` as a single character.
test_aliases	The default names for test blocks.

Functions

ancestors (i, contexts)

(local) Finds the value in the contexts table indexed with i, and returns a table of i's ancestor contexts.

Parameters:

i: The index in the contexts table to get ancestors for.
contexts: The table in which to find the ancestors.

error_report (contexts, results)

Return a table of stack traces for tests which produced a failure or an error.

Parameters:

contexts: The contexts returned by load_contexts.
results: The results returned by run.

filter (t, f)

(local) Filter a table's values by function. This function iterates over a table , returning only the table entries that, when passed into function f, yield a truthy value.

Parameters:

t: The table over which to iterate.
f: The filter function.

invert_table (t)

(local) Return a table with table t's values as keys and keys as values.

Parameters:

t: The table.

load_contexts (target, contexts)

Build a contexts table from the test file or function given in target. If the optional contexts table argument is provided, then the resulting contexts will be added to it.

The resulting contexts table's structure is as follows:


{
  {parent = 0, name = "this is a context", context = true},
  {parent = 1, name = "this is a nested context", context = true},
  {parent = 2, name = "this is a test", test = function},
  {parent = 2, name = "this is another test", test = function},
  {parent = 0, name = "this is test outside any context", test = function},
}

Parameters:

target:
contexts: A optional table in which to collect the resulting contexts and function.

make_assertion (name, message, func)

Create a custom assertion. This creates an assertion along with a corresponding negative assertion. It is used internally by telescope to create the default assertions.

Parameters:

name: The base name of the assertion.
The name will be used as the basis of the positive and negative assertions; i.e., the name equal would be used to create the assertions assert_equal and assert_not_equal.
message: The base message that will be shown.
The assertion message is what is shown when the assertion fails. It will be prefixed with the string in telescope.assertion_message_prefix. The variables passed to telescope.make_assertion are interpolated in the message string using string.format. When creating the inverse assertion, the message is reused, with " to be " replaced by " not to be ". Hence a recommended format is something like: "%s to be similar to %s".
func: The assertion function itself.
The assertion function can have any number of arguments.

Usage:

make_assertion("equal", "%s to be equal to %s", function(a, b) return a == b end)

Parameters:

contexts: The contexts created by load_contexts.
callbacks: A table of callback functions to be invoked before or after various test states.
There is a callback for each test status_code, and callbacks to run before or after each test invocation regardless of outcome.
- after - will be invoked after each test
- before - will be invoked before each test
- err - will be invoked after each test which results in an error
- fail - will be invoked after each failing test
- pass - will be invoked after each passing test
- pending - will be invoked after each pending test
- unassertive - will be invoked after each test which doesn't assert anything
Callbacks can be used, for example, to drop into a debugger upon a failed assertion or error, for profiling, or updating a GUI progress meter.
test_filter: A function to filter tests that match only conditions that you specify.
For example, the folling would allow you to run only tests whose name matches a pattern:

function(t) return t.name:match("%s* lexer") end

Return value:

A table of result tables. Each result table has the following fields:

assertions_invoked - the number of assertions the test invoked
context - the name of the context
message - a table with an error message and stack trace
name - the name of the test
status_code - the resulting status code
status_label - the label for the status_code

Parameters:

contexts: The contexts returned by load_contexts.
results: The results returned by run.

Return values:

A report that can be printed
A table with the various counts. Its fields are: assertions, errors, failed, passed, pending, tests, unassertive.

test_report (contexts, results)

Return a detailed report for each context, with the status of each test.

Parameters:

contexts: The contexts returned by load_contexts.
results: The results returned by run.

Tables

after_aliases

The default names for "after" blocks. It defaults to "after" and "teardown." The function in the after block will be run after each sibling test function or context.

assertions

The default assertions. These are the assertions built into telescope. You can override them or create your own custom assertions using make_assertion.

assert_blank(a) - true if a is nil, or the empty string

assert_empty(a) - true if a is an empty table

assert_equal(a, b) - true if a == b

assert_error(f) - true if function f produces an error

assert_false(a) - true if a is false

assert_greater_than(a, b) - true if a > b

assert_gte(a, b) - true if a >= b

assert_less_than(a, b) - true if a < b

assert_lte(a, b) - true if a <= b

assert_match(a, b) - true if b is a string that matches pattern a

assert_nil(a) - true if a is nil

assert_true(a) - true if a is true

assert_type(a, b) - true if a is of type b

assert_not_blank(a) - true if a is not nil and a is not the empty string

assert_not_empty(a) - true if a is a table, and a is not empty

assert_not_equal(a, b) - true if a ~= b

assert_not_error(f) - true if function f does not produce an error

assert_not_false(a) - true if a is not false

assert_not_greater_than(a, b) - true if not (a > b)

assert_not_gte(a, b) - true if not (a >= b)

assert_not_less_than(a, b) - true if not (a < b)

assert_not_lte(a, b) - true if not (a <= b)

assert_not_match(a, b) - true if the string b does not match the pattern a

assert_not_nil(a) - true if a is not nil

assert_not_true(a) - true if a is not true

assert_not_type(a, b) - true if a is not of type b

before_aliases

The default names for "before" blocks. It defaults to "before" and "setup." The function in the before block will be run before each sibling test function or context.

context_aliases

The default names for context blocks. It defaults to "context", "spec" and "describe."

status_codes

The status codes that can be returned by an invoked test. These should not be overidden. Fields

err: - This is returned when an invoked test results in an error rather than a passed or failed assertion.
fail: - This is returned when an invoked test contains one or more failing assertions.
pass: - This is returned when all of a test's assertions pass.
pending: - This is returned when a test does not have a corresponding function.
unassertive: - This is returned when an invoked test does not produce errors, but does not contain any assertions.

status_labels

Labels used to show the various status_codes as a single character. These can be overidden if you wish. Fields

status_codes.err: 'E'
status_codes.fail: 'F'
status_codes.pass: 'P'
status_codes.pending: '?'
status_codes.unassertive: 'U'

test_aliases

The default names for test blocks. It defaults to "test," "it", "expect", "they" and "should."

LuaDoc

Modules

Module "telescope"

Functions

Tables

Functions

Parameters:

Parameters:

Parameters:

Parameters:

Parameters:

Parameters:

Usage:

See also:

Parameters:

Return value:

See also:

Parameters:

Return values:

Parameters:

Tables