; --------------------------------------------------------------------------------
; @Title: Readme for LBTEST - Unit tests in PRACTICE
; @Description:
;   Readme for unit test framework for automated tests
; @Keywords: assertion assertions lbtest test unit unittest
; @Author: MOB
; @Copyright: (C) 1989-2021 Lauterbach GmbH, licensed for use with TRACE32(R) only
; --------------------------------------------------------------------------------
; $Id: README.md 18030 2021-07-26 11:42:05Z mobermeir $

#  Unit tests in PRACTICE - lbtest

Unit test framework for automated tests in PRACTICE

## Usage

    DO lbtest.cmm [options]

To see all available options run:

    DO lbtest.cmm --help

## Test Execution

Run `lbtest.cmm` from your current working directory, e.g.:

    ChDir /path/to/my/tests
    DO ~~/demo/practice/unittest/lbtest.cmm

Alternatively use the parameter `--workingdir=/path/to/my/tests` when running `lbtest.cmm`, e.g.:

    DO ~~/demo/practice/unittest/lbtest.cmm --workingdir=/path/to/my/tests

The script `lbtest.cmm` can also be used standalone, simply copy it
to the directory where your tests are located and run it from there:

    CD.DO lbtest.cmm

## Concept

The script `lbtest.cmm` will automatically find all available _test cases_
in your current working directory and execute them.

A _test case_ is a PRACTICE script named `test_<testcase>.cmm`. It starts with a
mandatory block followed by tests, see `test_example.cmm`.

A _test case_ contains one or more _tests_, where each _test_ is a PRACTICE
subroutine starting with the prefix `Test_`.

Optionally - when defined in the _test case_ - Setup and TearDown subroutines
will be executed:
- `SetupTestCase` will be called once at the beginning of the test case
- `SetupTest` will be called just before every test
- `TearDownTest` will be called just after every test
- `TearDownTestCase` will be called once at the end of the test case

The command `PUTS` can be used to print indented text (see example scripts).

_Tests_ can be written quickly using assertions, see `test_example_assertions.cmm`.
[Assertions](#Assertions) can be used inside _tests_, their subroutines and also inside the
_Setup_ and _TearDown_ routines.

A _test case_ will be marked as failed if one ore more _tests_ failed.

A _test_ will be marked as failed if one or more [assertions](#Assertions) failed, or if the
test returned `FAIL`.

To disable a test case simply rename the corresponding script file so it
doesn't start with `test_`.
To disable a single test simply rename it's label so it doesn't start with
`Test_`.

For available debugging options run:

    DO lbtest.cmm --help

## Assertions

### Generic assertions
* `A_TRUE <condition> [optional fail message]`
    Assert that given `<condition>` is true.
* `A_FALSE <condition> [optional fail message]`
    Assert that given `<condition>` is false.
* `A_EQUALS <expected> <actual> [optional fail message]`
    Assert that given arguments are equal.
    This is a generic command which also makes sure that the types of both
    arguments are equal. Use more specialized assertions if possible
    (e.g. `A_NUM_EQ` or `A_STR_EQ`).
* `A_UNEQUAL <expected> <actual> [optional fail message]`
    Assert that given arguments are unequal.

### Numerical assertions
* `A_NUM_EQ <expected> <actual> [optional fail message]`
    Assert that given arguments are numerically equal. This works for
    hexadecimal, integer and binary types.
* `A_NUM_NE <expected> <actual> [optional fail message]`
    Assert that given arguments are numerically not equal. This works for
    hexadecimal, integer and binary types.
* `A_NUM_GT <arg1> <arg2> [optional fail message]`
    Assert that `arg1` is numerically greater than `arg2`. This works for
    hexadecimal, integer and binary types.
* `A_NUM_GE <arg1> <arg2> [optional fail message]`
    Assert that `arg1` is numerically greater than or equal to `arg2`. This works
    for hexadecimal, integer and binary types.
* `A_NUM_LT <arg1> <arg2> [optional fail message]`
    Assert that `arg1` is numerically less than `arg2`. This works for hexadecimal,
    integer and binary types.
* `A_NUM_LE <arg1> <arg2> [optional fail message]`
    Assert that `arg1` is numerically less than or equal to `arg2`. This works for
    hexadecimal, integer and binary types.

### String assertions
* `A_STR_EQ <expected> <actual> [optional fail message]`
    Assert that given argument strings are equal. This works only for string
    types.
* `A_STR_NE <expected> <actual> [optional fail message]`
    Assert that given argument strings are not equal. This works only for
    string types.
* `A_STR_Z <arg> [optional fail message]`
    Assert that given argument string is empty.
* `A_STR_N <arg> [optional fail message]`
    Assert that given argument string is not empty.

### Execution assertions
* `A_X_PASS <command> [args] //no optional fail message`
    Assert that execution of given command raises no error.
* `A_X_FAIL <command> [args] //no optional fail message`
    Assert that execution of given command raises some error.