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)

See also:

run (contexts, callbacks, test_filter)
Run all tests. This function will exectute each function in the contexts table.

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

See also:

summary_report (contexts, results)
Get a one-line report and a summary table with the status counts. The counts given are: total tests, assertions, passed tests, failed tests, pending tests, and tests which didn't assert anything.

Parameters:

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

Return values:

  1. A report that can be printed
  2. 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."

Valid XHTML 1.0!