From b647f63fe18ab8564ed958fdfc1cf40417267f24 Mon Sep 17 00:00:00 2001 From: Daniel Hughes <2237515+dan-hughes@users.noreply.github.com> Date: Fri, 31 May 2024 13:25:16 +0100 Subject: [PATCH] Make `Generate_Wiki_Content` a metatask (#145) - Task `Generate_Wiki_Content` converted to a metatask. Existing functionality split into smaller tasks. Fixes issue #135 --- CHANGELOG.md | 2 + .../Private/Task.Copy_Source_Wiki_Folder.ps1 | 15 +++ .../Task.Create_Wiki_Output_Folder.ps1 | 15 +++ ...sk.Generate_Markdown_For_DSC_Resources.ps1 | 15 +++ .../tasks/Copy_Source_Wiki_Folder.build.ps1 | 117 ++++++++++++++++++ .../tasks/Create_Wiki_Output_Folder.build.ps1 | 96 ++++++++++++++ ...erate_Markdown_For_DSC_Resources.build.ps1 | 95 ++++++++++++++ source/tasks/Generate_Wiki_Content.build.ps1 | 50 +------- ....ps1 => Copy_Source_Wiki_Folder.Tests.ps1} | 28 +---- .../tasks/Create_Wiki_Output_Folder.Tests.ps1 | 59 +++++++++ ...erate_Markdown_For_DSC_Resources.Tests.ps1 | 52 ++++++++ 11 files changed, 474 insertions(+), 70 deletions(-) create mode 100644 source/Private/Task.Copy_Source_Wiki_Folder.ps1 create mode 100644 source/Private/Task.Create_Wiki_Output_Folder.ps1 create mode 100644 source/Private/Task.Generate_Markdown_For_DSC_Resources.ps1 create mode 100644 source/tasks/Copy_Source_Wiki_Folder.build.ps1 create mode 100644 source/tasks/Create_Wiki_Output_Folder.build.ps1 create mode 100644 source/tasks/Generate_Markdown_For_DSC_Resources.build.ps1 rename tests/unit/tasks/{Generate_Wiki_Content.build.Tests.ps1 => Copy_Source_Wiki_Folder.Tests.ps1} (67%) create mode 100644 tests/unit/tasks/Create_Wiki_Output_Folder.Tests.ps1 create mode 100644 tests/unit/tasks/Generate_Markdown_For_DSC_Resources.Tests.ps1 diff --git a/CHANGELOG.md b/CHANGELOG.md index 83e029f..da49e67 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Changed - Skipped failing tests on Linux due to libmi. +- Task `Generate_Wiki_Content` converted to a metatask. Existing + functionality split into smaller tasks. Fixes ([Issue #135](https://github.com/dsccommunity/DscResource.DocGenerator/issues/135)) ## [0.12.1] - 2024-01-21 diff --git a/source/Private/Task.Copy_Source_Wiki_Folder.ps1 b/source/Private/Task.Copy_Source_Wiki_Folder.ps1 new file mode 100644 index 0000000..2dcf242 --- /dev/null +++ b/source/Private/Task.Copy_Source_Wiki_Folder.ps1 @@ -0,0 +1,15 @@ +<# + .SYNOPSIS + This is the alias to the build task Copy_Source_Wiki_Folder's script file. + + .DESCRIPTION + This makes available the alias 'Task.Copy_Source_Wiki_Folder' that is + exported in the module manifest so that the build task can be correctly + imported using for example Invoke-Build. + + .NOTES + This is using the pattern lined out in the Invoke-Build repository + https://github.com/nightroman/Invoke-Build/tree/master/Tasks/Import. +#> + +Set-Alias -Name 'Task.Copy_Source_Wiki_Folder' -Value "$PSScriptRoot/tasks/Copy_Source_Wiki_Folder.build.ps1" diff --git a/source/Private/Task.Create_Wiki_Output_Folder.ps1 b/source/Private/Task.Create_Wiki_Output_Folder.ps1 new file mode 100644 index 0000000..8c4a083 --- /dev/null +++ b/source/Private/Task.Create_Wiki_Output_Folder.ps1 @@ -0,0 +1,15 @@ +<# + .SYNOPSIS + This is the alias to the build task Create_Wiki_Output_Folder's script file. + + .DESCRIPTION + This makes available the alias 'Task.Create_Wiki_Output_Folder' that is + exported in the module manifest so that the build task can be correctly + imported using for example Invoke-Build. + + .NOTES + This is using the pattern lined out in the Invoke-Build repository + https://github.com/nightroman/Invoke-Build/tree/master/Tasks/Import. +#> + +Set-Alias -Name 'Task.Create_Wiki_Output_Folder' -Value "$PSScriptRoot/tasks/Create_Wiki_Output_Folder.build.ps1" diff --git a/source/Private/Task.Generate_Markdown_For_DSC_Resources.ps1 b/source/Private/Task.Generate_Markdown_For_DSC_Resources.ps1 new file mode 100644 index 0000000..b110c2e --- /dev/null +++ b/source/Private/Task.Generate_Markdown_For_DSC_Resources.ps1 @@ -0,0 +1,15 @@ +<# + .SYNOPSIS + This is the alias to the build task Generate_Markdown_For_DSC_Resources's script file. + + .DESCRIPTION + This makes available the alias 'Task.Generate_Markdown_For_DSC_Resources' that is + exported in the module manifest so that the build task can be correctly + imported using for example Invoke-Build. + + .NOTES + This is using the pattern lined out in the Invoke-Build repository + https://github.com/nightroman/Invoke-Build/tree/master/Tasks/Import. +#> + +Set-Alias -Name 'Task.Generate_Markdown_For_DSC_Resources' -Value "$PSScriptRoot/tasks/Generate_Markdown_For_DSC_Resources.build.ps1" diff --git a/source/tasks/Copy_Source_Wiki_Folder.build.ps1 b/source/tasks/Copy_Source_Wiki_Folder.build.ps1 new file mode 100644 index 0000000..6950f96 --- /dev/null +++ b/source/tasks/Copy_Source_Wiki_Folder.build.ps1 @@ -0,0 +1,117 @@ +<# + .SYNOPSIS + This is a build task that generates conceptual help. + + .PARAMETER ProjectPath + The root path to the project. Defaults to $BuildRoot. + + .PARAMETER OutputDirectory + The base directory of all output. Defaults to folder 'output' relative to + the $BuildRoot. + + .PARAMETER BuiltModuleSubdirectory + Sub folder where you want to build the Module to (instead of $OutputDirectory/$ModuleName). + This is especially useful when you want to build DSC Resources, but you don't want the + `Get-DscResource` command to find several instances of the same DSC Resources because + of the overlapping $Env:PSmodulePath (`$buildRoot/output` for the built module and `$buildRoot/output/RequiredModules`). + + In most cases I would recommend against setting $BuiltModuleSubdirectory. + + .PARAMETER VersionedOutputDirectory + Whether the Module is built with its versioned Subdirectory, as you would see it on a System. + For instance, if VersionedOutputDirectory is $true, the built module's ModuleBase would be: `output/MyModuleName/2.0.1/` + + .PARAMETER ProjectName + The project name. Defaults to the empty string. + + .PARAMETER SourcePath + The path to the source folder name. Defaults to the empty string. + + .PARAMETER WikiSourceFolderName + The name of the folder that contains the source markdown files (e.g. 'Home.md') + to publish to the wiki. The name should be relative to the SourcePath. + Defaults to 'WikiSource'. + + .PARAMETER BuildInfo + The build info object from ModuleBuilder. Defaults to an empty hashtable. + + .NOTES + This is a build task that is primarily meant to be run by Invoke-Build but + wrapped by the Sampler project's build.ps1 (https://github.com/gaelcolas/Sampler). + + The function Set-WikiModuleVersion needed to be made a public function + for the build task to find it. Set-WikiModuleVersion function does not + need to be public so if there is a way found in the future that makes it + possible to have it as a private function then this code should refactored + to make that happen. +#> +param +( + [Parameter()] + [System.String] + $ProjectPath = (property ProjectPath $BuildRoot), + + [Parameter()] + [System.String] + $OutputDirectory = (property OutputDirectory (Join-Path $BuildRoot 'output')), + + [Parameter()] + [System.String] + $BuiltModuleSubdirectory = (property BuiltModuleSubdirectory ''), + + [Parameter()] + [System.Management.Automation.SwitchParameter] + $VersionedOutputDirectory = (property VersionedOutputDirectory $true), + + [Parameter()] + [System.String] + $ProjectName = (property ProjectName ''), + + [Parameter()] + [System.String] + $SourcePath = (property SourcePath ''), + + [Parameter()] + [System.String] + $WikiSourceFolderName = (property WikiSourceFolderName 'WikiSource'), + + [Parameter()] + [System.String] + $WikiOutputPath = (property WikiOutputPath ''), + + [Parameter()] + [System.Collections.Hashtable] + $BuildInfo = (property BuildInfo @{ }) +) + +# Synopsis: Generate wiki documentation for the DSC resources. +Task Copy_Source_Wiki_Folder { + # Get the values for task variables, see https://github.com/gaelcolas/Sampler#task-variables. + . Set-SamplerTaskVariable + + $wikiSourcePath = Join-Path -Path $SourcePath -ChildPath $WikiSourceFolderName + $wikiOutputPath = Join-Path -Path $OutputDirectory -ChildPath 'WikiContent' + + $wikiSourceExist = Test-Path -Path $wikiSourcePath + + if ($wikiSourceExist) + { + "`tWiki Source Path = $wikiSourcePath" + } + + if ($wikiSourceExist) + { + Write-Build -Color 'Magenta' -Text 'Copying Wiki content from the Wiki source folder.' + + Copy-Item -Path (Join-Path $wikiSourcePath -ChildPath '*') -Destination $wikiOutputPath -Recurse -Force + + $homeMarkdownFilePath = Join-Path -Path $wikiOutputPath -ChildPath 'Home.md' + + if (Test-Path -Path $homeMarkdownFilePath) + { + Write-Build -Color 'Magenta' -Text 'Updating module version in Home.md if there are any placeholders found.' + + Set-WikiModuleVersion -Path $homeMarkdownFilePath -ModuleVersion $moduleVersion + } + } +} diff --git a/source/tasks/Create_Wiki_Output_Folder.build.ps1 b/source/tasks/Create_Wiki_Output_Folder.build.ps1 new file mode 100644 index 0000000..da08118 --- /dev/null +++ b/source/tasks/Create_Wiki_Output_Folder.build.ps1 @@ -0,0 +1,96 @@ +<# + .SYNOPSIS + This is a build task that generates conceptual help. + + .PARAMETER ProjectPath + The root path to the project. Defaults to $BuildRoot. + + .PARAMETER OutputDirectory + The base directory of all output. Defaults to folder 'output' relative to + the $BuildRoot. + + .PARAMETER BuiltModuleSubdirectory + Sub folder where you want to build the Module to (instead of $OutputDirectory/$ModuleName). + This is especially useful when you want to build DSC Resources, but you don't want the + `Get-DscResource` command to find several instances of the same DSC Resources because + of the overlapping $Env:PSmodulePath (`$buildRoot/output` for the built module and `$buildRoot/output/RequiredModules`). + + In most cases I would recommend against setting $BuiltModuleSubdirectory. + + .PARAMETER VersionedOutputDirectory + Whether the Module is built with its versioned Subdirectory, as you would see it on a System. + For instance, if VersionedOutputDirectory is $true, the built module's ModuleBase would be: `output/MyModuleName/2.0.1/` + + .PARAMETER ProjectName + The project name. Defaults to the empty string. + + .PARAMETER SourcePath + The path to the source folder name. Defaults to the empty string. + + .PARAMETER WikiSourceFolderName + The name of the folder that contains the source markdown files (e.g. 'Home.md') + to publish to the wiki. The name should be relative to the SourcePath. + Defaults to 'WikiSource'. + + .PARAMETER BuildInfo + The build info object from ModuleBuilder. Defaults to an empty hashtable. + + .NOTES + This is a build task that is primarily meant to be run by Invoke-Build but + wrapped by the Sampler project's build.ps1 (https://github.com/gaelcolas/Sampler). + + The function Set-WikiModuleVersion needed to be made a public function + for the build task to find it. Set-WikiModuleVersion function does not + need to be public so if there is a way found in the future that makes it + possible to have it as a private function then this code should refactored + to make that happen. +#> +param +( + [Parameter()] + [System.String] + $ProjectPath = (property ProjectPath $BuildRoot), + + [Parameter()] + [System.String] + $OutputDirectory = (property OutputDirectory (Join-Path $BuildRoot 'output')), + + [Parameter()] + [System.String] + $BuiltModuleSubdirectory = (property BuiltModuleSubdirectory ''), + + [Parameter()] + [System.Management.Automation.SwitchParameter] + $VersionedOutputDirectory = (property VersionedOutputDirectory $true), + + [Parameter()] + [System.String] + $ProjectName = (property ProjectName ''), + + [Parameter()] + [System.String] + $SourcePath = (property SourcePath ''), + + [Parameter()] + [System.String] + $WikiSourceFolderName = (property WikiSourceFolderName 'WikiSource'), + + [Parameter()] + [System.Collections.Hashtable] + $BuildInfo = (property BuildInfo @{ }) +) + +# Synopsis: Create documentation output diretory for the DSC resources. +Task Create_Wiki_Output_Folder { + # Get the values for task variables, see https://github.com/gaelcolas/Sampler#task-variables. + . Set-SamplerTaskVariable + + $wikiOutputPath = Join-Path -Path $OutputDirectory -ChildPath 'WikiContent' + + if ((Test-Path -Path $wikiOutputPath) -eq $false) + { + $null = New-Item -Path $wikiOutputPath -ItemType Directory + } + + "`tWiki Output Path = $wikiOutputPath" +} diff --git a/source/tasks/Generate_Markdown_For_DSC_Resources.build.ps1 b/source/tasks/Generate_Markdown_For_DSC_Resources.build.ps1 new file mode 100644 index 0000000..cbfea68 --- /dev/null +++ b/source/tasks/Generate_Markdown_For_DSC_Resources.build.ps1 @@ -0,0 +1,95 @@ +<# + .SYNOPSIS + This is a build task that generates conceptual help. + + .PARAMETER ProjectPath + The root path to the project. Defaults to $BuildRoot. + + .PARAMETER OutputDirectory + The base directory of all output. Defaults to folder 'output' relative to + the $BuildRoot. + + .PARAMETER BuiltModuleSubdirectory + Sub folder where you want to build the Module to (instead of $OutputDirectory/$ModuleName). + This is especially useful when you want to build DSC Resources, but you don't want the + `Get-DscResource` command to find several instances of the same DSC Resources because + of the overlapping $Env:PSmodulePath (`$buildRoot/output` for the built module and `$buildRoot/output/RequiredModules`). + + In most cases I would recommend against setting $BuiltModuleSubdirectory. + + .PARAMETER VersionedOutputDirectory + Whether the Module is built with its versioned Subdirectory, as you would see it on a System. + For instance, if VersionedOutputDirectory is $true, the built module's ModuleBase would be: `output/MyModuleName/2.0.1/` + + .PARAMETER ProjectName + The project name. Defaults to the empty string. + + .PARAMETER SourcePath + The path to the source folder name. Defaults to the empty string. + + .PARAMETER WikiSourceFolderName + The name of the folder that contains the source markdown files (e.g. 'Home.md') + to publish to the wiki. The name should be relative to the SourcePath. + Defaults to 'WikiSource'. + + .PARAMETER BuildInfo + The build info object from ModuleBuilder. Defaults to an empty hashtable. + + .NOTES + This is a build task that is primarily meant to be run by Invoke-Build but + wrapped by the Sampler project's build.ps1 (https://github.com/gaelcolas/Sampler). + + The function Set-WikiModuleVersion needed to be made a public function + for the build task to find it. Set-WikiModuleVersion function does not + need to be public so if there is a way found in the future that makes it + possible to have it as a private function then this code should refactored + to make that happen. +#> +param +( + [Parameter()] + [System.String] + $ProjectPath = (property ProjectPath $BuildRoot), + + [Parameter()] + [System.String] + $OutputDirectory = (property OutputDirectory (Join-Path $BuildRoot 'output')), + + [Parameter()] + [System.String] + $BuiltModuleSubdirectory = (property BuiltModuleSubdirectory ''), + + [Parameter()] + [System.Management.Automation.SwitchParameter] + $VersionedOutputDirectory = (property VersionedOutputDirectory $true), + + [Parameter()] + [System.String] + $ProjectName = (property ProjectName ''), + + [Parameter()] + [System.String] + $SourcePath = (property SourcePath ''), + + [Parameter()] + [System.String] + $WikiSourceFolderName = (property WikiSourceFolderName 'WikiSource'), + + [Parameter()] + [System.Collections.Hashtable] + $BuildInfo = (property BuildInfo @{ }) +) + +# Synopsis: Generate wiki documentation for the DSC resources. +Task Generate_Markdown_For_DSC_Resources { + # Get the values for task variables, see https://github.com/gaelcolas/Sampler#task-variables. + . Set-SamplerTaskVariable + + $wikiOutputPath = Join-Path -Path $OutputDirectory -ChildPath 'WikiContent' + + Write-Build -Color 'Magenta' -Text 'Generating Wiki content for all DSC resources based on source and built module.' + + $dscResourceMarkdownMetadata = $BuildInfo.'DscResource.DocGenerator'.Generate_Markdown_For_DSC_Resources + + New-DscResourceWikiPage -SourcePath $SourcePath -BuiltModulePath $builtModuleBase -OutputPath $wikiOutputPath -Metadata $dscResourceMarkdownMetadata -Force +} diff --git a/source/tasks/Generate_Wiki_Content.build.ps1 b/source/tasks/Generate_Wiki_Content.build.ps1 index 0999361..bfea2c4 100644 --- a/source/tasks/Generate_Wiki_Content.build.ps1 +++ b/source/tasks/Generate_Wiki_Content.build.ps1 @@ -75,53 +75,13 @@ param [System.String] $WikiSourceFolderName = (property WikiSourceFolderName 'WikiSource'), + [Parameter()] + [System.String] + $WikiOutputPath = (property WikiOutputPath ''), + [Parameter()] [System.Collections.Hashtable] $BuildInfo = (property BuildInfo @{ }) ) -# Synopsis: Generate wiki documentation for the DSC resources. -task Generate_Wiki_Content { - # Get the values for task variables, see https://github.com/gaelcolas/Sampler#task-variables. - . Set-SamplerTaskVariable - - $wikiOutputPath = Join-Path -Path $OutputDirectory -ChildPath 'WikiContent' - - if ((Test-Path -Path $wikiOutputPath) -eq $false) - { - $null = New-Item -Path $wikiOutputPath -ItemType Directory - } - - "`tWiki Output Path = $wikiOutputPath" - - $wikiSourcePath = Join-Path -Path $SourcePath -ChildPath $WikiSourceFolderName - - $wikiSourceExist = Test-Path -Path $wikiSourcePath - - if ($wikiSourceExist) - { - "`tWiki Source Path = $wikiSourcePath" - } - - Write-Build -Color 'Magenta' -Text 'Generating Wiki content for all DSC resources based on source and built module.' - - $dscResourceMarkdownMetadata = $BuildInfo.'DscResource.DocGenerator'.Generate_Wiki_Content - - New-DscResourceWikiPage -SourcePath $SourcePath -BuiltModulePath $builtModuleBase -OutputPath $wikiOutputPath -Metadata $dscResourceMarkdownMetadata -Force - - if ($wikiSourceExist) - { - Write-Build -Color 'Magenta' -Text 'Copying Wiki content from the Wiki source folder.' - - Copy-Item -Path (Join-Path $wikiSourcePath -ChildPath '*') -Destination $wikiOutputPath -Recurse -Force - - $homeMarkdownFilePath = Join-Path -Path $wikiOutputPath -ChildPath 'Home.md' - - if (Test-Path -Path $homeMarkdownFilePath) - { - Write-Build -Color 'Magenta' -Text 'Updating module version in Home.md if there are any placeholders found.' - - Set-WikiModuleVersion -Path $homeMarkdownFilePath -ModuleVersion $moduleVersion - } - } -} +Task Generate_Wiki_Content Create_Wiki_Output_Folder, Copy_Source_Wiki_Folder, Generate_Markdown_For_DSC_Resources, Generate_Markdown_For_Public_Commands, Generate_External_Help_File_For_Public_Commands, Clean_Markdown_Of_Public_Commands diff --git a/tests/unit/tasks/Generate_Wiki_Content.build.Tests.ps1 b/tests/unit/tasks/Copy_Source_Wiki_Folder.Tests.ps1 similarity index 67% rename from tests/unit/tasks/Generate_Wiki_Content.build.Tests.ps1 rename to tests/unit/tasks/Copy_Source_Wiki_Folder.Tests.ps1 index b74d78d..9133128 100644 --- a/tests/unit/tasks/Generate_Wiki_Content.build.Tests.ps1 +++ b/tests/unit/tasks/Copy_Source_Wiki_Folder.Tests.ps1 @@ -18,40 +18,18 @@ Remove-Module -Name $script:moduleName -Force -ErrorAction 'SilentlyContinue' Import-Module $script:moduleName -Force -ErrorAction 'Stop' #endregion HEADER -Describe 'Generate_Wiki_Content' { +Describe 'Copy_Source_Wiki_Folder' { BeforeAll { - Mock -CommandName New-DscResourceWikiPage Mock -CommandName Copy-Item Mock -CommandName Set-WikiModuleVersion - Mock -Command Get-BuiltModuleVersion -MockWith { - return [PSCustomObject]@{ - Version = '1.0.0-preview1' - PreReleaseString = 'preview1' - ModuleVersion = '1.0.0' - } - } - - Mock -CommandName Get-Item -MockWith { - $Path = [System.String] ($Path -replace '\*','1.0.0') - - [PSCustomObject]@{ - FullName = $Path - } - } - - Mock -CommandName Get-SamplerModuleRootPath -MockWith { - # Return the path that was passed to the command. - return $BuiltModuleManifest - } - Mock -CommandName Test-Path -MockWith { return $true } } It 'Should export the build script alias' { - $buildTaskName = 'Generate_Wiki_Content' + $buildTaskName = 'Copy_Source_Wiki_Folder' $buildScriptAliasName = 'Task.{0}' -f $buildTaskName $script:buildScript = Get-Command -Name $buildScriptAliasName -Module $script:projectName @@ -74,6 +52,6 @@ Describe 'Generate_Wiki_Content' { Invoke-Build -Task $buildTaskName -File $script:buildScript.Definition @taskParameters } | Should -Not -Throw - Assert-MockCalled -CommandName New-DscResourceWikiPage -Exactly -Times 1 -Scope It + Assert-MockCalled -CommandName Set-WikiModuleVersion -Exactly -Times 1 -Scope It } } diff --git a/tests/unit/tasks/Create_Wiki_Output_Folder.Tests.ps1 b/tests/unit/tasks/Create_Wiki_Output_Folder.Tests.ps1 new file mode 100644 index 0000000..71749fa --- /dev/null +++ b/tests/unit/tasks/Create_Wiki_Output_Folder.Tests.ps1 @@ -0,0 +1,59 @@ +#region HEADER +$script:projectPath = "$PSScriptRoot\..\..\.." | Convert-Path +$script:projectName = (Get-ChildItem -Path "$script:projectPath\*\*.psd1" | Where-Object -FilterScript { + ($_.Directory.Name -match 'source|src' -or $_.Directory.Name -eq $_.BaseName) -and + $(try + { + Test-ModuleManifest -Path $_.FullName -ErrorAction Stop + } + catch + { + $false + }) + }).BaseName + +$script:moduleName = Get-Module -Name $script:projectName -ListAvailable | Select-Object -First 1 +Remove-Module -Name $script:moduleName -Force -ErrorAction 'SilentlyContinue' + +Import-Module $script:moduleName -Force -ErrorAction 'Stop' +#endregion HEADER + +Describe 'Create_Wiki_Output_Folder' { + BeforeAll { + Mock -CommandName New-Item + + + Mock -CommandName Test-Path -MockWith { + return $false + } -ParameterFilter { + $Path -eq $wikiOutputPath + } + } + + It 'Should export the build script alias' { + $buildTaskName = 'Create_Wiki_Output_Folder' + $buildScriptAliasName = 'Task.{0}' -f $buildTaskName + + $script:buildScript = Get-Command -Name $buildScriptAliasName -Module $script:projectName + + $script:buildScript.Name | Should -Be $buildScriptAliasName + $script:buildScript.ReferencedCommand | Should -Be ('{0}.build.ps1' -f $buildTaskName) + } + + It 'Should reference an existing build script' { + Test-Path -Path $script:buildScript.Definition | Should -BeTrue + } + + It 'Should run the build task without throwing' { + { + $taskParameters = @{ + ProjectName = 'DscResource.DocGenerator' + SourcePath = $TestDrive + } + + Invoke-Build -Task $buildTaskName -File $script:buildScript.Definition @taskParameters + } | Should -Not -Throw + + Assert-MockCalled -CommandName New-Item -Exactly -Times 1 -Scope It + } +} diff --git a/tests/unit/tasks/Generate_Markdown_For_DSC_Resources.Tests.ps1 b/tests/unit/tasks/Generate_Markdown_For_DSC_Resources.Tests.ps1 new file mode 100644 index 0000000..b31f9ee --- /dev/null +++ b/tests/unit/tasks/Generate_Markdown_For_DSC_Resources.Tests.ps1 @@ -0,0 +1,52 @@ +#region HEADER +$script:projectPath = "$PSScriptRoot\..\..\.." | Convert-Path +$script:projectName = (Get-ChildItem -Path "$script:projectPath\*\*.psd1" | Where-Object -FilterScript { + ($_.Directory.Name -match 'source|src' -or $_.Directory.Name -eq $_.BaseName) -and + $(try + { + Test-ModuleManifest -Path $_.FullName -ErrorAction Stop + } + catch + { + $false + }) + }).BaseName + +$script:moduleName = Get-Module -Name $script:projectName -ListAvailable | Select-Object -First 1 +Remove-Module -Name $script:moduleName -Force -ErrorAction 'SilentlyContinue' + +Import-Module $script:moduleName -Force -ErrorAction 'Stop' +#endregion HEADER + +Describe 'Generate_Markdown_For_DSC_Resources' { + BeforeAll { + Mock -CommandName New-DscResourceWikiPage + } + + It 'Should export the build script alias' { + $buildTaskName = 'Generate_Markdown_For_DSC_Resources' + $buildScriptAliasName = 'Task.{0}' -f $buildTaskName + + $script:buildScript = Get-Command -Name $buildScriptAliasName -Module $script:projectName + + $script:buildScript.Name | Should -Be $buildScriptAliasName + $script:buildScript.ReferencedCommand | Should -Be ('{0}.build.ps1' -f $buildTaskName) + } + + It 'Should reference an existing build script' { + Test-Path -Path $script:buildScript.Definition | Should -BeTrue + } + + It 'Should run the build task without throwing' { + { + $taskParameters = @{ + ProjectName = 'DscResource.DocGenerator' + SourcePath = $TestDrive + } + + Invoke-Build -Task $buildTaskName -File $script:buildScript.Definition @taskParameters + } | Should -Not -Throw + + Assert-MockCalled -CommandName New-DscResourceWikiPage -Exactly -Times 1 -Scope It + } +}