Module tap

Overview

The tap module streamlines the testing of other modules. It allows writing of tests in the TAP protocol. The results from the tests can be parsed by standard TAP-analyzers so they can be passed to utilities such as prove. Thus, one can run tests and then use the results for statistics, decision-making, and so on.

API Reference

Name	Use
tap.test()	Initialize
taptest:test()	Create a subtest and print the results
taptest:plan()	Indicate how many tests to perform
taptest:check()	Check the number of tests performed
taptest:diag()	Display a diagnostic message
taptest:ok()	Evaluate the condition and display the message
taptest:fail()	Evaluate the condition and display the message
taptest:skip()	Evaluate the condition and display the message
taptest:is()	Check if the two arguments are equal
taptest:isnt()	Check if the two arguments are different
taptest:is_deeply()	Recursively check if the two arguments are equal
taptest:like()	Check if the argument matches a pattern
taptest:unlike()	Check if the argument does not match a pattern
taptest:isnil() taptest:isstring() taptest:isnumber() taptest:istable() taptest:isboolean() taptest:isudata() taptest:iscdata()	Check if a value has a particular type
taptest.strict	Flag, true if comparisons with `nil` should be strict

tap.test(test-name)¶

Initialize.

The result of tap.test is an object, which will be called taptest in the rest of this discussion, which is necessary for taptest:plan() and all the other methods.

Parameters:	test-name (`string`) – an arbitrary name to give for the test outputs.
Return:	taptest
Rtype:	table

tap = require('tap')
taptest = tap.test('test-name')

object taptest¶

taptest:test(test-name, func)¶

Create a subtest (if no func argument specified), or (if all arguments are specified) create a subtest, run the test function and print the result.

See the example.

Parameters:	name (`string`) – an arbitrary name to give for the test outputs. fun (`function`) – the test logic to run.
Return:	taptest
Rtype:	userdata or string

taptest:plan(count)¶

Indicate how many tests will be performed.

Parameters:	count (`number`) –
Return:	nil

taptest:check()¶

Checks the number of tests performed.

The result will be a display saying # bad plan: ... if the number of completed tests is not equal to the number of tests specified by taptest:plan(...). (This is a purely Tarantool feature: “bad plan” messages are out of the TAP13 standard.)

This check should only be done after all planned tests are complete, so ordinarily taptest:check() will only appear at the end of a script. However, as a Tarantool extension, taptest:check() may appear at the end of any subtest. Therefore there are three ways to cause the check:

by calling taptest:check() at the end of a script,
by calling a function which ends with a call to taptest:check(),
or by calling taptest:test(‘…’, subtest-function-name) where subtest-function-name does not need to end with taptest:check() because it can be called after the subtest is complete.

Return:	true or false.
Rtype:	boolean

taptest:diag(message)¶

Display a diagnostic message.

Parameters:	message (`string`) – the message to be displayed.
Return:	nil

taptest:ok(condition, test-name)¶

This is a basic function which is used by other functions. Depending on the value of condition, print ‘ok’ or ‘not ok’ along with debugging information. Displays the message.

Parameters:	condition (`boolean`) – an expression which is true or false test-name (`string`) – name of the test
Return:	true or false.
Rtype:	boolean

Example:

tarantool> taptest:ok(true, 'x')
ok - x
---
- true
...
tarantool> tap = require('tap')
---
...
tarantool> taptest = tap.test('test-name')
TAP version 13
---
...
tarantool> taptest:ok(1 + 1 == 2, 'X')
ok - X
---
- true
...

taptest:fail(test-name)¶

taptest:fail('x') is equivalent to taptest:ok(false, 'x'). Displays the message.

Parameters:	test-name (`string`) – name of the test
Return:	true or false.
Rtype:	boolean

taptest:skip(message)¶

taptest:skip('x') is equivalent to taptest:ok(true, 'x' .. '# skip'). Displays the message.

