diff options
Diffstat (limited to 'meta/3rd/luassert/library/luassert.lua')
| -rw-r--r-- | meta/3rd/luassert/library/luassert.lua | 442 |
1 files changed, 442 insertions, 0 deletions
diff --git a/meta/3rd/luassert/library/luassert.lua b/meta/3rd/luassert/library/luassert.lua new file mode 100644 index 00000000..21f2fe9a --- /dev/null +++ b/meta/3rd/luassert/library/luassert.lua @@ -0,0 +1,442 @@ +---@meta + +---@class luassert.internal +local internal = {} + +---@class luassert:luassert.internal +local luassert = {} + +--#region Assertions + +---Assert that `value == true`. +---@param value any The value to confirm is `true`. +function internal.True(value) end + +internal.is_true = internal.True +internal.is_not_true = internal.True + +---Assert that `value == false`. +---@param value any The value to confirm is `false`. +function internal.False(value) end + +internal.is_false = internal.False +internal.is_not_false = internal.False + +---Assert that `type(value) == "boolean"`. +---@param value any The value to confirm is of type `boolean`. +function internal.Boolean(value) end + +internal.boolean = internal.Boolean +internal.is_boolean = internal.Boolean +internal.is_not_boolean = internal.Boolean + +---Assert that `type(value) == "number"`. +---@param value any The value to confirm is of type `number`. +function internal.Number(value) end + +internal.number = internal.Number +internal.is_number = internal.Number +internal.is_not_number = internal.Number + +---Assert that `type(value) == "string"`. +---@param value any The value to confirm is of type `string`. +function internal.String(value) end + +internal.string = internal.String +internal.is_string = internal.String +internal.is_not_string = internal.String + +---Assert that `type(value) == "table"`. +---@param value any The value to confirm is of type `table`. +function internal.Table(value) end + +internal.table = internal.Table +internal.is_table = internal.Table +internal.is_not_table = internal.Table + +---Assert that `type(value) == "nil"`. +---@param value any The value to confirm is of type `nil`. +function internal.Nil(value) end + +internal.is_nil = internal.Nil +internal.is_not_nil = internal.Nil + +---Assert that `type(value) == "userdata"`. +---@param value any The value to confirm is of type `userdata`. +function internal.Userdata(value) end + +internal.userdata = internal.Userdata +internal.is_userdata = internal.Userdata +internal.is_not_userdata = internal.Userdata + +---Assert that `type(value) == "function"`. +---@param value any The value to confirm is of type `function`. +function internal.Function(value) end + +internal.is_function = internal.Function +internal.is_not_function = internal.Function + +---Assert that `type(value) == "thread"`. +---@param value any The value to confirm is of type `thread`. +function internal.Thread(value) end + +internal.thread = internal.Thread +internal.is_thread = internal.Thread +internal.is_not_thread = internal.Thread + + +---Assert that a value is truthy. +---@param value any The value to confirm is truthy. +function internal.truthy(value) end + +internal.Truthy = internal.truthy +internal.is_truthy = internal.truthy +internal.is_not_truthy = internal.truthy + +---Assert that a value is falsy. +---@param value any The value to confirm is falsy. +function internal.falsy(value) end + +internal.Falsy = internal.falsy +internal.is_falsy = internal.falsy +internal.is_not_falsy = internal.falsy + +---Assert that a callback throws an error. +---@param callback function A callback function that should error +---@param error? string The specific error message that will be asserted +function internal.error(callback, error) end + +internal.Error = internal.error +internal.has_error = internal.error +internal.no_error = internal.error +internal.no_has_error = internal.error +internal.has_no_error = internal.error + +--- the api is the same as string.find +---@param pattern string +---@param actual string +---@param init? integer +---@param plain? boolean +---## Example +--[[ +```lua + it("Checks matches() assertion does string matching", function() + assert.is.error(function() assert.matches('.*') end) -- minimum 2 arguments + assert.is.error(function() assert.matches(nil, 's') end) -- arg1 must be a string + assert.is.error(function() assert.matches('s', {}) end) -- arg2 must be convertable to string + assert.is.error(function() assert.matches('s', 's', 's', 's') end) -- arg3 or arg4 must be a number or nil + assert.matches("%w+", "test") + assert.has.match("%w+", "test") + assert.has_no.match("%d+", "derp") + assert.has.match("test", "test", nil, true) + assert.has_no.match("%w+", "test", nil, true) + assert.has.match("^test", "123 test", 5) + assert.has_no.match("%d+", "123 test", '4') + end) +``` +]] +function internal.matches(pattern, actual, init, plain) end + +internal.is_matches = internal.matches +internal.is_not_matches = internal.matches + +internal.match = internal.matches +internal.is_match = internal.matches +internal.is_not_match = internal.matches + +---Assert that two values are near (equal to within a tolerance). +---@param expected number The expected value +---@param actual number The actual value +---@param tolerance number The tolerable difference between the two values +---## Example +--[[ + ```lua + it("Checks near() assertion handles tolerances", function() + assert.is.error(function() assert.near(0) end) -- minimum 3 arguments + assert.is.error(function() assert.near(0, 0) end) -- minimum 3 arguments + assert.is.error(function() assert.near('a', 0, 0) end) -- arg1 must be convertable to number + assert.is.error(function() assert.near(0, 'a', 0) end) -- arg2 must be convertable to number + assert.is.error(function() assert.near(0, 0, 'a') end) -- arg3 must be convertable to number + assert.is.near(1.5, 2.0, 0.5) + assert.is.near('1.5', '2.0', '0.5') + assert.is_not.near(1.5, 2.0, 0.499) + assert.is_not.near('1.5', '2.0', '0.499') + end) + ``` +]] +function internal.near(expected, actual, tolerance) end + +internal.Near = internal.near +internal.is_near = internal.near +internal.is_not_near = internal.near + +---Check that two or more items are equal. +--- +---When comparing tables, a reference check will be used. +---@param expected any The expected value +---@param ... any Values to check the equality of +function internal.equal(expected, ...) end + +internal.Equal = internal.equal +internal.are_equal = internal.equal +internal.are_not_equal = internal.equal + +---Check that two or more items that are considered the "same". +--- +---When comparing tables, a deep compare will be performed. +---@param expected any The expected value +---@param ... any Values to check +function internal.same(expected, ...) end + +internal.Same = internal.same +internal.are_same = internal.same +internal.are_not_same = internal.same + +--- Number of return values of function +---@param argument_number integer +---@param func fun() +function internal.returned_arguments(argument_number, func) end + +internal.not_returned_arguments = internal.returned_arguments + +--- check error message by string.match/string.find(`plain`=true) +---@param func function +---@param pattern string +---@param init? integer +---@param plain? boolean +---##Example +--[[ +```lua + it("Checks error_matches to accept only callable arguments", function() + local t_ok = setmetatable( {}, { __call = function() end } ) + local t_nok = setmetatable( {}, { __call = function() error("some error") end } ) + local f_ok = function() end + local f_nok = function() error("some error") end + + assert.error_matches(f_nok, ".*") + assert.no_error_matches(f_ok, ".*") + assert.error_matches(t_nok, ".*") + assert.no_error_matches(t_ok, ".*") + end) +``` +]] +function internal.error_matches(func, pattern, init, plain) end + +internal.no_error_matches = internal.error_matches + +internal.error_match = internal.error_matches +internal.no_error_match = internal.error_matches + +internal.matches_error = internal.error_matches +internal.no_matches_error = internal.error_matches + +internal.match_error = internal.error_matches +internal.no_match_error = internal.error_matches + +--#endregion + +--[[ Helpers ]] + +--#region + +---Assert that all numbers in two arrays are within a specified tolerance of +---each other. +---@param expected number[] The expected values +---@param actual number[] The actual values +---@param tolerance number The tolerable difference between the values in the two arrays +function internal.all_near(expected, actual, tolerance) end + +internal.are_all_near = internal.all_near +internal.are_not_all_near = internal.all_near + +--- array is uniqued +---@param arr any[] +---## Example +---```lua +---it("Checks to see if table1 only contains unique elements", function() +--- local table2 = { derp = false} +--- local table3 = { derp = true } +--- local table1 = {table2,table3} +--- local tablenotunique = {table2,table2} +--- assert.is.unique(table1) +--- assert.is_not.unique(tablenotunique) +--- end) +---``` +function internal.unique(arr) end + +internal.is_unique = internal.unique +internal.is_not_unique = internal.unique + +--#endregion + +--#region Spies + +---Perform an assertion on a spy object. This will allow you to call further +---functions to perform an assertion. +---@param spy luassert.spy The spy object to begin asserting +---@return luassert.spy.assert spyAssert A new object that has further assert function options +function internal.spy(spy) end + +---Perform an assertion on a stub object. This will allow you to call further +---functions to perform an assertion. +---@param stub luassert.spy The stub object to begin asserting +---@return luassert.spy.assert stubAssert A new object that has further assert function options +function internal.stub(stub) end + +--#endregion + +--#region Array + +---Perform an assertion on an array object. This will allow you to call further +---function to perform an assertion. +---@param object table<integer, any> The array object to begin asserting +---@return luassert.array arrayAssert A new object that has further assert function options +function internal.array(object) end + +--#endregion + +--#region test apis + +--- register custom assertions +---@param namespace 'assertion' | 'matcher' | 'modifier' | string +---@param name string +---@param callback function +---@param positive_message string +---@param negative_message string +---## Example +--[[ +```lua + it("Checks register creates custom assertions", function() + local say = require("say") + + local function has_property(state, arguments) + local property = arguments[1] + local table = arguments[2] + for key, value in pairs(table) do + if key == property then + return true + end + end + return false + end + + say:set_namespace("en") + say:set("assertion.has_property.positive", "Expected property %s in:\n%s") + say:set("assertion.has_property.negative", "Expected property %s to not be in:\n%s") + assert:register("assertion", "has_property", has_property, "assertion.has_property.positive", "assertion.has_property.negative") + + assert.has_property("name", { name = "jack" }) + assert.has.property("name", { name = "jack" }) + assert.not_has_property("surname", { name = "jack" }) + assert.Not.has.property("surname", { name = "jack" }) + assert.has_error(function() assert.has_property("surname", { name = "jack" }) end) + assert.has_error(function() assert.has.property("surname", { name = "jack" }) end) + assert.has_error(function() assert.no_has_property("name", { name = "jack" }) end) + assert.has_error(function() assert.no.has.property("name", { name = "jack" }) end) + end) +``` +]] +function luassert:register(namespace, name, callback, positive_message, negative_message) end + +--[[ + ### Customized formatters +The formatters are functions taking a single argument that needs to be converted to a string representation. The formatter should examine the value provided, if it can format the value, it should return the formatted string, otherwise it should return `nil`. +Formatters can be added through `assert:add_formatter(formatter_func)`, and removed by calling `assert:remove_formatter(formatter_func)`. + +Example using the included binary string formatter: +```lua +local binstring = require("luassert.formatters.binarystring") + +describe("Tests using a binary string formatter", function() + + setup(function() + assert:add_formatter(binstring) + end) + + teardown(function() + assert:remove_formatter(binstring) + end) + + it("tests a string comparison with binary formatting", function() + local s1, s2 = "", "" + for n = 65,88 do + s1 = s1 .. string.char(n) + s2 = string.char(n) .. s2 + end + assert.are.same(s1, s2) + + end) + +end) +``` + +Because this formatter formats string values, and is added last, it will take precedence over the regular string formatter. The results will be: +``` +Failure: ...ua projects\busted\formatter\spec\formatter_spec.lua @ 13 +tests a string comparison with binary formatting +...ua projects\busted\formatter\spec\formatter_spec.lua:19: Expected objects to be the same. Passed in: +Binary string length; 24 bytes +58 57 56 55 54 53 52 51 50 4f 4e 4d 4c 4b 4a 49 XWVUTSRQ PONMLKJI +48 47 46 45 44 43 42 41 HGFEDCBA + +Expected: +Binary string length; 24 bytes +41 42 43 44 45 46 47 48 49 4a 4b 4c 4d 4e 4f 50 ABCDEFGH IJKLMNOP +51 52 53 54 55 56 57 58 QRSTUVWX +``` +]] +---@param callback fun(obj:any):string|nil +function luassert:add_formatter(callback) end + +---@param fmtr function +function luassert:remove_formatter(fmtr) end + +--- To register state information 'parameters' can be used. The parameter is included in a snapshot and can hence be restored in between tests. For an example see `Configuring table depth display` below. +---@param name any +---@param value any +---## Example +--[[ +```lua +assert:set_parameter("my_param_name", 1) +local s = assert:snapshot() +assert:set_parameter("my_param_name", 2) +s:revert() +assert.are.equal(1, assert:get_parameter("my_param_name")) +``` +]] +function luassert:set_parameter(name, value) end + +--- get current snapshot parameter +---@param name any +---@return any value +function luassert:get_parameter(name) end + +---To be able to revert changes created by tests, inserting spies and stubs for example, luassert supports 'snapshots'. A snapshot includes the following; +---@return {revert:fun()} +function luassert:snapshot() end + +--#endregion + +--- unregister custom assertions +---@param namespace 'assertion' | 'matcher' | 'modifier' | string +---@param name string +function luassert:unregister(namespace, name) end + +--#region modifier namespace + +internal.are = internal +internal.is = internal +internal.has = internal +internal.does = internal + +internal.is_not = internal +internal.are_not = internal +internal.has_no = internal +internal.no_has = internal +internal.does_not = internal +internal.no = internal +internal.Not = internal + +--#endregion + +return luassert |