Module lua-nucleo.ensure

Tools to ensure correct code behaviour

This file is a part of lua-nucleo library

Info:

  • Copyright: lua-nucleo authors (see file COPYRIGHT for the license)

Local Functions

ensure (msg, value, ...)
ensure_equals (msg, actual, expected)
ensure_is (msg, value, expected_type)
ensure_tequals (msg, actual, expected)
ensure_tdeepequals (msg, actual, expected)
ensure_strequals (msg, actual, expected, ...)
ensure_strvariant (msg, actual, expected, ...) Checks if the actual string exists in the expected linear string array.
ensure_strlist (msg, actual, expected_prefix, expected_elements_list, expected_sep, expected_suffix, ...) Checks if the actual string is constructed by the elements of the expected_elements_list linear string array table.
ensure_strpermutations (msg, actual, expected_prefix, expected_elements_list, expected_sep, expected_suffix, ...) Checks if the actual string is constructed by the elements of the expected_elements_list linear string array table.
ensure_error (msg, expected_message, res, actual_message)
ensure_error_with_substring (msg, substring, res, err)
ensure_fails_with_substring (msg, fn, substring)
ensure_has_substring (msg, str, substring)
ensure_aposteriori_probability (num_runs, weights, stats, max_acceptable_diff) We want 99.9% probability of success Would not work for high-contrast weights.
ensure_returns (msg, num, expected, ...)


Local Functions

ensure (msg, value, ...)

Parameters:

  • msg
  • value
  • ...
ensure_equals (msg, actual, expected)

Parameters:

  • msg
  • actual
  • expected
ensure_is (msg, value, expected_type)

Parameters:

  • msg
  • value
  • expected_type
ensure_tequals (msg, actual, expected)

Parameters:

  • msg
  • actual
  • expected
ensure_tdeepequals (msg, actual, expected)

Parameters:

  • msg
  • actual
  • expected
ensure_strequals (msg, actual, expected, ...)

Parameters:

  • msg
  • actual
  • expected
  • ...
ensure_strvariant (msg, actual, expected, ...)
Checks if the actual string exists in the expected linear string array.
Returns all the arguments intact cutting the msg at beginning on success.
Raises the error on fail.

Parameters:

  • msg string Failing message that will be used in the error message if the check fails.
  • actual string A string to check.
  • expected string[] The linear array table of strings.
  • ... any[] Custom arguments.

Returns:

  1. string actual intact.
  2. string[] expected intact.
  3. any[] ... The rest of the arguments intact.

Raises:

ensure_strvariant failed error if unable to find the actual string in expected.

Usage:

    local ensure_strvariant
      = import 'lua-nucleo/ensure.lua'
      {
        'ensure_strvariant'
      }

-- will pass without errors:
ensure_strvariant('find elem1', 'elem1', { 'elem0', 'elem1', 'elem2' })

-- will throw the error:
ensure_strvariant(
    'find the_element_that_cannot_be_found',
    'the_element_that_cannot_be_found',
    { 'elem0', 'elem1', 'elem2' }
  )
ensure_strlist (msg, actual, expected_prefix, expected_elements_list, expected_sep, expected_suffix, ...)
Checks if the actual string is constructed by the elements of the expected_elements_list linear string array table. Expected that elements are joined together with the expected_sep in between and not necessarily have the same order as in the expected_elements_list. Also, expected that the constructed list is prefixed by the expected_prefix and terminated by the expected_suffix.
Returns all the arguments intact cutting the msg at beginning on success.
Raises the error on fail.
Best for simple long lists.

How it works: cut expected_prefix and expected_suffix from the actual and break by expected_sep. Then find missing and excess elements in two array traverses. Raises the error if found any.

Parameters:

  • msg string Failing message that will be used in the error message if the check fails.
  • actual string A string to check.
  • expected_prefix string Expected prefix. Expected that the actual must start with the expected_prefix.
  • expected_elements_list string[] Expected elements list. Expected that expected_elements_list elements exist in the actual whatever the original order from the expected_elements_list.
  • expected_sep string Expected separator character. Expected that this separator is used to join list elements together.
  • expected_suffix string Expected suffix character. Expected that the actual ends with the expected_suffix.
  • ... any[] Custom arguments.

Returns:

  1. string actual intact.
  2. string expected_prefix intact.
  3. string[] expected_elements_list intact.
  4. string expected_sep intact.
  5. string expected_suffix intact.
  6. any[] ... The rest of the arguments intact.

Raises:

ensure_strlist failed error if the check fails.

Usage:

    local ensure_strlist
      = import 'lua-nucleo/ensure.lua'
      {
        'ensure_strlist'
      }

-- will pass without errors:
ensure_strlist(
    'output check',
    '(a,b,c,d,e)',
    '(',
    { 'a', 'b', 'c', 'd', 'e' },
    ',',
    ')'
  )

