feat(test): add optional message to failed assertions

doc/mini-test.txt

@@ -525,25 +525,29 @@ Usage ~
 <
 ------------------------------------------------------------------------------
                                                     *MiniTest.expect.equality()*
-                  `MiniTest.expect.equality`({left}, {right})
+              `MiniTest.expect.equality`({left}, {right}, {opts})
 Expect equality of two objects
 
 Equality is tested via |vim.deep_equal()|.
 
 Parameters ~
 {left} `(any)` First object.
 {right} `(any)` Second object.
+{opts} `(table|nil)` Options:
+  - <msg> `(string)` Fails with the supplied failure message. Default: nil
 
 ------------------------------------------------------------------------------
                                                  *MiniTest.expect.no_equality()*
-                 `MiniTest.expect.no_equality`({left}, {right})
+             `MiniTest.expect.no_equality`({left}, {right}, {opts})
 Expect no equality of two objects
 
 Equality is tested via |vim.deep_equal()|.
 
 Parameters ~
 {left} `(any)` First object.
 {right} `(any)` Second object.
+{opts} `(table|nil)` Options:
+  - <msg> `(string)` Fails with the supplied failure message. Default: nil
 
 ------------------------------------------------------------------------------
                                                        *MiniTest.expect.error()*
@@ -589,6 +593,7 @@ Parameters ~
     if `false` - do not ignore any. Default: `false`.
   - <directory> `(string)` - directory where automatically constructed `path`
     is located. Default: "tests/screenshots".
+  - <msg> `(string)` - Fails with the supplied failure message. Default: nil
 
 ------------------------------------------------------------------------------
                                                     *MiniTest.new_expectation()*

lua/mini/test.lua

@@ -666,10 +666,14 @@ MiniTest.expect = {}
 ---
 ---@param left any First object.
 ---@param right any Second object.
-MiniTest.expect.equality = function(left, right)
+---@param opts table|nil Options:
+---   - <msg> `(string)` Fails with the supplied failure message. Default: nil
+MiniTest.expect.equality = function(left, right, opts)
   if vim.deep_equal(left, right) then return true end
 
   local context = string.format('Left:  %s\nRight: %s', vim.inspect(left), vim.inspect(right))
+  opts = opts or {}
+  if opts.msg then context = string.format('%s\n%s', opts.msg, context) end
   H.error_expect('equality', context)
 end
 
@@ -679,10 +683,15 @@ end
 ---
 ---@param left any First object.
 ---@param right any Second object.
-MiniTest.expect.no_equality = function(left, right)
+---@param opts table|nil Options:
+---   - <msg> `(string)` Fails with the supplied failure message. Default: nil
+MiniTest.expect.no_equality = function(left, right, opts)
+  opts = opts or {}
   if not vim.deep_equal(left, right) then return true end
 
   local context = string.format('Object: %s', vim.inspect(left))
+  opts = opts or {}
+  if opts.msg then context = string.format('%s\n%s', opts.msg, context) end
   H.error_expect('*no* equality', context)
 end
 
@@ -739,6 +748,7 @@ end
 ---     if `false` - do not ignore any. Default: `false`.
 ---   - <directory> `(string)` - directory where automatically constructed `path`
 ---     is located. Default: "tests/screenshots".
+---   - <msg> `(string)` - Fails with the supplied failure message. Default: nil
 MiniTest.expect.reference_screenshot = function(screenshot, path, opts)
   if screenshot == nil then return true end
 
@@ -794,6 +804,7 @@ MiniTest.expect.reference_screenshot = function(screenshot, path, opts)
   local cause = same_text and cause_attr or cause_text
   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))
+  if opts.msg then context = string.format('%s\n%s', opts.msg, context) end
   H.error_expect(subject, context)
 end
 

tests/test_test.lua

@@ -752,6 +752,13 @@ T['expect']['equality()/no_equality()']['return `true` on success'] = function()
   eq(MiniTest.expect.no_equality(1, 2), true)
 end
 
+T['expect']['equality()/no_equality()']['print message on failure'] = function()
+  local validate = function(fn, x, y, opts) expect.error(fn, '.*Test msg.*', x, y, opts) end
+
+  validate(MiniTest.expect.equality, 1, 2, { msg = 'Test msg' })
+  validate(MiniTest.expect.no_equality, 1, 1, { msg = 'Test msg' })
+end
+
 T['expect']['error()'] = new_set()
 
 T['expect']['error()']['works'] = function()
@@ -1061,6 +1068,16 @@ T['expect']['reference_screenshot()']['works with multibyte characters'] = funct
   expect.no_error(function() MiniTest.expect.reference_screenshot(child.get_screenshot()) end)
 end
 
+T['expect']['reference_screenshot()']['print message on failure'] = function()
+  local path = get_ref_path('reference-screenshot')
+  child.set_size(5, 12)
+  set_lines({ 'bbb' })
+  expect.error(
+    function() MiniTest.expect.reference_screenshot(child.get_screenshot(), path, { msg = 'Test msg' }) end,
+    'screenshot equality to reference at ' .. vim.pesc(vim.inspect(path)) .. '.*Test msg.*Reference:.*Observed:'
+  )
+end
+
 T['new_expectation()'] = new_set()
 
 T['new_expectation()']['works'] = function()