action.yml

name: Invoke-Pester (by PSModule)
description: Runs test, using Pester and PowerShell.
author: PSModule
branding:
  icon: check-square
  color: gray-dark

inputs:
  Path:
    description: |
      Path to where tests are located or a configuration file.
    required: false
  ReportAsJson:
    description: |
      Output generated reports in JSON format in addition to the configured format through Pester.
    required: false
    default: 'true'
  Prescript:
    description: |
      Script to be executed before the test run. This script is executed in the same context as the test run.
    required: false
  StepSummary_Mode:
    description: |
      Controls which tests to show in the GitHub step summary. Allows "Full" (show all tests), "Failed" (only failed tests), or "None" (disable step summary).
    required: false
    default: 'Failed'
  StepSummary_ShowTestOverview:
    description: |
      Controls whether to show the test overview table in the GitHub step summary.
    required: false
    default: 'false'
  StepSummary_ShowConfiguration:
    description: |
      Controls whether to show the configuration details in the GitHub step summary.
    required: false
    default: 'false'
  Run_Path:
    description: |
      Directories to be searched for tests, paths directly to test files, or combination of both.
    required: false
  Run_ExcludePath:
    description: |
      Directories or files to be excluded from the run.
    required: false
  Run_ScriptBlock:
    description: |
      ScriptBlocks containing tests to be executed.
    required: false
  Run_Container:
    description: |
      ContainerInfo objects containing tests to be executed.
    required: false
  Run_TestExtension:
    description: |
      Filter used to identify test files.
    required: false
  Run_Exit:
    description: |
      Exit with non-zero exit code when the test run fails. Exit code is always set to `$LASTEXITCODE` even when this option is `$false`.
      When used together with Throw, throwing an exception is preferred.
    required: false
  Run_Throw:
    description: |
      Throw an exception when test run fails. When used together with Exit, throwing an exception is preferred.
    required: false
  Run_SkipRun:
    description: |
      Runs the discovery phase but skips run. Use it with PassThru to get object populated with all tests.
    required: false
  Run_SkipRemainingOnFailure:
    description: |
      Skips remaining tests after failure for selected scope, options are None, Run, Container and Block.
    required: false
  Filter_Tag:
    description: |
      Tags of Describe, Context or It to be run.
    required: false
  Filter_ExcludeTag:
    description: |
      Tags of Describe, Context or It to be excluded from the run.
    required: false
  Filter_Line:
    description: |
      Filter by file and scriptblock start line, useful to run parsed tests programmatically to avoid problems with expanded names.
      Example: 'C:\tests\file1.Tests.ps1:37'
    required: false
  Filter_ExcludeLine:
    description: |
      Exclude by file and scriptblock start line, takes precedence over Line.
    required: false
  Filter_FullName:
    description: |
      Full name of test with -like wildcards, joined by dot. Example: '*.describe Get-Item.test1'
    required: false
  CodeCoverage_Enabled:
    description: |
      Enable CodeCoverage.
    required: false
  CodeCoverage_OutputFormat:
    description: |
      Format to use for code coverage report. Possible values: JaCoCo, CoverageGutters, Cobertura
    required: false
  CodeCoverage_OutputPath:
    description: |
      Path relative to the current directory where code coverage report is saved.
    required: false
  CodeCoverage_OutputEncoding:
    description: |
      Encoding of the output file.
    required: false
  CodeCoverage_Path:
    description: |
      Directories or files to be used for code coverage, by default the Path(s) from general settings are used, unless overridden here.
    required: false
  CodeCoverage_ExcludeTests:
    description: |
      Exclude tests from code coverage. This uses the TestFilter from general configuration.
    required: false
  CodeCoverage_RecursePaths:
    description: |
      Will recurse through directories in the Path option.
    required: false
  CodeCoverage_CoveragePercentTarget:
    description: |
      Target percent of code coverage that you want to achieve.
    required: false
  CodeCoverage_UseBreakpoints:
    description: |
      EXPERIMENTAL: When false, use Profiler based tracer to do CodeCoverage instead of using breakpoints.
    required: false
  CodeCoverage_SingleHitBreakpoints:
    description: |
      Remove breakpoint when it is hit.
    required: false
  TestResult_Enabled:
    description: |
      Enable TestResult.
    required: false
  TestResult_OutputFormat:
    description: |
      Format to use for test result report. Possible values: NUnitXml, NUnit2.5, NUnit3 or JUnitXml
    required: false
  TestResult_OutputPath:
    description: |
      Path relative to the current directory where test result report is saved.
    required: false
  TestResult_OutputEncoding:
    description: |
      Encoding of the output file.
    required: false
  TestResult_TestSuiteName:
    description: |
      Set the name assigned to the root 'test-suite' element.
    required: false
  Should_ErrorAction:
    description: |
      Controls if Should throws on error. Use 'Stop' to throw on error, or 'Continue' to fail at the end of the test.
    required: false
  Debug_ShowFullErrors:
    description: |
      Show full errors including Pester internal stack. This property is deprecated, and if set to true it will override Output.StackTraceVerbosity to 'Full'.
    required: false
  Debug_WriteDebugMessages:
    description: |
      Write Debug messages to screen.
    required: false
  Debug_WriteDebugMessagesFrom:
    description: |
      Write Debug messages from a given source, WriteDebugMessages must be set to true for this to work.
      You can use like wildcards to get messages from multiple sources, as well as * to get everything.
    required: false
  Debug_ShowNavigationMarkers:
    description: |
      Write paths after every block and test, for easy navigation in VSCode.
    required: false
  Debug_ReturnRawResultObject:
    description: |
      Returns unfiltered result object, this is for development only. Do not rely on this object for additional properties,
      non-public properties will be renamed without previous notice.
    required: false
  Output_Verbosity:
    description: |
      The verbosity of output, options are None, Normal, Detailed and Diagnostic.
    required: false
  Output_StackTraceVerbosity:
    description: |
      The verbosity of stacktrace output, options are None, FirstLine, Filtered and Full.
    required: false
  Output_CIFormat:
    description: |
      The CI format of error output in build logs, options are None, Auto, AzureDevops and GithubActions.
    required: false
  Output_CILogLevel:
    description: |
      The CI log level in build logs, options are Error and Warning.
    required: false
  Output_RenderMode:
    description: |
      The mode used to render console output, options are Auto, Ansi, ConsoleColor and Plaintext.
    required: false
  TestDrive_Enabled:
    description: |
      Enable TestDrive.
    required: false
  TestRegistry_Enabled:
    description: |
      Enable TestRegistry.
    required: false
  Debug:
    description: Enable debug output.
    required: false
    default: 'false'
  Verbose:
    description: Enable verbose output.
    required: false
    default: 'false'
  Version:
    description: Specifies the version of the GitHub module to be installed. The value must be an exact version.
    required: false
  Prerelease:
    description: Allow prerelease versions if available.
    required: false
    default: 'false'
  WorkingDirectory:
    description: The working directory where the script will run from.
    required: false
    default: '.'

