8000 mini.nvim/lua/mini/test.lua at sync · gmh5225/mini.nvim · GitHub
[go: up one dir, main page]

Skip to content

Latest commit

 

History

History
2312 lines (2000 loc) · 85.5 KB

test.lua

File metadata and controls

2312 lines (2000 loc) · 85.5 KB
)
H.error(msg)
end
-- If output is test set, always use it (even if 'busted' tests were added)
if H.is_instance(t, 'testset') then set[file] = t end
end
H.busted_deemulate()
-- Convert to test cases. This also creates separate aligned array of hooks
-- which should be executed once regarding test case. This is needed to
-- correctly inject those hooks after filtering is done.
local raw_cases, raw_hooks_once = H.set_to_testcases(set)
-- Filter cases (at this stage don't have injected `hooks_once`)
local cases, hooks_once = {}, {}
for i, c in ipairs(raw_cases) do
if opts.filter_cases(c) then
table.insert(cases, c)
table.insert(hooks_once, raw_hooks_once[i])
end
end
-- Inject `hooks_once` into appropriate cases
H.inject_hooks_once(cases, hooks_once)
return cases
end
--- Execute array of test cases
---
--- Overview of execution process:
--- - Reset `all_cases` in |MiniTest.current| with `cases` input.
--- - Call `reporter.start(cases)` (if present).
--- - Execute each case in natural array order (aligned with their integer
--- keys). Set `MiniTest.current.case` to currently executed case. Detailed
--- test case execution is described in |MiniTest-test-case|. After any state
--- change, call `reporter.update(case_num)` (if present), where `case_num` is an
--- integer key of current test case.
--- - Call `reporter.finish()` (if present).
---
--- Notes:
--- - Execution is done in asynchronous fashion with scheduling. This allows
--- making meaningful progress report during execution.
--- - This function doesn't return anything. Instead, it updates `cases` in
--- place with proper `exec` field. Use `all_cases` at |MiniTest.current| to
--- look at execution result.
---
---@param cases table Array of test cases (see |MiniTest-test-case|).
---@param opts table|nil Options controlling case collection. Possible fields:
--- - <reporter> - table with possible callable fields `start`, `update`,
--- `finish`. Default: |MiniTest.gen_reporter.buffer()| in interactive
--- usage and |MiniTest.gen_reporter.stdout()| in headless usage.
--- - <stop_on_error> - whether to stop execution (see |MiniTest.stop()|)
--- after first error. Default: `false`.
MiniTest.execute = function(cases, opts)
vim.validate({ cases = { cases, 'table' } })
MiniTest.current.all_cases = cases
-- Verify correct arguments
if #cases == 0 then
H.message('No cases to execute.')
return
end
opts = vim.tbl_deep_extend('force', H.get_config().execute, opts or {})
local reporter = opts.reporter or (H.is_headless and MiniTest.gen_reporter.stdout() or MiniTest.gen_reporter.buffer())
if type(reporter) ~= 'table' then
H.message('`opts.reporter` should be table or `nil`.')
return
end
opts.reporter = reporter
-- Start execution
H.cache = { is_executing = true }
vim.schedule(function() H.exec_callable(reporter.start, cases) end)
for case_num, cur_case in ipairs(cases) do
-- Schedule execution in async fashion. This allows doing other things
-- while tests are executed.
local schedule_step = H.make_step_scheduler(cur_case, case_num, opts)
vim.schedule(function() MiniTest.current.case = cur_case end)
for i, hook_pre in ipairs(cur_case.hooks.pre) do
schedule_step(hook_pre, 'hook_pre', [[Executing 'pre' hook #]] .. i)
end
schedule_step(function() cur_case.test(unpack(cur_case.args)) end, 'case', 'Executing test')
for i, hook_post in ipairs(cur_case.hooks.post) do
schedule_step(hook_post, 'hook_post', [[Executing 'post' hook #]] .. i)
end
-- Finalize state
schedule_step(nil, 'finalize', function() return H.case_final_state(cur_case) end)
end
vim.schedule(function() H.exec_callable(reporter.finish) end)
-- Use separate call to ensure that `reporter.finish` error won't interfere
vim.schedule(function() H.cache.is_executing = false end)
end
--- Stop test execution
---
---@param opts table|nil Options with fields:
--- - <close_all_child_neovim> - whether to close all child neovim processes
--- created with |MiniTest.new_child_neovim()|. Default: `true`.
MiniTest.stop = function(opts)
opts = vim.tbl_deep_extend('force', { close_all_child_neovim = true }, opts or {})
-- Register intention to stop execution
H.cache.should_stop_execution = true
-- Possibly stop all child Neovim processes
if not opts.close_all_child_neovim then return end
for _, child in ipairs(H.child_neovim_registry) do
pcall(child.stop)
end
H.child_neovim_registry = {}
end
--- Check if tests are being executed
---
---@return boolean
MiniTest.is_executing = function() return H.cache.is_executing == true end
-- Expectations ---------------------------------------------------------------
--- Table with expectation functions
---
--- Each function has the following behavior:
--- - Silently returns `true` if expectation is fulfilled.
--- - Throws an informative error with information helpful for debugging.
---
--- Mostly designed to be used within 'mini.test' framework.
---
---@usage >
--- local x = 1 + 1
--- MiniTest.expect.equality(x, 2) -- passes
--- MiniTest.expect.equality(x, 1) -- fails
MiniTest.expect = {}
--- Expect equality of two objects
---
--- Equality is tested via |vim.deep_equal()|.
---
---@param left any First object.
---@param right any Second object.
MiniTest.expect.equality = function(left, right)
if vim.deep_equal(left, right) then return true end
local context = string.format('Left: %s\nRight: %s', vim.inspect(left), vim.inspect(right))
H.error_expect('equality', context)
end
--- Expect no equality of two objects
---
--- Equality is tested via |vim.deep_equal()|.
---
---@param left any First object.
---@param right any Second object.
MiniTest.expect.no_equality = function(left, right)
if not vim.deep_equal(left, right) then return true end
local context = string.format('Object: %s', vim.inspect(left))
H.error_expect('*no* equality', context)
end
--- Expect function call to raise error
---
---@param f function|table Callable to be tested for raising error.
---@param pattern string|nil Pattern which error message should match.
--- Use `nil` or empty string to not test for pattern matching.
---@param ... any Extra arguments with which `f` will be called.
MiniTest.expect.error = function(f, pattern, ...)
vim.validate({ pattern = { pattern, 'string', true } })
local ok, err = pcall(f, ...)
err = err or ''
local has_matched_error = not ok and string.find(err, pattern or '') ~= nil
if has_matched_error then return true end
local matching_pattern = pattern == nil and '' or (' matching pattern %s'):format(vim.inspect(pattern))
local subject = 'error' .. matching_pattern
local context = ok and 'Observed no error' or ('Observed error: ' .. err)
H.error_expect(subject, context)
end
--- Expect function call to not raise error
---
---@param f function|table Callable to be tested for raising error.
---@param ... any Extra arguments with which `f` will be called.
MiniTest.expect.no_error = function(f, ...)
local ok, err = pcall(f, ...)
err = err or ''
if ok then return true end
H.error_expect('*no* error', 'Observed error: ' .. err)
end
--- Expect equality to reference screenshot
---
---@param screenshot table|nil Array with screenshot information. Usually an output
--- of `child.get_screenshot()` (see |MiniTest-child-neovim.get_screenshot()|).
--- If `nil`, expectation passed.
---@param path string|nil Path to reference screenshot. If `nil`, constructed
--- automatically in directory 'tests/screenshots' from current case info and
--- total number of times it was called inside current case. If there is no
--- file at `path`, it is created with content of `screenshot`.
---@param opts table|nil Options:
--- - <force> `(boolean)` - whether to forcefully create reference screenshot.
--- Temporary useful during test writing. Default: `false`.
--- - <ignore_lines> `(table)` - array of line numbers to ignore during compare.
--- Default: `nil` to check all lines.
MiniTest.expect.reference_screenshot = function(screenshot, path, opts)
if screenshot == nil then return true end
opts = vim.tbl_deep_extend('force', { force = false }, opts or {})
H.cache.n_screenshots = H.cache.n_screenshots + 1
if path == nil then
-- Sanitize path. Replace any control characters, whitespace, OS specific
-- forbidden characters with '-' (with some useful exception)
local linux_forbidden = [[/]]
local windows_forbidden = [[<>:"/\|?*]]
local pattern = string.format('[%%c%%s%s%s]', vim.pesc(linux_forbidden), vim.pesc(windows_forbidden))
local replacements = setmetatable({ ['"'] = "'" }, { __index = function() return '-' end })
local name = H.case_to_stringid(MiniTest.current.case):gsub(pattern, replacements)
-- Don't end with whitespace or dot (forbidden on Windows)
name = name:gsub('[%s%.]$', '-')
path = 'tests/screenshots/' .. name
-- Deal with multiple screenshots
if H.cache.n_screenshots > 1 then path = path .. string.format('-%03d', H.cache.n_screenshots) end
end
-- If there is no readable screenshot file, create it. Pass with note.
if opts.force or vim.fn.filereadable(path) == 0 then
local dir_path = vim.fn.fnamemodify(path, ':p:h')
vim.fn.mkdir(dir_path, 'p')
H.screenshot_write(screenshot, path)
MiniTest.add_note('Created reference screenshot at path ' .. vim.inspect(path))
return true
end
local reference = H.screenshot_read(path)
-- Compare
local are_same, cause = H.screenshot_compare(reference, screenshot, opts)
if are_same then return true end
local subject = 'screenshot equality to reference at ' .. vim.inspect(path)
local context = string.format('%s\nReference:\n%s\n\nObserved:\n%s', cause, tostring(reference), tostring(screenshot))
H.error_expect(subject, context)
end
--- Create new expectation function
---
--- Helper for writing custom functions with behavior similar to other methods
--- of |MiniTest.expect|.
---
---@param subject string|function|table Subject of expectation. If callable,
--- called with expectation input arguments to produce string value.
---@param predicate function|table Predicate callable. Called with expectation
--- input arguments. Output `false` or `nil` means failed expectation.
---@param fail_context string|function|table Information about fail. If callable,
--- called with expectation input arguments to produce string value.
---
---@return function Expectation function.
---
---@usage >
--- local expect_truthy = MiniTest.new_expectation(
--- 'truthy',
--- function(x) return x end,
--- function(x) return 'Object: ' .. vim.inspect(x) end
--- )
MiniTest.new_expectation = function(subject, predicate, fail_context)
return function(...)
if predicate(...) then return true end
local cur_subject = vim.is_callable(subject) and subject(...) or subject
local cur_context = vim.is_callable(fail_context) and fail_context(...) or fail_context
H.error_expect(cur_subject, cur_context)
end
end
-- Reporters ------------------------------------------------------------------
--- Table with pre-configured report generators
---
--- Each element is a function which returns reporter - table with callable
--- `start`, `update`, and `finish` fields.
MiniTest.gen_reporter = {}
--- Generate buffer reporter
---
--- This is a default choice for interactive (not headless) usage. Opens a window
--- with dedicated non-terminal buffer and updates it with throttled redraws.
---
--- Opened buffer has the following helpful Normal mode mappings:
--- - `<Esc>` - stop test execution if executing (see |MiniTest.is_executing()|
--- and |MiniTest.stop()|). Close window otherwise.
--- - `q` - same as `<Esc>` for convenience and compatibility.
---
--- General idea:
--- - Group cases by concatenating first `opts.group_depth` elements of case
--- description (`desc` field). Groups by collected files if using default values.
--- - In `start()` show some stats to know how much is scheduled to be executed.
--- - In `update()` show symbolic overview of current group and state of current
--- case. Each symbol represents one case and its state:
--- - `?` - case didn't finish executing.
--- - `o` - pass.
--- - `O` - pass with notes.
--- - `x` - fail.
--- - `X` - fail with notes.
--- - In `finish()` show all fails and notes ordered by case.
---
---@param opts table|nil Table with options. Used fields:
--- - <group_depth> - number of first elements of case description (can be zero)
--- used for grouping. Higher values mean higher granularity of output.
--- Default: 1.
--- - <throttle_delay> - minimum number of milliseconds to wait between
--- redrawing. Reduces screen flickering but not amount of computations.
--- Default: 10.
--- - <window> - definition of window to open. Can take one of the forms:
--- - Callable. It is called expecting output to be target window id
--- (current window is used if output is `nil`). Use this to open in
--- "normal" window (like `function() vim.cmd('vsplit') end`).
--- - Table. Used as `config` argument in |nvim_open_win()|.
--- Default: table for centered floating window.
MiniTest.gen_reporter.buffer = function(opts)
-- NOTE: another choice of implementing this is to use terminal buffer
-- `vim.api.nvim_open_term()`.
-- Pros:
-- - Renders ANSI escape sequences (mostly) correctly, i.e. no need in
-- replacing them with Neovim range highlights.
-- - This reporter and `stdout` one can share more of a codebase.
-- Cons:
-- - Couldn't manage to implement "redraw on every update".
-- - Extra steps still are needed in order to have richer output information.
-- This involves ANSI sequences that move cursor, which have same issues as
-- in `stdout`, albeit easier to overcome:
-- - Handling of scroll.
-- - Hard wrapping of lines leading to need of using window width.
opts = vim.tbl_deep_extend(
'force',
{ group_depth = 1, throttle_delay = 10, window = H.buffer_reporter.default_window_opts() },
opts or {}
)
local buf_id, win_id
local is_valid_buf_win = function() return vim.api.nvim_buf_is_valid(buf_id) and vim.api.nvim_win_is_valid(win_id) end
-- Helpers
local set_cursor =
function(line) vim.api.nvim_win_set_cursor(win_id, { line or vim.api.nvim_buf_line_count(buf_id), 0 }) end
-- Define "write from cursor line" function with throttled redraw
local latest_draw_time = 0
local replace_last = function(n_replace, lines, force)
H.buffer_reporter.set_lines(buf_id, lines, -n_replace - 1, -1)
-- Throttle redraw to reduce flicker
local cur_time = vim.loop.hrtime()
local is_enough_time_passed = (cur_time - latest_draw_time) > opts.throttle_delay * 1000000
if is_enough_time_passed or force then
vim.cmd('redraw')
latest_draw_time = cur_time
end
end
-- Create reporter functions
local res = {}
local all_cases, all_groups, latest_group_name
res.start = function(cases)
-- Set up buffer and window
buf_id, win_id = H.buffer_reporter.setup_buf_and_win(opts.window)
-- Set up data (taking into account possible not first time run)
all_cases = cases
all_groups = H.overview_reporter.compute_groups(cases, opts.group_depth)
latest_group_name = nil
-- Write lines
local lines = H.overview_reporter.start_lines(all_cases, all_groups)
replace_last(1, lines)
set_cursor()
end
res.update = function(case_num)
if not is_valid_buf_win() then return end
local case, cur_group_name = all_cases[case_num], all_groups[case_num].name
-- Update symbol
local state = type(case.exec) == 'table' and case.exec.state or nil
all_groups[case_num].symbol = H.reporter_symbols[state]
local n_replace = H.buffer_reporter.update_step_n_replace(latest_group_name, cur_group_name)
local lines = H.buffer_reporter.update_step_lines(case_num, all_cases, all_groups)
replace_last(n_replace, lines)
set_cursor()
latest_group_name = cur_group_name
end
res.finish = function()
if not is_valid_buf_win() then return end
-- Cache final cursor position to overwrite 'Current case state' header
local start_line = vim.api.nvim_buf_line_count(buf_id) - 1
-- Force writing lines
local lines = H.overview_reporter.finish_lines(all_cases)
replace_last(2, lines, true)
set_cursor(start_line)
end
return res
end
--- Generate stdout reporter
---
--- This is a default choice for headless usage. Writes to `stdout`. Uses
--- coloring ANSI escape sequences to make pretty and informative output
--- (should work in most modern terminals and continuous integration providers).
---
--- It has same general idea as |MiniTest.gen_reporter.buffer()| with slightly
--- less output (it doesn't overwrite previous text) to overcome typical
--- terminal limitations.
---
---@param opts table|nil Table with options. Used fields:
--- - <group_depth> - number of first elements of case description (can be zero)
--- used for grouping. Higher values mean higher granularity of output.
--- Default: 1.
--- - <quit_on_finish> - whether to quit after finishing test execution.
--- Default: `true`.
MiniTest.gen_reporter.stdout = function(opts)
opts = vim.tbl_deep_extend('force', { group_depth = 1, quit_on_finish = true }, opts or {})
local write = function(text)
text = type(text) == 'table' and table.concat(text, '\n') or text
io.stdout:write(text)
io.flush()
end
local all_cases, all_groups, latest_group_name
local default_symbol = H.reporter_symbols[nil]
local res = {}
res.start = function(cases)
-- Set up data
all_cases = cases
all_groups = H.overview_reporter.compute_groups(cases, opts.group_depth)
-- Write lines
local lines = H.overview_reporter.start_lines(all_cases, all_groups)
write(lines)
end
res.update = function(case_num)
local cur_case = all_cases[case_num]
local cur_group_name = all_groups[case_num].name
-- Possibly start overview of new group
if cur_group_name ~= latest_group_name then
write('\n')
write(cur_group_name)
if cur_group_name ~= '' then write(': ') end
end
-- Possibly show new symbol
local state = type(cur_case.exec) == 'table' and cur_case.exec.state or nil
local cur_symbol = H.reporter_symbols[state]
0