Assert

Assert

The batest assert statement functions similar to a Batch IF statement and supports most of the IF functionality. In pseudocode, the assert statement is approximately doing the following:

if condition
    ERRORLEVEL = 0
else
    output error message to console
    ERRORLEVEL = 1

Note that a passing assertion sets the ERRORLEVEL to 0, while a failing assertion sets the ERRORLEVEL to 1. Setting a custom ERRORLEVEL is not supported yet.

The assert statement is called in the following format:

call assert [NOT] CONDITION [ERROR_MESSAGE]

More information on the structure of the CONDITION may be found in the conditions and examples sections below.

Conditions

Supported conditions

The following assert conditions are supported:

OPERAND1 OPERATOR OPERAND2
EXIST OPERAND
DEFINED OPERAND
ERRORLEVEL OPERAND

For example, the following two assert conditions are valid:

2 GEQ 1
EXIST file.txt

Supported operators

The following operators are supported by the assert statement:

• ==
• EQU
• NEQ
• GEQ
• LEQ
• LSS
• GTR
• EXIST
• NOT
• ERRORLEVEL
• DEFINED

Note that, similar to the normal IF statement, all assert operators are case-insensitive.

Examples

The following example asserts that 1 equals 1. It will pass, set the ERRORLEVEL to 0 and not output the specified error message:

call assert 1 EQU 1 "my message"

The following example asserts that the file file.txt exists in the current directory. If the file exists, the assertion will pass, the ERRORLEVEL will be set to 0 and the error message not output. If the file does not exist, the assertion will fail, the ERRORLEVEL will be set to 1 and the error message ("file is missing") output to console:

call assert exist file.txt "file is missing"

The following example asserts that 1 is not greater than 2 (note the use of a leading NOT operator), which will pass and not output the error message:

call assert NOT 1 GEQ 2 "error message"

The following example asserts that the variable myvar is defined. If it is, the ERRORLEVEL is set to 0, else it is set to 1 and the specified error message ("Variable is not defined!") is output to console:

call assert DEFINED myvar "Variable is not defined!"

The following example asserts that ERRORLEVEL is greater than or equal to 1. If it is, ERRORLEVEL is set to 0, else it is set to 1 and the specified error message ("Error level is not geq 1") is output to console:

call assert ERRORLEVEL 1 "Error level is not geq 1"

Common pitfalls

Assert in local scope

As all changes to variables are discarded when exiting a local scope, an assertion that failed inside a local scope will not actually change the errorlevel variable, causing the test to look as if it passed when it maybe didn't:

::Don't do this
setlocal
assert 1 EQU 2

Multiple asserts in one file

When using multiple assertion statements, it is imperative to check the errorlevel after each assert, as otherwise only the errorlevel of the final assert in the file would get propagated and presented in the test report.

Wrong and dangerous:

Here, the first assert fails due to its condition not being met (1 is not equal to 2), while the second assert passes. This will cause the errorlevel of the first assert to be overwritten by the second, and the test will appear as having passed:

::this test file should fail but doesn't
assert 1 EQU 2
assert 1 EQU 1

Good:

In the example below, the test correctly fails and exits after the first assert, failing the entire test:

assert 1 EQU 2
if errorlevel 1 exit /b %errorlevel%

assert 1 EQU 1

Path

Note that the assert.bat file needs to be on the batchfile PATH while running batest.bat to test code.

More information

More information may be found directly on the command-line using:

assert help