vim-patch:8.0.1770: assert functions don't return anything

Problem:    Assert functions don't return anything.
Solution:   Return non-zero when the assertion fails.
65a5464985

runtime/doc/eval.txt

@@ -1547,10 +1547,12 @@ v:errmsg	Last given error message.
 	:if v:errmsg != ""
 	:  ... handle error
 <
-					*v:errors* *errors-variable*
+				*v:errors* *errors-variable* *assert-return*
 v:errors	Errors found by assert functions, such as |assert_true()|.
 		This is a list of strings.
 		The assert functions append an item when an assert fails.
+		The return value indicates this: a one is returned if an item
+		was added to v:errors, otherwise zero is returned.
 		To remove old results make it empty: >
 	:let v:errors = []
 <		If v:errors is set to anything but a list it is made an empty
@@ -2004,26 +2006,26 @@ argidx()			Number	current index in the argument list
 arglistid([{winnr} [, {tabnr}]]) Number	argument list id
 argv({nr} [, {winid}])		String	{nr} entry of the argument list
 argv([-1, {winid}])		List	the argument list
-assert_beeps({cmd})		none	assert {cmd} causes a beep
+assert_beeps({cmd})		Number	assert {cmd} causes a beep
 assert_equal({exp}, {act} [, {msg}])
-				none	assert {exp} is equal to {act}
+				Number	assert {exp} is equal to {act}
 assert_equalfile({fname-one}, {fname-two})
-				none	assert file contents is equal
+				Number	assert file contents is equal
 assert_exception({error} [, {msg}])
-				none	assert {error} is in v:exception
+				Number	assert {error} is in v:exception
-assert_fails({cmd} [, {error}])	none	assert {cmd} fails
+assert_fails({cmd} [, {error}])	Number	assert {cmd} fails
 assert_false({actual} [, {msg}])
-				none	assert {actual} is false
+				Number	assert {actual} is false
 assert_inrange({lower}, {upper}, {actual} [, {msg}])
-				none	assert {actual} is inside the range
+				Number	assert {actual} is inside the range
 assert_match({pat}, {text} [, {msg}])
-				none	assert {pat} matches {text}
+				Number	assert {pat} matches {text}
 assert_notequal({exp}, {act} [, {msg}])
-				none	assert {exp} is not equal {act}
+				Number	assert {exp} is not equal {act}
 assert_notmatch({pat}, {text} [, {msg}])
-				none	assert {pat} not matches {text}
+				Number	assert {pat} not matches {text}
-assert_report({msg})		none	report a test failure
+assert_report({msg})		Number	report a test failure
-assert_true({actual} [, {msg}])	none	assert {actual} is true
+assert_true({actual} [, {msg}])	Number	assert {actual} is true
 asin({expr})			Float	arc sine of {expr}
 atan({expr})			Float	arc tangent of {expr}
 atan2({expr}, {expr})		Float   arc tangent of {expr1} / {expr2}
