{"id":1441,"date":"2014-11-18T12:17:00","date_gmt":"2014-11-18T12:17:00","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/powershell\/2014\/11\/18\/powershell-dsc-resource-design-and-testing-checklist\/"},"modified":"2019-02-18T13:05:11","modified_gmt":"2019-02-18T20:05:11","slug":"powershell-dsc-resource-design-and-testing-checklist","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/powershell\/powershell-dsc-resource-design-and-testing-checklist\/","title":{"rendered":"PowerShell DSC Resource Design and Testing Checklist"},"content":{"rendered":"\n
\n

DSC Resource Design and Testing Checklist<\/p>\n

 <\/p>\n

Writing Desired State Configuration Resources is not trivial and there\u2019s many things which can go wrong. You should always spend significant amount of time testing resources you create. This task, although critical for quality, is often overlooked or performed carelessly and insufficiently. Below you can find DSC Resource Design and Testing Checklist<\/b> which will help you design the resource and identify critical areas for testing. Follow it the next time you want to verify quality of your resource and check whether it adheres to DSC best practices. <\/p>\n

 <\/p>\n

1       <\/span>Resource module contains .psd1 file and schema.mof for every resource   <\/span>1<\/span><\/a><\/p>\n

2       <\/span>Resource and schema are correct and have been verified using DscResourceDesigner cmdlets  <\/span>1<\/span><\/a><\/p>\n

3       <\/span>Resource loads without errors  <\/span>1<\/span><\/a><\/p>\n

4       <\/span>Resource is idempotent in the positive case   <\/span>1<\/span><\/a><\/p>\n

5       <\/span>User modification scenario was tested   <\/span>1<\/span><\/a><\/p>\n

6       <\/span>Get-TargetResource functionality was verified using Get-DscConfiguration   <\/span>1<\/span><\/a><\/p>\n

7       <\/span>Resource was verified by calling Get\/Set\/Test-TargetResource functions directly  <\/span>1<\/span><\/a><\/p>\n

8       <\/span>Resource was verified End to End using Start-DscConfiguration   <\/span>1<\/span><\/a><\/p>\n

9       <\/span>Resource behaves correctly on all DSC supported platforms (or returns a specific error otherwise)  <\/span>1<\/span><\/a><\/p>\n

10     <\/span>Resource functionality was verified on Windows Client (if applicable)  <\/span>1<\/span><\/a><\/p>\n

11     <\/span>Get-DSCResource lists the resource   <\/span>1<\/span><\/a><\/p>\n

12     <\/span>Resource module contains examples  <\/span>1<\/span><\/a><\/p>\n

13     <\/span>Error messages are easy to understand and help users solve problems  <\/span>1<\/span><\/a><\/p>\n

14     <\/span>Log messages are easy to understand and informative (including \u2013verbose, \u2013debug and ETW logs)  <\/span>1<\/span><\/a><\/p>\n

15     <\/span>Resource implementation does not contain hardcoded paths  <\/span>1<\/span><\/a><\/p>\n

16     <\/span>Resource implementation does not contain user information   <\/span>1<\/span><\/a><\/p>\n

17     <\/span>Resource was tested with valid\/invalid credentials  <\/span>1<\/span><\/a><\/p>\n

18     <\/span>Resource is not using cmdlets requiring interactive input  <\/span>1<\/span><\/a><\/p>\n

19     <\/span>Resource functionality was thoroughly tested   <\/span>1<\/span><\/a><\/p>\n

20     <\/span>Best practice: Resource module contains Tests folder with ResourceDesignerTests.ps1 script  <\/span>1<\/span><\/a><\/p>\n

21     <\/span>Best practice: Resource folder contains resource designer script for generating schema  <\/span>1<\/span><\/a><\/p>\n

22     <\/span>Best practice: Resource supports -whatif  <\/span>1<\/span><\/a><\/p>\n

 <\/p>\n

1         <\/span>Resource module contains .psd1 file and schema.mof for every resource<\/a> <\/h2>\n

The first think you should do is to check that your resource has correct structure and contains all required files. Every resource module should contain a .psd1 file and every non-composite resource should have schema.mof file. Resources that do not contain schema will not be listed by Get-DscResource and users will not be able to use the intellisense when writing code against those modules in ISE. <\/p>\n

The sample directory structure for xRemoteFile resource, which is part of the xPSDesiredStateConfiguration resource module, could look as follows:<\/p>\n

 <\/p>\n

xPSDesiredStateConfiguration<\/p>\n

                DSCResources<\/p>\n

                                MSFT_xRemoteFile<\/p>\n

                                                MSFT_xRemoteFile.psm1<\/p>\n

                                                MSFT_xRemoteFile.schema.mof<\/p>\n

                Examples<\/p>\n

                                xRemoteFile_DownloadFile.ps1<\/p>\n

                ResourceDesignerScripts<\/p>\n

                                GenerateXRemoteFileSchema.ps1<\/p>\n

                Tests<\/p>\n

                                ResourceDesignerTests.ps1<\/p>\n

                xPSDesiredStateConfiguration.psd1<\/p>\n

 <\/p>\n

If you don\u2019t quite understand what every single item on this list is for, keep reading \u2013 I\u2019ll explain it in the sections below. <\/p>\n

2         <\/span>Resource and schema are correct and have been verified using DscResourceDesigner cmdlets<\/a><\/h2>\n

Another important aspect is verifying the resource schema (*.schema.mof) file. <\/p>\n

Make sure that:<\/p>\n

–          <\/span>Property types are correct (e.g. don\u2019t use String for properties which accept numeric values, you should use UInt32 or other numeric types instead)<\/p>\n

–          <\/span>Property attributes are specified correctly ([key], [required], [write], [read])<\/p>\n

o   <\/span><\/span>At least one parameter in the schema has to be marked as [key]<\/p>\n

o   <\/span><\/span>[read] property cannot coexist together with any of: [required], [key], [write]<\/p>\n

o   <\/span><\/span>If multiple qualifiers are specified except [read], then [key] takes precedence<\/p>\n

o   <\/span><\/span>If [write] and [required] are specified, then [required] takes precedence<\/p>\n

–          <\/span>ValueMap is specified where appropriate<\/p>\n

 <\/p>\n

Example:<\/p>\n

[Read, ValueMap{"Present", "Absent"}, Values{"Present", "Absent"}, Description("Says whether DestinationPath exists on the machine")] String Ensure;<\/span><\/p>\n

 <\/p>\n

–          <\/span>Friendly name is specified and confirms to DSC naming conventions<\/p>\n

 <\/p>\n

Example: <\/p>\n

[ClassVersion("1.0.0.0"), FriendlyName("xRemoteFile")]<\/span><\/p>\n

 <\/p>\n

–          <\/span>Every field has meaningful description<\/p>\n

Below you can find a good example of the resource schema file (this is the actual schema of xRemoteFile resource from the DSC Resource Kit<\/a>)<\/p>\n

 <\/p>\n

[ClassVersion("1.0.0.0"), FriendlyName("xRemoteFile")]<\/span><\/p>\n

class MSFT_xRemoteFile : OMI_BaseResource<\/span><\/p>\n

{<\/span><\/p>\n

       [Key, Description("Path under which downloaded or copied file should be accessible after operation.")] String DestinationPath;<\/span><\/p>\n

       [Required, Description("Uri of a file which should be copied or downloaded. This parameter supports HTTP and HTTPS values.")] String Uri;<\/span><\/p>\n

       [Write, Description("User agent for the web request.")] String UserAgent;<\/span><\/p>\n

       [Write, EmbeddedInstance("MSFT_KeyValuePair"), Description("Headers of the web request.")] String Headers[];<\/span><\/p>\n

       [Write, EmbeddedInstance("MSFT_Credential"), Description("Specifies a user account that has permission to send the request.")] String Credential;<\/span><\/p>\n

       [Read, ValueMap{"Present", "Absent"}, Values{"Present", "Absent"}, Description("Says whether DestinationPath exists on the machine")] String Ensure;<\/span><\/p>\n

}; <\/span><\/p>\n

 <\/p>\n

Additionally, you should use Test-xDscResource and Test-xDscSchema cmdlets from Dsc Resource Designer<\/a> to automatically verify the resource and schema:<\/p>\n

Test-xDscResource <Resource_folder><\/p>\n

Test-xDscSchema <Path_to_resource_schema_file><\/p>\n

For example:<\/p>\n

Test-xDscResource ..\\DSCResources\\MSFT_xRemoteFile<\/p>\n

Test-xDscSchema ..\\DSCResources\\MSFT_xRemoteFile\\MSFT_xRemoteFile.schema.mof<\/p>\n

<\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a> <\/p>\n

3         <\/span>Resource loads without errors<\/a><\/h2>\n

Once you verified that resource contains all necessary files and verified them using DSC Resource Designer, it\u2019s time to check whether resource module can be successfully loaded.<\/p>\n

You can do it either manually, by running Import-Module<\/span> <<\/span>resource_module><\/span> -force <\/span><\/span>and confirming that no errors occurred, or by writing test automation. In case of the latter, you can follow this structure in your test case:<\/p>\n

$error<\/span> =<\/span> $null<\/span><\/span><\/p>\n

Import-Module<\/span> <<\/span>resource_module> <\/span>\u2013force<\/span><\/span><\/p>\n

If<\/span> ($error<\/span>.<\/span>count \u2013ne<\/span> 0<\/span>) {<\/span><\/p>\n

       Throw<\/span> \u201cModule was not imported correctly. Errors returned: <\/span>$error<\/span>\u201d<\/span><\/span><\/p>\n

}<\/span><\/p>\n

<\/a><\/a><\/a><\/a><\/a><\/a> <\/p>\n

<\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a>4         <\/span>Resource is idempotent in the positive case <\/h2>\n

One of the fundamental characteristics of every DSC resource should be idempotence. It means that we can apply a DSC configuration containing that resource multiple times without changing the result beyond the initial application. For example, if we create a configuration which contains the following File resource:<\/p>\n

File<\/span> file<\/span> {<\/span><\/p>\n

    DestinationPath<\/span> =<\/span> "C:\\test\\test.txt"<\/span><\/span><\/p>\n

    Contents<\/span> =<\/span> "Sample text"<\/span><\/span><\/p>\n

} <\/span><\/p>\n

After applying it for the first time, file test.txt should appear in C:\\test folder. However, subsequent runs of the same configuration should not change the state of the machine (e.g. no copies of the test.txt file should be created).<\/p>\n

To ensure our resource is idempotent we can repeatedly call Set-TargetResource when testing the resource directly, or call Start-DscConfiguration multiple times when doing end to end testing. The result should be the same after every run. <\/p>\n

5         <\/span>User modification scenario was tested<\/a><\/h2>\n

User modification is another common scenario worth testing out. It helps you verify that Set-TargetResource and Test-TargetResource function properly. Here are steps you should take to test it:<\/p>\n

1.       <\/span>Start with the resource not in the desired state.<\/p>\n

    \n
  1. Run configuration with your resource <\/li>\n
  2. Verify Test-DscConfiguration returns True <\/li>\n
  3. Modify the resource out of the desired state <\/li>\n
  4. Verify Test-DscConfiguration returns false <\/li>\n<\/ol>\n

    Here\u2019s a more concrete example using Registry resource:<\/p>\n

    1.       <\/span>Start with registry key not in the desired state<\/p>\n

      \n
    1. Run Start-DscConfiguration with a configuration to put it in the desired state and verify it passes. <\/li>\n
    2. Run Test-DscConfiguration and verify it returns true <\/li>\n
    3. Modify the value of the key so that it is not in the desired state <\/li>\n
    4. Run Test-DscConfiguration and verify it returns false <\/li>\n<\/ol>\n

      <\/a> <\/p>\n

      <\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a>6         <\/span>Get-TargetResource functionality was verified using Get-DscConfiguration<\/h2>\n

       <\/p>\n

      Get-TargetResource should return details of the current state of the resource. Make sure you test it by calling Get-DscConfiguration after you apply the configuration and verifying that output correctly reflects the current state of the machine. It’s important to test it separately, since any issues in this area won’t appear when calling Start-DscConfiguration.<\/p>\n

       <\/p>\n

      <\/a><\/a>7         <\/span>Resource was verified by calling Get\/Set\/Test-TargetResource functions directly<\/h2>\n

       <\/p>\n

      Make sure you test the Get\/Set\/Test-TargetResource functions implemented in your resource by calling them directly and verifying that they work as expected.<\/p>\n

      8         <\/span>Resource was verified End to End using Start-DscConfiguration<\/a><\/h2>\n

       <\/p>\n

      Testing Get\/Set\/Test-TargetResource functions by calling them directly is important, but not all issues will be discovered this way. You should focus significant part of your testing on using Start-DscConfiguration or the pull server. In fact, this is how users will use the resource, so don\u2019t underestimate the significance of this type of tests. <\/p>\n

      Possible types of issues:<\/p>\n

      –          <\/span>Credential\/Session may behave differently because the DSC agent runs as a service.  Be sure to test any features here end to end.<\/p>\n

      –          <\/span>Verify error messages displayed by the resource make sense. For example, errors outputted by Start-DscConfiguration may be different than those displayed when calling the Set-TargetResource function directly.<\/p>\n

      9         <\/span>Resource behaves correctly on all DSC supported platforms (or returns a specific error otherwise)<\/a><\/h2>\n

      Resource should work on all DSC supported platforms (Windows Server 2008 R2 and newer). Make sure you install latest WMF (Windows Management Framework) on your OS to get the latest version of DSC. If resource by-design does not work on some of these platforms, a specific error message should be returned. Also, make sure your resource checks whether cmdlets you are calling are present on particular machine. Windows Server 2012 added a large number of new cmdlets that are not available on Windows Server 2008R2, even with WMF installed. <\/p>\n

       <\/p>\n

      10    <\/span>Resource functionality was verified on Windows Client (if applicable)<\/a><\/h2>\n

      One very common test gap is verifying the resource only on server versions of Windows. Many resources are also designed to work on Client SKUs, so if that\u2019s true in your case, don\u2019t forget to test it on those platforms as well. <\/p>\n

      11    <\/span>Get-DSCResource lists the resource<\/a><\/h2>\n

      After deploying the module on the machine, calling Get-DscResource should list your resource among others as a result. If you can\u2019t find your resource in the list, make sure that schema.mof file for that resource exists. <\/p>\n

      <\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a><\/a>12    <\/span>Resource module contains examples<\/h2>\n

      If you intend to share the resource (which you hopefully do), creating quality examples which will help others understand how to use it. This is crucial, especially since many users treat sample code as documentation. <\/p>\n

      –          <\/span>First, you should determine the examples that will be included with the module \u2013 at minimum, you should cover most important use cases for your resource:<\/p>\n