TestOrg

java.lang.Object
- org.vishia.util.TestOrg

```
public class TestOrg
extends java.lang.Object
```
This class supports testing. It may be seen as an alternative concept to the known Unit test concept (org.junit.Assert). But it is more simple and obviously because the test case is shown, all successfully tests can be shown. The result is given as text, it is able to evaluate for overview.

Pattern to use:
```
 public static void main(String[] args) { 
   TestOrg test = new TestOrg("Test description", 2, args);
   test.finish();
 }
 
 void testRoutine(TestOrg testParent) {
   TestOrg test = new TestOrg("Test routine description", 4, testParent);
   try {
     result = doSomethingToTest();
     test.expect(result == expected, 5, "test case description");
   } 
   catch (Exception exc) {
     test.exception(exc); 
   }
   test.finish();
 }
   
 
```
The output for this situation for a well test can be:
```
 ==================================================
 ok Test description
 ok Test routine description
 ok test case description
 
```
or the output is empty. It depends of a calling argument "---TESTverbose:1" on any position of main(). If the calling argument is "---TESTverbose:5" for this example it is outputted: The output for this situation for a well test can be:
```
 ==================================================
 Test routine description
   ok: test case description
 
```
It means the showing output depends on the verbose argument. The output will be written to standard output (System.out). If the output should be more verbose, all test cases are shown. So the tester can see what is tested. If the verbose level is less, only an overview over the test is created.

If the test fails, also on verbose level 0 it is shown:
```
 =========================================================================
 Test description
 Test routine description
   ERROR: test case description @ org.vishia.util.test.Test_TestOrg.mainF(Test_TestOrg.java:45); ... 
 
```
It means the test routine (title) and the failing test case is shown inclusively the line with calling stack of mex. 5 levels. So it may be possible to immediately find the failing reason if it is trivial (which is often so).

Especially for string comparison using expect(CharSequence, CharSequence, int, String) the position of the first difference can be shown, for example:
```
 ==============================================
 Test description
 Test routine description
   ERROR: @45 test case description @ org.vishia....
 ERROR  
 
```
Nested test routines will be supported well. See the examples on org.vishia.util.test.Test_TestOrg.java which is found on https://github.com/JzHartmut/testJava_vishiaBase.

The evaluation of the test results can be done by searching "ERROR:" in the output text or by text difference evaluation of the produced test output. Especially the second case shows additionally which test cases are changed. The reference output text can be stored in a text file with a specified version in a version management system, So the progress can be visited. It is some more better than a polish html view result.

The advantage of this system in comparison to unit test: Very simple. Only this class should be used, no complex package.
An individual test can be start in any main() routine of a test class
All tests of a module are programmed immediately by a main() routine in a TestAll class.

Field Summary

Fields
Modifier and Type	Field and Description
`private boolean`	`bOk`
`private boolean`	`bTitleShown`
`private java.util.Formatter`	`formatter`
`private int`	`nTestVerboseLevel`
`private int`	`nVerboseTitle`
`private java.lang.Appendable`	`out`
`private TestOrg`	`parent`
`private java.lang.StringBuilder`	`sbTxt`
`static java.lang.String`	`sVersion` Version, history and license.
`private java.lang.String`	`title`

Constructor Summary

