Run {cmd} and add an error message to v:errors if it does 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. If there is only one error then both patterns must match. This can be used to check that there is only one error. To only match the last error use an empty string for the first error:

assert_fails('cmd', ['', 'E987:'])

If {msg} is empty then it is not used. Do this to get the default message when passing the {lnum} argument.

When {lnum} is present and not negative, and the {error} argument is present and matches, then this is compared with the line number at which the error was reported. That can be the line number in a function or in a script.

When {context} is present it is used as a pattern and matched against the context (script name or function name) where {lnum} is located in.

Note that beeping is not considered an error, and some failing commands only beep. Use assert_beeps() for those.

Can also be used as a method:

GetCmd()->assert_fails('E99:')