psmodule/test-psmodule

Test PowerShell modules with Pester and PSScriptAnalyzer.

Test-PSModule

Test PowerShell modules with Pester and PSScriptAnalyzer.

This GitHub Action is a part of the PSModule framework. It is recommended to use the Process-PSModule workflow to automate the whole process of managing the PowerShell module.

Specifications and practices

Test-PSModule enables:

• Test-Driven Development using Pester and PSScriptAnalyzer

How it works

The action runs the following the Pester test framework:

• PSScriptAnalyzer tests
• PSModule framework tests
• If TestType is set to Module:
  • The module manifest is tested using Test-ModuleManifest.
  • The module is imported.
  • Custom module tests from the tests directory in the module repository are run.
  • CodeCoverage is calculated.
• If TestType is set to SourceCode:
  • The source code is tested with:
    • PSScriptAnalyzer for best practices, using custom settings.
    • PSModule.SourceCode for other PSModule standards.
• The action returns a passed output that is true if all tests pass, else false.
• The following reports are calculated and uploaded as artifacts:
  • Test suite results.
  • Code coverage results.

The action fails if any of the tests fail or it fails to run the tests. This is mitigated by the continue-on-error option in the workflow.

How to use it

To use the action, create a new file in the .github/workflows directory of the module repository and add the following content.

Workflow suggestion - before module is built

name: Test-PSModule

on: [push]

jobs:
  Test-PSModule:
    name: Test-PSModule
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4

      - name: Initialize environment
        uses: PSModule/Initialize-PSModule@main

      - name: Test-PSModule
        uses: PSModule/Test-PSModule@main
        with:
          Path: src
          TestType: SourceCode

Workflow suggestion - after module is built

name: Test-PSModule

on: [push]

jobs:
  Test-PSModule:
    name: Test-PSModule
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4

      - name: Initialize environment
        uses: PSModule/Initialize-PSModule@main

      - name: Test-PSModule
        uses: PSModule/Test-PSModule@main
        with:
          Path: outputs/modules
          TestType: Module

Usage

Inputs

Name	Description	Required	Default
Path	The path to the code to test.	true
TestType	The type of tests to run. Can be either Module or SourceCode.	true
Name	The name of the module to test. The name of the repository is used if not specified.	false
TestsPath	The path to the tests to run.	false	tests
StackTraceVerbosity	Verbosity level of the stack trace. Allowed values: None, FirstLine, Filtered, Full.	false	None
Verbosity	Verbosity level of the test output. Allowed values: None, Normal, Detailed, Diagnostic.	false	Detailed

Outputs

Name	Description	Possible values
passed	If the tests passed.	true, false

PSModule tests

The PSModule framework tests verifies the following coding practices that the framework enforces:

• Script filename and function/filter name should match.

Tools

• Pester | Docs | GitHub | PS Gallery
• PSScriptAnalyzer Docs | GitHub | PS Gallery
• PSResourceGet | Docs | GitHub | PS Gallery
• Test-ModuleManifest | Microsoft Learn
• PowerShellGet | Microsoft Learn

test-psmodule's Issues

[New Test] Add check for manifest file name

[New Test] Script file doesnt start with an empty line

🚀[Feature]: Test on MacOS, Linux and Windows

Description

Run tests on MacOS, Linux and Windows and make the tests result in what tags/labels it should end up with.

[New test]: Check that params have examples

Description

When writing params, ensure that every [PARAMETER()] description has a Example set.

params(
   # This is a description
   # Example: 'This is an example of a description'
   [Parameter()]
   $Description
)

[Feature] Add ability to override the PSScriptAnalyser settings file from local repo

[New Test] Compatability warning: Use of ternary

Description

Use of ternary operator limits use of module to 7.0 and newer.

Use of ternary should set required PowerShellVersion to be Core and atleast 7.0

Should assure we dont get the alias ? for Where-Object.

[New Test]: Use `[System.Environment]::ProcessorCount` instead of `$env:NUMBER_OF_PROCESSORS`

Description

Check for usage of $env:NUMBER_OF_PROCESSORS` if used, fail and suggest [System.Environment]::ProcessorCount, which is available in both core and desktop versions.

Add annotation at the end of a pester tests so the result are shown on workflow page

🚀[Feature]: Publish test results to workflow or PR

Description

https://github.com/marketplace/actions/pester-tests-report

🚀[Feature]: Merge results on module tests to get correct coverage stats

Description

After the module tests have run, the code coverage stats are not merged to check overall coverage. Check if there is a way to merge these to indicate total coverage after running in different environments (macOS, ubuntu and windows + powershell vs pwsh).

[New test] Avoid setting param and function attributes to $true, when defining them is enough

[CmdletBinding()]
param (
    # The string to convert to a hashtable.
    [Parameter(Mandatory = $true)]
    [string]$InputString
)

Should be:

[CmdletBinding()]
param (
    # The string to convert to a hashtable.
    [Parameter(Mandatory)]
    [string]$InputString
)

[New test] Check that aliases are added using `[Alias(string[])]`

Check that aliases are defined using [Alias(string[])] instead of Set-Alias and New-Alias.

[New Test] Manifest content: has a valid help URL

🪲[Bug]: Pester + PSScriptAnalyzer failing sometimes

Describe the bug

Version information

N/A

To reproduce

N/A

Code snippet

N/A

Relevant output

N/A

[New Test] Manifest content: Has a valid license URL

[New test] All the required module are specified in the script header

All scripts should be using a #Required if it is relying on external PS modules.

For each file

• Collect the #Requires modules
• Search the file for all the commands
• list the modules they belong to
• see if they are apart of the Get-PSResource module list
• for each of the modules found, verify they are defines in the #Required list
• If it is missing, then fail the test.

[New Test] PowerShell keywords use lower case

[New Test] Should not hardcode `-Verbose` switches on commands

The whole point about [CmdLetBinding()] is to be able to control that from the "outside".

You should however be able to explicitly hide verbose by adding -Verbose:$false

[New Test] Manifest content: has a valid project URL

🚀[Feature]: New Test: Parameters must have a data type

Description

Parameters must have a data type

[New Test]: Use [System.Environment]::OS instead of `$IsWindows`

Description

Warn if $IsWindows, $IsLinux and $IsMacOS are used in the module.

If its used, the module is compatability on Core and PSVersion limited to 7.2 or grater.

🚀[Feature]: Add comment on PR after test is run.

Description

The comment on PR could say something like

• OS tested
• PS Edition
• Code Coverage
• Errors if any
• Number of tests succeeded, failed.

🚀[Feature]: Let a local config control what tests should be run

Description

Manifest should overside module settings, so we should no use this file i think. Might need another file?

Add '::warning::*

[New Test]: Use `$null = ...` instead of `... | Out-Null`

Description

Use $null = ... instead of ... | Out-Null

🚀[Feature]: Test on different versions of PowerShell

Description

Run test on different versions of PowerShell and make tags/labels show what works.

Desktop if working on Windows PowerShell 5.1
Core if it runs on greater that 5.x
PowerShell version should show least required version.

[New Test]: Every function/filter should have a test

Description

Get all tests from the test folder, and all the functions/filters from the module and see if there is one not covered by the test. Could use code coverage?

[New Test] Manifest content: has a valid icon URL

[New Test]: Dont use TypeAccelerator, use full name instead.

Description

ordered -> System.Collections.Specialized.OrderedDictionary

[Feature] On failures, post a number in the PR + link to the failing run

[New Test] Add [CmdletBinding()] and param() in every script file