Parameters:	test-name (`string`) – name of the test
Return:	nil

Example:

tarantool> taptest:skip('message')
ok - message # skip
---
- true
...

taptest:is(got, expected, test-name)¶

Check whether the first argument equals the second argument. Displays extensive message if the result is false.

Parameters:	got (`number`) – actual result expected (`number`) – expected result test-name (`string`) – name of the test
Return:	true or false.
Rtype:	boolean

taptest:isnt(got, expected, test-name)¶

This is the negation of taptest:is().

Parameters:	got (`number`) – actual result expected (`number`) – expected result test-name (`string`) – name of the test
Return:	true or false.
Rtype:	boolean

taptest:is_deeply(got, expected, test-name)¶

Recursive version of taptest:is(...), which can be used to compare tables as well as scalar values.

Return:	true or false.
Rtype:	boolean
Parameters:	got (`lua-value`) – actual result expected (`lua-value`) – expected result test-name (`string`) – name of the test

taptest:like(got, expected, test-name)¶

Verify a string against a pattern. Ok if match is found.

Return:	true or false.
Rtype:	boolean
Parameters:	got (`lua-value`) – actual result expected (`lua-value`) – pattern test-name (`string`) – name of the test

test:like(tarantool.version, '^[1-9]', "version")

taptest:unlike(got, expected, test-name)¶

This is the negation of taptest:like().

Parameters:	got (`number`) – actual result expected (`number`) – pattern test-name (`string`) – name of the test
Return:	true or false.
Rtype:	boolean

taptest:isnil(value, message, extra)¶

taptest:isstring(value, message, extra)¶

taptest:isnumber(value, message, extra)¶

taptest:istable(value, message, extra)¶

taptest:isboolean(value, message, extra)¶

taptest:isudata(value, utype, message, extra)¶

taptest:iscdata(value, ctype, message, extra)¶

Test whether a value has a particular type. Displays a long message if the value is not of the specified type.

Parameters:	value (`lua-value`) – value the type of which is to be checked utype (`string`) – type of data that a passed value should have ctype (`string`) – type of data that a passed value should have message (`string`) – text that will be shown to the user in case of failure
Return:	true or false.
Rtype:	boolean

test:iscdata(slab_info.quota_size, ffi.typeof('uint64_t'), 'memcached.slab.info().quota_size returns a cdata')

taptest.strict¶

Set taptest.strict=true if taptest:is() and taptest:isnt() and taptest:is_deeply() must be compared strictly with nil. Set taptest.strict=false if nil and box.NULL both have the same effect.

The default is false. For example, if and only if taptest.strict=true has happened, then taptest:is_deeply({a = box.NULL}, {}) will return false.

Since v. 2.8.3, taptest.strict is inherited in all subtests:

t = require('tap').test('123')
t.strict = true

t:is_deeply({a = box.NULL}, {}) -- false

t:test('subtest', function(t)
    t:is_deeply({a = box.NULL}, {}) -- also false
end)

Example

To run this example: put the script in a file named ./tap.lua, then make tap.lua executable by saying chmod a+x ./tap.lua, then execute using Tarantool as a script processor by saying ./tap.lua.

#!/usr/bin/tarantool
local tap = require('tap')
test = tap.test("my test name")
test:plan(2)
test:ok(2 * 2 == 4, "2 * 2 is 4")
test:test("some subtests for test2", function(test)
    test:plan(2)
    test:is(2 + 2, 4, "2 + 2 is 4")
    test:isnt(2 + 3, 4, "2 + 3 is not 4")
end)
test:check()

The output from the above script will look approximately like this:

TAP version 13
1..2
ok - 2 * 2 is 4
    # Some subtests for test2
    1..2
    ok - 2 + 2 is 4,
    ok - 2 + 3 is not 4
    # Some subtests for test2: end
ok - some subtests for test2

Version:

Module tap

Overview

API Reference

Example