Constructors
Constructor and Description
`TestOrg(java.lang.String title, int nVerbose, java.lang.String[] args)` Ctor stores the title and sets the internal `bOk` to true.
`TestOrg(java.lang.String title, int nVerbose, java.lang.String[] args, java.lang.Appendable testout)` Ctor like `TestOrg(String, int, String[])` but with: Parameter see `TestOrg(String, int, String[])`
`TestOrg(java.lang.String title, int nVerbose, TestOrg parent)` Ctor for nested tests. stores the title and sets the internal `bOk` to true.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`exception(java.lang.Exception exc)` Shows a proper text on an non expected exception, sets the internal `bOk` to false Note: An exception aborts the normal execution.
`private void`	`expect_(boolean cond, int nVerbose, java.lang.String txt, int nStackLevel, java.lang.Object... args)` core test routine
`void`	`expect(boolean cond, int nVerbose, java.lang.String txt, java.lang.Object... args)` Simple test check routine
`int`	`expect(java.lang.CharSequence s1, java.lang.CharSequence s2, int nVerbose, java.lang.String txt)` Compares both CharSequences, should be equal.
`void`	`finish()` This should use as last statement in a test routine.
`boolean`	`isOk()` Returns true if this test level has no error, may be invoked before finish for additional action on error.
`void`	`out(java.lang.CharSequence txt, java.lang.Object... args)` Out to the test output.
`void`	`outln(java.lang.CharSequence txt, java.lang.Object... args)` Out to the test output with following newline ('\n').
`private void`	`showParentTitle(java.lang.String sPreText)`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - sVersion
```
public static final java.lang.String sVersion
```
    Version, history and license.
    - 2023-07-15 Hartmut using Locale.ENGLISH for formatted output, elsewhere a goofy 12,34 comes in German numbers instead 12.34
    - 2023-02-02 Hartmut expect(boolean, int, String, Object...), out(CharSequence, Object...) now with arguemnts
    - 2022-09-13 Hartmut expect(CharSequence, CharSequence, int, String) now returns the position of difference for evaluation.
    - 2021-10-06 Hartmut expect(CharSequence, CharSequence, int, String) enhanced with showing positions of difference
    - 2020-06-21 Hartmut created as new feature for test organization.
    Copyright/Copyleft: For this source the LGPL Lesser General Public License, published by the Free Software Foundation is valid. It means:
    1. You can use this source without any restriction for any desired purpose.
    2. You can redistribute copies of this source to everybody.
    3. Every user of this source, also the user of redistribute copies with or without payment, must accept this license for further using.
    4. But the LPGL is not appropriate for a whole software product, if this source is only a part of them. It means, the user must publish this part of source, but don't need to publish the whole source of the own product.
    5. You can study and modify (improve) this source for own using or for redistribution, but you have to license the modified sources likewise under this LGPL Lesser General Public License. You mustn't delete this Copyright/Copyleft inscription in this source file.
    If you are intent to use this sources without publishing its usage, you can get a second license subscribing a special contract with the author.
    See Also:
    
    Constant Field Values
  - bOk
```
private boolean bOk
```
  - title
```
private final java.lang.String title
```
  - bTitleShown
```
private boolean bTitleShown
```
  - nTestVerboseLevel
```
private final int nTestVerboseLevel
```
  - sbTxt
```
private final java.lang.StringBuilder sbTxt
```
  - formatter
```
private final java.util.Formatter formatter
```
  - nVerboseTitle
```
private final int nVerboseTitle
```
  - out
```
private java.lang.Appendable out
```
  - parent
```
private final TestOrg parent
```
- Constructor Detail
  - TestOrg
```
public TestOrg(java.lang.String title,
               int nVerbose,
               java.lang.String[] args)
```
    Ctor stores the title and sets the internal bOk to true. The output is written to System.out (stdout). It calls TestOrg(String, int, String[], Appendable).
    
    Parameters:
    
    title - it is stored on shown on finish() or on an error.
    
    nVerbose - verbose level for the title. A lower number is a more prior message, a higher (..9) is a message only for a verbose output. Hence the output is not shown if the basic level (default 4) is lesser. This is the possibility to hide too much information about "ok" test cases.
    
    args - if one of the args contains "---TESTverbose:4" where the "4" is a digit between 0 and 9, then all messages with a nVerboseLevel <= this number are shown also in the ok case as information. ok messages with verbose level > this level are not shown to prevent to much information about test cases. The default value is 4.
  - TestOrg
```
public TestOrg(java.lang.String title,
               int nVerbose,
               java.lang.String[] args,
               java.lang.Appendable testout)
```
    Ctor like TestOrg(String, int, String[]) but with: Parameter see TestOrg(String, int, String[])
    
    Parameters:
    
    testout - any output channel (may be an opened file) for the test output.
  - TestOrg
```
public TestOrg(java.lang.String title,
               int nVerbose,
               TestOrg parent)
```
    Ctor for nested tests. stores the title and sets the internal bOk to true. The settings for the used verbose level and the testout came from parent.
    
    Parameters:
    
    title - it is stored on shown on finish() or on an error.
    
    nVerbose - verbose level for the title. A lower number is a more prior message, a higher (..9) is a message only for a verbose output.
    
    parent - from the calling routine. On an error or #finish() the title of all parent are shown.
