Skip to content

Commit 0d172f7

Browse files
johljujohlju
authored
Add new common test helper functions (#90)
- Updated cmdlet documentation in README.md. - Added test helper functions `Get-InvalidResultRecord` and `Get-InvalidOperationRecord`. - Added alias `Get-ObjectNotFoundRecord` that points to `Get-InvalidResultRecord`.
1 parent aa7b2cb commit 0d172f7

9 files changed

Lines changed: 724 additions & 0 deletions

‎CHANGELOG.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
77

88
## [Unreleased]
99

10+
### Added
11+
12+
- Added test helper functions `Get-InvalidResultRecord` and `Get-InvalidOperationRecord`.
13+
- Added alias `Get-ObjectNotFoundRecord` that points to `Get-InvalidResultRecord`.
14+
1015
## [0.14.3] - 2021-01-13
1116

1217
### Fixed
@@ -20,6 +25,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
2025

2126
- Now the path separators are handled correctly in the filter functions
2227
`WhereModuleFileNotExcluded` and `WhereSourceFileNotExcluded`.
28+
- Updated cmdlet documentation in README.md.
2329

2430
## [0.14.1] - 2020-11-12
2531

‎README.md‎

Lines changed: 353 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,3 +59,356 @@ PS C:\src\DscResource.Test> build.ps1 -ResolveDependency
5959
# this will first bootstrap the environment by downloading dependencies required
6060
# then run the '.' task workflow as defined in build.yml
6161
```
62+
63+
## Cmdlets
64+
<!-- markdownlint-disable MD036 - Emphasis used instead of a heading -->
65+
66+
Refer to the comment-based help for more information about these helper
67+
functions.
68+
69+
### `Clear-DscLcmConfiguration`
70+
71+
Clear the DSC LCM by performing the following functions:
72+
73+
1. Cancel any currently executing DSC LCM operations
74+
1. Remove any DSC configurations that:
75+
- are currently applied
76+
- are pending application
77+
- have been previously applied
78+
79+
The purpose of this function is to ensure the DSC LCM is in a known
80+
and idle state before an integration test is performed that will
81+
apply a configuration.
82+
83+
This is to prevent an integration test from being performed but failing
84+
because the DSC LCM is applying a previous configuration.
85+
86+
This function should be called after each Describe block in an integration
87+
test to ensure the DSC LCM is reset before another test DSC configuration
88+
is applied.
89+
90+
#### Syntax
91+
92+
<!-- markdownlint-disable MD013 - Line length -->
93+
```plaintext
94+
Clear-DscLcmConfiguration [<CommonParameters>]
95+
```
96+
<!-- markdownlint-enable MD013 - Line length -->
97+
98+
#### Outputs
99+
100+
None.
101+
102+
#### Example
103+
104+
```powershell
105+
Clear-DscLcmConfiguration
106+
```
107+
108+
This command will Stop the DSC LCM and clear out any DSC configurations.
109+
110+
### `Get-InvalidOperationRecord`
111+
112+
Returns an invalid operation exception object.
113+
114+
#### Syntax
115+
116+
<!-- markdownlint-disable MD013 - Line length -->
117+
```plaintext
118+
Get-InvalidOperationRecord [-Message] <string> [[-ErrorRecord] <ErrorRecord>] [<CommonParameters>]
119+
```
120+
<!-- markdownlint-enable MD013 - Line length -->
121+
122+
#### Outputs
123+
124+
**System.Object**
125+
126+
#### Example
127+
128+
```powershell
129+
$mockErrorRecord = Get-InvalidOperationRecord -Message (
130+
$script:localizedData.FailedToRename -f $name
131+
)
132+
```
133+
134+
This will return an error record with the localized string as the exception
135+
message.
136+
137+
```powershell
138+
try
139+
{
140+
# Something that tries an operation.
141+
}
142+
catch
143+
{
144+
$mockErrorRecord = Get-InvalidOperationRecord -ErrorRecord $_ -Message (
145+
$script:localizedData.FailedToRename -f $name
146+
)
147+
}
148+
```
149+
150+
This will return an error record. The exception message will be concatenated
151+
to include both the localized string and all the inner exceptions messages
152+
from error record that was passed from the `catch`-block.
153+
154+
### `Get-InvalidResultRecord`
155+
156+
Returns an invalid result exception object.
157+
158+
#### Syntax
159+
160+
<!-- markdownlint-disable MD013 - Line length -->
161+
```plaintext
162+
Get-InvalidResultRecord [-Message] <string> [[-ErrorRecord] <ErrorRecord>] [<CommonParameters>]
163+
```
164+
<!-- markdownlint-enable MD013 - Line length -->
165+
166+
#### Aliases
167+
168+
`Get-ObjectNotFound`
169+
170+
#### Outputs
171+
172+
**System.Object**
173+
174+
#### Example
175+
176+
```powershell
177+
$mockErrorRecord = Get-InvalidResultRecord -Message (
178+
$script:localizedData.FailedToGetAllFromName -f $name
179+
)
180+
```
181+
182+
This will return an error record with the localized string as the exception
183+
message.
184+
185+
```powershell
186+
try
187+
{
188+
# Something that tries to return an expected result.
189+
}
190+
catch
191+
{
192+
$mockErrorRecord = Get-InvalidResultRecord -ErrorRecord $_ -Message (
193+
$script:localizedData.FailedToGetAllFromName -f $name
194+
)
195+
}
196+
```
197+
198+
This will return an error record. The exception message will be concatenated
199+
to include both the localized string and all the inner exceptions messages
200+
from error record that was passed from the `catch`-block.
201+
202+
### `Initialize-TestEnvironment`
203+
204+
Initializes an environment for running unit or integration tests
205+
on a DSC resource.
206+
207+
This includes:
208+
209+
1. Updates the $env:PSModulePath to ensure the correct module is tested.
210+
1. Imports the module to test.
211+
1. Sets the PowerShell ExecutionMode to Unrestricted.
212+
1. returns a test environment object to store the settings.
213+
214+
The above changes are reverted by calling the Restore-TestEnvironment
215+
function with the returned object.
216+
217+
Returns a test environment object which must be passed to the
218+
Restore-TestEnvironment function to allow it to restore the system
219+
back to the original state.
220+
221+
#### Syntax
222+
223+
<!-- markdownlint-disable MD013 - Line length -->
224+
```plaintext
225+
Initialize-TestEnvironment [-Module] <string> [-DscResourceName] <string>
226+
[-TestType] {Unit | Integration | All} [[-ResourceType] {Mof | Class}]
227+
[[-ProcessExecutionPolicy] {AllSigned | Bypass | RemoteSigned | Unrestricted}]
228+
[[-MachineExecutionPolicy] {AllSigned | Bypass | RemoteSigned | Unrestricted}]
229+
[<CommonParameters>]
230+
```
231+
<!-- markdownlint-enable MD013 - Line length -->
232+
233+
#### Outputs
234+
235+
**System.Collections.Hashtable**
236+
237+
#### Example
238+
239+
```powershell
240+
$script:testEnvironment = Initialize-TestEnvironment `
241+
-DSCModuleName 'NetworkingDsc' `
242+
-DSCResourceName 'DSC_Firewall' `
243+
-ResourceType 'Mof' `
244+
-TestType 'Unit'
245+
```
246+
247+
This command will initialize the test environment for Unit testing
248+
the DSC_Firewall MOF-based DSC resource in the NetworkingDsc DSC resource
249+
module.
250+
251+
```powershell
252+
$script:testEnvironment = Initialize-TestEnvironment `
253+
-DSCModuleName 'NetworkingDsc' `
254+
-DSCResourceName 'DSC_Firewall' `
255+
-ResourceType 'Class' `
256+
-TestType 'Unit'
257+
```
258+
259+
This command will initialize the test environment for Unit testing
260+
the DSC_Firewall Class-based DSC resource in the NetworkingDsc DSC resource'
261+
module.
262+
263+
```powershell
264+
$script:testEnvironment = Initialize-TestEnvironment `
265+
-DSCModuleName 'NetworkingDsc' `
266+
-DSCResourceName 'DSC_Firewall' `
267+
-ResourceType 'Class' `
268+
-TestType 'Integration'
269+
```
270+
271+
This command will initialize the test environment for Integration testing
272+
the DSC_Firewall DSC resource in the NetworkingDsc DSC resource module.
273+
274+
### `Invoke-DscResourceTest`
275+
276+
Wrapper for Invoke-Pester. It is used primarily by the pipeline and can
277+
be used to run test by providing a project path, module specification,
278+
by module name, or path.
279+
280+
#### Syntax
281+
282+
<!-- markdownlint-disable MD013 - Line length -->
283+
```plaintext
284+
Invoke-DscResourceTest [[-ProjectPath] <string>] [[-Path] <Object[]>] [[-TestName] <string[]>]
285+
[[-EnableExit]] [[-TagFilter] <string[]>] [-ExcludeTagFilter <string[]>] [-ExcludeModuleFile <string[]>]
286+
[-ExcludeSourceFile <string[]>] [-PassThru] [-CodeCoverage <Object[]>] [-CodeCoverageOutputFile <string>]
287+
[-CodeCoverageOutputFileFormat {JaCoCo}] [-Strict] [-Output <string>] [-OutputFile <string>]
288+
[-OutputFormat {NUnitXml | JUnitXml}] [-Quiet] [-PesterOption <Object>]
289+
[-Show {None | Default | Passed | Failed | Pending | Skipped | Inconclusive | Describe | Context | Summary | Header | Fails | All}]
290+
[-Settings <hashtable>] [-MainGitBranch <string>] [<CommonParameters>]
291+
292+
Invoke-DscResourceTest [[-Module] <string>] [[-Path] <Object[]>] [[-TestName] <string[]>]
293+
[[-EnableExit]] [[-TagFilter] <string[]>] [-ExcludeTagFilter <string[]>] [-ExcludeModuleFile <string[]>]
294+
[-ExcludeSourceFile <string[]>] [-PassThru] [-CodeCoverage <Object[]>] [-CodeCoverageOutputFile <string>]
295+
[-CodeCoverageOutputFileFormat {JaCoCo}] [-Strict] [-Output <string>] [-OutputFile <string>]
296+
[-OutputFormat {NUnitXml | JUnitXml}] [-Quiet] [-PesterOption <Object>]
297+
[-Show {None | Default | Passed | Failed | Pending | Skipped | Inconclusive | Describe | Context | Summary | Header | Fails | All}]
298+
[-Settings <hashtable>] [-MainGitBranch <string>] [<CommonParameters>]
299+
300+
Invoke-DscResourceTest [[-FullyQualifiedModule] <ModuleSpecification>] [[-Path] <Object[]>]
301+
[[-TestName] <string[]>] [[-EnableExit]] [[-TagFilter] <string[]>] [-ExcludeTagFilter <string[]>]
302+
[-ExcludeModuleFile <string[]>] [-ExcludeSourceFile <string[]>] [-PassThru] [-CodeCoverage <Object[]>]
303+
[-CodeCoverageOutputFile <string>] [-CodeCoverageOutputFileFormat {JaCoCo}] [-Strict] [-Output <string>]
304+
[-OutputFile <string>] [-OutputFormat {NUnitXml | JUnitXml}] [-Quiet] [-PesterOption <Object>]
305+
[-Show {None | Default | Passed | Failed | Pending | Skipped | Inconclusive | Describe | Context | Summary | Header | Fails | All}]
306+
[-Settings <hashtable>] [-MainGitBranch <string>] [<CommonParameters>]
307+
```
308+
<!-- markdownlint-enable MD013 - Line length -->
309+
310+
#### Outputs
311+
312+
**System.Object**
313+
314+
#### Example
315+
316+
None.
317+
318+
### `New-DscSelfSignedCertificate`
319+
320+
This command will create a new self-signed certificate to be used to
321+
compile configurations.
322+
323+
#### Syntax
324+
325+
<!-- markdownlint-disable MD013 - Line length -->
326+
```plaintext
327+
New-DscSelfSignedCertificate [<CommonParameters>]
328+
```
329+
<!-- markdownlint-enable MD013 - Line length -->
330+
331+
#### Outputs
332+
333+
Returns the created certificate. Writes the path to the public
334+
certificate in the machine environment variable $env:DscPublicCertificatePath,
335+
and the certificate thumbprint in the machine environment variable
336+
$env:DscCertificateThumbprint.
337+
338+
#### Example
339+
340+
```powershell
341+
$certificate = New-DscSelfSignedCertificate
342+
```
343+
344+
This command will create and return a new self-signed certificate to be
345+
used to compile configurations. The command will write the path to the
346+
public certificate in the machine environment variable `$env:DscPublicCertificatePath`,
347+
and the certificate thumbprint in the machine environment variable
348+
`$env:DscCertificateThumbprint`.
349+
350+
If a certificate with subject 'DscEncryptionCert' already exists, that
351+
certificate will be returned instead of creating a new. The command will
352+
assume that the existing certificate was created with the same command.
353+
354+
### `Restore-TestEnvironment`
355+
356+
Restores the environment after running unit or integration tests
357+
on a DSC resource.
358+
359+
This restores the following changes made by calling
360+
Initialize-TestEnvironment:
361+
362+
1. Restores the $env:PSModulePath if it was changed.
363+
1. Restores the PowerShell execution policy.
364+
1. Resets the DSC LCM if running Integration tests.
365+
366+
#### Syntax
367+
368+
<!-- markdownlint-disable MD013 - Line length -->
369+
```plaintext
370+
Restore-TestEnvironment [-TestEnvironment] <hashtable> [<CommonParameters>]
371+
```
372+
<!-- markdownlint-enable MD013 - Line length -->
373+
374+
#### Outputs
375+
376+
None.
377+
378+
#### Example
379+
380+
```powershell
381+
Restore-TestEnvironment -TestEnvironment $script:testEnvironment
382+
```
383+
384+
This will restore the test environment and use the values that is provided
385+
in the hashtable passed to the command. The hasttable that is passed should
386+
have been created by `Initialize-TestEnvironment`.
387+
388+
### `Wait-ForIdleLcm`
389+
390+
Waits for LCM to become idle and optionally clears the LCM by running
391+
`Clear-DscLcmConfiguration`.
392+
393+
It is meant to be used in integration test where integration tests run to
394+
quickly before LCM have time to cool down.
395+
396+
#### Syntax
397+
398+
<!-- markdownlint-disable MD013 - Line length -->
399+
```plaintext
400+
Wait-ForIdleLcm [-Clear] [<CommonParameters>]
401+
```
402+
<!-- markdownlint-enable MD013 - Line length -->
403+
404+
#### Outputs
405+
406+
None.
407+
408+
#### Example
409+
410+
```powershell
411+
Wait-ForIdleLcm -Clear
412+
```
413+
414+
This will wait for the LCM to become idle and then clear the LCM.

‎source/Public/Clear-DscLcmConfiguration.ps1‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@
1717
This function should be called after each Describe block in an integration
1818
test to ensure the DSC LCM is reset before another test DSC configuration
1919
is applied.
20+
2021
.EXAMPLE
2122
Clear-DscLcmConfiguration
2223

0 commit comments

Comments
 (0)