@@ -2582,12 +2584,13 @@ argv([{nr} [, {winid}])
 assert_beeps({cmd})					*assert_beeps()*
 		Run {cmd} and add an error message to |v:errors| if it does
 		NOT produce a beep or visual bell.
-		Also see |assert_fails()|.
+		Also see |assert_fails()| and |assert-return|.
 
 							*assert_equal()*
 assert_equal({expected}, {actual}, [, {msg}])
 		When {expected} and {actual} are not equal an error message is
-		added to |v:errors|.
+		added to |v:errors| and 1 is returned.  Otherwise zero is
+		returned |assert-return|.
 		There is no automatic conversion, the String "4" is different
 		from the Number 4.  And the number 4 is different from the
 		Float 4.0.  The value of 'ignorecase' is not used here, case
@@ -2603,12 +2606,13 @@ assert_equal({expected}, {actual}, [, {msg}])
 assert_equalfile({fname-one}, {fname-two})
 		When the files {fname-one} and {fname-two} do not contain
 		exactly the same text an error message is added to |v:errors|.
+		Also see |assert-return|.
 		When {fname-one} or {fname-two} does not exist the error will
 		mention that.
 
 assert_exception({error} [, {msg}])			*assert_exception()*
 		When v:exception does not contain the string {error} an error
-		message is added to |v:errors|.
+		message is added to |v:errors|.  Also see |assert-return|.
 		This can be used to assert that a command throws an exception.
 		Using the error number, followed by a colon, avoids problems
 		with translations: >
@@ -2621,7 +2625,7 @@ assert_exception({error} [, {msg}])			*assert_exception()*
 
 assert_fails({cmd} [, {error} [, {msg}]])			*assert_fails()*
 		Run {cmd} and add an error message to |v:errors| if it does
-		NOT produce an error.
+		NOT produce an error.  Also see |assert-return|.
 		When {error} is given it must match in |v:errmsg|.
 		Note that beeping is not considered an error, and some failing
 		commands only beep.  Use |assert_beeps()| for those.
@@ -2629,6 +2633,7 @@ assert_fails({cmd} [, {error} [, {msg}]])			*assert_fails()*
 assert_false({actual} [, {msg}])				*assert_false()*
 		When {actual} is not false an error message is added to
 		|v:errors|, like with |assert_equal()|.
+		Also see |assert-return|.
 		A value is false when it is zero or |v:false|. When "{actual}"
 		is not a number or |v:false| the assert fails.
 		When {msg} is omitted an error in the form
@@ -2645,7 +2650,7 @@ assert_inrange({lower}, {upper}, {actual} [, {msg}])	 *assert_inrange()*
 								*assert_match()*
 assert_match({pattern}, {actual} [, {msg}])
 		When {pattern} does not match {actual} an error message is
-		added to |v:errors|.
+		added to |v:errors|.  Also see |assert-return|.
 
 		{pattern} is used as with |=~|: The matching is always done
 		like 'magic' was set and 'cpoptions' is empty, no matter what
@@ -2666,18 +2671,22 @@ assert_match({pattern}, {actual} [, {msg}])
 assert_notequal({expected}, {actual} [, {msg}])
 		The opposite of `assert_equal()`: add an error message to
 		|v:errors| when {expected} and {actual} are equal.
+		Also see |assert-return|.
 
 							*assert_notmatch()*
 assert_notmatch({pattern}, {actual} [, {msg}])
 		The opposite of `assert_match()`: add an error message to
 		|v:errors| when {pattern} matches {actual}.
+		Also see |assert-return|.
 
 assert_report({msg})					*assert_report()*
 		Report a test failure directly, using {msg}.
+		Always returns one.
 
 assert_true({actual} [, {msg}])					*assert_true()*
 		When {actual} is not true an error message is added to
 		|v:errors|, like with |assert_equal()|.
+		Also see |assert-return|.
 		A value is |TRUE| when it is a non-zero number or |v:true|.
 		When {actual} is not a number or |v:true| the assert fails.
 		When {msg} is omitted an error in the form "Expected True but

src/nvim/eval.c

@@ -6947,7 +6947,8 @@ static void assert_error(garray_T *gap)
                         (const char *)gap->ga_data, (ptrdiff_t)gap->ga_len);
 }
 
-static void assert_equal_common(typval_T *argvars, assert_type_T atype)
+static int assert_equal_common(typval_T *argvars, assert_type_T atype)
+  FUNC_ATTR_NONNULL_ALL
 {
   garray_T ga;
 
@@ -6958,10 +6959,12 @@ static void assert_equal_common(typval_T *argvars, assert_type_T atype)
                       &argvars[0], &argvars[1], atype);
     assert_error(&ga);
     ga_clear(&ga);
+    return 1;
   }
+  return 0;
 }
 
-static void assert_equalfile(typval_T *argvars)
+static int assert_equalfile(typval_T *argvars)
   FUNC_ATTR_NONNULL_ALL
 {
   char buf1[NUMBUFLEN];
@@ -6971,7 +6974,7 @@ static void assert_equalfile(typval_T *argvars)
   garray_T ga;
 
   if (fname1 == NULL || fname2 == NULL) {
-    return;
+    return 0;
   }
 
   IObuff[0] = NUL;
@@ -7008,13 +7011,16 @@ static void assert_equalfile(typval_T *argvars)
     ga_concat(&ga, IObuff);
     assert_error(&ga);
     ga_clear(&ga);
+    return 1;
   }
+  return 0;
 }
 
 static void f_assert_beeps(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   const char *const cmd = tv_get_string_chk(&argvars[0]);
   garray_T ga;
+  int ret = 0;
 
   called_vim_beep = false;
   suppress_errthrow = true;
@@ -7026,28 +7032,30 @@ static void f_assert_beeps(typval_T *argvars, typval_T *rettv, FunPtr fptr)
     ga_concat(&ga, (const char_u *)cmd);
     assert_error(&ga);
     ga_clear(&ga);
+    ret = 1;
   }
 
   suppress_errthrow = false;
   emsg_on_display = false;