-- will fail because the real separator is ', ':
-- ensure_strlist(
--     'output check',
--     '(a, b, c, d, e)',
--     '(',
--     { 'a', 'b', 'c', 'd', 'e' },
--     ',',
--     ')'
--   )

-- will pass without errors:
ensure_strlist(
    'output check',
    '1+b*c+m^2/2',
    '',
    { '1', 'b*c', 'm^2/2' },
    '+',
    ''
  )
ensure_strpermutations (msg, actual, expected_prefix, expected_elements_list, expected_sep, expected_suffix, ...)
Checks if the actual string is constructed by the elements of the expected_elements_list linear string array table. Expected that elements are joined together with the expected_sep in between and not necessarily have the same order as in the expected_elements_list. Also, expected that the constructed list is prefixed by the expected_prefix and terminated by the expected_suffix.
Returns all the arguments intact cutting the msg at beginning on success.
Raises the error on fail.
Best for complex short lists.

How it works: tifindallpermutations for the expected_elements_list then build a table array containing all possible actuals using expected_prefix, expected_sep, expected_suffix for each resulted permutation. The ensure_strvariant is invoked as ensure_strvariant(msg, actual, expected_actuals)

Parameters:

  • msg string Failing message that will be used in the error message if the check fails.
  • actual string A string to check.
  • expected_prefix string Expected prefix. Expected that the actual must start with the expected_prefix.
  • expected_elements_list string[] Expected elements list. Expected that expected_elements_list elements exist in the actual whatever the original order from the expected_elements_list.
  • expected_sep string Expected separator. Expected that this separator is used to join list elements together.
  • expected_suffix string Expected suffix / footer. Expected that the actual ends with the expected_suffix.
  • ... any[] Custom arguments.

Returns:

  1. string actual intact.
  2. string expected_prefix intact.
  3. string[] expected_elements_list intact.
  4. string expected_sep intact.
  5. string expected_suffix intact.
  6. any[] ... The rest of the arguments intact.

Raises:

ensure_strpermutations failed error if the check fails.

Usage:

    local ensure_strpermutations
      = import 'lua-nucleo/ensure.lua'
      {
        'ensure_strpermutations'
      }

-- will pass without errors:
ensure_strlist(
    'output check', "('a'+'b'+'c')", "('", { 'a', 'b', 'c' }) "'+'", "')"
  )
ensure_strlist(
    'output check', "('a'+'c'+'b')", "('", { 'a', 'b', 'c' }) "'+'", "')"
  )
ensure_strlist(
    'output check', "('c'+'a'+'b')", "('", { 'a', 'b', 'c' }) "'+'", "')"
  )
ensure_strlist(
    'output check', "('b'+'a'+'c')", "('", { 'a', 'b', 'c' }) "'+'", "')"
  )
ensure_strlist(
    'output check', "('b'+'c'+'a')", "('", { 'a', 'b', 'c' }) "'+'", "')"
)

-- wrong separator:
-- ensure_strlist(
--     'output check', "('a'+'b'+'c')", "('", { 'a', 'b', 'c' }) "' + '", "')"
--   )

-- wrong prefix:
-- ensure_strlist(
--     'output check', "['a'+'b'+'c')", "('", { 'a', 'b', 'c' }) "'+'", "')"
--   )

-- wrong suffix:
-- ensure_strlist(
--     'output check', "('a'+'b'+'c')", "('", { 'a', 'b', 'c' }) "'+'", "');"
--   )

-- missing elements:
-- ensure_strlist(
--     'output check', "('a'+'b')", "('", { 'a', 'b', 'c' }) "'+'", "');"
--   )

-- excess elements:
-- ensure_strlist(
--     'output check', "('a'+'b'+'c')", "('", { 'a', 'b' }) "'+'", "');"
--   )
ensure_error (msg, expected_message, res, actual_message)

Parameters:

  • msg
  • expected_message
  • res
  • actual_message
ensure_error_with_substring (msg, substring, res, err)

Parameters:

  • msg
  • substring
  • res
  • err
ensure_fails_with_substring (msg, fn, substring)

Parameters:

  • msg
  • fn
  • substring
ensure_has_substring (msg, str, substring)

Parameters:

  • msg
  • str
  • substring
ensure_aposteriori_probability (num_runs, weights, stats, max_acceptable_diff)
We want 99.9% probability of success Would not work for high-contrast weights. Use for tests only.

Parameters:

  • num_runs
  • weights
  • stats
  • max_acceptable_diff
ensure_returns (msg, num, expected, ...)

Parameters:

  • msg
  • num
  • expected
  • ...
generated by LDoc 1.4.6 Last updated 2021-04-22 13:57:02