Skip to content

Commit caf1fd4

Browse files
justin-pjustin-p
committed
Updated documentation
1 parent 94eddd0 commit caf1fd4

5 files changed

Lines changed: 79 additions & 5 deletions

File tree

‎Readme.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ This build framework for PowerShell modules comes with several appealing baked i
3333
- Automatically scan your module release with PSScriptAnalyzer
3434
- Automatically upload your script to the PowerShell Gallery (with appropriate API key)
3535
- Automatically create project documentation folder structure and yml definition file for ReadTheDocs.org integration
36+
- Automatically start Pester tests during build process
3637
- Visual Studio Code integration (tasks)
3738
- Easy to manage build configuration with forward compatible design and easy to use commands
3839
- Includes ability to scan for sensitive terms (like your company domain name or other items that you may not want published)

‎docs/Introduction/Introduction.md‎

Lines changed: 15 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
## Introduction
2+
23
This is a scaffolding framework which can be used to kickstart a generic PowerShell module project. It includes the base files and scripts required to perform regular build releases, uploading to the powershell gallery, and other such fun. All the hard work is done with the excellent invoke-build project engine, a rather large set of build tasks for it, and a custom Plaster template.
34

45
The general idea of the base module is that you will develop and test without having to worry about keeping your manifest file up to date with your public functions. When you finally build the module, then the functions are explicitly injected into the manifest file and the source files are all (optionally) combined into one psm1 for distribution.
@@ -22,7 +23,9 @@ Aside from the handful of helper functions there is an included 'plaster' folder
2223
The scaffolding itself is mostly a big invoke-build script and does not need the ModuleBuild loaded to perform build tasks.
2324

2425
## Folder Structure
25-
A default ModuleBuild project scaffold will look like the following for a project named 'ModuleName' with build version 0.0.1 sucessfully built.
26+
27+
A default ModuleBuild project scaffold will look like the following for a project named 'ModuleName' with build version 0.0.1 successfully built.
28+
2629
```
2730
ProjectRootFolder
2831
- .vscode
@@ -56,9 +59,10 @@ ProjectRootFolder
5659
ModuleName-0.0.1.zip
5760
ModuleName-current.zip
5861
- build
59-
- startup
60-
- shutdown
61-
- dotsource
62+
- cleanup
63+
- dependencies
64+
- PSDepend
65+
build.depend.psd1
6266
- docs
6367
- Additional
6468
Acknowledgements.md
@@ -71,9 +75,16 @@ ProjectRootFolder
7175
index.md
7276
- EN-us
7377
about_ModuleName.help.txt
78+
- reports
79+
- startup
7480
ModuleName.buildenvironment.json
7581
ModuleName.buildenvironment.ps1
7682
- tests
83+
- intergration
84+
- Meta
85+
- Meta.tests.ps1
86+
- MetaFixers.psm1
87+
- Unit
7788
.gitattributes
7889
.gitignore
7990
Build.ps1

‎docs/Usage/12 - Writing Pester tests.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Writing Pester tests with ModuleBuild
2+
3+
We wont go deep into how to write pester tests, just how they are integrated into ModuleBuild.
4+
5+
ModuleBuild sorts Pester tests in 3 flavours. Meta, Unit and Intergration tests.
6+
7+
- Meta are very basics tests such as file encoding or Tabs vs Spaces
8+
- Unit testing is a type of testing to check if the small piece of code is doing what it is suppose to do
9+
- Integration testing is a type of testing to check if different pieces of the modules are working together
10+
11+
You will most likely only write Unit tests for your powershell module.
12+
13+
## Matching the folder structure
14+
15+
When writing tests you are expected to match the folder structure of the src folder.
16+
For example, if you want to unit test `src\public\Write-SomeTestModule.ps1` you are expected to create the following test file at `tests\unit\public\Write-SomeTestModule.Tests.ps1`.
17+
18+
The `tests\unit\public\Write-SomeTestModule.Tests.ps1` would look something like this.
19+
The first 8 lines do some 'magic' to replace the path of the current file and match it to the correct source file.
20+
21+
```powershell
22+
#Requires -Modules Pester
23+
$here = Split-Path -Parent $MyInvocation.MyCommand.Path
24+
$sut = (Split-Path -Leaf $MyInvocation.MyCommand.Path) -replace '\.Tests\.', '.'
25+
26+
# Since we match the srs/tests stucture we can use this to dotsource the function.
27+
$here = $here -replace 'tests\\unit', 'src'
28+
29+
. "$here\$sut"
30+
31+
Describe "Testing Write-SomeTestModule" -Tags @('UnitTest') {
32+
it "Should return a specific string: (Yerp. This is a function.)" {
33+
$result = Write-SomeTestModule
34+
$result | Should -Be "Yerp. This is a function."
35+
}
36+
}
37+
```
38+
39+
## Tagging your tests
40+
41+
To support different kind of tests ModuleBuild uses Tags in the pester files. These are specified in `Describe` as following:
42+
43+
```powershell
44+
Describe "Testing Write-SomeTestModule" -Tags @('UnitTest') {
45+
...
46+
}
47+
```
48+
49+
During the build process pester is started multiple times and told to run tests with tag X. This ensure only specific type of tests are ran when we want them to.
50+
51+
Possible tags:
52+
53+
- UnitTest
54+
- MetaTest
55+
- IntergrationTest

‎docs/Usage/4 - Test A Release.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,11 @@
11
# Step 4 - Test a Release
2-
You may get a build to complete without errors but that doesn't mean that the module will behave as expected. You can do a quick module install and load test if you like:
2+
3+
You may get a build to complete without errors but that doesn't mean that the module will behave as expected. ModuleBuild includes a couple of simple Pester tests.
4+
You can run these with the following command:
5+
6+
`.\Build.ps1 -Test`
7+
8+
If this tests works you can do a quick module install and load test if you like:
39

410
`.\Build.ps1 -InstallAndTestModule`
511

‎docs/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ This build framework for PowerShell modules comes with several appealing baked i
1919
- Automatically upload your script to the PowerShell Gallery (with appropriate API key)
2020
- Automatically create project documentation folder structure and yml definition file for ReadTheDocs.org integration
2121
- Automatically generate module documentation with PlatyPS
22+
- Automatically start Pester tests during build process
2223
- Visual Studio Code integration (tasks)
2324
- Easy to manage build configuration with forward compatible design and easy to use commands
2425
- Includes ability to scan for sensitive terms (like your company domain name or other items that you may not want published)

0 commit comments

Comments
 (0)