Skip to content

Initial release

Latest
Latest
Compare
Choose a tag to compare
@rbaltrusch rbaltrusch released this 07 Mar 20:59
· 45 commits to master since this release
v1.0.0
733bb7e

Batest 1.0.0

Welcome to the batest 1.0.0 release notes!

Batest is a lightweight batchfile unit testing framework, shipping with an assert statement to make testing batchfiles easy. It generates a simple HTML test report containing the results after every run.

1. Functionality

Batest 1.0.0 ships with the following functionality:

2. 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"

More information

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

assert help

3. Setup

Every tests directory scanned by batest may contain an optional setup.bat file, which will be run before any test file is run, but not before each test file. Note that the name of the setup file must be setup.bat, otherwise batest will not recognize and run it.

Use of setup

The setup file may be used to setup test fixtures or files which will be used by more than once test file. The setup file may also be accompanied by a teardown, which will be run after batest ran all the test files in that tests directory.

Examples

For an example tests directory using setup and teardown files, see this example.

4. Teardown

Every tests directory scanned by batest may contain an optional teardown.bat file, which will be run after any test file is run, but not after each test file. Note that the name of the teardown file must be teardown.bat, otherwise batest will not recognize and run it.

Use of teardown

The teardown file may be used to teardown test fixtures or temporary files which were written to by setup.bat or other test files.

Examples

For an example tests directory using setup and teardown files, see this example.

5. Test report

Batest generates a simple HTML test report for the specified test directory.

Screenshots of the test reports

Test report information

The test report contains the following information:

  • The test directory
  • Number of passed and failed tests
  • DATE TIME COMPUTERNAME:USERNAME
  • Test script information:
    1. Name of the test script,
    2. Test status (passed/failed),
    3. Any output captured during the test run (including the error message),
    4. Directory of the test script

Dark and Light modes

Batest supports test reports in dark and light modes. The light mode test report is the default. To generate a dark mode test report, run batest with the --night or -n option, as below:

batest --night "test_path"
batest -n "test_path"

6. Folder structure

The folder containing the scripts to be tested should contain a subfolder called tests (as in the example folder structure below). The tests folder must contain all test files that test the scripts under test.

+---scripts1
|   \---tests
\---scripts2
    \---tests

Test file naming

All test files must end with the suffix _test to be recognized and run by batest. For example, some_test.bat would be recognized and run by batest, but test_something.bat would not be.

To list all test files recognized by batest under a path without actually running them, use the --list [-l] option, as in the example below:

batest --list "path/to/folder"

More information

More information on valid test folder structures is available in the examples.

7. Fixtures

Fixtures are not supported directly by batest. Instead, variables may be defined in the global scope in a test directory's setup.bat file. Any variables defined in the setup.bat file that are not declared in a setlocal block will be available in any test scripts that are run after setup.

Setup caveats

Note that the contents of variables declared in the setup.bat file can be modified (unlike normal test fixtures).

Deinitialization

It is good practice for any variables declared in the setup.bat file to be deinitialized in the teardown.bat file of the same tests directory. Otherwise, you risk that the declared variables affect any tests run in a different tests directory, which may not be desireable.

Assets 2
Loading