- Method Detail
  - expect
```
public int expect(java.lang.CharSequence s1,
                  java.lang.CharSequence s2,
                  int nVerbose,
                  java.lang.String txt)
```
    Compares both CharSequences, should be equal. If not, shows the position of the first difference and the difference in s1. This difference position should help for evaluate the problem, to support recognizing what's happen without debugging. The difference is shown on error in form " ERROR: @pos: s1_onPos: txt"
    
    Parameters:
    
    s1 - The test result text to compare.
    
    s2 - The expected text.
    
    nVerbose - level of verbose: Same as in #expect(boolean, int, String). A lower number is a more prior message, a higher (..9) is a message only for a verbose output.
    
    txt - Understandable description of the test case
    
    Returns:
    
    0 if matching, position of difference in the strings if >0, never <0
  - expect
```
public void expect(boolean cond,
                   int nVerbose,
                   java.lang.String txt,
                   java.lang.Object... args)
```
    Simple test check routine
    
    Parameters:
    
    cond - if false, bOk and all parent.bOk are set to false because the test serie has an error. If false then "ERROR" on first line position is shown, the txt and 3 stack levels (File and line) are shown to locate the error in the sources. If true and nVerbose is <= the given verbose level on constructor (more prior), then then "ok" and the text is shown.
    
    nVerbose - level of verbose: A lower number is a more prior message, a higher (..9) is a message only for a verbose output.
    
    txt - Understandable description of the test case
  - expect_
```
private void expect_(boolean cond,
                     int nVerbose,
                     java.lang.String txt,
                     int nStackLevel,
                     java.lang.Object... args)
```
    core test routine
  - showParentTitle
```
private void showParentTitle(java.lang.String sPreText)
```
  - exception
```
public void exception(java.lang.Exception exc)
```
    Shows a proper text on an non expected exception, sets the internal bOk to false Note: An exception aborts the normal execution. Hence an exception in a test scenario is only practicable if the exception feature itself should be tested. Then the test routine should be written in a special:
```
   boolean bOk = false;
   try {
     testRoutineShouldThrow()
   } catch Exception(exc) {
     bOk = (exc instanceof Type...);
     test.expect(exc.getMessage(), expectedMessage,...)
   }
   test.expect(bOk, ...)
 
```
    It means this routine is not appropriate to use! This routine is only proper for an unexpected exception. To continue a test though unexected exceptions are possible you should wrap less tests, or only one in a try frame:
```
   try {
     result = testRoutine();
     test.expect(result, expectedResult, ...);
   } catch Exception(exc) {
     test.exception(exc);  //will be notified as not successfully test.
   }
 
```
    Parameters:
    
    exc - The exception.
  - finish
```
public void finish()
```
    This should use as last statement in a test routine. It writes "ok Test routine title" if no ERROR output was produced (checks internal bOk). depending of the verbose level. The verbose level is given on ctor of this. If an error was shown in an expect...(...) routine or in exception(Exception) then the title of all test routines are shown already. Hence this routine does nothing.
    
    If an inner finish() is called it writes firstly the title of the test routine of parent levels if they are not shown already. The title of parents are shown if either an error in another parallel test routine before was shown or if a finish() of a called test routine before was executed.
    
    See examples is org.vishia.util.test.Test_TestOrg on https://github.com/JzHartmut/testJava_vishiaBase.
  - isOk
```
public boolean isOk()
```
    Returns true if this test level has no error, may be invoked before finish for additional action on error.
    
    Returns:
    
    this.bOk of this level.
  - out
```
public void out(java.lang.CharSequence txt,
                java.lang.Object... args)
```
    Out to the test output.
    
    Parameters:
    
    txt -
  - outln
```
public void outln(java.lang.CharSequence txt,
                  java.lang.Object... args)
```
    Out to the test output with following newline ('\n').
    
    Parameters:
    
    txt -

Class TestOrg

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

sVersion

bOk

title

bTitleShown

nTestVerboseLevel

sbTxt

formatter

nVerboseTitle

out

parent

Constructor Detail

TestOrg

TestOrg

TestOrg

Method Detail

expect

expect

expect_

showParentTitle

exception

finish

isOk

out

outln