Repository files navigation

Infrastructure test runner and notification system usingOperation Validation Framework (OVF) PowerShell modules and Pester.

Watchmen is a PowerShell module to make executing Pester tests contained in OVF modules easier using a simple PowerShell-based Domain SpecificLanguage (DSL). It also provides the ability to execute a number of actions (notifiers) upon failing (or successful) infrastructure tests. Watchmencan also dynamically install OVF modules from public or private PowerShell repositories like thePowerShell Galleryshould the module not be found on the system.

More information about creating Watchmen files and executing notifiers can be found athttp://watchmen.readthedocs.io/en/latest/

The easiest and prefered way to install Watchmen is via thePowerShell Gallery. To use the PowerShell Gallery,you must be on Windows 10, have PowerShell 5, or PowerShell 3 or 4 with thePowerShellGetmodule. See thePowerShell Gallery Getting Started page for more information.Run the following command to install Watchmen and the two dependent modulesPSSlack andPosh-SYSLOG.

Install-Module-Name Watchmen-Repository PSGallery

As an alternative, you can clone this repository the a location on your system and copy the subfolderWatchmen toC:\Program Files\WindowsPowerShell\Modules\. If you downloaded the repository as a ZIP file, extract it, and copy the subfolderWatchmen toC:\Program Files\WindowsPowerShell\Modules\. If you copied Watchmen to theModules folder manually, you must ensure both the depended modulesPSSlack andPosh-SYSLOG are installed there as well.

TheOperation Validation Framework is a PowerShell module used to executePester tests that validate the operation of asystem rather than test the behavior of code. This could meanrunning tests that validate certain Windows services are running and IIS is responding on port 443.

An OVF module is a PowerShell module that includes Pester tests in a certain folder structure:

• ModuleBase\
  • ModuleName.psd1
  • Diagnostics\
    • Simple\
      • simple.tests.ps1simple tests (e.g., service checks, endpoint checks)
    • Comprehensive\
      • comprehensive.tests.ps1comprehensive scenario tests

• Service 'W3SVC' is running
• Localhost responds on port 443 with HTTP code 200.
• All volumes have a minimum of 5GB free space.

Pester tests packaged into a PowerShell module gain the immediate benefit of being versionable just like any other PowerShell module. They also areeasily publishable to public or private NuGet-based repositories like thePowerShell Gallery. This facilitateshigh quality test modules that validate common infrastructure to be shared and improved upon by the broader community.

The example Watchmen file below will execute Pester tests contained inside theMyAppOVF module installed on the location machine. Upon any failing(or optionally successful) tests, Watchmen will then execute a number of notifiers such as sending an email, writing to the eventlog, appending to alog file, executing an arbitrary PowerShell script block or script, sending a message to a Slack channel, and send a message to a syslog server.

# Global notifiers that are executed upon any failing testWatchmenOptions {    notifies {        When'OnFailure'        email@{fromAddress='watchmen@mydomain.tld'smtpServer='smtp.mydomain.tld'port=25subject='Watchmen alert - #{computername} - [#{test}] failed!'to='admin@mydomain.tld'        }        eventlog@{eventid=1eventtype='error'        }        eventlog@{eventid=100eventtype='information'        }-when'onsuccess'        logfile'\\fileserver01.mydomain.tld\monitoringshare\#{computername}.log'        powershell {Write-Host"Something bad happended!$args[0]"        }        powershell'\notifier.ps1'        slack@{Token='<webhookurl>'Channel='#Watchmen'AuthorName=$env:COMPUTERNAMEPreText='Everything is on :fire:'IconEmoji=':fire:'        }        syslog'syslog.mydomain.tld'-when'always'    }}# Execute the 'Storage.Capacity' tests in version 1.0.0 of the 'MyAppOVF' moduleWatchmenTest'MyAppOVF' {    version1.0.0# Execute tests from a specific version of the module. Default is latest    testType'Simple'# Valid values 'simple', 'comprehensive', 'all'. Default is 'all'    test'Storage.Capacity'# Name of test to execute. Default is '*'    fromSource'PSGallery'# Name of PowerShell repository to install module from if not found on system.    parameters {# Parameters that are passed into the Pester script to change the behaviour of the test.        FreeSystemDriveThreshold=40000    }    notifies {# Notifiers to execute for this test in addition to ones defined in 'WatchmenOptions'        logfile'\\fileserver01.mydomain.tld\monitoringshare\#{computername}.log'-when'always'    }}# Execute all tests in the SystemOVF module and install module from the 'PSPrivateGallery' repository if not installed on the system.# Global notifiers will be executed upon any failing tests.WatchmenTest'SystemOVF' {    fromSource'PSPrivateGallery'}

A Watchmen file is a PowerShell script that can be read by callingGet-WatchmenTest. The object(s) returned represent the OVF tests to executeand the associated notifiers to call upon any failing tests. RunningInvoke-WatchmenTest will execute the tests and call any notifiers asappropriate.

Getting watchmen tests

$tests=Get-WatchmenTest-Path'.\myapp.watchmen.ps1'

Executing watchmen tests

$tests|Invoke-WatchmenTest-Verbose-IncludePesterOutput