+  rettv->vval.v_number = ret;
 }
 
 // "assert_equal(expected, actual[, msg])" function
 static void f_assert_equal(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
-  assert_equal_common(argvars, ASSERT_EQUAL);
+  rettv->vval.v_number = assert_equal_common(argvars, ASSERT_EQUAL);
 }
 
 // "assert_equalfile(fname-one, fname-two)" function
 static void f_assert_equalfile(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
-  assert_equalfile(argvars);
+  rettv->vval.v_number = assert_equalfile(argvars);
 }
 
 // "assert_notequal(expected, actual[, msg])" function
 static void f_assert_notequal(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
-  assert_equal_common(argvars, ASSERT_NOTEQUAL);
+  rettv->vval.v_number = assert_equal_common(argvars, ASSERT_NOTEQUAL);
 }
 
 /// "assert_report(msg)
@@ -7059,27 +7067,13 @@ static void f_assert_report(typval_T *argvars, typval_T *rettv, FunPtr fptr)
     ga_concat(&ga, (const char_u *)tv_get_string(&argvars[0]));
     assert_error(&ga);
     ga_clear(&ga);
+    rettv->vval.v_number = 1;
 }
 
 /// "assert_exception(string[, msg])" function
 static void f_assert_exception(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
-  garray_T ga;
+  rettv->vval.v_number = assert_exception(argvars);
-
-  const char *const error = tv_get_string_chk(&argvars[0]);
-  if (vimvars[VV_EXCEPTION].vv_str == NULL) {
-    prepare_assert_error(&ga);
-    ga_concat(&ga, (char_u *)"v:exception is not set");
-    assert_error(&ga);
-    ga_clear(&ga);
-  } else if (error != NULL
-             && strstr((char *)vimvars[VV_EXCEPTION].vv_str, error) == NULL) {
-    prepare_assert_error(&ga);
-    fill_assert_error(&ga, &argvars[1], NULL, &argvars[0],
-                      &vimvars[VV_EXCEPTION].vv_tv, ASSERT_OTHER);
-    assert_error(&ga);
-    ga_clear(&ga);
-  }
 }
 
 /// "assert_fails(cmd [, error])" function
@@ -7087,6 +7081,7 @@ static void f_assert_fails(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
   const char *const cmd = tv_get_string_chk(&argvars[0]);
   garray_T    ga;
+  int ret = 0;
   int         save_trylevel = trylevel;
 
   // trylevel must be zero for a ":throw" command to be considered failed
@@ -7102,6 +7097,7 @@ static void f_assert_fails(typval_T *argvars, typval_T *rettv, FunPtr fptr)
     ga_concat(&ga, (const char_u *)cmd);
     assert_error(&ga);
     ga_clear(&ga);
+    ret = 1;
   } else if (argvars[1].v_type != VAR_UNKNOWN) {
     char buf[NUMBUFLEN];
     const char *const error = tv_get_string_buf_chk(&argvars[1], buf);
@@ -7113,6 +7109,7 @@ static void f_assert_fails(typval_T *argvars, typval_T *rettv, FunPtr fptr)
                         &vimvars[VV_ERRMSG].vv_tv, ASSERT_OTHER);
       assert_error(&ga);
       ga_clear(&ga);
+      ret = 1;
     }
   }
 
@@ -7122,9 +7119,11 @@ static void f_assert_fails(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   emsg_silent = false;
   emsg_on_display = false;
   set_vim_var_string(VV_ERRMSG, NULL, 0);
+  rettv->vval.v_number = ret;
 }
 
-void assert_inrange(typval_T *argvars)
+static int assert_inrange(typval_T *argvars)
+  FUNC_ATTR_NONNULL_ALL
 {
   bool error = false;
   const varnumber_T lower = tv_get_number_chk(&argvars[0], &error);
@@ -7132,7 +7131,7 @@ void assert_inrange(typval_T *argvars)
   const varnumber_T actual = tv_get_number_chk(&argvars[2], &error);
 
   if (error) {
-    return;
+    return 0;
   }
   if (actual < lower || actual > upper) {
     garray_T ga;
@@ -7146,11 +7145,14 @@ void assert_inrange(typval_T *argvars)
                       ASSERT_INRANGE);
     assert_error(&ga);
     ga_clear(&ga);
+    return 1;
   }
+  return 0;
 }
 
 // Common for assert_true() and assert_false().
