bare-script 3.8.2__py3-none-any.whl

bare_script/include/unittest.bare

@@ -0,0 +1,529 @@
+# Licensed under the MIT License
+# https://github.com/craigahobbs/bare-script/blob/main/LICENSE
+
+
+include <args.bare>
+include <dataTable.bare>
+include <diff.bare>
+
+
+# $function: unittestRunTest
+# $group: unittest.bare
+# $doc: Run a unit test
+# $arg testName: The test function name
+async function unittestRunTest(testName):
+    # Tests disabled?
+    if systemGlobalGet('vUnittestDisabled'):
+        return
+    endif
+
+    # Single test argument?
+    vUnittestTest = systemGlobalGet('vUnittestTest')
+    if vUnittestTest && vUnittestTest != testName:
+        return
+    endif
+
+    # Get the global unittest data
+    unittestData = unittestDataGet()
+    unittestTests = objectGet(unittestData, 'tests')
+    unittestWarnings = objectGet(unittestData, 'warnings')
+
+    # Test run multiple times?
+    if objectHas(unittestTests, testName):
+        arrayPush(unittestWarnings, 'Test "' + testName + '" run multiple times')
+        return
+    endif
+
+    # Get the test func
+    testFn = systemGlobalGet(testName)
+    if !testFn:
+        arrayPush(unittestWarnings, 'Test "' + testName + '" not found')
+        return
+    endif
+
+    # Add the unit test result array
+    testFailures = []
+    objectSet(unittestTests, testName, testFailures)
+
+    # Run the test
+    objectSet(unittestData, 'current', testName)
+    testFn()
+    objectSet(unittestData, 'current', null)
+endfunction
+
+
+# For backward compatibility
+async function unittestRunTestAsync(testName):
+    systemLogDebug('unittest.bare: unittestRunTestAsync is deprecated - use unittestRunTest')
+    return unittestRunTest(testName)
+endfunction
+
+
+# $function: unittestEqual
+# $group: unittest.bare
+# $doc: Assert an actual value is equal to the expected value
+# $arg actual: The actual value
+# $arg expected: The expected value
+# $arg description: The description of the assertion
+function unittestEqual(actual, expected, description):
+    if actual == expected:
+        return
+    endif
+
+    # Get the global unittest data
+    unittestData = unittestDataGet()
+    unittestTests = objectGet(unittestData, 'tests')
+    unittestCurrent = objectGet(unittestData, 'current')
+    testFailures = objectGet(unittestTests, unittestCurrent)
+
+    # Add the test failure error lines
+    errorLines = [ \
+        'Equal:', \
+        '', \
+        '```', \
+        jsonStringify(actual), \
+        '```', \
+        '', \
+        '```', \
+        jsonStringify(expected), \
+        '```' \
+    ]
+    if description:
+        arrayPush(testFailures, arrayExtend([markdownEscape(description), ''], errorLines))
+    else:
+        arrayPush(testFailures, errorLines)
+    endif
+endfunction
+
+
+# $function: unittestDeepEqual
+# $group: unittest.bare
+# $doc: Assert an actual value is *deeply* equal to the expected value
+# $arg actual: The actual value
+# $arg expected: The expected value
+# $arg description: The description of the assertion
+function unittestDeepEqual(actual, expected, description):
+    # Serialize as JSON
+    actualJSON = if(systemType(actual) == 'string', actual, jsonStringify(actual, 4))
+    expectedJSON = if(systemType(expected) == 'string', expected, jsonStringify(expected, 4))
+    if actualJSON == expectedJSON:
+        return
+    endif
+
+    # Compute the difference lines
+    errorLines = []
+    diffErrorLines = []
+    for diff in diffLines(actualJSON, expectedJSON):
+        diffType = objectGet(diff, 'type')
+        if diffType == 'Remove':
+            for diffLine in objectGet(diff, 'lines'):
+                arrayPush(diffErrorLines, '--- ' + diffLine)
+            endfor
+        elif diffType == 'Add':
+            for diffLine in objectGet(diff, 'lines'):
+                arrayPush(diffErrorLines, '+++ ' + diffLine)
+            endfor
+        else:
+            # diffType == 'Identical'
+            if diffErrorLines:
+                arrayExtend(errorLines, ['Deep-equal:', '', '```'])
+                arrayExtend(errorLines, diffErrorLines)
+                arrayPush(errorLines, '```')
+                diffErrorLines = []
+            endif
+        endif
+    endfor
+    if diffErrorLines:
+        arrayExtend(errorLines, ['Deep-equal:', '', '```'])
+        arrayExtend(errorLines, diffErrorLines)
+        arrayPush(errorLines, '```')
+    endif
+
+    # Get the global unittest data
+    unittestData = unittestDataGet()
+    unittestTests = objectGet(unittestData, 'tests')
+    unittestCurrent = objectGet(unittestData, 'current')
+    testFailures = objectGet(unittestTests, unittestCurrent)
+
+    # Add the test failure error lines
+    if description:
+        arrayPush(testFailures, arrayExtend([markdownEscape(description), ''], errorLines))
+    else:
+        arrayPush(testFailures, errorLines)
+    endif
+endfunction
+
+
+# Helper to get the global unittest data object
+function unittestDataGet():
+    unittestData = systemGlobalGet('unittestData')
+    if unittestData == null:
+        unittestData = {'tests': {}, 'warnings': [], 'current': null}
+        systemGlobalSet('unittestData', unittestData)
+    endif
+    return unittestData
+endfunction
+
+
+# $function: unittestReport
+# $group: unittest.bare
+# $doc: Render the unit test report
+# $arg options: Optional unittest report options object. The following options are available:
+# $arg options: - **coverageExclude** - array of script names to exclude from coverage
+# $arg options: - **coverageMin** - verify minimum coverage percent (0 - 100)
+# $arg options: - **links** - the array of page links
+# $arg options: - **title** - the page title
+# $return: The number of unit test failures
+function unittestReport(options):
+    coverageMin = if(options, objectGet(options, 'coverageMin', 0), 0)
+    coverageExclude = if(options, objectGet(options, 'coverageExclude'))
+    links = if(options, objectGet(options, 'links'))
+    defaultTitle = 'unittestReport'
+    title = if(options, objectGet(options, 'title', defaultTitle), defaultTitle)
+
+    # Parse arguments
+    args = argsParse(unittestReportArguments)
+    isDisabled = objectGet(args, 'disabled')
+    hideTests = objectGet(args, 'hideTests')
+    isReport = objectGet(args, 'report')
+    scriptName = objectGet(args, 'script')
+    testNameArg = objectGet(args, 'test')
+
+    # Disabled?
+    if isDisabled:
+        return 0
+    endif
+
+    # Script coverage details page?
+    if scriptName:
+        unittestReportScript(scriptName)
+        return 0
+    endif
+
+    # Get the global unittest data
+    unittestData = unittestDataGet()
+    unittestTests = objectGet(unittestData, 'tests')
+    unittestWarnings = objectGet(unittestData, 'warnings')
+
+    # Compute test statistics
+    testNames = arraySort(objectKeys(unittestTests))
+    testCount = arrayLength(testNames)
+    testFailCount = 0
+    for testName in testNames:
+        testFailures = objectGet(unittestTests, testName)
+        if arrayLength(testFailures):
+            testFailCount = testFailCount + 1
+        endif
+    endfor
+    testPassCount = testCount - testFailCount
+
+    # Render the links
+    if !isReport && links:
+        markdownPrint(arrayJoin(links, ' | '))
+    endif
+
+    # Render the page title
+    documentSetTitle(title)
+    markdownPrint( \
+        '# ' + markdownEscape(title), \
+        '', \
+        'Ran ' + testCount + ' tests - ' + testPassCount + ' passed, ' + testFailCount + ' failed' \
+    )
+    if !isReport:
+        if testNameArg:
+            markdownPrint('', argsLink(unittestReportArguments, 'All tests', null, true))
+        else:
+            markdownPrint('', argsLink(unittestReportArguments, if(hideTests, 'Show', 'Hide') + ' tests', {'hideTests': !hideTests}))
+        endif
+    endif
+
+    # Report any warnings
+    testWarningCount = arrayLength(unittestWarnings)
+    if testWarningCount:
+        markdownPrint('', '## Warnings')
+        for warning in unittestWarnings:
+            markdownPrint('', '- ' + markdownEscape(warning))
+        endfor
+    endif
+
+    # Report the failing tests
+    if testFailCount:
+        markdownPrint('', '## Failing Tests')
+        if hideTests && !isReport && !testNameArg:
+            markdownPrint('', argsLink(unittestReportArguments, 'Show', {'hideTests': false}))
+        endif
+        if !hideTests || testNameArg:
+            for testName in testNames:
+                testFailures = objectGet(unittestTests, testName)
+                if arrayLength(testFailures):
+                    failureLink = if(isReport, testName, \
+                        argsLink(unittestReportArguments, testName, {'test': testName}, false, '_top'))
+                    failureLines = ['', failureLink + ' - FAIL']
+                    for errorLines in testFailures:
+                        for errorLine, ixErrorLine in errorLines:
+                            if ixErrorLine == 0:
+                                arrayPush(failureLines, '')
+                                arrayPush(failureLines, '- ' + errorLine)
+                            else:
+                                arrayPush(failureLines, if(errorLine, '  ' + errorLine, ''))
+                            endif
+                        endfor
+                    endfor
+                    markdownPrint(failureLines)
+                endif
+            endfor
+        endif
+    endif
+
+    # Report the passing tests
+    if testPassCount:
+        markdownPrint('', '## Passing Tests')
+        if hideTests && !isReport && !testNameArg:
+            markdownPrint('', argsLink(unittestReportArguments, 'Show', {'hideTests': false}))
+        endif
+        if !hideTests || testNameArg:
+            for testName in testNames:
+                testFailures = objectGet(unittestTests, testName)
+                if !arrayLength(testFailures):
+                    testLink = if(isReport, testName, \
+                        argsLink(unittestReportArguments, testName, {'test': testName}, false, '_top'))
+                    markdownPrint('', testLink + ' - OK')
+                endif
+            endfor
+        endif
+    endif
+
+    # Coverage report
+    coverage = coverageGlobalGet()
+    coverageFailCount = 0
+    if !testNameArg && coverage:
+        markdownPrint('', '## Coverage Report')
+
+        # Compute the coverage data table
+        coverageData = unittestCoverageData(coverageExclude)
+        if coverageData:
+            # Verify the coverage percent
+            coveragePercent = objectGet(arrayGet(coverageData, arrayLength(coverageData) - 1), 'Coverage')
+            if coveragePercent < coverageMin:
+                markdownPrint( \
+                    '', \
+                    '**Error**: Coverage percentage, ' + numberToFixed(coveragePercent, 1, true) + \
+                        '%, is below the minimum coverage percentage of ' + numberToFixed(coverageMin, 1, true) + '%.' \
+                )
+                coverageFailCount = coverageFailCount + 1
+            endif
+
+            # Render the coverage data table
+            for row in coverageData:
+                scriptName = objectGet(row, 'Script')
+                if !isReport && !stringStartsWith(scriptName, '**'):
+                    objectSet(row, 'Script', argsLink(unittestReportArguments, scriptName, {"script": scriptName}, false, "_top"))
+                endif
+                objectSet(row, 'Coverage', numberToFixed(objectGet(row, 'Coverage'), 1) + '%')
+            endfor
+            markdownPrint('', dataTableMarkdown(coverageData, { \
+                'fields': ['Script', 'Statements', 'Missing', 'Coverage'], \
+                'formats': { \
+                    'Statements': {'align': 'right'}, \
+                    'Missing': {'align': 'right'}, \
+                    'Coverage': {'align': 'right'} \
+                } \
+            }))
+        else:
+            markdownPrint('', '*No data.*')
+        endif
+    endif
+
+    # Return status code
+    return testWarningCount + testFailCount + coverageFailCount
+endfunction
+
+
+# unittestReport application arguments
+unittestReportArguments = argsValidate([ \
+    {'name': 'disabled', 'global': 'vUnittestDisabled', 'type': 'bool', 'default': false}, \
+    {'name': 'hideTests', 'global': 'vUnittestHideTests', 'type': 'bool', 'default': false}, \
+    {'name': 'report', 'global': 'vUnittestReport', 'type': 'bool', 'default': false}, \
+    {'name': 'script', 'global': 'vUnittestScript'}, \
+    {'name': 'test', 'global': 'vUnittestTest'} \
+])
+
+
+# Render the script coverage details page
+function unittestReportScript(scriptName):
+    # Render the script coverage page title
+    title = scriptName + ' Coverage'
+    documentSetTitle(title)
+    markdownPrint( \
+        argsLink(unittestReportArguments, 'Back', {'script': null}, false, '_top'), \
+        '', \
+        '# ' + markdownEscape(title) \
+    )
+
+    # Get the script coverage data
+    coverage = coverageGlobalGet()
+    scripts = if(coverage, objectGet(coverage, 'scripts'))
+    coverageScript = if(scripts, objectGet(scripts, scriptName))
+    if !coverageScript:
+        markdownPrint('', '*No data.*')
+        return
+    endif
+    script = objectGet(coverageScript, 'script')
+    covered = objectGet(coverageScript, 'covered')
+    scriptLines = objectGet(script, 'scriptLines')
+
+    # Mark the statements covered or not-covered
+    lineColors = {}
+    statements = unittestScriptStatements(script)
+    for statement in statements:
+        statementKey = arrayGet(objectKeys(statement), 0)
+        lineNumber = objectGet(objectGet(statement, statementKey), 'lineNumber')
+        lineCount = objectGet(objectGet(statement, statementKey), 'lineCount', 1)
+        lineStr = stringNew(lineNumber)
+        lineColor = if(objectHas(covered, lineStr), '#a0a0a030', '#f0808080')
+        objectSet(lineColors, lineStr, lineColor)
+        if lineCount > 1:
+            lineNumberEnd = lineNumber + lineCount
+            lineNumber = lineNumber + 1
+            while lineNumber < lineNumberEnd:
+                objectSet(lineColors, stringNew(lineNumber), lineColor)
+                lineNumber = lineNumber + 1
+            endwhile
+        endif
+    endfor
+
+    # Generate the code coverage details
+    codeLineElements = []
+    codeElements = {'html': 'pre', 'elem': codeLineElements}
+    currentLines = []
+    currentColor = null
+    for line, ixLine in scriptLines:
+        # Accumulate lines of the same color
+        lineColor = objectGet(lineColors, stringNew(ixLine + 1))
+        if lineColor == currentColor:
+            arrayPush(currentLines, line)
+            continue
+        endif
+
+        # Render the current lines
+        unittestReportScriptLines(codeLineElements, currentLines, currentColor)
+        currentLines = [line]
+        currentColor = lineColor
+    endfor
+    unittestReportScriptLines(codeLineElements, currentLines, currentColor, true)
+    elementModelRender(codeElements)
+endfunction
+
+
+function unittestReportScriptLines(codeLineElements, lines, color, noNewline):
+    if lines:
+        linesStr = arrayJoin(lines, '\n') + if(noNewline, '', '\n')
+        if !color:
+            arrayPush(codeLineElements, {'text': linesStr})
+        else:
+            arrayPush(codeLineElements, { \
+                'html': 'span', \
+                'attr': {'style': 'display: block; background-color: ' + color}, \
+                'elem': {'text': linesStr} \
+            })
+        endif
+    endif
+endfunction
+
+
+# Get the coverage data table - columns are "Script", "Statement", "Covered", and "Percent"
+function unittestCoverageData(coverageExclude):
+    data = []
+
+    # Get the global coverage object
+    coverage = coverageGlobalGet()
+    if coverage:
+        # Get the script names with coverage data
+        scripts = objectGet(coverage, 'scripts')
+        scriptNames = if(scripts, arraySort(objectKeys(scripts)), [])
+
+        # Compute script statement coverage
+        totalStatements = 0
+        totalMissing = 0
+        for scriptName in scriptNames:
+            # Excluded?
+            if coverageExclude:
+                isExcluded = false
+                for excludeScriptName in coverageExclude:
+                    if stringEndsWith(scriptName, excludeScriptName):
+                        isExcluded = true
+                        break
+                    endif
+                endfor
+                if isExcluded:
+                    continue
+                endif
+            endif
+
+            # Get the script members
+            coverageScript = objectGet(scripts, scriptName)
+            script = objectGet(coverageScript, 'script')
+            covered = objectGet(coverageScript, 'covered')
+            statements = unittestScriptStatements(script)
+            statementCount = arrayLength(statements)
+
+            # Count statements with coverage
+            missingCount = 0
+            for statement in statements:
+                statementKey = arrayGet(objectKeys(statement), 0)
+                lineNumber = objectGet(objectGet(statement, statementKey), 'lineNumber')
+                lineStr = stringNew(lineNumber)
+                if !objectHas(covered, lineStr):
+                    missingCount = missingCount + 1
+                    totalMissing = totalMissing + 1
+                endif
+                totalStatements = totalStatements + 1
+            endfor
+
+            # Add the script coverage data row
+            coveragePercent = if(statementCount, 100 * (statementCount - missingCount) / statementCount, 100)
+            arrayPush(data, { \
+                'Script': scriptName, \
+                'Statements': statementCount, \
+                'Missing': missingCount, \
+                'Coverage':  coveragePercent, \
+                'CoverageStr': numberToFixed(coveragePercent, 1) + '%'  \
+            })
+        endfor
+
+        # Add the coverage totals data row
+        if scriptNames:
+            coveragePercent = if(totalStatements, 100 * (totalStatements - totalMissing) / totalStatements, 100)
+            arrayPush(data, { \
+                'Script': '**Total**', \
+                'Statements': totalStatements, \
+                'Missing': totalMissing, \
+                'Coverage': coveragePercent, \
+                'CoverageStr': numberToFixed(coveragePercent, 1) + '%'  \
+            })
+        endif
+    endif
+
+    return data
+endfunction
+
+
+# Get a script's array of statements
+function unittestScriptStatements(script):
+    statements = []
+
+    # Add the top-level script statements
+    for statement in objectGet(script, 'statements'):
+        arrayPush(statements, statement)
+
+        # Add function statements
+        statementKey = arrayGet(objectKeys(statement), 0)
+        if statementKey == 'function':
+            for funcStatement in objectGet(objectGet(statement, statementKey), 'statements'):
+                arrayPush(statements, funcStatement)
+            endfor
+        endif
+    endfor
+
+    return statements
+endfunction