GacUI/.github/Guidelines/Running-UnitTest.md

Running a Unit Test Project

• Only run copilotExecute.ps1 to run a unit test project.
• DO NOT call executables or scripts yourself.

Executing copilotExecute.ps1

PROJECT-NAME is the name of the project.

Before testing, ensure the debugger has stopped. If there is any error message, it means the debugger is not alive, it is good.

& REPO-ROOT\.github\Scripts\copilotDebug_Stop.ps1

And then run test cases in SOLUTION-ROOT\PROJECT-NAME\PROJECT-NAME.vcxproj:

cd SOLUTION-ROOT
& REPO-ROOT\.github\Scripts\copilotExecute.ps1 -Mode UnitTest -Executable PROJECT-NAME

-Mode and -Executable are required.

-Configuration and -Platform arguments are available to specify the target configuration:

• When both arguments are omitted, the last build configuration will be picked up.
• Both arguments should be omitted or not omitted at the same time.
• -Configuration could be Debug (default) or Release.
• -Platform could be x64 (default) or Win32
• Pick the default option (omit both arguments) when there is no specific requirements.

Ensure Expected Test Files are Selected

Test cases are organized in multiple test files. In PROJECT-NAME\PROJECT-NAME.vcxproj.user there is a filter, when it is effective, you will see filtered test files marked with [SKIPPED] in Execute.log. The filter is defined in this XPath: /Project/PropertyGroup@Condition="'$(Configuration)|$(Platform)'=='Debug|x64'"/LocalDebuggerCommandArguments. The filter is effective only when the file exists and the element exists with one or multiple /F:FILE-NAME.cpp, listing all test files to execute, unlisted files are skipped. If the element exists but there is no /F:FILE-NAME.cpp, it executes all test files, none is skipped.

IMPORTANT:

ONLY WHEN test files you want to run is skipped, you can edit PROJECT-NAME\PROJECT-NAME.vcxproj.user to activate your filter.

• This would typically happen when:
  • A new test file is added.
  • A test file is renamed.

You can clean up the filter to remove unrelated files that are either not existing or are totally unrelated to the current task you are working on. If the current task does not work on that test file, but it tests a closely related topic, you should better keep it in the list.

DO NOT delete this *.vcxproj.user file. DO NOT clean the filter (aka delete all /FILE-NAME.cpp) by yourself. I put a filter there because running everything is slow and unnecessary for the current task. Ignore LocalDebuggerCommandArgumentsHistory in *.vcxproj.user.

The Correct Way to Read Test Result

• The only source of trust is the raw output of the unit test process.
• Wait for the script to finish before reading the log file.
  • DO NOT need to read the output from the script.
  • Testing takes a long time. DO NOT hurry.
  • When the script finishes, the result is saved to REPO-ROOT/.github/Scripts/Execute.log.
  • A temporary file Execute.log.unfinished is created during testing. It will be automatically deleted as soon as the testing finishes. If you see this file, it means the testing is not finished yet.
• When all test cases pass, the last several lines of Execute.log should be in the following pattern; otherwise it crashed at the last shown test case:
  • "Passed test files: X/X"
  • "Passed test cases: Y/Y"
• DO NOT delete the log file by yourself unless explicitly required.