-static void assert_bool(typval_T *argvars, bool is_true)
+static int assert_bool(typval_T *argvars, bool is_true)
+  FUNC_ATTR_NONNULL_ALL
 {
   bool error = false;
   garray_T ga;
@@ -7169,16 +7171,43 @@ static void assert_bool(typval_T *argvars, bool is_true)
                       NULL, &argvars[0], ASSERT_OTHER);
     assert_error(&ga);
     ga_clear(&ga);
+    return 1;
   }
+  return 0;
+}
+
+static int assert_exception(typval_T *argvars)
+  FUNC_ATTR_NONNULL_ALL
+{
+  garray_T ga;
+
+  const char *const error = tv_get_string_chk(&argvars[0]);
+  if (vimvars[VV_EXCEPTION].vv_str == NULL) {
+    prepare_assert_error(&ga);
+    ga_concat(&ga, (char_u *)"v:exception is not set");
+    assert_error(&ga);
+    ga_clear(&ga);
+    return 1;
+  } else if (error != NULL
+             && strstr((char *)vimvars[VV_EXCEPTION].vv_str, error) == NULL) {
+    prepare_assert_error(&ga);
+    fill_assert_error(&ga, &argvars[1], NULL, &argvars[0],
+                      &vimvars[VV_EXCEPTION].vv_tv, ASSERT_OTHER);
+    assert_error(&ga);
+    ga_clear(&ga);
+    return 1;
+  }
+  return 0;
 }
 
 // "assert_false(actual[, msg])" function
 static void f_assert_false(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
-  assert_bool(argvars, false);
+  rettv->vval.v_number = assert_bool(argvars, false);
 }
 
-static void assert_match_common(typval_T *argvars, assert_type_T atype)
+static int assert_match_common(typval_T *argvars, assert_type_T atype)
+  FUNC_ATTR_NONNULL_ALL
 {
   char buf1[NUMBUFLEN];
   char buf2[NUMBUFLEN];
@@ -7194,31 +7223,33 @@ static void assert_match_common(typval_T *argvars, assert_type_T atype)
     fill_assert_error(&ga, &argvars[2], NULL, &argvars[0], &argvars[1], atype);
     assert_error(&ga);
     ga_clear(&ga);
+    return 1;
   }
