tap-parser.node.txt

                                  ┏━━━━━━━━━━━━━━━━┓
                                  ┃   TAP-PARSER   ┃
                                  ┗━━━━━━━━━━━━━━━━┛

ALTERNATIVES ==>                  #  - tap-parser (prefered): most high-profile
                                  #  - tap-out:
                                  #     - not well maintained
                                  #     - does not handle todo|skip|bailout|children|pragma
                                  #     - does not handle node-tap output
                                  #     - better support for specific comments (TEST_TITLE, summary)

VERSION ==>                       #10.1.0

                                  ┌─────────┐
                                  │   RUN   │
                                  └─────────┘

new TapParser([OPTS, ][FUNC])     #IOSTREAM (in object mode) that parses TAP format from input
                                  #OPTS:
                                  #  - passes BOOL (def: false): add RESULTS.passes
                                  #  - strict BOOL (def: false):
                                  #     - consider invalid TAP (e.g. unknown line, invalid YAML) as an assertion failure
                                  #     - can use pragma +strict|-strict to turn on|off
                                  #  - preserveWhitespace BOOL (def: false): emit 'line' events for empty lines outside YAML props
                                  #  - bail BOOL (def: false): stop parsing on 'bailout' event
                                  #  - omitVersion BOOL (def: false): do not emit 'version' event
                                  #  - name STR
                                  #  - parent TAPPARSER
                                  #FUNC is 'complete' event

parse(STR[, OPTS])->RESULTS       #
stringify(RESULTS[, OPTS])->STR   #

tap-parser                        #Same as CLI
                                  #Prints all ['EVENT', EVENT_VAL]
                                  #Exit code 1 if RESULTS.ok false
                                  #Uses stdin and stdout
--ignore-all-whitespaces|w
--[no-]bail|b
--omit-version|o                  #Same as respective OPTS
--json|j [NUM]                    #Prints using JSON.stringify() instead of UTIL.inspect()
--lines|l                         #Prints input back, but only the lines that generated a 'line' event
--tap|t                           #Prints as TAP instead
--[no-]silent|s                   #Only exit code
--[no-]strict                     #
--[no-]flat|f                     #Flattens nested TAPPARSER (def: not flattened)

                                  ┌────────────┐
                                  │   TOKENS   │
                                  └────────────┘

TAPPARSER.on                      #Summary. RESULTS:
 ('complete', FUNC(RESULTS))      #  - plan PLAN
                                  #  - count NUM: of assertions
                                  #  - pass|fail|todo|skip NUM: of successful|failed|todo|skipped assertions
                                  #  - failures|passes ASSERT_ARR
                                  #  - bailout BOOL
                                  #  - ok BOOL: count === pass (except skipped|todo), no Bail out, no Plan error and no syntax error

TAPPARSER.on('line', FUNC('LINE'))#Single line (of any type)
TAPPARSER.on
 ('comment', FUNC('COMMENT'))     #Single #COMMENT line
TAPPARSER.on('plan', FUNC(PLAN))  #Single plan line. PLAN:
                                  #  - start|end NUM
                                  #  - comment 'COMMENT'
                                  #  - skipAll BOOL
                                  #  - skipReason 'COMMENT'
TAPPARSER.on
 ('version', FUNC(VERSION_NUM))   #
TAPPARSER.on                      #Single assertion. ASSERT:
 ('assert|result', FUNC(ASSERT))  #  - ok BOOL
                                  #  - id INDEX
                                  #  - name 'ASSERT_TITLE'
                                  #  - fullname
                                  #  - todo|skip undefined|true|'COMMENT'
                                  #  - diag OBJ (YAML properties)
                                  #  - buffered BOOL (buffered child)
                                  #  - tapError STR (TAP syntax error)
                                  #If 'result', only top-level assertions
TAPPASER.on('pass|fail|skip|todo',
 FUNC(ASSERT))                    #
TAPPARSER.on
 ('bailout', FUNC('COMMENT'))     #

TAPPARSER.on                      #Supports any of the syntaxes
 ('child', FUNC(TAPPARSER2))      #Propagates to its parent: RESULTS.ok, 'bailout|line' events
                                  #Does not propagate to its parent: 'complete|comment|assert|plan|extra' events
                                  #Not allowed: 'pragma' events
                                  #TAPPARSER2:
                                  #  - name 'TEST_TITLE' (using '# Subtest: TEST_TITLE')
                                  #  - level NUM is nesting depth

TAPPARSER.on
 ('pragma', FUNC('VAR', BOOL))    #On pragma +VAR|-VAR

TAPPARSER.on('extra', FUNC(STR))  #Unknown line

TAPPARSER.fullname                #'ASSERT_TITLE [CHILD_TEST_TITLE]'