02. Syntax

Unit test cases are defined in a text file using a Cobol-like syntax. Cobol statements can be embedded in the test cases as appropriate. The precompiler will copy the program under test to a temporary source file and merge the test cases into the copy.

General structure of a unit test file:

TESTSUITE 'description'

BEFORE-EACH
   _Cobol statements_
END-BEFORE

AFTER-EACH
   _Cobol statements_
END-AFTER

TESTCASE 'description'
    MOCK ... END-MOCK
    _Cobol statements_
    EXPECT fieldname TO BE value
    VERIFY mock [HAPPENED n TIMES | HAPPENED ONCE | NEVER HAPPENED]

TESTCASE 'description'
    etc.

Alphabetical list of keywords

AFTER-EACH

Cobol statements that you want to be executed after each TESTCASE (common teardown).

Example:

    AFTER-EACH
        MOVE SPACES TO WS-WORK-AREA
        MOVE ZERO TO WS-COUNTER
    END-AFTER

BEFORE-EACH

Cobol statements that you want to be executed before each TESTCASE (common setup).

Example:

    BEFORE-EACH
        INITIALIZE WS-FLAGS
        MOVE SPACES TO WS-TEMP-RECORD-AREA
    END-BEFORE

EXPECT

Assert a result.

Examples:

    EXPECT WS-ACCOUNT-STATUS TO BE 'ACTIVE'
    EXPECT WS-ACCOUNT-STATUS NOT TO BE 'CLOSED'
    EXPECT WS-SALE-AMT TO BE NUMERIC 123.45
    EXPECT WS-88-LEVEL-ITEM TO BE FALSE

IGNORE

Ignore the following TESTCASE.

Example:

    IGNORE
    TESTCASE 'This is a test case'
    MOVE SOMETHING TO SOMEWHERE.
    EXPECT SOMETHING-ELSE TO BE 'OK'

MOCK

Declare mock behavior for an external resource.

Examples:

Mock batch file access

    MOCK FILE INVOICE-FILE 
        ON OPEN STATUS IS OK
    END-MOCK
    MOCK FILE INVOICE-FILE
        ON READ RECORD IS 'ABCDEFGHIJKLMNOP'
    END-MOCK

Mock CALL statements

    MOCK CALL 'SUBPROG'
             USING ARG0 ARG1
         END-CALL
         MOVE 'TESTVALUE' TO WS-CALL-RESULT
    END-MOCK
    . . .
    MOCK CALL WS-SUBPROG-NAME
             USING BY CONTENT 'X'
                   BY REFERENCE ARG2
         END-CALL
         MOVE 'TESTVALUE1' TO RESULT-FIELD-1
         MOVE 'TESTVALUE2' TO RESULT-FIELD-2
    END-MOCK

Mock CICS commands

    MOCK CICS READ DATASET('FILENAME')
         INTO(WS-RECORD) LENGTH(WS-RECLEN) RIDFLD(WS-KEY)
         MOVE 'fakerecord' TO WS-RECORD
    END-MOCK
    . . .
    MOCK CICS DELAY 
         FOR SECONDS(WS-DELAY-INTERVAL) 
         REQID('splat')
    END-MOCK
    . . .
   * Simulate TRANSIDERR condition
    MOCK CICS START TRANSID('TR01')
         MOVE 28 TO DFHEIBRESP
    END-MOCK

Mock paragraphs

    MOCK PARAGRAPH 1000-PARA-A
        MOVE 'ABC' TO WS-FIELD-1
        MOVE 'XYZ' TO WS-FIELD-2
    END-MOCK

    MOCK PARA 2000-PARA-B
   * Do nothing
    END-MOCK

TESTCASE

Marks the beginning of a test case and provides a description for the test case.

Example:

    TESTCASE 'It doesn''t allow funds transfer from an overdrawn account'

   * Fake out the read from the input file
    MOCK FILE INPUT-FILE
        ON READ RECORD IS WS-TEMP-RECORD
    END-MOCK

   * Fake out the write to the transaction log file
    MOCK FILE TRANSACTION-LOG
        ON WRITE STATUS IS OK
    END-MOCK

   * Set the preconditions for the test case
    MOVE 'the values I want' TO WS-TEMP-RECORD
    MOVE ZERO TO WS-COUNTER
    SET ACCOUNT-STATUS-OVERDRAWN TO TRUE

   * Invoke the paragraph to be tested
    PERFORM 3500-FUNDS-TRANSFER

   * Assert the expected results
    EXPECT TRANSACTION-RESPONSE TO BE 'DENIED'
    EXPECT RESPONSE-REASON-CODE TO BE NUMERIC 129
    VERIFY FILE TRANSACTION-LOG WRITE HAPPENED ONCE

TESTSUITE

Provides a description for a set of unit test cases.

Example:

    TESTSUITE 'Unit tests for the invoice preparation program'

VERIFY

Asserts that a MOCK was accessed a given number of times during the test run.

General:

VERIFY [mock type] [mock identifier] [happened clause] [count]

Happened clause:

NEVER HAPPENED
HAPPENED [ONCE] [[AT LEAST | NO MORE THAN] count TIME[S]]

* For PARAGRAPH mocks only:
[[WAS] NEVER] PERFORMED
[WAS] PERFORMED [ONCE] [[AT LEAST | NO MORE THAN] count TIME[S]]

Examples:

VERIFY FILE INVOICE-FILE READ HAPPENED 24 TIMES
VERIFY FILE INVOICE-FILE OPEN HAPPENED ONCE
VERIFY FILE ERROR-LOG WRITE NEVER HAPPENED
VERIFY FILE INPUT-FILE OPEN HAPPENED NO MORE THAN ONCE
VERIFY FILE MASTER-FILE READ HAPPENED AT LEAST 2 TIMES
VERIFY CICS START TRANSID('TR01') HAPPENED ONCE
VERIFY PARAGRAPH 1000-PARA-A WAS PERFORMED 4 TIMES
VERIFY PARA 2000-PARA-B PERFORMED AT LEAST 3 TIMES
VERIFY PARAGRAPH 3000-PARA-C WAS NEVER PERFORMED
VERIFY PARA 4000-PARA-D NEVER PERFORMED