outputs:
  Outcome:
    description: |
      The outcome of the test run.
    value: ${{ steps.test.outcome }}
  Conclusion:
    description: |
      The conclusion of the test run.
    value: ${{ steps.test.conclusion }}
  Executed:
    description: |
      Whether tests were executed.
    value: ${{ steps.status.outputs.Executed }}
  Result:
    description: |
      Overall result of the Pester test run (e.g., Passed, Failed).
    value: ${{ steps.test.outputs.Result }}
  FailedCount:
    description: |
      Number of failed tests.
    value: ${{ steps.test.outputs.FailedCount }}
  FailedBlocksCount:
    description: |
      Number of failed blocks.
    value: ${{ steps.test.outputs.FailedBlocksCount }}
  FailedContainersCount:
    description: |
      Number of failed containers.
    value: ${{ steps.test.outputs.FailedContainersCount }}
  PassedCount:
    description: |
      Number of passed tests.
    value: ${{ steps.test.outputs.PassedCount }}
  SkippedCount:
    description: |
      Number of skipped tests.
    value: ${{ steps.test.outputs.SkippedCount }}
  InconclusiveCount:
    description: |
      Number of inconclusive tests.
    value: ${{ steps.test.outputs.InconclusiveCount }}
  NotRunCount:
    description: |
      Number of tests not run.
    value: ${{ steps.test.outputs.NotRunCount }}
  TotalCount:
    description: |
      Total count of tests.
    value: ${{ steps.test.outputs.TotalCount }}

