--[[
Minimal test framework for Lua.
lester - v0.1.2 - 15/Feb/2021
Eduardo Bart - edub4rt@gmail.com
https://github.com/edubart/lester
Minimal Lua test framework.
See end of file for LICENSE.
]]

--[[--
Lester is a minimal unit testing framework for Lua with a focus on being simple to use.

## Features

* Minimal, just one file.
* Self contained, no external dependencies.
* Simple and hackable when needed.
* Use `describe` and `it` blocks to describe tests.
* Supports `before` and `after` handlers.
* Colored output.
* Configurable via the script or with environment variables.
* Quiet mode, to use in live development.
* Optionally filter tests by name.
* Show traceback on errors.
* Show time to complete tests.
* Works with Lua 5.1+.
* Efficient.

## Usage

Copy `lester.lua` file to a project and require it,
which returns a table that includes all of the functionality:

```lua
local lester = require 'lester'
local describe, it, expect = lester.describe, lester.it, lester.expect

-- Customize lester configuration.
lester.show_traceback = false

describe('my project', function()
  lester.before(function()
    -- This function is run before every test.
  end)

  describe('module1', function() -- Describe blocks can be nested.
    it('feature1', function()
      expect.equal('something', 'something') -- Pass.
    end)

    it('feature2', function()
      expect.truthy(false) -- Fail.
    end)
  end)
end)

lester.report() -- Print overall statistic of the tests run.
lester.exit() -- Exit with success if all tests passed.
```

## Customizing output with environment variables

To customize the output of lester externally,
you can set the following environment variables before running a test suite:

* `LESTER_QUIET="true"`, omit print of passed tests.
* `LESTER_COLORED="false"`, disable colored output.
* `LESTER_SHOW_TRACEBACK="false"`, disable traceback on test failures.
* `LESTER_SHOW_ERROR="false"`, omit print of error description of failed tests.
* `LESTER_STOP_ON_FAIL="true"`, stop on first test failure.
* `LESTER_UTF8TERM="false"`, disable printing of UTF-8 characters.
* `LESTER_FILTER="some text"`, filter the tests that should be run.

Note that these configurations can be changed via script too, check the documentation.

]]

-- Returns whether the terminal supports UTF-8 characters.
local function is_utf8term()
  local lang = os.getenv('LANG')
  return (lang and lang:lower():match('utf%-?8$')) and true or false
end

-- Returns whether a system environment variable is "true".
local function getboolenv(varname, default)
  local val = os.getenv(varname)
  if val == 'true' then
    return true
  elseif val == 'false' then
    return false
  end
  return default
end

-- The lester module.
local lester = {
  --- Weather lines of passed tests should not be printed. False by default.
  quiet = getboolenv('LESTER_QUIET', false),
  --- Weather the output should  be colorized. True by default.
  colored = getboolenv('LESTER_COLORED', true),
  --- Weather a traceback must be shown on test failures. True by default.
  show_traceback = getboolenv('LESTER_SHOW_TRACEBACK', true),
  --- Weather the error description of a test failure should be shown. True by default.
  show_error = getboolenv('LESTER_SHOW_ERROR', true),
  --- Weather test suite should exit on first test failure. False by default.
  stop_on_fail = getboolenv('LESTER_STOP_ON_FAIL', false),
  --- Weather we can print UTF-8 characters to the terminal. True by default when supported.
  utf8term = getboolenv('LESTER_UTF8TERM', is_utf8term()),
  --- A string with a lua pattern to filter tests. Nil by default.
  filter = os.getenv('LESTER_FILTER'),
  --- Function to retrieve time in seconds with milliseconds precision, `os.clock` by default.
  seconds = os.clock,
}

-- Variables used internally for the lester state.
local lester_start = nil
local last_succeeded = false
local level = 0
local successes = 0
local total_successes = 0
local failures = 0
local total_failures = 0
local start = 0
local befores = {}
local afters = {}
local names = {}

-- Color codes.
local color_codes = {
  reset = string.char(27) .. '[0m',
  bright = string.char(27) .. '[1m',
  red = string.char(27) .. '[31m',
  green = string.char(27) .. '[32m',
  blue = string.char(27) .. '[34m',
  magenta = string.char(27) .. '[35m',
}

-- Colors table, returning proper color code if colored mode is enabled.
local colors = setmetatable({}, { __index = function(_, key)
  return lester.colored and color_codes[key] or ''
end})

--- Table of terminal colors codes, can be customized.
lester.colors = colors

