feat(test): add optional message to failed assertions

Allow user to add an optional message to failed assertions in mini test.
This allow providing more context to specific failures when they arise.

Usage:

```lua
MiniTest.expect.equality(x, y, "Invalid number of items")
MiniTest.expect.no_equality(x, y, "Unexpected line counts")
MiniTest.expect.reference_screenshot(screen, path, nil, "Buffer not matching")
```

Author: dimtion

doc/mini-test.txt

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

lua/mini/test.lua

@@ -666,10 +666,12 @@ MiniTest.expect = {}
 ---
 ---@param left any First object.
 ---@param right any Second object.
-MiniTest.expect.equality = function(left, right)
+---@param msg string|nil Fails with the supplied failure message.
+MiniTest.expect.equality = function(left, right, msg)
   if vim.deep_equal(left, right) then return true end
 
   local context = string.format('Left:  %s\nRight: %s', vim.inspect(left), vim.inspect(right))
+  if msg then context = string.format('%s\n%s', msg, context) end
   H.error_expect('equality', context)
 end
 
@@ -679,10 +681,12 @@ end
 ---
 ---@param left any First object.
 ---@param right any Second object.
-MiniTest.expect.no_equality = function(left, right)
+---@param msg string|nil Fails with the supplied failure message.
+MiniTest.expect.no_equality = function(left, right, msg)
   if not vim.deep_equal(left, right) then return true end
 
   local context = string.format('Object: %s', vim.inspect(left))
+  if msg then context = string.format('%s\n%s', msg, context) end
   H.error_expect('*no* equality', context)
 end
 
@@ -739,7 +743,8 @@ end
 ---     if `false` - do not ignore any. Default: `false`.
 ---   - <directory> `(string)` - directory where automatically constructed `path`
 ---     is located. Default: "tests/screenshots".
-MiniTest.expect.reference_screenshot = function(screenshot, path, opts)
+---@param msg string|nil Fails with the supplied failure message.
+MiniTest.expect.reference_screenshot = function(screenshot, path, opts, msg)
   if screenshot == nil then return true end
 
   local default_opts = { force = false, ignore_text = false, ignore_attr = false, directory = 'tests/screenshots' }
@@ -794,6 +799,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 msg then context = string.format('%s\n%s', 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, msg) expect.error(fn, '.*Test msg.*', x, y, msg) end
+
+  validate(MiniTest.expect.equality, 1, 2, 'Test msg')
+  validate(MiniTest.expect.no_equality, 1, 1, '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, nil, '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()