SqlServerDsc: Unit tests are run in containers (dsccommunity#1236)

- Changes to SqlServerDsc
  - Updated the Contributing section in the README.md after
    Style Guideline and Best Practices guidelines has merged into one document.
  - To speed up testing in AppVeyor, unit tests are now run in two containers.
  - Adding the PowerShell script `Assert-TestEnvironment.ps1` which
    must be run prior to running any unit tests locally with
    `Invoke-Pester`.
    Read more in the specific contributing guidelines, under the section
    Unit Tests in the CONTRIBUTING.md.

.gitignore

@@ -1,4 +1,5 @@
-DSCResource.Tests
+DscResource.Tests
+DSCResource.Tests
 .vs
 .vscode
 node_modules

Assert-TestEnvironment.ps1

@@ -0,0 +1,103 @@
+<#
+    .SYNOPSIS
+        Assert that the test environment is properly setup and loaded into the
+        PowerShell session.
+
+    .DESCRIPTION
+        Assert that the test environment is properly setup and loaded into the
+        PowerShell session.
+
+    .EXAMPLE
+        .\Assert-testEnvironment.ps1
+
+        Will assert that the current PowerShell session is ready to run tests.
+#>
+
+[CmdletBinding(SupportsShouldProcess = $true)]
+param
+(
+)
+
+#region Verify prerequisites Pester
+$pesterModuleName = 'Pester'
+
+# This is the minimum version that can be used with the tests in this repo.
+$pesterModuleMinimumVersion = '4.0.2'
+
+<#
+    Pester v4.4.0 has a fix for '-Not -Throw' so it shows the actual error
+    message if an unexpected exception does occur. It will help when debugging
+    tests.
+    If no Pester module exist, then use this as the minimum version.
+#>
+$pesterModuleRecommendedMinimumVersion = '4.4.0'
+
+$pesterModule = Get-Module $pesterModuleName -ListAvailable -Verbose:$false |
+    Where-Object -Property 'Version' -GE -Value $pesterModuleMinimumVersion |
+    Sort-Object -Property 'Version' -Descending |
+    Select-Object -First 1
+
+if (-not $pesterModule)
+{
+    <#
+        Not installing the module here because it's not known what scope the
+        user want (can) to install the module in.
+    #>
+    $message = 'Missing a compatible version of the {0} module. Minimum version of {0} module can be ''{2}'', but the recommended minimum version is ''{1}''.' -f $pesterModuleName, $pesterModuleRecommendedMinimumVersion, $pesterModuleMinimumVersion
+    Write-Warning -Message $message
+    $dependencyMissing = $true
+}
+else
+{
+    Write-Verbose -Message ('A compatible {0} module is already installed (v{1}). If you want to use a newer version of {0} module, please install it manually.' -f $pesterModule.Name, $pesterModule.Version)
+}
+#endregion Verify prerequisites Pester
+
+#region Verify prerequisites PSDepend
+$psDependModuleName = 'PSDepend'
+
+# This is the minimum version that can be used with the tests in this repo.
+$psDependModuleMinimumVersion = '0.3.0'
+$psDependModuleRecommendedMinimumVersion = 'latest'
+
+$psDependModule = Get-Module $psDependModuleName -ListAvailable -Verbose:$false |
+    Where-Object -Property 'Version' -GE -Value $psDependModuleMinimumVersion |
+    Sort-Object -Property 'Version' -Descending |
+    Select-Object -First 1
+
+if (-not $psDependModule)
+{
+    <#
+        Not installing the module here because it's not known what scope the
+        user want (can) to install the module in.
+    #>
+    $message = 'Missing a compatible version of the {0} module. Minimum version of {0} module can be ''{2}'', but the recommended minimum version is ''{1}''. Please install {0} module manually, then run this script again.' -f $psDependModuleName, $psDependModuleRecommendedMinimumVersion, $psDependModuleMinimumVersion
+    Write-Warning -Message $message
+    $dependencyMissing = $true
+}
+else
+{
+    Write-Verbose -Message ('A compatible {0} module is already installed (v{1}). If you want to use a newer version of {0} module, please install it manually.' -f $psDependModule.Name, $psDependModule.Version)
+}
+#endregion Verify prerequisites PSDepend
+
+if ($dependencyMissing)
+{
+    Write-Output -InputObject 'Please install the necessary dependencies manually, then run this script again.'
+    return
+}
+
+$dependenciesPath = Join-Path $PSScriptRoot -ChildPath 'Tests'
+
+Write-Verbose -Message ('Running Invoke-PSDepend using dependencies found under the path ''{0}''.' -f $dependenciesPath)
+
+if ($PSBoundParameters.ContainsKey('Confirm'))
+{
+    $invokePSDependConfirmation = $ConfirmPreference
+}
+else
+{
+    $invokePSDependConfirmation = $false
+}
+
+Invoke-PSDepend -Path $dependenciesPath -Confirm:$invokePSDependConfirmation

CHANGELOG.md

@@ -10,6 +10,15 @@
   - Updated broken links in `\README.md` and in `\Examples\README.md`
   - Opt-in for common test 'Common Tests - Relative Path Length'.
   - Updated the Installation section in the README.md.
+  - Updated the Contributing section in the README.md after
+    [Style Guideline and Best Practices guidelines](https://github.com/PowerShell/DscResources/blob/master/StyleGuidelines.md)
+    has merged into one document.
+  - To speed up testing in AppVeyor, unit tests are now run in two containers.
+  - Adding the PowerShell script `Assert-TestEnvironment.ps1` which
+    must be run prior to running any unit tests locally with
+    `Invoke-Pester`.
+    Read more in the specific contributing guidelines, under the section
+    [Unit Tests](https://github.com/PowerShell/SqlServerDsc/blob/dev/CONTRIBUTING.md#unit-tests).
 - Changes to SqlServerDscHelper
   - Fix style guideline lint errors.
   - Changes to Connect-SQL

CONTRIBUTING.md

@@ -378,14 +378,23 @@ For a review of a Pull Request (PR) to start, all tests must pass without error.
 If you need help to figure why some test don't pass, just write a comment in the
 Pull Request (PR), or submit an issue, and somebody will come along and assist.
 
-To run all tests manually run the following.
+To run all unit tests manually run the following.
 
 ```powershell
-Install-Module Pester
-cd '<path to cloned repository>\Tests'
+cd '<path to cloned repository>'
+.\Assert-TestEnvironment.ps1 -Confirm -Verbose
+cd '<path to cloned repository>\Tests\Unit'
 Invoke-Pester
 ```
 
+The script `Assert-TestEnvironment.ps1` will clone the test framework
+from GitHub, and load some necessary types which is needed to run some
+of the tests. Read more about the bootstrap script in the section
+[Bootstrap script Assert-TestEnvironment](#bootstrap-script-assert-testenvironment).
+
+The cmdlet `Invoke-Pester` looks for all the '*.Tests.ps1' PowerShell
+script files recursively and executes the tests.
+
 #### Unit tests for style check of Markdown files
 
 When sending in a Pull Request (PR) a style check will be performed on all Markdown
@@ -439,3 +448,29 @@ If using Visual Studio Code to edit Markdown files it can be a good idea to inst
 the markdownlint extension. It will help to do style checking.
 The file [.markdownlint.json](/.markdownlint.json) is prepared with a default set
 of rules which will automatically be used by the extension.
+
+## Bootstrap script Assert-TestEnvironment
+
+The bootstrap script [`Assert-TestEnvironment.ps1`](Assert-TestEnvironment.ps1)
+was needed when tests were updated to run in containers.
+There are some custom types (`Microsoft.DscResourceKit.*`) that are needed
+to be able to parse the test script files. Those types must be loaded
+into the session prior to running any unit tests with `Invoke-Pester`.
+
+The script works without any parameters and will do the following.
+
+>**Note:** If you want to confirm each step, then add the `-Confirm`
+>parameter.
+
+- Check if a compatible *Pester* version is available.
+- Check if a compatible *PSDepend* version is available.
+- Invoke PSDepend (using `Tests/Tests.depend.psd1`).
+  - Remove local cloned repository *DscResource.Tests* if it is present
+    (always assumes it's an older version).
+  - Clone *DscResource.Tests* from GitHub into the local repository
+    folder, and check out the branch `dev` to always be on the latest
+    commit available.
+  - Load the necessary types from the test framework *DscResource.Tests*.
+
+If there are no compatible Pester or PSDepend version available, you will be asked
+to install it manually, and then run the script again.

README.md

@@ -47,16 +47,11 @@ by sending in pull requests yourself.
   please first check out the [Review Pull Request guidelines](https://github.com/PowerShell/DscResources/blob/master/CONTRIBUTING.md#reviewing-pull-requests),
   and the browse the list of [pull requests](https://github.com/PowerShell/SqlServerDsc/pulls)
   and look for those pull requests with label 'needs review'.
-* If you want to improve the resources or tests,
-  or create a new resource,
+* If you want to improve this resource module,
   then please check out the following guidelines.
-  * The [Contributing to the DSC Resource Kit](https://github.com/PowerShell/DscResources/blob/master/CONTRIBUTING.md)
-    guidelines.
   * The specific [Contributing to SqlServerDsc](https://github.com/PowerShell/SqlServerDsc/blob/dev/CONTRIBUTING.md)
     guidelines.
-  * The common [Style Guidelines](https://github.com/PowerShell/DscResources/blob/master/StyleGuidelines.md).
-  * The common [Best Practices](https://github.com/PowerShell/DscResources/blob/master/BestPractices.md)
-    guidelines.
+  * The common [Style Guidelines & Best Practices](https://github.com/PowerShell/DscResources/blob/master/StyleGuidelines.md).
   * The common [Testing Guidelines](https://github.com/PowerShell/DscResources/blob/master/TestsGuidelines.md).
   * If you are new to GitHub (and git),
     then please check out [Getting Started with GitHub](https://github.com/PowerShell/DscResources/blob/master/GettingStartedWithGitHub.md).

Tests/Tests.depend.psd1

@@ -0,0 +1,42 @@
+<#
+    .DESCRIPTION
+        This is the dependency file for use with Assert-TestEnvironment.ps1 and/or
+        Invoke-PSDepend (PSSDepend).
+#>
+@{
+    RemoveTestFramework = @{
+        DependencyType = 'Command'
+        Source = '
+            $testFrameWorkPath = Join-Path -Path $PWD -ChildPath ''DscResource.Tests''
+            if (Test-Path -Path $testFrameWorkPath)
+            {
+                Write-Verbose -Message ''Removing local test framework repository.''
+                Remove-Item -Path (Join-Path -Path $PWD -ChildPath ''DscResource.Tests'') -Recurse -Force
+            }
+        '
+    }
+
+    'CloneTestFramework' = @{
+        DependencyType = 'Git'
+        Name = 'https://github.com/PowerShell/DscResource.Tests'
+        Version = 'dev'
+        DependsOn = 'RemoveTestFramework'
+    }
+
+    LoadDscResourceKitTypes = @{
+        DependencyType = 'Command'
+        Source = '
+            if (-not (''Microsoft.DscResourceKit.Test'' -as [Type]))
+            {
+                Write-Verbose -Message ''Loading the Microsoft.DscResourceKit types into the current session.''
+                $typesSourceFile = Join-Path -Path ''$PWD\DscResource.Tests'' -ChildPath ''Microsoft.DscResourceKit.cs''
+                Add-Type -Path $typesSourceFile -WarningAction SilentlyContinue
+            }
+            else
+            {
+                Write-Verbose -Message ''The Microsoft.DscResourceKit types was already loaded into the current session.''
+            }
+        '
+        DependsOn = 'CloneTestFramework'
+    }
+}

Tests/Unit/CommonResourceHelper.Tests.ps1

@@ -1,3 +1,17 @@
+<#
+    .SYNOPSIS
+        Automated unit test for helper functions in module CommonResourceHelper.
+
+    .NOTES
+        To run this script locally, please make sure to first run the bootstrap
+        script. Read more at
+        https://github.com/PowerShell/SqlServerDsc/blob/dev/CONTRIBUTING.md#bootstrap-script-assert-testenvironment
+#>
+
+# This is used to make sure the unit test run in a container.
+[Microsoft.DscResourceKit.UnitTest(ContainerName = 'Container1', ContainerImage = 'microsoft/windowsservercore')]
+param()
+
 Describe 'CommonResourceHelper Unit Tests' {
     BeforeAll {
         # Import the CommonResourceHelper module to test

Tests/Unit/MSFT_SqlAG.Tests.ps1

@@ -1,3 +1,17 @@
+<#
+    .SYNOPSIS
+        Automated unit test for MSFT_SqlAG DSC resource.
+
+    .NOTES
+        To run this script locally, please make sure to first run the bootstrap
+        script. Read more at
+        https://github.com/PowerShell/SqlServerDsc/blob/dev/CONTRIBUTING.md#bootstrap-script-assert-testenvironment
+#>
+
+# This is used to make sure the unit test run in a container.
+[Microsoft.DscResourceKit.UnitTest(ContainerName = 'Container1', ContainerImage = 'microsoft/windowsservercore')]
+param()
+
 #region HEADER
 
 # Unit Test Template Version: 1.2.1

Tests/Unit/MSFT_SqlAGDatabase.Tests.ps1

@@ -1,3 +1,17 @@
+<#
+    .SYNOPSIS
+        Automated unit test for MSFT_SqlAGDatabase DSC resource.
+
+    .NOTES
+        To run this script locally, please make sure to first run the bootstrap
+        script. Read more at
+        https://github.com/PowerShell/SqlServerDsc/blob/dev/CONTRIBUTING.md#bootstrap-script-assert-testenvironment
+#>
+
+# This is used to make sure the unit test run in a container.
+[Microsoft.DscResourceKit.UnitTest(ContainerName = 'Container1', ContainerImage = 'microsoft/windowsservercore')]
+param()
+
 #region HEADER
 
 # Unit Test Template Version: 1.2.0

Tests/Unit/MSFT_SqlAGListener.Tests.ps1

@@ -1,3 +1,17 @@
+<#
+    .SYNOPSIS
+        Automated unit test for MSFT_SqlAGListener DSC resource.
+
+    .NOTES
+        To run this script locally, please make sure to first run the bootstrap
+        script. Read more at
+        https://github.com/PowerShell/SqlServerDsc/blob/dev/CONTRIBUTING.md#bootstrap-script-assert-testenvironment
+#>
+
+# This is used to make sure the unit test run in a container.
+[Microsoft.DscResourceKit.UnitTest(ContainerName = 'Container1', ContainerImage = 'microsoft/windowsservercore')]
+param()
+
 $script:DSCModuleName = 'SqlServerDsc'
 $script:DSCResourceName = 'MSFT_SqlAGListener'
 

Tests/Unit/MSFT_SqlAGReplica.Tests.ps1

@@ -1,3 +1,17 @@
+<#
+    .SYNOPSIS
+        Automated unit test for MSFT_SqlAGReplica DSC resource.
+
+    .NOTES
+        To run this script locally, please make sure to first run the bootstrap
+        script. Read more at
+        https://github.com/PowerShell/SqlServerDsc/blob/dev/CONTRIBUTING.md#bootstrap-script-assert-testenvironment
+#>
+
+# This is used to make sure the unit test run in a container.
+[Microsoft.DscResourceKit.UnitTest(ContainerName = 'Container1', ContainerImage = 'microsoft/windowsservercore')]
+param()
+
 #region HEADER
 
 # Unit Test Template Version: 1.2.0

Tests/Unit/MSFT_SqlAlias.Tests.ps1

@@ -1,3 +1,17 @@
+<#
+    .SYNOPSIS
+        Automated unit test for MSFT_SqlAlias DSC resource.
+
+    .NOTES
+        To run this script locally, please make sure to first run the bootstrap
+        script. Read more at
+        https://github.com/PowerShell/SqlServerDsc/blob/dev/CONTRIBUTING.md#bootstrap-script-assert-testenvironment
+#>
+
+# This is used to make sure the unit test run in a container.
+[Microsoft.DscResourceKit.UnitTest(ContainerName = 'Container1', ContainerImage = 'microsoft/windowsservercore')]
+param()
+
 #region HEADER
 
 # Unit Test Template Version: 1.2.1

Tests/Unit/MSFT_SqlAlwaysOnService.Tests.ps1

@@ -1,3 +1,17 @@
+<#
+    .SYNOPSIS
+        Automated unit test for MSFT_SqlAlwaysOnService DSC resource.
+
+    .NOTES
+        To run this script locally, please make sure to first run the bootstrap
+        script. Read more at
+        https://github.com/PowerShell/SqlServerDsc/blob/dev/CONTRIBUTING.md#bootstrap-script-assert-testenvironment
+#>
+
+# This is used to make sure the unit test run in a container.
+[Microsoft.DscResourceKit.UnitTest(ContainerName = 'Container1', ContainerImage = 'microsoft/windowsservercore')]
+param()
+
 $script:DSCModuleName = 'SqlServerDsc'
 $script:DSCResourceName = 'MSFT_SqlAlwaysOnService'
 

Tests/Unit/MSFT_SqlDatabase.Tests.ps1

@@ -1,3 +1,17 @@
+<#
+    .SYNOPSIS
+        Automated unit test for MSFT_SqlDatabase DSC resource.
+
+    .NOTES
+        To run this script locally, please make sure to first run the bootstrap
+        script. Read more at
+        https://github.com/PowerShell/SqlServerDsc/blob/dev/CONTRIBUTING.md#bootstrap-script-assert-testenvironment
+#>
+
+# This is used to make sure the unit test run in a container.
+[Microsoft.DscResourceKit.UnitTest(ContainerName = 'Container1', ContainerImage = 'microsoft/windowsservercore')]
+param()
+
 $script:DSCModuleName = 'SqlServerDsc'
 $script:DSCResourceName = 'MSFT_SqlDatabase'