runs:
  using: composite
  steps:
    - name: Invoke-Pester (init)
      uses: PSModule/GitHub-Script@v1
      env:
        PSMODULE_INVOKE_PESTER_INPUT_Path: ${{ inputs.Path }}
        PSMODULE_INVOKE_PESTER_INPUT_Run_Path: ${{ inputs.Run_Path }}
        PSMODULE_INVOKE_PESTER_INPUT_Run_ExcludePath: ${{ inputs.Run_ExcludePath }}
        PSMODULE_INVOKE_PESTER_INPUT_Run_ScriptBlock: ${{ inputs.Run_ScriptBlock }}
        PSMODULE_INVOKE_PESTER_INPUT_Run_Container: ${{ inputs.Run_Container }}
        PSMODULE_INVOKE_PESTER_INPUT_Run_TestExtension: ${{ inputs.Run_TestExtension }}
        PSMODULE_INVOKE_PESTER_INPUT_Run_Exit: ${{ inputs.Run_Exit }}
        PSMODULE_INVOKE_PESTER_INPUT_Run_Throw: ${{ inputs.Run_Throw }}
        PSMODULE_INVOKE_PESTER_INPUT_Run_SkipRun: ${{ inputs.Run_SkipRun }}
        PSMODULE_INVOKE_PESTER_INPUT_Run_SkipRemainingOnFailure: ${{ inputs.Run_SkipRemainingOnFailure }}
        PSMODULE_INVOKE_PESTER_INPUT_Filter_Tag: ${{ inputs.Filter_Tag }}
        PSMODULE_INVOKE_PESTER_INPUT_Filter_ExcludeTag: ${{ inputs.Filter_ExcludeTag }}
        PSMODULE_INVOKE_PESTER_INPUT_Filter_Line: ${{ inputs.Filter_Line }}
        PSMODULE_INVOKE_PESTER_INPUT_Filter_ExcludeLine: ${{ inputs.Filter_ExcludeLine }}
        PSMODULE_INVOKE_PESTER_INPUT_Filter_FullName: ${{ inputs.Filter_FullName }}
        PSMODULE_INVOKE_PESTER_INPUT_CodeCoverage_Enabled: ${{ inputs.CodeCoverage_Enabled }}
        PSMODULE_INVOKE_PESTER_INPUT_CodeCoverage_OutputFormat: ${{ inputs.CodeCoverage_OutputFormat }}
        PSMODULE_INVOKE_PESTER_INPUT_CodeCoverage_OutputPath: ${{ inputs.CodeCoverage_OutputPath }}
        PSMODULE_INVOKE_PESTER_INPUT_CodeCoverage_OutputEncoding: ${{ inputs.CodeCoverage_OutputEncoding }}
        PSMODULE_INVOKE_PESTER_INPUT_CodeCoverage_Path: ${{ inputs.CodeCoverage_Path }}
        PSMODULE_INVOKE_PESTER_INPUT_CodeCoverage_ExcludeTests: ${{ inputs.CodeCoverage_ExcludeTests }}
        PSMODULE_INVOKE_PESTER_INPUT_CodeCoverage_RecursePaths: ${{ inputs.CodeCoverage_RecursePaths }}
        PSMODULE_INVOKE_PESTER_INPUT_CodeCoverage_CoveragePercentTarget: ${{ inputs.CodeCoverage_CoveragePercentTarget }}
        PSMODULE_INVOKE_PESTER_INPUT_CodeCoverage_UseBreakpoints: ${{ inputs.CodeCoverage_UseBreakpoints }}
        PSMODULE_INVOKE_PESTER_INPUT_CodeCoverage_SingleHitBreakpoints: ${{ inputs.CodeCoverage_SingleHitBreakpoints }}
        PSMODULE_INVOKE_PESTER_INPUT_TestResult_Enabled: ${{ inputs.TestResult_Enabled }}
        PSMODULE_INVOKE_PESTER_INPUT_TestResult_OutputFormat: ${{ inputs.TestResult_OutputFormat }}
        PSMODULE_INVOKE_PESTER_INPUT_TestResult_OutputPath: ${{ inputs.TestResult_OutputPath }}
        PSMODULE_INVOKE_PESTER_INPUT_TestResult_OutputEncoding: ${{ inputs.TestResult_OutputEncoding }}
        PSMODULE_INVOKE_PESTER_INPUT_TestResult_TestSuiteName: ${{ inputs.TestResult_TestSuiteName }}
        PSMODULE_INVOKE_PESTER_INPUT_Should_ErrorAction: ${{ inputs.Should_ErrorAction }}
        PSMODULE_INVOKE_PESTER_INPUT_Debug_ShowFullErrors: ${{ inputs.Debug_ShowFullErrors }}
        PSMODULE_INVOKE_PESTER_INPUT_Debug_WriteDebugMessages: ${{ inputs.Debug_WriteDebugMessages }}
        PSMODULE_INVOKE_PESTER_INPUT_Debug_WriteDebugMessagesFrom: ${{ inputs.Debug_WriteDebugMessagesFrom }}
        PSMODULE_INVOKE_PESTER_INPUT_Debug_ShowNavigationMarkers: ${{ inputs.Debug_ShowNavigationMarkers }}
        PSMODULE_INVOKE_PESTER_INPUT_Debug_ReturnRawResultObject: ${{ inputs.Debug_ReturnRawResultObject }}
        PSMODULE_INVOKE_PESTER_INPUT_Output_Verbosity: ${{ inputs.Output_Verbosity }}
        PSMODULE_INVOKE_PESTER_INPUT_Output_StackTraceVerbosity: ${{ inputs.Output_StackTraceVerbosity }}
        PSMODULE_INVOKE_PESTER_INPUT_Output_CIFormat: ${{ inputs.Output_CIFormat }}
        PSMODULE_INVOKE_PESTER_INPUT_Output_CILogLevel: ${{ inputs.Output_CILogLevel }}
        PSMODULE_INVOKE_PESTER_INPUT_Output_RenderMode: ${{ inputs.Output_RenderMode }}
        PSMODULE_INVOKE_PESTER_INPUT_TestDrive_Enabled: ${{ inputs.TestDrive_Enabled }}
        PSMODULE_INVOKE_PESTER_INPUT_TestRegistry_Enabled: ${{ inputs.TestRegistry_Enabled }}
      with:
        ShowInfo: false
        ShowOutput: true
        Debug: ${{ inputs.Debug }}
        Prerelease: ${{ inputs.Prerelease }}
        Verbose: ${{ inputs.Verbose }}
        Version: ${{ inputs.Version }}
        WorkingDirectory: ${{ inputs.WorkingDirectory }}
        Script: |
          # Invoke-Pester (init)
          ${{ github.action_path }}/scripts/init.ps1

    - name: Invoke-Pester (exec)
      shell: pwsh
      continue-on-error: true
      working-directory: ${{ inputs.WorkingDirectory }}
      env:
        PSMODULE_INVOKE_PESTER_INPUT_ReportAsJson: ${{ inputs.ReportAsJson }}
        PSMODULE_INVOKE_PESTER_INPUT_StepSummary_Mode: ${{ inputs.StepSummary_Mode }}
        PSMODULE_INVOKE_PESTER_INPUT_StepSummary_ShowTestOverview: ${{ inputs.StepSummary_ShowTestOverview }}
        PSMODULE_INVOKE_PESTER_INPUT_StepSummary_ShowConfiguration: ${{ inputs.StepSummary_ShowConfiguration }}
        PSMODULE_INVOKE_PESTER_INPUT_Debug: ${{ inputs.Debug }}
        PSMODULE_INVOKE_PESTER_INPUT_Verbose: ${{ inputs.Verbose }}
      id: test
      run: |
        # Invoke-Pester (exec)
        ${{ inputs.Prescript }}
        ${{ github.action_path }}/scripts/exec.ps1

    - name: Upload test results - [${{ steps.test.outputs.TestSuiteName }}-TestResults]
      uses: actions/upload-artifact@v4
      if: ${{ steps.test.outputs.TestResultEnabled == 'true' && (success() || failure()) }}
      with:
        name: ${{ steps.test.outputs.TestSuiteName }}-TestResults
        path: ${{ steps.test.outputs.TestResultOutputPath }}
        retention-days: 1
        if-no-files-found: error

    - name: Upload code coverage report - [${{ steps.test.outputs.TestSuiteName }}-CodeCoverage]
      uses: actions/upload-artifact@v4
      if: ${{ steps.test.outputs.CodeCoverageEnabled == 'true' && (success() || failure()) }}
      with:
        name: ${{ steps.test.outputs.TestSuiteName }}-CodeCoverage
        path: ${{ steps.test.outputs.CodeCoverageOutputPath }}
        retention-days: 1
        if-no-files-found: error

    - name: Status
      shell: pwsh
      id: status
      working-directory: ${{ inputs.WorkingDirectory }}
      env:
        PSMODULE_INVOKE_PESTER_INTERNAL_Outcome: ${{ steps.test.outcome }}
        PSMODULE_INVOKE_PESTER_INTERNAL_Conclusion: ${{ steps.test.conclusion }}
        PSMODULE_INVOKE_PESTER_INTERNAL_Executed: ${{ steps.test.outputs.Executed }}
        PSMODULE_INVOKE_PESTER_INTERNAL_Result: ${{ steps.test.outputs.Result }}
        PSMODULE_INVOKE_PESTER_INTERNAL_FailedCount: ${{ steps.test.outputs.FailedCount }}
        PSMODULE_INVOKE_PESTER_INTERNAL_FailedBlocksCount: ${{ steps.test.outputs.FailedBlocksCount }}
        PSMODULE_INVOKE_PESTER_INTERNAL_FailedContainersCount: ${{ steps.test.outputs.FailedContainersCount }}
        PSMODULE_INVOKE_PESTER_INTERNAL_PassedCount: ${{ steps.test.outputs.PassedCount }}
        PSMODULE_INVOKE_PESTER_INTERNAL_SkippedCount: ${{ steps.test.outputs.SkippedCount }}
        PSMODULE_INVOKE_PESTER_INTERNAL_InconclusiveCount: ${{ steps.test.outputs.InconclusiveCount }}
        PSMODULE_INVOKE_PESTER_INTERNAL_NotRunCount: ${{ steps.test.outputs.NotRunCount }}
        PSMODULE_INVOKE_PESTER_INTERNAL_TotalCount: ${{ steps.test.outputs.TotalCount }}
      run: |
        # Status
        ${{ github.action_path }}/scripts/status.ps1