patch 8.2.1183: assert_fails() checks the last error messagev8.2.1183

Problem:    assert_fails() checks the last error message.
Solution:   Check the first error, it is more relevant.  Fix all the tests
            that rely on the old behavior.

1 files changed, 17 insertions, 2 deletions

diff --git a/runtime/doc/testing.txt b/runtime/doc/testing.txt
index b7825b90f9..53ed0818e4 100644
--- a/runtime/doc/testing.txt
+++ b/runtime/doc/testing.txt
@@ -295,8 +295,23 @@ 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.  Also see |assert-return|.
-		When {error} is given it must match in |v:errmsg|.
+		NOT produce an error or when {error} is not found in the
+		error message.  Also see |assert-return|.
+
+		When {error} is a string it must be found literally in the
+		first reported error. Most often this will be the error code,
+		including the colon, e.g. "E123:". >
+			assert_fails('bad cmd', 'E987:')
+<
+		When {error} is a |List| with one or two strings, these are
+		used as patterns.  The first pattern is matched against the
+		first reported error: >
+			assert_fails('cmd', ['E987:.*expected bool'])
+<		The second pattern, if present, is matched against the last
+		reported error.  To only match the last error use an empty
+		string for the first error: >
+			assert_fails('cmd', ['', 'E987:'])
+<
 		Note that beeping is not considered an error, and some failing
 		commands only beep.  Use |assert_beeps()| for those.