<commit_before>#TODO: conurrently run tests.
#TODO: Determine if detection pipeline functions for scanning are still necessary
##############################################################################
##
##  Purpose:
##    Test component dependencies, like Docker CLI version, to ensure
##    they exist and are of proper verison.
##
##  Note:
##    Although this function should unwind itself when it detects
##    dependency problems, it should attempt to identify as many dependency
##    and environment setup problems as it can before executing the uwind.
## 
##  Inputs:
##    None.
##
##  Outputs:
##    When successful - none.
##    Otherwise - Write error messages to STDERR.
##
###############################################################################
TestEnvironentDependenciesAssert(){
  ScriptUnwind "$LINENO"  "Please override '$FUNCNAME'."
}
##############################################################################
##
##  Purpose:
##    see VirtCmmdInterface.sh -> VirtCmmdConfigSetDefault
##    However, this called after the framework adds its own default settigs.
##
###############################################################################
TestConfigSetDefault(){
  ScriptUnwind "$LINENO"  "Please override '$FUNCNAME'."
}
##############################################################################
##
##  Purpose:
##    Display "Usage:" information for the specific test.
##
###############################################################################
TestHelpCmmdUsageDisplay(){
  ScriptUnwind "$LINENO"  "Please override '$FUNCNAME'."
}
##############################################################################
##
##  Purpose:
##    see VirtCmmdInterface.sh -> VirtCmmdConfigSetDefault
##
###############################################################################
VirtCmmdConfigSetDefault(){
  TEST_SELECT_ALL='[0-9]*'
  TestConfigSetDefault
}
##############################################################################
##
##  Purpose:
##    see VirtCmmdInterface.sh -> VirtCmmdHelpDisplay
##
###############################################################################
VirtCmmdHelpDisplay() {
  echo
  TestHelpCmmdUsageDisplay
  cat <<COMMAND_HELP
TEST_NUM:  {'${TEST_SELECT}'| REGEX_SPEC [REGEX_SPEC...]}
    '${TEST_SELECT}'    Execute every test in numerical order.  Default value.
    REGEX_SPEC  A regular expression that selects the desired integer test label
                set. Must select at least one test to be considered valid. 
                Selected set executed in numerical order.
OPTIONS:
    --no-depnd=false     Execute dependency testing to ensure that dependent components
                           exist and are in correct state. 
    --no-scan=false      Execute tests without initially scanning the environment for 
                           every artifact created, used, and destroyed by every test.
                           Test artifact names may overlap with existing ones, not
                           produced by testing that share identical names/identities.
                           Detecting artifacts during a scan terminates testing 
                           before executing any tests or performing cleanup.
    --no-clean=false     Retain current testing environment and begin executing tests.
                           Otherwise, clean the environment before testing begins.
                           In any case, each test's cleanup routine will be executed
                           after its successful completion.
    --help               Provide command description.
    --ver                Display version and dependencies.
COMMAND_HELP
}
###############################################################################
##
##  Purpose:
##    see VirtCmmdInterface.sh -> VirtCmmdOptionsArgsDef
##
###############################################################################
VirtCmmdOptionsArgsDef(){
cat <<OPTIONARGS
Arg1 single '[0-9]*' "TestSelectSpecificationVerify \\<Arg1\\>" required ""
ArgN single ''       "TestSelectSpecificationVerify \\<ArgN\\>" optional ""
--no-depnd single false=EXIST=true "OptionsArgsBooleanVerify \\<--no-depnd\\>" required ""
--no-scan  single false=EXIST=true "OptionsArgsBooleanVerify \\<--no-scan\\>"  required ""
--no-clean single false=EXIST=true "OptionsArgsBooleanVerify \\<--no-clean\\>" required ""
OPTIONARGS
}
###############################################################################
##
##  Purpose:
##    Ensure test selection specification selects at least one test.
##
##  Input:
##    $1 - A potential RegEx expression.
##
##  Output:
##    When failure:
##      SYSERR    
##
###############################################################################
TestSelectSpecificationVerify(){
  local -r testSelectSpec="$1"
  if ! read < <( TestSelectSpecificationApply "$testSelectSpec" ); then
    ScriptError "Regex spec of: '$testSelectSpec' must select at least one test."
  fi
}
###############################################################################
##
##  Purpose:
##    Ensure specification selects at least one test.
##
##  Input:
##    $1 - A possible RegEx
##
##  Output:
##    SYSOUT - zero or more test function names matching RegEx filter.
##
###############################################################################
TestSelectSpecificationApply(){
  declare -F | awk '{ print $3 }' | grep "^${TEST_NAME_SPACE}$1\$"
}
##############################################################################
##
##  Purpose:
##    Execute Test Framework:
##      TestEnvironentDependenciesAssert:
##        Ensure proper component dependencies & global environment.
##      TestEnvironmentAssert:
##        For every selected test, ensure that any objects it creates
##        doesn't already exist.  Each test is responsible for creating
##        or obtaining the components necessary to execute the test.  
##      TestEnvironmentClean:
##        For every selected test, clean up any objects it produced.
##      TestExecuteAssert:
##        Execute the following interface when running a test:
##          $TEST_NAME_SPACE_NNN()
##            $TEST_NAME_SPACE:
##              A prefix encoded for every test function.
##            NNN:
##              The number assigned to a given test.
##            Purpose:
##              This particular function exposes the remaining
##              functions so they can be called.  It acts as a
##              name space
##            Inputs:
##          ${TEST_NAME_SPACE}_Desc()
##            Purpose:
##              Method outputs single line description to STDOUT
##          ${TEST_NAME_SPACE}_EnvCheck()
##            Purpose:
##              Method checks environment to determine if previous
##              test run left remnants or overlapping artifacts produced
##              by other processes.
##            Inputs:
##              $1 - variable name whose value is set according to the
##                   outputs below .
##            Outputs:
##              $1 - variable value set:
##                'false'- no remnants detected.
##                'true' - remnant detected.
##              STDERR - Error messages revealing found remnants or overlapping artifacts.
##          ${TEST_NAME_SPACE}_Run()
##            Purpose:
##              Execute the test.  Each test creates its required artifacts and 
##              runs its validation to assert that the output of the test matches what's
##              expected.  A failed assert immediately terminates the test leaving behind
##              any test artifacts.  These remnants hopefully permit debugging 
##              the test's failure.
##            Inputs:
##              None.
##            Outputs:
##              When successful - None.
##              Otherwise:
##                STDERR - Assert message explaining failure's cause.
##          ${TEST_NAME_SPACE}_EnvClean()
##            Purpose:
##              After executing the test, cleanup any artifacts produced by it.  By design
##              a test failure will ignore running this function so it's artifacts
##              can be reviewed to ascertain the failure's cause.  This routine should
##              eliminate as much of the failed artifacts as is reasonable so re-execution
##              of the test at a future point within the same contained environment won't
##              trigger asserts in EnvCheck() nor affect the test Run method.
##            Inputs:
##              None.
##            Outputs:
##              When successful - None.
##              Otherwise:
##                STDERR - Assert message explaining why EnvClean() failured.
## 
##  Assumption:
##    Since bash variable names are passed to this routine, these names
##    cannot overlap the variable names locally declared within the
##    scope of this routine or its descendants.
##
##  Input:
##    $1 - Variable name to an array whose values contain the label names
##         of the options and arguments appearing on the command line in the
##         order specified by it.
##    $2 - Variable name to an associative array whose key is either the
##         option or argument label and whose value represents the value
##         associated to that label.
## 
##  Output:
##    When success:
##      
##    When failure:
##      STDERR - Reflects error message generated by an Assert..
##
###############################################################################
VirtCmmdExecute(){
  local argOptList_ref="$1"
  local argOptMap_ref="$2"
  # assert testing dependencies are sufficient to support testing environment
  local -r ignoreDepend="`AssociativeMapAssignIndirect "$argOptMap_ref" '--no-depnd'`"
  if ! $ignoreDepend; then
    TestEnvironentDependenciesAssert
  fi

  local -a regexList
  local -A regexExpressMap
  if ! OptionsArgsFilter "$argOptList_ref" "$argOptMap_ref" 'regexList' 'regexExpressMap' '[[ "$optArg" =~ Arg[0-9][0-9]* ]]' 'true'; then
    ScriptUnwind $LINENO "Unexpectd return code."
  fi
  local regexArgList="`OptionsArgsGen 'regexList' 'regexExpressMap'`"
  regexArgList="${regexArgList:4}"
  local -r ignoreScan="`AssociativeMapAssignIndirect "$argOptMap_ref" '--no-scan'`"
  if ! $ignoreScan; then
    eval TestEnvironmentAssert $regexArgList
  fi
  local -r ignoreClean="`AssociativeMapAssignIndirect "$argOptMap_ref" '--no-clean'`"
  if ! $ignoreClean; then
    eval TestEnvironmentClean $regexArgList
  fi
  local remnantScan='true'
  if $ignoreScan; then remnantScan='false'; fi 
  eval TestExecuteAssert \"\$remnantScan\" $regexArgList
  ScriptInform "Testing Complete & Successful!"
}
##############################################################################
##
##  Purpose:
##    Scan current test environment for test artifacts that are either
##    remnants produced by prior test interation that failed or overlapping
##    artifacts, generated by so other process, that happen to have
##    identical names.
##
##    This scan is optionally performed before executing any tests to ensure
##    the environment is free of test artifacts that potentially affect 
##    a test's outcome.
##
##  Input:
##    $1-$N    - One to N regex instructions that specify the set of 
##               executed tests.  This set determines the scope/subset
##               of the environment scanned.
##    EnvCheck - Every test must define this method.
##
##  Output:
##    STDOUT - Displays scanning report.
##    When failure:
##      STDERR - Reflects error message.
##      STDOUT - Should identify failed test.
##
###############################################################################
TestEnvironmentAssert(){
  ScriptInform "Scanning: Start: Test Environment for remnants."
  local regexArgs
  args_single_quote_Encapsulate 'regexArgs' "$@"
  if ! ( PipeFailCheck 'TestSelect '"$regexArgs"' | TestFunctionExecTemplate AtEndNotify EnvCheck '  "$LINENO" "Failed environment scan."); then
    ScriptError 'One or more remnants were detected during the scan.'
    ScriptError 'Check to ensure remnants refer to test artifacts.'
    ScriptError 'If the remnants are unwanted test artifacts, rerun specifying'
    ScriptError '"'"--no-check"'" option to delete them before executing'
    ScriptError 'a specific test.'
    ScriptUnwind "$LINENO" "Scan detected artifacts in environment that overlap ones produced during testing."
  fi
  ScriptInform "Scanning: Complete: Test Environment for remnants."
}
ScriptDetectNotify(){
  ScriptError 'Detected existence of '"$1"
}
##############################################################################
##
##  Purpose:
##    Destroy artifacts generated by the selected set of tests.
##    
##    This scan is optionally executed before running the selected tests to
##    to avoid test failures produced by artifacts that exist before
##    they were created (science fiction?) by the current testing iteration.
##
##  Input:
##    $1-$N    - One to N regex instructions that specify the set of 
##               executed tests.  This set determines the scope/subset
##               of the environment scanned.<commit_msg>Align option name in message to reflect new option name<commit_after>#TODO: conurrently run tests.
#TODO: Determine if detection pipeline functions for scanning are still necessary
##############################################################################
##
##  Purpose:
##    Test component dependencies, like Docker CLI version, to ensure
##    they exist and are of proper verison.
##
##  Note:
##    Although this function should unwind itself when it detects
##    dependency problems, it should attempt to identify as many dependency
##    and environment setup problems as it can before executing the uwind.
## 
##  Inputs:
##    None.
##
##  Outputs:
##    When successful - none.
##    Otherwise - Write error messages to STDERR.
##
###############################################################################
TestEnvironentDependenciesAssert(){
  ScriptUnwind "$LINENO"  "Please override '$FUNCNAME'."
}
##############################################################################
##
##  Purpose:
##    see VirtCmmdInterface.sh -> VirtCmmdConfigSetDefault
##    However, this called after the framework adds its own default settigs.
##
###############################################################################
TestConfigSetDefault(){
  ScriptUnwind "$LINENO"  "Please override '$FUNCNAME'."
}
##############################################################################
##
##  Purpose:
##    Display "Usage:" information for the specific test.
##
###############################################################################
TestHelpCmmdUsageDisplay(){
  ScriptUnwind "$LINENO"  "Please override '$FUNCNAME'."
}
##############################################################################
##
##  Purpose:
##    see VirtCmmdInterface.sh -> VirtCmmdConfigSetDefault
##
###############################################################################
VirtCmmdConfigSetDefault(){
  TEST_SELECT_ALL='[0-9]*'
  TestConfigSetDefault
}
##############################################################################
##
##  Purpose:
##    see VirtCmmdInterface.sh -> VirtCmmdHelpDisplay
##
###############################################################################
VirtCmmdHelpDisplay() {
  echo
  TestHelpCmmdUsageDisplay
  cat <<COMMAND_HELP
TEST_NUM:  {'${TEST_SELECT}'| REGEX_SPEC [REGEX_SPEC...]}
    '${TEST_SELECT}'    Execute every test in numerical order.  Default value.
    REGEX_SPEC  A regular expression that selects the desired integer test label
                set. Must select at least one test to be considered valid. 
                Selected set executed in numerical order.
OPTIONS:
    --no-depnd=false     Execute dependency testing to ensure that dependent components
                           exist and are in correct state. 
    --no-scan=false      Execute tests without initially scanning the environment for 
                           every artifact created, used, and destroyed by every test.
                           Test artifact names may overlap with existing ones, not
                           produced by testing that share identical names/identities.
                           Detecting artifacts during a scan terminates testing 
                           before executing any tests or performing cleanup.
    --no-clean=false     Retain current testing environment and begin executing tests.
                           Otherwise, clean the environment before testing begins.
                           In any case, each test's cleanup routine will be executed
                           after its successful completion.
    --help               Provide command description.
    --ver                Display version and dependencies.
COMMAND_HELP
}
###############################################################################
##
##  Purpose:
##    see VirtCmmdInterface.sh -> VirtCmmdOptionsArgsDef
##
###############################################################################
VirtCmmdOptionsArgsDef(){
cat <<OPTIONARGS
Arg1 single '[0-9]*' "TestSelectSpecificationVerify \\<Arg1\\>" required ""
ArgN single ''       "TestSelectSpecificationVerify \\<ArgN\\>" optional ""
--no-depnd single false=EXIST=true "OptionsArgsBooleanVerify \\<--no-depnd\\>" required ""
--no-scan  single false=EXIST=true "OptionsArgsBooleanVerify \\<--no-scan\\>"  required ""
--no-clean single false=EXIST=true "OptionsArgsBooleanVerify \\<--no-clean\\>" required ""
OPTIONARGS
}
###############################################################################
##
##  Purpose:
##    Ensure test selection specification selects at least one test.
##
##  Input:
##    $1 - A potential RegEx expression.
##
##  Output:
##    When failure:
##      SYSERR    
##
###############################################################################
TestSelectSpecificationVerify(){
  local -r testSelectSpec="$1"
  if ! read < <( TestSelectSpecificationApply "$testSelectSpec" ); then
    ScriptError "Regex spec of: '$testSelectSpec' must select at least one test."
  fi
}
###############################################################################
##
##  Purpose:
##    Ensure specification selects at least one test.
##
##  Input:
##    $1 - A possible RegEx
##
##  Output:
##    SYSOUT - zero or more test function names matching RegEx filter.
##
###############################################################################
TestSelectSpecificationApply(){
  declare -F | awk '{ print $3 }' | grep "^${TEST_NAME_SPACE}$1\$"
}
##############################################################################
##
##  Purpose:
##    Execute Test Framework:
##      TestEnvironentDependenciesAssert:
##        Ensure proper component dependencies & global environment.
##      TestEnvironmentAssert:
##        For every selected test, ensure that any objects it creates
##        doesn't already exist.  Each test is responsible for creating
##        or obtaining the components necessary to execute the test.  
##      TestEnvironmentClean:
##        For every selected test, clean up any objects it produced.
##      TestExecuteAssert:
##        Execute the following interface when running a test:
##          $TEST_NAME_SPACE_NNN()
##            $TEST_NAME_SPACE:
##              A prefix encoded for every test function.
##            NNN:
##              The number assigned to a given test.
##            Purpose:
##              This particular function exposes the remaining
##              functions so they can be called.  It acts as a
##              name space
##            Inputs:
##          ${TEST_NAME_SPACE}_Desc()
##            Purpose:
##              Method outputs single line description to STDOUT
##          ${TEST_NAME_SPACE}_EnvCheck()
##            Purpose:
##              Method checks environment to determine if previous
##              test run left remnants or overlapping artifacts produced
##              by other processes.
##            Inputs:
##              $1 - variable name whose value is set according to the
##                   outputs below .
##            Outputs:
##              $1 - variable value set:
##                'false'- no remnants detected.
##                'true' - remnant detected.
##              STDERR - Error messages revealing found remnants or overlapping artifacts.
##          ${TEST_NAME_SPACE}_Run()
##            Purpose:
##              Execute the test.  Each test creates its required artifacts and 
##              runs its validation to assert that the output of the test matches what's
##              expected.  A failed assert immediately terminates the test leaving behind
##              any test artifacts.  These remnants hopefully permit debugging 
##              the test's failure.
##            Inputs:
##              None.
##            Outputs:
##              When successful - None.
##              Otherwise:
##                STDERR - Assert message explaining failure's cause.
##          ${TEST_NAME_SPACE}_EnvClean()
##            Purpose:
##              After executing the test, cleanup any artifacts produced by it.  By design
##              a test failure will ignore running this function so it's artifacts
##              can be reviewed to ascertain the failure's cause.  This routine should
##              eliminate as much of the failed artifacts as is reasonable so re-execution
##              of the test at a future point within the same contained environment won't
##              trigger asserts in EnvCheck() nor affect the test Run method.
##            Inputs:
##              None.
##            Outputs:
##              When successful - None.
##              Otherwise:
##                STDERR - Assert message explaining why EnvClean() failured.
## 
##  Assumption:
##    Since bash variable names are passed to this routine, these names
##    cannot overlap the variable names locally declared within the
##    scope of this routine or its descendants.
##
##  Input:
##    $1 - Variable name to an array whose values contain the label names
##         of the options and arguments appearing on the command line in the
##         order specified by it.
##    $2 - Variable name to an associative array whose key is either the
##         option or argument label and whose value represents the value
##         associated to that label.
## 
##  Output:
##    When success:
##      
##    When failure:
##      STDERR - Reflects error message generated by an Assert..
##
###############################################################################
VirtCmmdExecute(){
  local argOptList_ref="$1"
  local argOptMap_ref="$2"
  # assert testing dependencies are sufficient to support testing environment
  local -r ignoreDepend="`AssociativeMapAssignIndirect "$argOptMap_ref" '--no-depnd'`"
  if ! $ignoreDepend; then
    TestEnvironentDependenciesAssert
  fi

  local -a regexList
  local -A regexExpressMap
  if ! OptionsArgsFilter "$argOptList_ref" "$argOptMap_ref" 'regexList' 'regexExpressMap' '[[ "$optArg" =~ Arg[0-9][0-9]* ]]' 'true'; then
    ScriptUnwind $LINENO "Unexpectd return code."
  fi
  local regexArgList="`OptionsArgsGen 'regexList' 'regexExpressMap'`"
  regexArgList="${regexArgList:4}"
  local -r ignoreScan="`AssociativeMapAssignIndirect "$argOptMap_ref" '--no-scan'`"
  if ! $ignoreScan; then
    eval TestEnvironmentAssert $regexArgList
  fi
  local -r ignoreClean="`AssociativeMapAssignIndirect "$argOptMap_ref" '--no-clean'`"
  if ! $ignoreClean; then
    eval TestEnvironmentClean $regexArgList
  fi
  local remnantScan='true'
  if $ignoreScan; then remnantScan='false'; fi 
  eval TestExecuteAssert \"\$remnantScan\" $regexArgList
  ScriptInform "Testing Complete & Successful!"
}
##############################################################################
##
##  Purpose:
##    Scan current test environment for test artifacts that are either
##    remnants produced by prior test interation that failed or overlapping
##    artifacts, generated by so other process, that happen to have
##    identical names.
##
##    This scan is optionally performed before executing any tests to ensure
##    the environment is free of test artifacts that potentially affect 
##    a test's outcome.
##
##  Input:
##    $1-$N    - One to N regex instructions that specify the set of 
##               executed tests.  This set determines the scope/subset
##               of the environment scanned.
##    EnvCheck - Every test must define this method.
##
##  Output:
##    STDOUT - Displays scanning report.
##    When failure:
##      STDERR - Reflects error message.
##      STDOUT - Should identify failed test.
##
###############################################################################
TestEnvironmentAssert(){
  ScriptInform "Scanning: Start: Test Environment for remnants."
  local regexArgs
  args_single_quote_Encapsulate 'regexArgs' "$@"
  if ! ( PipeFailCheck 'TestSelect '"$regexArgs"' | TestFunctionExecTemplate AtEndNotify EnvCheck '  "$LINENO" "Failed environment scan."); then
    ScriptError 'One or more remnants were detected during the scan.'
    ScriptError 'Check to ensure remnants refer to test artifacts.'
    ScriptError 'If the remnants are unwanted test artifacts, rerun specifying'
    ScriptError '"'"--no-scan"'" option to delete them before executing'
    ScriptError 'a specific test.'
    ScriptUnwind "$LINENO" "Scan detected artifacts in environment that overlap ones produced during testing."
  fi
  ScriptInform "Scanning: Complete: Test Environment for remnants."
}
ScriptDetectNotify(){
  ScriptError 'Detected existence of '"$1"
}
##############################################################################
##
##  Purpose:
##    Destroy artifacts generated by the selected set of tests.
##    
##    This scan is optionally executed before running the selected tests to
##    to avoid test failures produced by artifacts that exist before
##    they were created (science fiction?) by the current testing iteration.
##
##  Input:
##    $1-$N    - One to N regex instructions that specify the set of 
##               executed tests.  This set determines the scope/subset
##               of the environment scanned.
{'fraction_non_alphanumeric': 0.2048298155542879, 'fraction_numerical': 0.0019015021867275148, 'mean_word_length': 3.212752322973406, 'pattern_counts': {'":': 0, '<': 25, '<?xml version=': 0, '>': 21, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6295205', 'n_tokens_mistral': 6377, 'n_tokens_neox': 6040, 'n_words': 2282}