feat(test)!: soft deprecate ignore_lines in expect_screenshot()

Details:
- Use new `ignore_text` and `ignore_attr` options instead.

Related to #1300

Author: echasnovski

CHANGELOG.md

@@ -61,6 +61,12 @@ There are following change types:
 
 ## mini.test
 
+### Refine
+
+- Soft deprecate `ignore_lines` option in `expect.reference_screenshot()` in favor of more capable `ignore_text` and `ignore_attr` options. For example, `ignore_lines = { 1 }` is the same as supplying both `ignore_text = { 1 }` and `ignore_attr = { 1 }`.
+
+    It will work at least until the next release, after which its support will be removed. Sorry for the inconvenience.
+
 ### Expand
 
 - Update `expect.reference_screenshot()` to support separate ignoring of text and attribute screenshot data via new `ignore_text` and `ignore_attr` options.

doc/mini-test.txt

@@ -587,9 +587,6 @@ Parameters ~
   - <ignore_attr> `(boolean|table)` - whether to ignore all or some attr lines.
     If `true` - ignore all, if number array - ignore attr of those lines,
     if `false` - do not ignore any. Default: `false`.
-  - <ignore_lines> `(table)` - array of line numbers to ignore during compare.
-    Same as supplying line number as part of <ignore_text> and <ignore_attr>.
-    Default: `nil` to check all lines.
   - <directory> `(string)` - directory where automatically constructed `path`
     is located. Default: "tests/screenshots".
 

lua/mini/test.lua

@@ -746,18 +746,24 @@ end
 ---   - <ignore_attr> `(boolean|table)` - whether to ignore all or some attr lines.
 ---     If `true` - ignore all, if number array - ignore attr of those lines,
 ---     if `false` - do not ignore any. Default: `false`.
----   - <ignore_lines> `(table)` - array of line numbers to ignore during compare.
----     Same as supplying line number as part of <ignore_text> and <ignore_attr>.
----     Default: `nil` to check all lines.
 ---   - <directory> `(string)` - directory where automatically constructed `path`
 ---     is located. Default: "tests/screenshots".
 MiniTest.expect.reference_screenshot = function(screenshot, path, opts)
   if screenshot == nil then return true end
 
-  local default_opts = { force = false, ignore_lines = {}, directory = 'tests/screenshots' }
-  default_opts.ignore_text, default_opts.ignore_attr = false, false
+  local default_opts = { force = false, ignore_text = false, ignore_attr = false, directory = 'tests/screenshots' }
   opts = vim.tbl_extend('force', default_opts, opts or {})
 
+  -- TODO: Remove after releasing 'mini.nvim' 0.17.0
+  if opts.ignore_lines ~= nil then
+    vim.notify(
+      '(mini.test) `ignore_lines` is soft deprecated in favor of separate `ignore_text` and `ignore_attr`.'
+        .. ' It will work at least until the next release, after which its support will be removed.'
+        .. ' Sorry for the inconvenience.'
+    )
+  end
+  opts.ignore_lines = opts.ignore_lines or {}
+
   H.cache.n_screenshots = H.cache.n_screenshots + 1
 
   if path == nil then

tests/test_test.lua

@@ -969,6 +969,11 @@ T['expect']['reference_screenshot()']['respects `opts.force` argument'] = functi
 end
 
 T['expect']['reference_screenshot()']['respects `opts.ignore_lines`'] = function()
+  -- Do not show soft deprecation message
+  local notify_orig = vim.notify
+  vim.notify = function() end
+  MiniTest.finally(function() vim.notify = notify_orig end)
+
   local path = get_ref_path('reference-screenshot')
   child.set_size(5, 12)
   local validate = function(ignore_lines, ref)