+  return 0;
 }
 
 /// "assert_inrange(lower, upper[, msg])" function
 static void f_assert_inrange(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
-    assert_inrange(argvars);
+  rettv->vval.v_number = assert_inrange(argvars);
 }
 
 /// "assert_match(pattern, actual[, msg])" function
 static void f_assert_match(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
-  assert_match_common(argvars, ASSERT_MATCH);
+  rettv->vval.v_number = assert_match_common(argvars, ASSERT_MATCH);
 }
 
 /// "assert_notmatch(pattern, actual[, msg])" function
 static void f_assert_notmatch(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
-  assert_match_common(argvars, ASSERT_NOTMATCH);
+  rettv->vval.v_number = assert_match_common(argvars, ASSERT_NOTMATCH);
 }
 
 // "assert_true(actual[, msg])" function
 static void f_assert_true(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {
-  assert_bool(argvars, true);
+  rettv->vval.v_number = assert_bool(argvars, true);
 }
 
 /*

src/nvim/testdir/test_assert.vim

@@ -1,33 +1,33 @@
 " Test that the methods used for testing work.
 
 func Test_assert_equalfile()
-  call assert_equalfile('abcabc', 'xyzxyz')
+  call assert_equal(1, assert_equalfile('abcabc', 'xyzxyz'))
   call assert_match("E485: Can't read file abcabc", v:errors[0])
   call remove(v:errors, 0)
 
   let goodtext = ["one", "two", "three"]
   call writefile(goodtext, 'Xone')
-  call assert_equalfile('Xone', 'xyzxyz')
+  call assert_equal(1, assert_equalfile('Xone', 'xyzxyz'))
   call assert_match("E485: Can't read file xyzxyz", v:errors[0])
   call remove(v:errors, 0)
 
   call writefile(goodtext, 'Xtwo')
-  call assert_equalfile('Xone', 'Xtwo')
+  call assert_equal(0, assert_equalfile('Xone', 'Xtwo'))
 
   call writefile([goodtext[0]], 'Xone')
-  call assert_equalfile('Xone', 'Xtwo')
+  call assert_equal(1, assert_equalfile('Xone', 'Xtwo'))
   call assert_match("first file is shorter", v:errors[0])
   call remove(v:errors, 0)
 
   call writefile(goodtext, 'Xone')
   call writefile([goodtext[0]], 'Xtwo')
-  call assert_equalfile('Xone', 'Xtwo')
+  call assert_equal(1, assert_equalfile('Xone', 'Xtwo'))
   call assert_match("second file is shorter", v:errors[0])
   call remove(v:errors, 0)
 
   call writefile(['1234X89'], 'Xone')
   call writefile(['1234Y89'], 'Xtwo')
-  call assert_equalfile('Xone', 'Xtwo')
+  call assert_equal(1, assert_equalfile('Xone', 'Xtwo'))
   call assert_match("difference at byte 4", v:errors[0])
   call remove(v:errors, 0)
 

test/functional/legacy/assert_spec.lua

@@ -47,18 +47,18 @@ describe('assert function:', function()
     end)
 
     it('should not change v:errors when expected is equal to actual', function()
-      call('assert_equal', '', '')
+      eq(0, call('assert_equal', '', ''))
-      call('assert_equal', 'string', 'string')
+      eq(0, call('assert_equal', 'string', 'string'))
       expected_empty()
     end)
 
     it('should change v:errors when expected is not equal to actual', function()
-      call('assert_equal', 0, {0})
+      eq(1, call('assert_equal', 0, {0}))
       expected_errors({'Expected 0 but got [0]'})
     end)
 
     it('should change v:errors when expected is not equal to actual', function()
-      call('assert_equal', 0, "0")
+      eq(1, call('assert_equal', 0, "0"))
       expected_errors({"Expected 0 but got '0'"})
     end)
 
@@ -96,13 +96,13 @@ describe('assert function:', function()
   -- assert_notequal({expected}, {actual}[, {msg}])
   describe('assert_notequal', function()
     it('should not change v:errors when expected differs from actual', function()
-      call('assert_notequal', 'foo', 4)
+      eq(0, call('assert_notequal', 'foo', 4))
-      call('assert_notequal', {1, 2, 3}, 'foo')
+      eq(0, call('assert_notequal', {1, 2, 3}, 'foo'))
       expected_empty()
     end)
 
     it('should change v:errors when expected is equal to actual', function()
-      call('assert_notequal', 'foo', 'foo')
+      eq(1, call('assert_notequal', 'foo', 'foo'))
       expected_errors({"Expected not equal to 'foo'"})
     end)
   end)
@@ -110,13 +110,13 @@ describe('assert function:', function()
   -- assert_false({actual}, [, {msg}])
   describe('assert_false', function()
     it('should not change v:errors when actual is false', function()
-      call('assert_false', 0)
+      eq(0, call('assert_false', 0))
-      call('assert_false', false)
+      eq(0, call('assert_false', false))
       expected_empty()
     end)
 
     it('should change v:errors when actual is not false', function()
-      call('assert_false', 1)
+      eq(1, call('assert_false', 1))
       expected_errors({'Expected False but got 1'})
     end)
 
@@ -129,14 +129,14 @@ describe('assert function:', function()
   -- assert_true({actual}, [, {msg}])
   describe('assert_true', function()
     it('should not change v:errors when actual is true', function()
-      call('assert_true', 1)
+      eq(0, call('assert_true', 1))
-      call('assert_true', -1) -- In Vim script, non-zero Numbers are TRUE.
+      eq(0, call('assert_true', -1))  -- In Vim script, non-zero Numbers are TRUE.
-      call('assert_true', true)
+      eq(0, call('assert_true', true))
       expected_empty()
     end)
 
     it('should change v:errors when actual is not true', function()
-      call('assert_true', 1.5)
+      eq(1, call('assert_true', 1.5))
       expected_errors({'Expected True but got 1.5'})
     end)
   end)
@@ -277,7 +277,7 @@ describe('assert function:', function()
   -- assert_report({msg})
   describe('assert_report()', function()
     it('should add a message to v:errors', function()
-      command("call assert_report('something is wrong')")
+      eq(1, call('assert_report', 'something is wrong'))
       command("call assert_match('something is wrong', v:errors[0])")
       command('call remove(v:errors, 0)')
       expected_empty()
@@ -291,7 +291,7 @@ describe('assert function:', function()
         try
           nocommand
         catch
-          call assert_exception('E492')
+          call assert_equal(0, assert_exception('E492'))
         endtry
       ]])
       expected_empty()
@@ -304,9 +304,9 @@ describe('assert function:', function()
         catch
           try
             " illegal argument, get NULL for error
-            call assert_exception([])
+            call assert_equal(1, assert_exception([]))
           catch
-            call assert_exception('E730')
+            call assert_equal(0, assert_exception('E730'))
           endtry
         endtry
       ]])