--- Describe a block of tests, which consists in a set of tests.
-- Describes can be nested.
-- @param name A string used to describe the block.
-- @param func A function containing all the tests or other describes.
function lester.describe(name, func)
  if level == 0 then -- Get start time for top level describe blocks.
    start = lester.seconds()
    if not lester_start then
      lester_start = start
    end
  end
  -- Setup describe block variables.
  failures = 0
  successes = 0
  level = level + 1
  names[level] = name
  -- Run the describe block.
  func()
  -- Cleanup describe block.
  afters[level] = nil
  befores[level] = nil
  names[level] = nil
  level = level - 1
  -- Pretty print statistics for top level describe block.
  if level == 0 and not lester.quiet and (successes > 0 or failures > 0) then
    local io_write = io.write
    local colors_reset, colors_green = colors.reset, colors.green
    io_write(failures == 0 and colors_green or colors.red, '[====] ',
             colors.magenta, name, colors_reset, ' | ',
             colors_green, successes, colors_reset, ' successes / ')
    if failures > 0 then
      io_write(colors.red, failures, colors_reset, ' failures / ')
    end
    io_write(colors.bright, string.format('%.6f', lester.seconds() - start), colors_reset, ' seconds\n')
  end
end

-- Error handler used to get traceback for errors.
local function xpcall_error_handler(err)
  return debug.traceback(tostring(err), 2)
end

-- Pretty print the line on the test file where an error happened.
local function show_error_line(err)
  local info = debug.getinfo(3)
  local io_write = io.write
  local colors_reset = colors.reset
  local short_src, currentline = info.short_src, info.currentline
  io_write(' (', colors.blue, short_src, colors_reset,
           ':', colors.bright, currentline, colors_reset)
  if err and lester.show_traceback then
    local fnsrc = short_src..':'..currentline
    for cap1, cap2 in err:gmatch('\t[^\n:]+:(%d+): in function <([^>]+)>\n') do
      if cap2 == fnsrc then
        io_write('/', colors.bright, cap1, colors_reset)
        break
      end
    end
  end
  io_write(')')
end

-- Pretty print the test name, with breadcrumb for the describe blocks.
local function show_test_name(name)
  local io_write = io.write
  local colors_reset = colors.reset
  for _,descname in ipairs(names) do
    io_write(colors.magenta, descname, colors_reset, ' | ')
  end
  io_write(colors.bright, name, colors_reset)
end

--- Declare a test, which consists of a set of assertions.
-- @param name A name for the test.
-- @param func The function containing all assertions.
function lester.it(name, func)
  -- Skip the test if it does not match the filter.
  if lester.filter then
    local fullname = table.concat(names, ' | ')..' | '..name
    if not fullname:match(lester.filter) then
      return
    end
  end
  -- Execute before handlers.
  for _,levelbefores in ipairs(befores) do
    for _,beforefn in ipairs(levelbefores) do
      beforefn(name)
    end
  end
  -- Run the test, capturing errors if any.
  local success, err
  if lester.show_traceback then
    success, err = xpcall(func, xpcall_error_handler)
  else
    success, err = pcall(func)
    if not success and err then
      err = tostring(err)
    end
  end
  -- Count successes and failures.
  if success then
    successes = successes + 1
    total_successes = total_successes + 1
  else
    failures = failures + 1
    total_failures = total_failures + 1
  end
  local io_write = io.write
  local colors_reset = colors.reset
  -- Print the test run.
  if not lester.quiet then -- Show test status and complete test name.
    if success then
      io_write(colors.green, '[PASS] ', colors_reset)
    else
      io_write(colors.red, '[FAIL] ', colors_reset)
    end
    show_test_name(name)
    if not success then
      show_error_line(err)
    end
    io_write('\n')
  else
    if success then -- Show just a character hinting that the test succeeded.
      local o = (lester.utf8term and lester.colored) and
                string.char(226, 151, 143) or 'o'
      io_write(colors.green, o, colors_reset)
    else -- Show complete test name on failure.
      io_write(last_succeeded and '\n' or '',
               colors.red, '[FAIL] ', colors_reset)
      show_test_name(name)
      show_error_line(err)
      io_write('\n')
    end
  end
  -- Print error message, colorizing its output if possible.
  if err and lester.show_error then
    if lester.colored then
      local errfile, errline, errmsg, rest = err:match('^([^:\n]+):(%d+): ([^\n]+)(.*)')
      if errfile and errline and errmsg and rest then
        io_write(colors.blue, errfile, colors_reset,
                 ':', colors.bright, errline, colors_reset, ': ')
        if errmsg:match('^%w([^:]*)$') then
          io_write(colors.red, errmsg, colors_reset)
        else
          io_write(errmsg)
        end
        err = rest
      end
    end
    io_write(err, '\n\n')
  end
  io.flush()
  -- Stop on failure.
  if not success and lester.stop_on_fail then
    if lester.quiet then
      io_write('\n')
      io.flush()
    end
    lester.exit()
  end
  -- Execute after handlers.
  for _,levelafters in ipairs(afters) do
    for _,afterfn in ipairs(levelafters) do
      afterfn(name)
    end
  end
  last_succeeded = success
