{"id":14063936,"url":"https://github.com/devblackops/watchmen","last_synced_at":"2025-05-16T05:32:04.481Z","repository":{"id":142026390,"uuid":"60676945","full_name":"devblackops/watchmen","owner":"devblackops","description":"Infrastructure test runner using Pester and OVF modules","archived":false,"fork":false,"pushed_at":"2019-08-20T05:55:09.000Z","size":252,"stargazers_count":85,"open_issues_count":0,"forks_count":6,"subscribers_count":13,"default_branch":"dev","last_synced_at":"2025-04-03T20:51:15.409Z","etag":null,"topics":["framework","infrastructure-tests","operation","ovf","powershell","testing","validation","watchmen"],"latest_commit_sha":null,"homepage":"","language":"PowerShell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/devblackops.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null},"funding":{"github":"devblackops","patreon":"devblackops"}},"created_at":"2016-06-08T07:14:12.000Z","updated_at":"2024-04-12T21:26:06.000Z","dependencies_parsed_at":"2024-02-07T17:07:36.900Z","dependency_job_id":"0132cd94-a051-475f-a177-e88ca3329834","html_url":"https://github.com/devblackops/watchmen","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devblackops%2Fwatchmen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devblackops%2Fwatchmen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devblackops%2Fwatchmen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devblackops%2Fwatchmen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/devblackops","download_url":"https://codeload.github.com/devblackops/watchmen/tar.gz/refs/heads/dev","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254474460,"owners_count":22077286,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["framework","infrastructure-tests","operation","ovf","powershell","testing","validation","watchmen"],"created_at":"2024-08-13T07:03:35.100Z","updated_at":"2025-05-16T05:32:02.949Z","avatar_url":"https://github.com/devblackops.png","language":"PowerShell","readme":"[![Build status](https://ci.appveyor.com/api/projects/status/vci22inhjp3wn13n?svg=true)](https://ci.appveyor.com/project/devblackops/watchmen)\n[![Documentation Status](https://readthedocs.org/projects/watchmen/badge/?version=latest)](http://watchmen.readthedocs.io/en/latest/?badge=latest)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/devblackops/watchmen/raw/master/Media/logo.png\" alt=\"Watchmen logo\"/\u003e\n\u003c/p\u003e\n\nInfrastructure test runner and notification system using\n[Operation Validation Framework (OVF)](https://github.com/PowerShell/Operation-Validation-Framework) PowerShell modules and Pester.\n\n## Overview\nWatchmen is a PowerShell module to make executing Pester tests contained in OVF modules easier using a simple PowerShell-based Domain Specific\nLanguage (DSL). It also provides the ability to execute a number of actions (notifiers) upon failing (or successful) infrastructure tests. Watchmen\ncan also dynamically install OVF modules from public or private PowerShell repositories like the [PowerShell Gallery](https://www.powershellgallery.com/)\nshould the module not be found on the system.\n\n\u003e More information about creating Watchmen files and executing notifiers can be found at [http://watchmen.readthedocs.io/en/latest/](http://watchmen.readthedocs.io/en/latest/)\n\n## Installation\nThe easiest and prefered way to install Watchmen is via the [PowerShell Gallery](https://www.powershellgallery.com/). To use the PowerShell Gallery,\nyou must be on Windows 10, have PowerShell 5, or PowerShell 3 or 4 with the [PowerShellGet](http://go.microsoft.com/fwlink/?LinkID=746217\u0026clcid=0x409)\nmodule. See the [PowerShell Gallery Getting Started](https://www.powershellgallery.com/GettingStarted?section=Get%20Started) page for more information.\nRun the following command to install Watchmen and the two dependent modules [PSSlack](https://github.com/RamblingCookieMonster/PSSlack) and\n[Posh-SYSLOG](https://github.com/poshsecurity/Posh-SYSLOG).\n\n```powershell\nInstall-Module -Name Watchmen -Repository PSGallery\n```\n\nAs an alternative, you can clone this repository the a location on your system and copy the subfolder `Watchmen` to\n`C:\\Program Files\\WindowsPowerShell\\Modules\\`. If you downloaded the repository as a ZIP file, extract it, and copy the subfolder `Watchmen` to\n`C:\\Program Files\\WindowsPowerShell\\Modules\\`. If you copied Watchmen to the `Modules` folder manually, you must ensure both the depended modules\n[PSSlack](https://github.com/RamblingCookieMonster/PSSlack) and [Posh-SYSLOG](https://github.com/poshsecurity/Posh-SYSLOG) are installed there as well.\n\n## What is OVF?\nThe [Operation Validation Framework](https://github.com/PowerShell/Operation-Validation-Framework) is a PowerShell module used to execute\n[Pester](https://github.com/pester/Pester) tests that validate the operation of a **system** rather than test the behavior of code. This could mean\nrunning tests that validate certain Windows services are running and IIS is responding on port 443.\n\nAn OVF module is a PowerShell module that includes Pester tests in a certain folder structure:\n\n- ModuleBase\\\n  - ModuleName.psd1\n  - Diagnostics\\\n    - Simple\\\n      - simple.tests.ps1 *simple tests (e.g., service checks, endpoint checks)*\n    - Comprehensive\\\n      - comprehensive.tests.ps1 *comprehensive scenario tests*\n\n#### Example infrastructure tests\n* Service 'W3SVC' is running\n* Localhost responds on port 443 with HTTP code 200.\n* All volumes have a minimum of 5GB free space.\n\n## Why OVF?\nPester tests packaged into a PowerShell module gain the immediate benefit of being versionable just like any other PowerShell module. They also are\neasily publishable to public or private NuGet-based repositories like the [PowerShell Gallery](https://www.powershellgallery.com/). This facilitates\nhigh quality test modules that validate common infrastructure to be shared and improved upon by the broader community.\n\n## Example Watchmen File\nThe example Watchmen file below will execute Pester tests contained inside the **MyAppOVF** module installed on the location machine. Upon any failing\n(or optionally successful) tests, Watchmen will then execute a number of notifiers such as sending an email, writing to the eventlog, appending to a\nlog file, executing an arbitrary PowerShell script block or script, sending a message to a Slack channel, and send a message to a syslog server.\n\n#### myapp.watchmen.ps1\n```powershell\n# Global notifiers that are executed upon any failing test\nWatchmenOptions {\n    notifies {\n        When 'OnFailure'\n        email @{\n            fromAddress = 'watchmen@mydomain.tld'\n            smtpServer = 'smtp.mydomain.tld'\n            port = 25\n            subject = 'Watchmen alert - #{computername} - [#{test}] failed!'\n            to = 'admin@mydomain.tld'\n        }\n        eventlog @{\n            eventid = 1\n            eventtype = 'error'\n        }\n        eventlog @{\n            eventid = 100\n            eventtype = 'information'\n        } -when 'onsuccess'\n        logfile '\\\\fileserver01.mydomain.tld\\monitoringshare\\#{computername}.log'\n        powershell {\n            Write-Host \"Something bad happended! $args[0]\"\n        }\n        powershell '\\notifier.ps1'\n        slack @{\n            Token = '\u003cwebhookurl\u003e'\n            Channel = '#Watchmen'\n            AuthorName = $env:COMPUTERNAME\n            PreText = 'Everything is on :fire:'\n            IconEmoji = ':fire:'\n        }\n        syslog 'syslog.mydomain.tld' -when 'always'\n    }\n}\n\n# Execute the 'Storage.Capacity' tests in version 1.0.0 of the 'MyAppOVF' module\nWatchmenTest 'MyAppOVF' {\n    version 1.0.0                   # Execute tests from a specific version of the module. Default is latest \n    testType 'Simple'               # Valid values 'simple', 'comprehensive', 'all'. Default is 'all'\n    test 'Storage.Capacity'         # Name of test to execute. Default is '*'\n    fromSource 'PSGallery'          # Name of PowerShell repository to install module from if not found on system.\n    parameters {                    # Parameters that are passed into the Pester script to change the behaviour of the test.\n        FreeSystemDriveThreshold = 40000\n    }\n    notifies {                      # Notifiers to execute for this test in addition to ones defined in 'WatchmenOptions'\n        logfile '\\\\fileserver01.mydomain.tld\\monitoringshare\\#{computername}.log' -when 'always'\n    }\n}\n\n# Execute all tests in the SystemOVF module and install module from the 'PSPrivateGallery' repository if not installed on the system.\n# Global notifiers will be executed upon any failing tests.\nWatchmenTest 'SystemOVF' {\n    fromSource 'PSPrivateGallery'\n}\n```\n\n## Using Watchmen\nA Watchmen file is a PowerShell script that can be read by calling **Get-WatchmenTest**. The object(s) returned represent the OVF tests to execute\nand the associated notifiers to call upon any failing tests. Running **Invoke-WatchmenTest** will execute the tests and call any notifiers as\nappropriate.\n\nGetting watchmen tests\n```powershell\n$tests = Get-WatchmenTest -Path '.\\myapp.watchmen.ps1'\n```\n\nExecuting watchmen tests\n```powershell\n$tests | Invoke-WatchmenTest -Verbose -IncludePesterOutput\n```\n","funding_links":["https://github.com/sponsors/devblackops","https://patreon.com/devblackops"],"categories":["PowerShell"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevblackops%2Fwatchmen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdevblackops%2Fwatchmen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevblackops%2Fwatchmen/lists"}