Define and provide a harness for testable DSC Resource examples

[michaeltlombardi]

As an engineer writing and maintaining class-based DSC Resources, I want to be able to write examples of using my DSC Resources which can double as minimal acceptance tests and end-user facing documentation to ensure that users get the best experience and safety from my DSC Resources.

An example workflow for this might look like defining a script in the Examples folder of my repository which has one or more calls to Invoke-DscResource and uses comment-based help in the script file. When a PR is made against the repository, a matrix is spun up, one per script file and supported operating system, and verifies:

• that the script runs once in Get mode to retrieve current state, ensuring it matches expectations
• that the script runs once in test mode to compare current state to desired, ensuring it matches expectations
• that the script runs twice in Set mode, first ensuring it changes state as expected and the second time to ensure it does nothing
• That the script runs a final time in Test mode, ensuring it reports that the resource is in the desired state

Advanced considerations about spin-up/down/reset/rerun of the harness are opportunities for further improvement but secondary to the primary usefulness of having testable examples as documentation.