This is just some quick tips and suggestions for creating Pester tests for this project.
The Pester community is vibrant and active, if you have questions about Pester or creating tests, the [Pester Wiki](https://github.com/pester/pester/wiki) has a lot of great information.
As of January 2018, PowerShell Core is using Pester version 4 which has some changes from earlier versions.
See [Migrating from Pester 3 to Pester 4](https://github.com/pester/Pester/wiki/Migrating-from-Pester-3-to-Pester-4) for more information.
For creation of PowerShell tests, the `Describe` block is the level of granularity suggested and one of three tags should be used: `CI`, `Feature`, or `Scenario`.
Provides logical grouping of `It` blocks within a single `Describe` block. Any `Mocks` defined inside a `Context` are removed at the end of the `Context` scope, as are any files or folders added to the `TestDrive` during the `Context` block's execution.
The `It` block is intended to be used inside of a `Describe` or `Context` block. If you are familiar with the AAA pattern (Arrange-Act-Assert), the body of the `It` block is the appropriate location for an assert.
The convention is to assert a single expectation for each `It` block. The code inside of the `It` block should throw a terminating error if the expectation of the test is not met and thus cause the test to fail.
The name of the `It` block should expressively state the expectation of the test.
A `PSDrive` is available for file activity during a test and this drive is limited to the scope of a single `Describe` block. The contents of the drive are cleared when a `Context` block is exited.
A test may need to work with file operations and validate certain types of file activities. It is usually desirable not to perform file activity tests that will produce side effects outside of an individual test.
Pester creates a `PSDrive` inside the user's temporary drive that is accessible via `TestDrive:` or `$TestDrive`. **Pester will remove** this drive after the test completes.
You may use this drive to isolate the file operations of your test to a temporary store.
Mocks the behavior of an existing command with an alternate implementation. This creates new behavior for any existing command within the scope of a `Describe` or `Context` block.
The function allows you to specify a script block that will become the command's new behavior.
Code execution in Pester can be very subtle and can cause issues when executing test code. The execution of code which lays outside of the usual code blocks may not happen as you expect. Consider the following:
The `Describe` - `BeforeAll` block is executed before any other code even though it was at the bottom of the `Describe` block.
So if some state is set elsewhere in the `Describe` block, that state will not yet be visible (as the code will not yet been run).
Notice, too, that the `BeforeAll` block in `Context` is executed before any other code in that block.
Generally, you should have code reside in one of the code block elements of `BeforeAll`, `BeforeEach`, `AfterEach` and/or `AfterAll`, especially if those blocks rely on some state set by free code elsewhere in the block.
### Skipping Tests in Bulk
Sometimes it is beneficial to skip all the tests in a particular `Describe` block.
For example, tests which are not applicable to a platform could be skipped, and they would be reported as skipped.
This technique uses the `$PSDefaultParameterValues` feature of PowerShell to temporarily set the `It` block parameter `-skip` to true (or in the case of Windows, it is not set at all)
- Tag `CI` indicates that it will be run as part of the continuous integration process. These should be unit test like, and generally take less than a second.
- Tag `Feature` indicates a higher level feature test (we will run these on a regular basis), for example, tests which go to remote resources, or test broader functionality.
- Tag `Scenario` indicates tests of integration with other features (these will be run on a less regular basis and test even broader functionality than feature tests.
4. Make sure that `Describe`/`Context`/`It` descriptions are useful.
- The error message should not be the place where you describe the test.
5. Use `Context` to group tests.
- Multiple `Context` blocks can help you group your test suite into logical sections.
6. Use `BeforeAll`/`BeforeEach`/`AfterEach`/`AfterAll` instead of custom initiators.
7. Use `Should -Throw -ErrorId` to check for expected errors.
8. Use `-TestCases` when iterating over multiple `It` blocks.
9. Use code coverage functionality where appropriate.
10. Use `Mock` functionality when you don't have your entire environment.
11. Avoid free code in a `Describe` block.
- Use `BeforeAll`/`BeforeEach`/`AfterEach`/`AfterAll`.
- See [Free Code in a Describe block](WritingPesterTests.md#free-code-in-a-describe-block)
12. Avoid creating or using test files outside of `TESTDRIVE:`.
-`TESTDRIVE:` has automatic clean-up.
13. Keep in mind that we are creating cross platform tests.
- Avoid using the registry.
- Avoid using COM.
14. Avoid being too specific about the _count_ of a resource as these can change platform to platform.
- Example: Avoid checking for the count of loaded format files, but rather check for format data for a specific type.
### Don't
1. Don't have too many evaluations in a single `It` block.
- The first `Should` failure will stop that block.
2. Don't use `Should` outside of an `It` Block.
3. Don't use the word "Error" or "Fail" to test a positive case.
- Example: Rephrase the negative sentence `"Get-ChildItem TESTDRIVE: shouldn't fail"` to the following positive case `"Get-ChildItem should be able to retrieve file listing from TESTDRIVE"`.