SCCM deployment validation using PowerShell Pester

The objective of this post is to share step by step examples of how to use a PowerShell Pester script to validate the deployment of System Center Configuration Manager (SCCM), which has been rebranded Microsoft Endpoint Manager (MEM). In addition to post deployment validation, admins can use the script as a troubleshooting tool to gain insight into the health of their environment.

Once the required components are inplace, which is super easy to do, running this script is a simple cut and paste process of just one line, or three lines to create the html report. No knowledge of PowerShell or Pester are required. To convey the benefits of this script, we will cover the following:

  1. Required components and files
  2. How to run the script
    • Using the script as troubleshooting tool
  3. Prevent sections of the script from running
  4. How to create the report dashboard

Required components and files

  • Pester PowerShell Module
    Pester is a test framework for PowerShell. It provides a language that allows you to define test cases, execute the tests and report the results. Pester comes natively installed with Windows Server 2016 and Windows 10. To use Pester, do the following.
    • Run Import-Module Pester from a PowerShell window on the CAS\Primary or a jump server(with the configuration manager console installed). This script was tested on the top-level server (CAS or standalone Primary), so if possible, import the pester module on one of those servers. If you have to, you can run it from a jump server as well.

  • SQL Server PowerShell Module
    There are two SQL Server PowerShell modules, Sqlps and SqlServer. The SQLPS module is included with the installation of SQL Server for backwards compatibility, but is no longer being updated. The most up-to-date PowerShell module is the SqlServer module. If possible install the SqlServer module.
    • If the CAS\Primary or the jump server do not have internet connection, install the SqlServer module on a workstation with internet access, then copy the folder to one of the three servers. To install, run Install-Module SqlServer. After installation, navigate to C:\Program Files\WindowsPowerShell\Modules, then copy the SqlServer folder to the same location(C:\ProgramFiles\WindowsPowerShell\Modules) on the CAS\Primary or jump server. Once copied, run Import-Module SqlServer.
    • If those steps are not working out for some reason, open CMValidation.Tests.ps1 with PowerShell ISE and change line 55 or search for “Import Module SqlServer” and change it to “Import Module SQLPS“.

  • PSRemoting
    The Enable-PSRemoting cmdlet configures the computer to receive PowerShell remote commands that are sent by using the WS-Management technology. Normally this task is already completed by your IT department. If not, run Enable-PSRemoting on the computers that you would like to run the validation script on.

  • Extent Framework for Reporting
    Extent.exe is used to create the html report\dashboard. With Extent you can create beautiful, interactive and detailed reports for your tests. Extent allows you to add events, screenshots, tags, devices, authors or any other relevant information.
    • Download Extent.exe from GitHub. Once you are on the page, click on the download link.
    • Copy Extent.exe and CMValidate.Tests.ps1 in the same folder on the CAS\Primary.

  • CMValidation.Tests.ps1 and InputFile.psd1.
    CMValidation.Tests.ps1 uses the Pester test framework to validate the deployment of SCCM or can be used as an every day troubleshooting tool.
    • Documentation on how to run the script, create an XML output and create the report dashboard are included in the script. To view the command examples, open PowerShell and run the command: Get-Help -Path . C:\Scripts\CMValidation.Tests.ps1 -Examples
    • InputFile.psd1 – This file stores the values that are used to validate desired state. Edit this file to match your environment before running the script.

How to run the script

All the examples are listed in the script. Run the command listed below to get all the examples.

Get-Help -Path . C:\Scripts\CMValidation.Tests.ps1 -Examples

You can change the file path and place the files anywhere you like, but my directory looks like this.

To run the script, cut and paste the first command example from CMValidation.Tests.ps1.

Invoke-Pester -Script @{ Path = 'C:\Script\CMValidation.Tests.ps1'; Parameters = @{Credential = Get-Credential; Inputfile = 'C:\Script\InputFile.psd1'}}

The output is displayed on the screen. Two example outputs are listed below. The first of the two is a successful test, and the other a failed test (the SCCM environment did not have a passive site server.)

In addition to the post deployment validation, the script can be used to troubleshoot your environment via the use of tags. Tags allows you to run only a specific section of this script because their might be no need to run the entire script against all servers if you only need to check the health of your management points.

For example, to get an on demand health report of your management points, run the command below using the tag “MP”. To run multiple descripbe blocks, use more than one tags. Two examples are listed below.

Invoke-Pester -Script @{ Path = 'C:\Script\CMValidation.Tests.ps1'; Parameters = @{Credential = Get-Credential; Inputfile = 'C:\Script\InputFile.psd1'}} -Tag "MP"

Invoke-Pester -Script @{ Path = 'C:\Script\CMValidation.Tests.ps1'; Parameters = @{Credential = Get-Credential; Inputfile = 'C:\Script\InputFile.psd1'}} -Tag "MP","DP"

To create the html report dashboard, we need to create an xml file for Extent.exe to consume. To output the Pester results to an xml file, run this command.

Invoke-Pester -Script @{ Path = 'C:\Script\CMValidation.Tests.ps1'; Parameters = @{Credential = Get-Credential; Inputfile = 'C:\Script\InputFile.psd1'}} -Outputfile C:\Script\OutPut\CMValidation.xml -OutputFormat NUnitXml

The additional commands that are needed to create the report will be covered in the last section.

Prevent sections of the script from running

You might not want to validate the hardware components of the servers every time you run the script. So to comment out a Describe or It blocks, add “<#” before the key word “Describe” or “It” and then at the end of the block “#>”. The before and after examples – Before:

         Describe "Validating the hardware configuration for each server in site: $($cmSite.Sitecode)" -Tags 'Hardware' {
            $db = Get-CMHierarchySetting | Where-Object -FilterScript {$_.Sitecode -eq $($cmSite.Sitecode)} | Select-Object SQLDatabaseName, SQLServerName
            $sqlServers = [String]$db.SQLServerName

            $allServers = "
            Use $($db.SQLDatabaseName)
            SELECT rl.SiteCode, rl.RoleName, rl.ServerName
            FROM v_SystemResourceList rl
            "
         }

After:

How to create the report dashboard

To share the PowerShell Pester results, you can create an html dashboard that can be shared with the team or your manager. To create the report then automatically open the html file, highlight and run the three lines listed below. Confirm that the path in each command are correct.

        Invoke-Pester -Script @{ Path = 'C:\Script\CMValidation.Tests.ps1'; Parameters = @{Credential = Get-Credential; Inputfile = 'C:\Script\InputFile.psd1'}} -Outputfile C:\Script\OutPut\CMValidation.xml -OutputFormat NUnitXml
        Start-Process -filePath "C:\Script\extent.exe" -ArgumentList '-i C:\Script\Output\CMValidation.xml','-o C:\Script\OutPut\CMReport'
        Start-Process -filePath "C:\Script\Output\CMReport\dashboard.html"

The report dashboard looks like this.

Click on Test to see the details of each test.

For large environments, you can search for specific results, like SQL

To download the script and the input file, click here.