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, { msg = "Invalid number of items" })
MiniTest.expect.no_equality(x, y, { msg = "Unexpected line counts" })
MiniTest.expect.reference_screenshot(screen, path, { msg = "Buffer not matching" })
```

Author: dimtion

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()