# Module `pl.test`

Useful test utilities.

    test.asserteq({1,2},{1,2}) -- can compare tables
    test.asserteq(1.2,1.19,0.02) -- compare FP numbers within precision
    T = test.tuple -- used for comparing multiple results
    test.asserteq(T(string.find(" me","me")),T(2,3))

Dependencies: pl.utils, pl.tablex, pl.pretty, pl.path, debug

## Functions

error_handler (file, line, got_text, needed_text, msg) | error handling for test results.
complain (x, y, msg, where) | general test complain message.
asserteq (x, y, eps, where) | like assert, except takes two arguments that must be equal and can be tables.
assertmatch (s1, s2, where) | assert that the first string matches the second.
assertraise (fn, e, where) | assert that the function raises a particular error.
asserteq2 (x1, x2, y1, y2, where) | a version of asserteq that takes two pairs of values.
tuple (...) | encode an arbitrary argument list as a tuple.
timer (msg, n, fun, ...) | Time a function.

## Functions

error_handler (file, line, got_text, needed_text, msg)
  error handling for test results. By default, this writes to stderr and exits the program. Re-define this function to raise an error and/or redirect output

  ### Parameters:

  - file
  - line
  - got_text
  - needed_text
  - msg
complain (x, y, msg, where)
  general test complain message. Useful for composing new test functions (see tests/tablex.lua for an example)

  ### Parameters:

  - x a value
  - y value to compare first value against
  - msg message
  - where extra level offset for errors
asserteq (x, y, eps, where)
  like assert, except takes two arguments that must be equal and can be tables. If they are plain tables, it will use tablex.deepcompare.

  ### Parameters:

  - x any value
  - y a value equal to x
  - eps an optional tolerance for numerical comparisons
  - where extra level offset
assertmatch (s1, s2, where)
  assert that the first string matches the second.

  ### Parameters:

  - s1 a string
  - s2 a string
  - where extra level offset
assertraise (fn, e, where)
  assert that the function raises a particular error.

  ### Parameters:

  - fn a function or a table of the form {function,arg1,...}
  - e a string to match the error against
  - where extra level offset
asserteq2 (x1, x2, y1, y2, where)
  a version of asserteq that takes two pairs of values. `x1==y1 and x2==y2` must be true. Useful for functions that naturally return two values.

  ### Parameters:

  - x1 any value
  - x2 any value
  - y1 any value
  - y2 any value
  - where extra level offset
tuple (...)
  encode an arbitrary argument list as a tuple. This can be used to compare to other argument lists, which is very useful for testing functions which return a number of values. Unlike regular array-like tables ('sequences') they may contain nils. Tuples understand equality and know how to print themselves out. The # operator is defined to be the size, irrespecive of any nils, and there is an `unpack` method.

  ### Parameters:

  - ...

  ### Usage:

      asserteq(tuple( ('ab'):find 'a'), tuple(1,1))

timer (msg, n, fun, ...)
  Time a function. Call the function a given number of times, and report the number of seconds taken, together with a message. Any extra arguments will be passed to the function.

  ### Parameters:

  - msg string a descriptive message
  - n integer number of times to call the function
  - fun function the function
  - ... optional arguments to fun

generated by LDoc 1.5.0