ASSERT

implements a logical check for testing

<conditional> - Logical test to be performed (EQ,EQS,... see IF tests)

The ASSERT command uses IF style conditions to perform tests.  The <conditional>
is the same type of <conditional> used in the IF command, i.e:
  IF <conditional> [AND/OR] [<conditional2>] ... statements.

The ASSERT intrinsic keeps a running count of the number of failures encountered
by ASSERT since initialization.  The /INIT=table also initializes a table name
<table> in the results table with the results of each ASSERT command with the
/TOTAL switch applied to construct an overall status for the test_all macro.

EXAMPLES:
  1) General usage within a test macro
    nM> ASSERT/TEXT="description of test" x eq 3.14

  2) To keep a running  total of all tests
    nM> ASSERT/INIT=G_STATUS           ! Initialize the failure count and use
                                       ! the result g_status to hold test data
    nM> %test_if                       ! Run the if tests
    nM> ASSERT/TID="IF"/TOTAL=TEST
    nM> ASSERT/TID="ALL"/TOTAL=TESTALL

  3) Run a simple test and keep the result of the test in STATUS
    nM> ASSERT/STAT=STATUS/DEBUG=NO 1 EQ 1
    nM> res status
     4S: STATUS          = PASS

  4) Use the /NOOP switch to exclude a missing test from counting as a failure
     for the cumulative tests.
    nM> assert/stat=status/text="missing test" /noop=MISS
    INFO: missing test.................................................MISS

  5) Use /GROUP= and /SUMMARY in testing data from a file:

    res t:myfileTests {TEXT="Testing myfile.prm"}
    file open f myfile.prm
      assert/group=myfileTests/test f.SIZE   EQ 1024
      assert/group=myfileTests/test f.XSTART EQ 0
      assert/group=myfileTests/test f.XDELTA EQ 0.123
      
      do i 0 f.size-1
        ! more tests
      enddo
    enddo
    assert/group=myfileTests/summary

  See the tests (test*.mm) in $NMROOT/nxm/sys/test for many more examples.

SWITCHES:
  /CS            - Perform a CASE SENSITIVE test (for EQS, EQSS and SUBS only).
                   [DEF=IgnoreCase]
  /DEBUG=NO      - Hide normal output, unless the test fails.
  /EXCEPT        - Condition should generate an exception.
  /GROUP=<tbl>   - Indicates a test is part of a group of tests, such as tests
                   for rows in a file. The table should contain the following
                   entries:
                      TEXT=<msg>  - Basic description of the test.
                   Note that this must be a table in the results table that is
                   writable as additional information will be written to it
                   to total up the number of tests that PASS/FAIL. Setting this
                   automatically sets /DEBUG=NO unless /SUMMARY is given. See
                   example #5 (above) for sample usage.            (Since 3.3.2)
  /NOOP=<text>   - Exclude a test from counting as a failure of the cumulative
                   tests. Default <text> is "N/A".
  /SUMMARY       - Used with /GROUP= to assert that all previous tests for that
                   group have passed. See example #5 (above).      (Since 3.3.2)
  /TEST=PASS     - Assert that a test case will pass, and set the description
                   string (i.e. /TEXT=) to match the test case.
  /TEST=FAIL     - Assert that a test case will fail, and set the description
                   string (i.e. /TEXT=) to match the test case.
  /TEXT=<descr>  - String describing the test being performed. [DEFAULT="TEST"]
  /TOL=<n>       - The *relative* tolerance for EQT test (see IF)
  /DELTA=<n>     - The *absolute* tolerance for EQT test (see IF)  (Since 3.3.1)


  ---- The following switches are special-purpose or used within CONFIDENCE ----
  /HIDEFAIL=[Y|N]- INTERNAL USE ONLY to test ASSERT itself. [DEFAULT=NO]
                   If Yes, assert failure will NOT be displayed, but still
                   counted as a failed test.
  /INIT=<name>   - Initialize global counters and create global status table
                   names <name> (CONFIDENCE uses /INIT="G_STATUS").
  /LABEL=<label> - Used with /TOTAL= to indicate an alternate table to write
                   results to (rather than the global table set in /INIT=).
  /LTEXT=<n>     - Length of text when padded [DEFAULT=80]
  /PAD=[Y|N]     - Pad the output? [DEFAULT=YES]
  /STAT=<label>  - Result name to hold status of test = PASS or FAIL
                   [DEFAULT=no result]
  /TID=<tid>     - Table ID, used with /TOTAL to denote overall results entry,
                   this also overrides the default value for /TEXT= with the
                   given test id.
  /TOTAL=RESET   - INTERNAL USE ONLY, do not use! Saves the current test
                   results into results table specified by /LABEL= and then
                   reset the test counters.
  /TOTAL=TEST    - Test current group (i.e. since last /TOTAL=TEST), write
                   table entry named by the /TID=entry value.
  /TOTAL=TESTALL - Test the total of all test since /INIT

SEE ALSO:  CONFIDENCE, IF, nxm.sys.lib.Args