end

--- Set a function that is called before every test inside a describe block.
-- A single string containing the name of the test about to be run will be passed to `func`.
function lester.before(func)
  local levelbefores = befores[level]
  if not levelbefores then
    levelbefores = {}
    befores[level] = levelbefores
  end
  levelbefores[#levelbefores+1] = func
end

--- Set a function that is called after every test inside a describe block.
-- A single string containing the name of the test that was finished will be passed to `func`.
-- The function is executed independently if the test passed or failed.
function lester.after(func)
  local levelafters = afters[level]
  if not levelafters then
    levelafters = {}
    afters[level] = levelafters
  end
  levelafters[#levelafters+1] = func
end

--- Pretty print statistics of all test runs.
-- With total success, total failures and run time in seconds.
function lester.report()
  local now = lester.seconds()
  local colors_reset = colors.reset
  io.write(lester.quiet and '\n' or '',
           colors.green, total_successes, colors_reset, ' successes / ',
           colors.red, total_failures, colors_reset, ' failures / ',
           colors.bright, string.format('%.6f', now - (lester_start or now)), colors_reset, ' seconds\n')
  io.flush()
  return total_failures == 0
end

--- Exit the application with success code if all tests passed, or failure code otherwise.
function lester.exit()
  os.exit(total_failures == 0)
end

local expect = {}
--- Expect module, containing utility function for doing assertions inside a test.
lester.expect = expect

--- Check if a function fails with an error.
-- If `expected` is nil then any error is accepted.
-- If `expected` is a string then we check if the error contains that string.
-- If `expected` is anything else then we check if both are equal.
function expect.fail(func, expected)
  local ok, err = pcall(func)
  if ok then
    error('expected function to fail', 2)
  elseif expected ~= nil then
    local found = expected == err
    if not found and type(expected) == 'string' then
      found = string.find(tostring(err), expected, 1, true)
    end
    if not found then
      error('expected function to fail\nexpected:\n'..tostring(expected)..'\ngot:\n'..tostring(err), 2)
    end
  end
end

--- Check if a function does not fail with a error.
function expect.not_fail(func)
  local ok, err = pcall(func)
  if not ok then
    error('expected function to not fail\ngot error:\n'..tostring(err), 2)
  end
end

--- Check if a value is not `nil`.
function expect.exist(v)
  if v == nil then
    error('expected value to exist\ngot:\n'..tostring(v), 2)
  end
end

--- Check if a value is `nil`.
function expect.not_exist(v)
  if v ~= nil then
    error('expected value to not exist\ngot:\n'..tostring(v), 2)
  end
end

--- Check if an expression is evaluates to `true`.
function expect.truthy(v)
  if not v then
    error('expected expression to be true\ngot:\n'..tostring(v), 2)
  end
end

--- Check if an expression is evaluates to `false`.
function expect.falsy(v)
  if v then
    error('expected expression to be false\ngot:\n'..tostring(v), 2)
  end
end

--- Compare if two values are equal, considering nested tables.
local function strict_eq(t1, t2)
  if rawequal(t1, t2) then return true end
  if type(t1) ~= type(t2) then return false end
  if type(t1) ~= 'table' then return t1 == t2 end
  if getmetatable(t1) ~= getmetatable(t2) then return false end
  for k,v1 in pairs(t1) do
    if not strict_eq(v1, t2[k]) then return false end
  end
  for k,v2 in pairs(t2) do
    if not strict_eq(v2, t1[k]) then return false end
  end
  return true
end

--- Check if two values are equal.
function expect.equal(v1, v2)
  if not strict_eq(v1, v2) then
    error('expected values to be equal\nfirst value:\n'..tostring(v1)..'\nsecond value:\n'..tostring(v2), 2)
  end
end

--- Check if two values are not equal.
function expect.not_equal(v1, v2)
  if strict_eq(v1, v2) then
    error('expected values to be not equal\nfirst value:\n'..tostring(v1)..'\nsecond value:\n'..tostring(v2), 2)
  end
end

return lester

--[[
The MIT License (MIT)

Copyright (c) 2021 Eduardo Bart (https://github.com/edubart)

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
]]
