├── .gitignore ├── LICENSE ├── README.md ├── SampleModule.build.ps1 ├── SampleModule.depend.psd1 ├── SampleModule ├── Public │ ├── Get-RandomGuid.Tests.ps1 │ └── Get-RandomGuid.ps1 ├── SampleModule.PSSATests.ps1 ├── SampleModule.Tests.ps1 ├── SampleModule.nuspec ├── SampleModule.psd1 └── SampleModule.psm1 └── azure-pipelines.yml /.gitignore: -------------------------------------------------------------------------------- 1 | # Build output 2 | build/ 3 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2020 Andrew Matveychuk 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # powershell.sample-module 2 | 3 | A sample CI/CD pipeline for a PowerShell module. 4 | 5 | Before starting to work with this sample project, I suggest reading the information in the following blog posts: 6 | 7 | * [A sample CI/CD pipeline for PowerShell module](https://andrewmatveychuk.com/a-sample-ci-cd-pipeline-for-powershell-module/) 8 | 9 | ## Build Status 10 | 11 | [![Build Status](https://dev.azure.com/matveychuk/powershell.sample-module/_apis/build/status/andrewmatveychuk.powershell.sample-module?branchName=master)](https://dev.azure.com/matveychuk/powershell.sample-module/_build/latest?definitionId=4&branchName=master) 12 | 13 | [![SampleModule package in AMGallery feed in Azure Artifacts](https://feeds.dev.azure.com/matveychuk/cb70e260-566b-4d91-9f8f-81840641e8f3/_apis/public/Packaging/Feeds/86bae25a-d541-4a81-957a-21549283fca5/Packages/683d9381-327e-4f38-9539-2c2746f52cb3/Badge)](https://dev.azure.com/matveychuk/powershell.sample-module/_packaging?_a=package&feed=86bae25a-d541-4a81-957a-21549283fca5&package=683d9381-327e-4f38-9539-2c2746f52cb3&preferRelease=true) 14 | 15 | ## Introduction 16 | 17 | This repository contains the source code for a sample PowerShell module along with Azure DevOps pipeline configuration to perform all build, test and publish tasks. 18 | 19 | ## Getting Started 20 | 21 | Clone the repository to your local machine and look for project artifacts in the following locations: 22 | 23 | * [SampleModule](https://github.com/andrewmatveychuk/powershell.sample-module/tree/master/SampleModule) - source code for the module itself along with tests 24 | * [SampleModule.build.ps1](https://github.com/andrewmatveychuk/powershell.sample-module/blob/master/SampleModule.build.ps1) - build script for the module 25 | * [SampleModule.depend.psd1](https://github.com/andrewmatveychuk/powershell.sample-module/blob/master/SampleModule.depend.psd1) - managing module dependencies with PSDepend 26 | * build - this folder will be created during the build process and will contain the build artifacts 27 | 28 | ## Build and Test 29 | 30 | This project uses [InvokeBuild](https://github.com/nightroman/Invoke-Build) module to automate build tasks such as running test, performing static code analysis, building the module, etc. 31 | 32 | * To build the module, run: Invoke-Build 33 | * To see other build options: Invoke-Build ? 34 | 35 | ## Suggested tools 36 | 37 | * Editing - [Visual Studio Code](https://github.com/Microsoft/vscode) 38 | * Runtime - [PowerShell Core](https://github.com/powershell) 39 | * Build tool - [InvokeBuild](https://github.com/nightroman/Invoke-Build) 40 | * Dependency management - [PSDepend](https://github.com/RamblingCookieMonster/PSDepend) 41 | * Testing - [Pester](https://github.com/Pester/Pester) 42 | * Code coverage - [Pester](https://pester.dev/docs/usage/code-coverage) 43 | * Static code analysis - [PSScriptAnalyzer](https://github.com/PowerShell/PSScriptAnalyzer) 44 | -------------------------------------------------------------------------------- /SampleModule.build.ps1: -------------------------------------------------------------------------------- 1 | #requires -modules InvokeBuild 2 | 3 | <# 4 | .SYNOPSIS 5 | Build script (https://github.com/nightroman/Invoke-Build) 6 | 7 | .DESCRIPTION 8 | This script contains the tasks for building the 'SampleModule' PowerShell module 9 | #> 10 | 11 | Param ( 12 | [Parameter(ValueFromPipelineByPropertyName = $true)] 13 | [ValidateSet('Debug', 'Release')] 14 | [String] 15 | $Configuration = 'Debug', 16 | [Parameter(ValueFromPipelineByPropertyName = $true)] 17 | [ValidateNotNullOrEmpty()] 18 | [String] 19 | $SourceLocation 20 | ) 21 | 22 | Set-StrictMode -Version Latest 23 | 24 | # Synopsis: Default task 25 | task . Clean, Build 26 | 27 | 28 | # Install build dependencies 29 | Enter-Build { 30 | 31 | # Installing PSDepend for dependency management 32 | if (-not (Get-Module -Name PSDepend -ListAvailable)) { 33 | Install-Module PSDepend -Force 34 | } 35 | Import-Module PSDepend 36 | 37 | # Installing dependencies 38 | Invoke-PSDepend -Force 39 | 40 | # Setting build script variables 41 | $script:moduleName = 'SampleModule' 42 | $script:moduleSourcePath = Join-Path -Path $BuildRoot -ChildPath $moduleName 43 | $script:moduleManifestPath = Join-Path -Path $moduleSourcePath -ChildPath "$moduleName.psd1" 44 | $script:nuspecPath = Join-Path -Path $moduleSourcePath -ChildPath "$moduleName.nuspec" 45 | $script:buildOutputPath = Join-Path -Path $BuildRoot -ChildPath 'build' 46 | 47 | # Setting base module version and using it if building locally 48 | $script:newModuleVersion = New-Object -TypeName 'System.Version' -ArgumentList (0, 0, 1) 49 | 50 | # Setting the list of functions ot be exported by module 51 | $script:functionsToExport = (Test-ModuleManifest $moduleManifestPath).ExportedFunctions 52 | } 53 | 54 | # Synopsis: Analyze the project with PSScriptAnalyzer 55 | task Analyze { 56 | # Get-ChildItem parameters 57 | $TestFiles = Get-ChildItem -Path $moduleSourcePath -Recurse -Include "*.PSSATests.*" 58 | 59 | $Config = New-PesterConfiguration @{ 60 | Run = @{ 61 | Path = $TestFiles 62 | Exit = $true 63 | } 64 | TestResult = @{ 65 | Enabled = $true 66 | } 67 | } 68 | 69 | # Additional parameters on Azure Pipelines agents to generate test results 70 | if ($env:TF_BUILD) { 71 | if (-not (Test-Path -Path $buildOutputPath -ErrorAction SilentlyContinue)) { 72 | New-Item -Path $buildOutputPath -ItemType Directory 73 | } 74 | $Timestamp = Get-date -UFormat "%Y%m%d-%H%M%S" 75 | $PSVersion = $PSVersionTable.PSVersion.Major 76 | $TestResultFile = "AnalysisResults_PS$PSVersion`_$TimeStamp.xml" 77 | $Config.TestResult.OutputPath = "$buildOutputPath\$TestResultFile" 78 | } 79 | 80 | # Invoke all tests 81 | Invoke-Pester -Configuration $Config 82 | } 83 | 84 | # Synopsis: Test the project with Pester tests 85 | task Test { 86 | $TestFiles = Get-ChildItem -Path $moduleSourcePath -Recurse -Include "*.Tests.*" 87 | 88 | $Config = New-PesterConfiguration @{ 89 | Run = @{ 90 | Path = $TestFiles 91 | Exit = $true 92 | } 93 | TestResult = @{ 94 | Enabled = $true 95 | } 96 | } 97 | 98 | # Additional parameters on Azure Pipelines agents to generate test results 99 | if ($env:TF_BUILD) { 100 | if (-not (Test-Path -Path $buildOutputPath -ErrorAction SilentlyContinue)) { 101 | New-Item -Path $buildOutputPath -ItemType Directory 102 | } 103 | 104 | $Timestamp = Get-date -UFormat "%Y%m%d-%H%M%S" 105 | $PSVersion = $PSVersionTable.PSVersion.Major 106 | $TestResultFile = "TestResults_PS$PSVersion`_$TimeStamp.xml" 107 | $Config.TestResult.OutputPath = "$buildOutputPath\$TestResultFile" 108 | } 109 | 110 | # Invoke all tests 111 | Invoke-Pester -Configuration $Config 112 | } 113 | 114 | # Synopsis: Generate a new module version if creating a release build 115 | task GenerateNewModuleVersion -If ($Configuration -eq 'Release') { 116 | # Using the current NuGet package version from the feed as a version base when building via Azure DevOps pipeline 117 | 118 | # Define package repository name 119 | $repositoryName = $moduleName + '-repository' 120 | 121 | # Register a target PSRepository 122 | try { 123 | Register-PSRepository -Name $repositoryName -SourceLocation $SourceLocation -InstallationPolicy Trusted 124 | } 125 | catch { 126 | throw "Cannot register '$repositoryName' repository with source location '$SourceLocation'!" 127 | } 128 | 129 | # Define variable for existing package 130 | $existingPackage = $null 131 | 132 | try { 133 | # Look for the module package in the repository 134 | $existingPackage = Find-Module -Name $moduleName -Repository $repositoryName 135 | } 136 | # In no existing module package was found, the base module version defined in the script will be used 137 | catch { 138 | Write-Warning "No existing package for '$moduleName' module was found in '$repositoryName' repository!" 139 | } 140 | 141 | # If existing module package was found, try to install the module 142 | if ($existingPackage) { 143 | # Get the largest module version 144 | # $currentModuleVersion = (Get-Module -Name $moduleName -ListAvailable | Measure-Object -Property 'Version' -Maximum).Maximum 145 | $currentModuleVersion = New-Object -TypeName 'System.Version' -ArgumentList ($existingPackage.Version) 146 | 147 | # Set module version base numbers 148 | [int]$Major = $currentModuleVersion.Major 149 | [int]$Minor = $currentModuleVersion.Minor 150 | [int]$Build = $currentModuleVersion.Build 151 | 152 | try { 153 | # Install the existing module from the repository 154 | Install-Module -Name $moduleName -Repository $repositoryName -RequiredVersion $existingPackage.Version 155 | } 156 | catch { 157 | throw "Cannot import module '$moduleName'!" 158 | } 159 | 160 | # Get the count of exported module functions 161 | $existingFunctionsCount = (Get-Command -Module $moduleName | Where-Object -Property Version -EQ $existingPackage.Version | Measure-Object).Count 162 | # Check if new public functions were added in the current build 163 | [int]$sourceFunctionsCount = (Get-ChildItem -Path "$moduleSourcePath\Public\*.ps1" -Exclude "*.Tests.*" | Measure-Object).Count 164 | [int]$newFunctionsCount = [System.Math]::Abs($sourceFunctionsCount - $existingFunctionsCount) 165 | 166 | # Increase the minor number if any new public functions have been added 167 | if ($newFunctionsCount -gt 0) { 168 | [int]$Minor = $Minor + 1 169 | [int]$Build = 0 170 | } 171 | # If not, just increase the build number 172 | else { 173 | [int]$Build = $Build + 1 174 | } 175 | 176 | # Update the module version object 177 | $Script:newModuleVersion = New-Object -TypeName 'System.Version' -ArgumentList ($Major, $Minor, $Build) 178 | } 179 | } 180 | 181 | # Synopsis: Generate list of functions to be exported by module 182 | task GenerateListOfFunctionsToExport { 183 | # Set exported functions by finding functions exported by *.psm1 file via Export-ModuleMember 184 | $params = @{ 185 | Force = $true 186 | Passthru = $true 187 | Name = (Resolve-Path (Get-ChildItem -Path $moduleSourcePath -Filter '*.psm1')).Path 188 | } 189 | $PowerShell = [Powershell]::Create() 190 | [void]$PowerShell.AddScript( 191 | { 192 | Param ($Force, $Passthru, $Name) 193 | $module = Import-Module -Name $Name -PassThru:$Passthru -Force:$Force 194 | $module | Where-Object { $_.Path -notin $module.Scripts } 195 | } 196 | ).AddParameters($Params) 197 | $module = $PowerShell.Invoke() 198 | $Script:functionsToExport = $module.ExportedFunctions.Keys 199 | } 200 | 201 | # Synopsis: Update the module manifest with module version and functions to export 202 | task UpdateModuleManifest GenerateNewModuleVersion, GenerateListOfFunctionsToExport, { 203 | # Update-ModuleManifest parameters 204 | $Params = @{ 205 | Path = $moduleManifestPath 206 | ModuleVersion = $newModuleVersion 207 | FunctionsToExport = $functionsToExport 208 | } 209 | 210 | # Update the manifest file 211 | Update-ModuleManifest @Params 212 | } 213 | 214 | # Synopsis: Update the NuGet package specification with module version 215 | task UpdatePackageSpecification GenerateNewModuleVersion, { 216 | # Load the specification into XML object 217 | $xml = New-Object -TypeName 'XML' 218 | $xml.Load($nuspecPath) 219 | 220 | # Update package version 221 | $metadata = Select-XML -Xml $xml -XPath '//package/metadata' 222 | $metadata.Node.Version = $newModuleVersion 223 | 224 | # Save XML object back to the specification file 225 | $xml.Save($nuspecPath) 226 | } 227 | 228 | # Synopsis: Build the project 229 | task Build UpdateModuleManifest, UpdatePackageSpecification, { 230 | # Warning on local builds 231 | if ($Configuration -eq 'Debug') { 232 | Write-Warning "Creating a debug build. Use it for test purpose only!" 233 | } 234 | 235 | # Create versioned output folder 236 | $moduleOutputPath = Join-Path -Path $buildOutputPath -ChildPath $moduleName -AdditionalChildPath $newModuleVersion 237 | if (-not (Test-Path $moduleOutputPath)) { 238 | New-Item -Path $moduleOutputPath -ItemType Directory 239 | } 240 | 241 | # Copy-Item parameters 242 | $Params = @{ 243 | Path = "$moduleSourcePath\*" 244 | Destination = $moduleOutputPath 245 | Exclude = "*.Tests.*", "*.PSSATests.*" 246 | Recurse = $true 247 | Force = $true 248 | } 249 | 250 | # Copy module files to the target build folder 251 | Copy-Item @Params 252 | } 253 | 254 | # Synopsis: Verify the code coverage by tests 255 | task CodeCoverage { 256 | $files = Get-ChildItem $moduleSourcePath -Dir -Force -Recurse | 257 | Where-Object {$_.FullName -notLike '*build*' -and $_.FullName -notLike '*.git*'} | 258 | Get-ChildItem -File -Force -Include '*.ps1' -Exclude '*.Tests.ps1' | 259 | Select-Object -ExpandProperty FullName 260 | 261 | $Config = New-PesterConfiguration @{ 262 | Run = @{ 263 | Path = $moduleSourcePath 264 | PassThru = $true 265 | } 266 | Output = @{ 267 | Verbosity = 'Normal' 268 | } 269 | CodeCoverage = @{ 270 | Enabled = $true 271 | Path = $files 272 | CoveragePercentTarget = 60 273 | } 274 | } 275 | 276 | # Additional parameters on Azure Pipelines agents to generate code coverage report 277 | if ($env:TF_BUILD) { 278 | if (-not (Test-Path -Path $buildOutputPath -ErrorAction SilentlyContinue)) { 279 | New-Item -Path $buildOutputPath -ItemType Directory 280 | } 281 | $Timestamp = Get-date -UFormat "%Y%m%d-%H%M%S" 282 | $PSVersion = $PSVersionTable.PSVersion.Major 283 | $TestResultFile = "CodeCoverageResults_PS$PSVersion`_$TimeStamp.xml" 284 | $Config.CodeCoverage.OutputPath = "$buildOutputPath\$TestResultFile" 285 | } 286 | 287 | $result = Invoke-Pester -Configuration $config 288 | 289 | # Fail the task if the code coverage results are not acceptable 290 | if ( $result.CodeCoverage.CoveragePercent -lt $result.CodeCoverage.CoveragePercentTarget) { 291 | throw "The overall code coverage by Pester tests is $("0:0.##" -f $result.CodeCoverage.CoveragePercent)% which is less than quality gate of $($result.CodeCoverage.CoveragePercentTarget)%. Pester ModuleVersion is: $((Get-Module -Name Pester -ListAvailable).ModuleVersion)." 292 | } 293 | } 294 | 295 | # Synopsis: Clean up the target build directory 296 | task Clean { 297 | if (Test-Path $buildOutputPath) { 298 | Remove-Item -Path $buildOutputPath -Recurse 299 | } 300 | } 301 | -------------------------------------------------------------------------------- /SampleModule.depend.psd1: -------------------------------------------------------------------------------- 1 | @{ 2 | # Build dependencies 3 | Pester = @{ target = 'CurrentUser'; version = 'latest' } 4 | PSScriptAnalyzer = @{ target = 'CurrentUser'; version = 'latest' } 5 | PlatyPS = @{ target = 'CurrentUser'; version = 'latest' } 6 | } -------------------------------------------------------------------------------- /SampleModule/Public/Get-RandomGuid.Tests.ps1: -------------------------------------------------------------------------------- 1 | BeforeAll { 2 | $here = Split-Path -Parent $PSCommandPath 3 | $sut = (Split-Path -Leaf $PSCommandPath) -replace '\.Tests\.', '.' 4 | . "$here\$sut" 5 | } 6 | 7 | Describe "'Get-RandomGuid' Function Functional Tests" { 8 | 9 | Context "Accepting input data" { 10 | BeforeAll { 11 | #region Arrange 12 | $inputData = 10 13 | #endregion 14 | } 15 | 16 | #region Act&Assert 17 | It "should accept input from the parameter" { 18 | $guids = Get-RandomGuid -Number $inputData 19 | $guids | Should -HaveCount $inputData 20 | } 21 | 22 | It "should accept input from the pipeline" { 23 | $guids = $inputData | Get-RandomGuid 24 | $guids | Should -HaveCount $inputData 25 | } 26 | #endregion 27 | } 28 | } -------------------------------------------------------------------------------- /SampleModule/Public/Get-RandomGuid.ps1: -------------------------------------------------------------------------------- 1 | function Get-RandomGuid { 2 | <# 3 | .SYNOPSIS 4 | Generates a list of random GUIDs 5 | .DESCRIPTION 6 | The Get-RandomGuid cmdlet generates a list of random GUIDs based on the input number 7 | .PARAMETER Number 8 | Number of GUIDs to generate. 9 | .EXAMPLE 10 | Get-RandomGuid -Number 10 11 | Accept input data from the parameter 12 | .EXAMPLE 13 | 10 | Get-RandomGuid 14 | Accept input data from the pipeline 15 | .INPUTS 16 | System.Int 17 | .OUTPUTS 18 | System.Guid 19 | #> 20 | 21 | [CmdletBinding( 22 | DefaultParameterSetName = 'Parameter Set 1', 23 | PositionalBinding = $true)] 24 | [OutputType([System.Guid])] 25 | Param ( 26 | [Parameter( 27 | Mandatory = $true, 28 | Position = 0, 29 | ValueFromPipeline = $true, 30 | ValueFromPipelineByPropertyName = $true, 31 | ParameterSetName = 'Parameter Set 1')] 32 | [ValidateNotNull()] 33 | [ValidateNotNullOrEmpty()] 34 | [Int] 35 | $Number 36 | ) 37 | 38 | begin { 39 | Write-Verbose "Starting GUID generation..." 40 | } 41 | 42 | process { 43 | 1..$Number | ForEach-Object { New-Guid } 44 | } 45 | 46 | end { 47 | Write-Verbose "GUID generation finished." 48 | } 49 | } -------------------------------------------------------------------------------- /SampleModule/SampleModule.PSSATests.ps1: -------------------------------------------------------------------------------- 1 | BeforeDiscovery { 2 | # For use during discovery to generate tests and correctly name the Describe block 3 | $modulePath = Split-Path -Parent $PSCommandPath 4 | $moduleName = Split-Path -Path $modulePath -Leaf 5 | } 6 | 7 | BeforeAll { 8 | # For use within the tests, during the Run phase 9 | $modulePath = Split-Path -Parent $PSCommandPath 10 | $moduleName = Split-Path -Path $modulePath -Leaf 11 | } 12 | 13 | Describe "'$moduleName' Module Analysis with PSScriptAnalyzer" { 14 | Context 'Standard Rules' { 15 | # Define PSScriptAnalyzer rules 16 | $scriptAnalyzerRules = Get-ScriptAnalyzerRule # Just getting all default rules 17 | 18 | # Perform analysis against each rule 19 | $scriptAnalyzerRules | ForEach-Object { 20 | It "should pass '' rule" -TestCases @{ Rule = $_ } { 21 | Invoke-ScriptAnalyzer -Path "$modulePath\$moduleName.psm1" -IncludeRule $Rule | Should -BeNullOrEmpty 22 | } 23 | } 24 | } 25 | } 26 | 27 | # Dynamically defining the functions to analyze 28 | $functionPaths = @() 29 | if (Test-Path -Path "$modulePath\Private\*.ps1") { 30 | $functionPaths += Get-ChildItem -Path "$modulePath\Private\*.ps1" -Exclude "*.Tests.*" 31 | } 32 | if (Test-Path -Path "$modulePath\Public\*.ps1") { 33 | $functionPaths += Get-ChildItem -Path "$modulePath\Public\*.ps1" -Exclude "*.Tests.*" 34 | } 35 | 36 | Describe "'<_>' Function Analysis with PSScriptAnalyzer" -ForEach $functionPaths { 37 | BeforeAll { 38 | $functionName = $_.BaseName 39 | $functionPath = $_ 40 | } 41 | 42 | Context 'Standard Rules' { 43 | # Define PSScriptAnalyzer rules 44 | $scriptAnalyzerRules = Get-ScriptAnalyzerRule # Just getting all default rules 45 | 46 | # Perform analysis against each rule 47 | $scriptAnalyzerRules | ForEach-Object { 48 | It "should pass '' rule" -TestCases @{ Rule = $_ } { 49 | Invoke-ScriptAnalyzer -Path $functionPath -IncludeRule $Rule | Should -BeNullOrEmpty 50 | } 51 | } 52 | } 53 | } -------------------------------------------------------------------------------- /SampleModule/SampleModule.Tests.ps1: -------------------------------------------------------------------------------- 1 | BeforeAll { 2 | # For use within the tests, during the Run phase 3 | $here = Split-Path -Parent $PSCommandPath 4 | 5 | #region Reloading SUT 6 | # Ensuring that we are testing this version of module and not any other version that could be in memory 7 | $modulePath = "$($PSCommandPath -replace '.Tests.ps1$', '').psm1" 8 | $moduleName = (($modulePath | Split-Path -Leaf) -replace '.psm1') 9 | @(Get-Module -Name $moduleName).where({ $_.version -ne '0.0' }) | Remove-Module # Removing all module versions from the current context if there are any 10 | Import-Module -Name $modulePath -Force -ErrorAction Stop # Loading module explicitly by path and not via the manifest 11 | #endregion 12 | } 13 | 14 | Describe "'$moduleName' Module Tests" { 15 | 16 | Context 'Module Setup' { 17 | It "should have a root module" { 18 | Test-Path $modulePath | Should -Be $true 19 | } 20 | 21 | It "should have an associated manifest" { 22 | Test-Path "$here\$moduleName.psd1" | Should -Be $true 23 | } 24 | 25 | It "should have public functions" { 26 | Test-Path "$here\public\*.ps1" | Should -Be $true 27 | } 28 | 29 | It "should be a valid PowerShell code" { 30 | $psFile = Get-Content -Path $modulePath -ErrorAction Stop 31 | $errors = $null 32 | $null = [System.Management.Automation.PSParser]::Tokenize($psFile, [ref]$errors) 33 | $errors.Count | Should -Be 0 34 | } 35 | } 36 | 37 | Context "Module Control" { 38 | It "should import without errors" { 39 | { Import-Module -Name $modulePath -Force -ErrorAction Stop } | Should -Not -Throw 40 | Get-Module -Name $moduleName | Should -Not -BeNullOrEmpty 41 | } 42 | 43 | It 'should remove without errors' { 44 | { Remove-Module -Name $moduleName -ErrorAction Stop } | Should -Not -Throw 45 | Get-Module -Name $moduleName | Should -BeNullOrEmpty 46 | } 47 | } 48 | } 49 | 50 | # Duplicated from the BeforeAll above. 51 | # Implicitly runs during Discovery, required to populate 52 | # $functionPaths for Pester to properly generate the tests 53 | $here = Split-Path -Parent $PSCommandPath 54 | 55 | # Dynamically defining the functions to test 56 | $functionPaths = @() 57 | if (Test-Path -Path "$here\Private\*.ps1") { 58 | $functionPaths += Get-ChildItem -Path "$here\Private\*.ps1" -Exclude "*.Tests.*" 59 | } 60 | if (Test-Path -Path "$here\Public\*.ps1") { 61 | $functionPaths += Get-ChildItem -Path "$here\Public\*.ps1" -Exclude "*.Tests.*" 62 | } 63 | 64 | Describe "'<_>' Function Tests" -ForEach $functionPaths { 65 | BeforeDiscovery { 66 | # Required in order to populate $parameters during discovery to find all parameters 67 | # Getting function 68 | $AbstractSyntaxTree = [System.Management.Automation.Language.Parser]::ParseInput((Get-Content -raw $_), [ref]$null, [ref]$null) 69 | $AstSearchDelegate = { $args[0] -is [System.Management.Automation.Language.FunctionDefinitionAst] } 70 | $ParsedFunction = $AbstractSyntaxTree.FindAll( $AstSearchDelegate, $true ) | Where-Object Name -eq $_.BaseName 71 | 72 | # Getting the list of function parameters 73 | $parameters = @($ParsedFunction.Body.ParamBlock.Parameters.name.VariablePath.Foreach{ $_.ToString() }) 74 | } 75 | 76 | BeforeAll { 77 | $functionName = $_.BaseName 78 | $functionPath = $_ 79 | } 80 | 81 | Context "Function Code Style Tests" { 82 | It "should be an advanced function" { 83 | $functionPath | Should -FileContentMatch 'Function' 84 | $functionPath | Should -FileContentMatch 'CmdletBinding' 85 | $functionPath | Should -FileContentMatch 'Param' 86 | } 87 | 88 | It "should contain Write-Verbose blocks" { 89 | $functionPath | Should -FileContentMatch 'Write-Verbose' 90 | } 91 | 92 | It "should be a valid PowerShell code" { 93 | $psFile = Get-Content -Path $functionPath -ErrorAction Stop 94 | $errors = $null 95 | $null = [System.Management.Automation.PSParser]::Tokenize($psFile, [ref]$errors) 96 | $errors.Count | Should -Be 0 97 | } 98 | 99 | It "should have tests" { 100 | Test-Path ($functionPath -replace ".ps1", ".Tests.ps1") | Should -Be $true 101 | ($functionPath -replace ".ps1", ".Tests.ps1") | Should -FileContentMatch "Describe `"'$functionName'" 102 | } 103 | } 104 | 105 | Context "Function Help Quality Tests" { 106 | BeforeAll { 107 | # Getting function help 108 | $AbstractSyntaxTree = [System.Management.Automation.Language.Parser]::ParseInput((Get-Content -raw $functionPath), [ref]$null, [ref]$null) 109 | $AstSearchDelegate = { $args[0] -is [System.Management.Automation.Language.FunctionDefinitionAst] } 110 | $ParsedFunction = $AbstractSyntaxTree.FindAll( $AstSearchDelegate, $true ) | Where-Object Name -eq $functionName 111 | $functionHelp = $ParsedFunction.GetHelpContent() 112 | } 113 | 114 | It "should have a SYNOPSIS" { 115 | $functionHelp.Synopsis | Should -Not -BeNullOrEmpty 116 | } 117 | 118 | It "should have a DESCRIPTION with length > 40 symbols" { 119 | $functionHelp.Description.Length | Should -BeGreaterThan 40 120 | } 121 | 122 | It "should have at least one EXAMPLE" { 123 | $functionHelp.Examples.Count | Should -BeGreaterThan 0 124 | $functionHelp.Examples[0] | Should -Match ([regex]::Escape($functionName)) 125 | $functionHelp.Examples[0].Length | Should -BeGreaterThan ($functionName.Length + 10) 126 | } 127 | 128 | $parameters | ForEach-Object { 129 | It "should have descriptive help for '' parameter" -TestCases @{parameter = $_} { 130 | $functionHelp.Parameters.($parameter.ToUpper()) | Should -Not -BeNullOrEmpty 131 | $functionHelp.Parameters.($parameter.ToUpper()).Length | Should -BeGreaterThan 25 132 | } 133 | } 134 | } 135 | } -------------------------------------------------------------------------------- /SampleModule/SampleModule.nuspec: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | SampleModule 5 | 0.0.1 6 | Andrew Matveychuk 7 | A sample PowerShell module. 8 | (c) Andrew Matveychuk. 9 | https://github.com/andrewmatveychuk/powershell.sample-module/LICENSE 10 | https://github.com/andrewmatveychuk/powershell.sample-module 11 | 12 | -------------------------------------------------------------------------------- /SampleModule/SampleModule.psd1: -------------------------------------------------------------------------------- 1 | # 2 | # Module manifest for module 'SampleModule' 3 | # 4 | # Generated by: Andrew Matveychuk 5 | # 6 | # Generated on: 3/29/2020 7 | # 8 | 9 | @{ 10 | 11 | # Script module or binary module file associated with this manifest. 12 | RootModule = 'SampleModule.psm1' 13 | 14 | # Version number of this module. 15 | ModuleVersion = '0.0.1' 16 | 17 | # Supported PSEditions 18 | # CompatiblePSEditions = @() 19 | 20 | # ID used to uniquely identify this module 21 | GUID = 'e1a0f085-ee1a-4c27-b91a-fd130a6c753c' 22 | 23 | # Author of this module 24 | Author = 'Andrew Matveychuk' 25 | 26 | # Company or vendor of this module 27 | CompanyName = '' 28 | 29 | # Copyright statement for this module 30 | Copyright = '(c) Andrew Matveychuk.' 31 | 32 | # Description of the functionality provided by this module 33 | Description = 'A sample PowerShell Module.' 34 | 35 | # Minimum version of the PowerShell engine required by this module 36 | PowerShellVersion = '5.1' 37 | 38 | # Name of the PowerShell host required by this module 39 | # PowerShellHostName = '' 40 | 41 | # Minimum version of the PowerShell host required by this module 42 | # PowerShellHostVersion = '' 43 | 44 | # Minimum version of Microsoft .NET Framework required by this module. This prerequisite is valid for the PowerShell Desktop edition only. 45 | # DotNetFrameworkVersion = '' 46 | 47 | # Minimum version of the common language runtime (CLR) required by this module. This prerequisite is valid for the PowerShell Desktop edition only. 48 | # ClrVersion = '' 49 | 50 | # Processor architecture (None, X86, Amd64) required by this module 51 | # ProcessorArchitecture = '' 52 | 53 | # Modules that must be imported into the global environment prior to importing this module 54 | # RequiredModules = @() 55 | 56 | # Assemblies that must be loaded prior to importing this module 57 | # RequiredAssemblies = @() 58 | 59 | # Script files (.ps1) that are run in the caller's environment prior to importing this module. 60 | # ScriptsToProcess = @() 61 | 62 | # Type files (.ps1xml) to be loaded when importing this module 63 | # TypesToProcess = @() 64 | 65 | # Format files (.ps1xml) to be loaded when importing this module 66 | # FormatsToProcess = @() 67 | 68 | # Modules to import as nested modules of the module specified in RootModule/ModuleToProcess 69 | # NestedModules = @() 70 | 71 | # Functions to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no functions to export. 72 | FunctionsToExport = '*' 73 | 74 | # Cmdlets to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no cmdlets to export. 75 | CmdletsToExport = @() 76 | 77 | # Variables to export from this module 78 | VariablesToExport = '*' 79 | 80 | # Aliases to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no aliases to export. 81 | AliasesToExport = @() 82 | 83 | # DSC resources to export from this module 84 | # DscResourcesToExport = @() 85 | 86 | # List of all modules packaged with this module 87 | # ModuleList = @() 88 | 89 | # List of all files packaged with this module 90 | # FileList = @() 91 | 92 | # Private data to pass to the module specified in RootModule/ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell. 93 | PrivateData = @{ 94 | 95 | PSData = @{ 96 | 97 | # Tags applied to this module. These help with module discovery in online galleries. 98 | # Tags = @() 99 | 100 | # A URL to the license for this module. 101 | # LicenseUri = '' 102 | 103 | # A URL to the main website for this project. 104 | # ProjectUri = '' 105 | 106 | # A URL to an icon representing this module. 107 | # IconUri = '' 108 | 109 | # ReleaseNotes of this module 110 | # ReleaseNotes = '' 111 | 112 | # Prerelease string of this module 113 | # Prerelease = '' 114 | 115 | # Flag to indicate whether the module requires explicit user acceptance for install/update/save 116 | # RequireLicenseAcceptance = $false 117 | 118 | # External dependent modules of this module 119 | # ExternalModuleDependencies = @() 120 | 121 | } # End of PSData hashtable 122 | 123 | } # End of PrivateData hashtable 124 | 125 | # HelpInfo URI of this module 126 | # HelpInfoURI = '' 127 | 128 | # Default prefix for commands exported from this module. Override the default prefix using Import-Module -Prefix. 129 | # DefaultCommandPrefix = '' 130 | 131 | } 132 | -------------------------------------------------------------------------------- /SampleModule/SampleModule.psm1: -------------------------------------------------------------------------------- 1 | Set-StrictMode -Version Latest 2 | 3 | # Get public and private function definition files 4 | $public = @(Get-ChildItem -Path "$PSScriptRoot\Public\*.ps1" -Exclude "*.Tests.*" -ErrorAction SilentlyContinue) 5 | $private = @(Get-ChildItem -Path "$PSScriptRoot\Private\*.ps1" -Exclude "*.Tests.*" -ErrorAction SilentlyContinue) 6 | 7 | # Importing all functions 8 | foreach ($import in @($public + $private)) { 9 | try { 10 | Write-Verbose "Importing $($import.FullName)..." 11 | . $import.FullName 12 | } 13 | catch { 14 | Write-Error "Failed to import function $($import.FullName): $_" 15 | } 16 | } 17 | 18 | # Export public functions 19 | Export-ModuleMember -Function $public.BaseName -------------------------------------------------------------------------------- /azure-pipelines.yml: -------------------------------------------------------------------------------- 1 | trigger: 2 | branches: 3 | include: 4 | - master 5 | - feature/* 6 | - bugfix/* 7 | paths: 8 | exclude: 9 | - README.md 10 | 11 | pool: 12 | vmImage: 'windows-latest' 13 | 14 | # abc 15 | # some changes 16 | stages: 17 | - stage: Test 18 | jobs: 19 | - job: TestJob 20 | steps: 21 | 22 | - task: PowerShell@2 23 | displayName: Install InvokeBuild module on the build agent 24 | inputs: 25 | targetType: 'inline' 26 | pwsh: true 27 | script: | 28 | if (-not (Get-Module -Name InvokeBuild -ListAvailable)) { 29 | Install-Module InvokeBuild -Force 30 | } 31 | Import-Module InvokeBuild 32 | 33 | - task: PowerShell@2 34 | displayName: Analyze code with PSScriptAnalyzer 35 | inputs: 36 | targetType: 'inline' 37 | pwsh: true 38 | failOnStderr: false 39 | script: Invoke-Build -Task Analyze 40 | workingDirectory: $(System.DefaultWorkingDirectory) 41 | 42 | - task: PublishTestResults@2 43 | displayName: Publish code analysis results 44 | condition: succeededOrFailed() 45 | inputs: 46 | testResultsFormat: 'NUnit' 47 | testResultsFiles: '$(System.DefaultWorkingDirectory)/**/AnalysisResults*.xml' 48 | failTaskOnFailedTests: true 49 | 50 | - task: PowerShell@2 51 | displayName: Test code with Pester tests 52 | inputs: 53 | targetType: 'inline' 54 | pwsh: true 55 | failOnStderr: false 56 | script: Invoke-Build -Task Test 57 | workingDirectory: $(System.DefaultWorkingDirectory) 58 | 59 | - task: PublishTestResults@2 60 | displayName: Publish test results 61 | condition: succeededOrFailed() 62 | inputs: 63 | testResultsFormat: 'NUnit' 64 | testResultsFiles: '$(System.DefaultWorkingDirectory)/**/TestResults*.xml' 65 | failTaskOnFailedTests: true 66 | 67 | - task: PowerShell@2 68 | displayName: Verify code coverage 69 | inputs: 70 | targetType: 'inline' 71 | pwsh: true 72 | failOnStderr: true 73 | script: Invoke-Build -Task CodeCoverage 74 | workingDirectory: $(System.DefaultWorkingDirectory) 75 | 76 | - task: PublishCodeCoverageResults@1 77 | displayName: Publish code coverage results 78 | condition: succeededOrFailed() 79 | inputs: 80 | codeCoverageTool: 'JaCoCo' 81 | summaryFileLocation: '$(System.DefaultWorkingDirectory)/**/CodeCoverageResults*.xml' 82 | pathToSources: '$(System.DefaultWorkingDirectory)/$(module.Name)/' 83 | failIfCoverageEmpty: true 84 | 85 | - stage: Build 86 | condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/master')) # Create builds only from the master branch 87 | jobs: 88 | - job: BuildJob 89 | steps: 90 | 91 | - task: PowerShell@2 92 | displayName: Install InvokeBuild module on the build agent 93 | inputs: 94 | targetType: 'inline' 95 | pwsh: true 96 | script: | 97 | if (-not (Get-Module -Name InvokeBuild -ListAvailable)) { 98 | Install-Module InvokeBuild -Force 99 | } 100 | Import-Module InvokeBuild 101 | 102 | - task: PowerShell@2 103 | displayName: Build PowerShell module 104 | inputs: 105 | targetType: 'inline' 106 | pwsh: true 107 | failOnStderr: false 108 | script: Invoke-Build -Task Build -Configuration Release -Sourcelocation $(module.SourceLocation) 109 | workingDirectory: $(System.DefaultWorkingDirectory) 110 | 111 | - task: NuGetCommand@2 112 | displayName: Create a NuGet package 113 | inputs: 114 | command: 'pack' 115 | packagesToPack: '$(System.DefaultWorkingDirectory)/build/**/*.nuspec' 116 | packDestination: '$(Build.ArtifactStagingDirectory)' 117 | 118 | - task: PublishBuildArtifacts@1 119 | displayName: Publish build artifact 120 | inputs: 121 | PathtoPublish: '$(Build.ArtifactStagingDirectory)' 122 | ArtifactName: '$(module.Name)' 123 | publishLocation: Container 124 | 125 | - stage: Publish 126 | condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/master')) # Publish the module only from the master branch 127 | jobs: 128 | - job: PublishJob 129 | steps: 130 | 131 | - task: DownloadPipelineArtifact@2 132 | displayName: Download pipeline artifact 133 | inputs: 134 | buildType: 'current' 135 | artifactName: '$(module.Name)' 136 | itemPattern: '**/*.nupkg' 137 | targetPath: '$(Pipeline.Workspace)' 138 | 139 | - task: NuGetCommand@2 140 | displayName: Publish module to NuGet feed 141 | inputs: 142 | command: 'push' 143 | packagesToPush: '$(Pipeline.Workspace)/**/*.nupkg' 144 | nuGetFeedType: 'internal' 145 | publishVstsFeed: '$(System.TeamProject)/$(module.FeedName)' --------------------------------------------------------------------------------