Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .claude/rules/powershell-standards/powershell-pester.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
---
paths:
- "**/*.Tests.ps1"
- "**/Tests/**/*.ps1"
---

@../../../.github/instructions/powershell-pester.instructions.md
Expand Down
12 changes: 9 additions & 3 deletions .github/copilot-instructions.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,7 @@ These are the rules for writing and reviewing PowerShell in this repository. **M

## Topic rules

The rules below are the ones that matter in almost every file. Each topic has a file with the
complete rules, the reasons, and examples:
Each topic has a file with the complete rules, the reasons, and examples:

| When the work involves | Read |
| --- | --- |
Expand All @@ -41,6 +40,12 @@ your tooling does not, you MUST read the matching files before creating or chang

## Core rules

These are the rules that matter in almost every file. They are a selection from the topic files, and
each one keeps the ID it has there, so the numbers below are not consecutive: STY-04, for example, is
in the style file. The topic files have gaps of their own, because most of them start each section
at a new ten. A gap does not mean that a rule is missing, and a rule that is only in a topic file
counts as much as one listed here.

### Version

- **VER-01** Write for PowerShell 7.6 (LTS) unless the project declares another target. The
Expand All @@ -63,7 +68,8 @@ your tooling does not, you MUST read the matching files before creating or chang
- **STY-03** Lines SHOULD NOT exceed 115 characters. Shorten a long command with splatting, or break
the line after a pipe, comma, or operator. Backtick line continuation MUST NOT be used.
- **STY-06** Source MUST be ASCII unless a string literal needs another character: no emoji,
typographic quotes, or en and em dashes in code or comments.
typographic quotes, or en and em dashes in code or comments. Generated documentation and test
output MUST NOT contain emoji either.
- **STY-12** Name local variables in descriptive camelCase without a type prefix: `$retryCount`, not
`$RetryCount` or `$intRetryCount`.
- **STY-13** Automatic variables MUST NOT be assigned or reused as parameter, loop, or test-data
Expand Down
21 changes: 16 additions & 5 deletions .github/instructions/pester-supporting-docs/assertion-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,9 +17,11 @@ Setting `Should.DisableV5 = $true` makes every classic assertion fail with

- Each assertion does one job, so its options are its own (`Should-BeString -IgnoreWhitespace`) and
its failure message is specific: a caret under the first differing character of a string, a line
diff for a long string, the missing and extra values of a collection.
diff for a long string, the missing and extra values of a collection with the index of each.
- `-Expected` decides how the values are compared. `1 | Should-Be $true` and `'1' | Should-Be 1` both
pass, so assert the type as well when the type matters.
- `$null`, an empty collection, and a single-item array are handled by the same rules in every
assertion of a family. The table under "Pipeline Or -Actual" lists them.
- A value assertion refuses a collection as `-Expected`. `Should-Be -Expected @(1, 2)` is an error
that names `Should-BeCollection`.
- The set can be extended. See the [custom assertion guide](./custom-assertions.md).
Expand Down Expand Up @@ -72,7 +74,7 @@ the pipeline did and points to `-Actual`.
| `Should -BeGreaterOrEqual $x` | `Should-BeGreaterThanOrEqual $x` | Name changed |
| `Should -BeLessOrEqual $x` | `Should-BeLessThanOrEqual $x` | Name changed |
| `Should -Contain $item` | `Should-ContainCollection $item` | |
| `$item \| Should -BeIn $list` | `$list \| Should-ContainCollection $item` | The list is piped |
| `$item \| Should -BeIn $list` | `$list \| Should-ContainCollection $item` | The list is piped. `$list \| Should-Any { $_ -eq $item }` also works |
| `Should -HaveCount 3` | `Should-BeCollection -Count 3` | |
| `Should -Throw '*msg*'` | `Should-Throw -ExceptionMessage '*msg*'` | Both need the wildcards |
| `Should -Invoke Cmd` | `Should-Invoke Cmd` | |
Expand All @@ -92,6 +94,10 @@ $result.Items | Should-BeFalsy
`Should-BeFalsy` passes for `$null`, `''`, `0`, `$false`, and `@()`. `'' | Should-BeNull` fails, and
so does `$null | Should-BeEmptyString`.

A file that keeps the classic style keeps `Should -Exist`. Pester 6 gave it a `-LiteralPath` switch:
`$path | Should -Exist -LiteralPath` passes for a path that contains brackets, where the plain form
reads the brackets as a wildcard and fails.

## The Four Families

| Family | Examples | Use for |
Expand Down Expand Up @@ -131,9 +137,10 @@ Get-Content -LiteralPath $reportPath -Raw | Should-BeString $expected -Normalize

#### Long Strings

A failing `Should-BeString` prints a line diff in place of the caret when the strings have more than
one line and either more than 10 lines or more than 120 characters. Expected line numbers are on the
left and actual on the right:
From 6.2, a failing `Should-BeString` prints a line diff in place of the caret when the strings have
more than one line and either more than 10 lines or more than 120 characters. Pester 6.1 prints the
caret for the same strings. Expected line numbers are on the left and actual on the right, so the
output stays readable when lines were added or removed:

```text
Expected strings to be the same, but they were different.
Expand All @@ -150,6 +157,9 @@ Expected 11 line(s), actual 11 line(s).
7 7 | line 7 of the expected text
```

Only the differing lines are expanded. In them a tab or a trailing space is drawn as a visible
symbol, and the unchanged lines around them are printed as they are, not turned into escape codes.

This makes `Should-BeString` the assertion for rendered templates and generated files. `Should-Be`
on the same strings prints both in full.

Expand Down Expand Up @@ -419,6 +429,7 @@ that later lines depend on, such as a count before an index.
- Assert the narrowest fact that proves the behaviour. `Should-Be 'Active'` is better than
`Should-NotBeNull` (TST-11).
- Assert the count before reading an element by index (TST-12).
- Use `Should-HaveType` rather than asserting on `.GetType().Name` as a string (TST-13).
- Prefer one `Should-BeEquivalent -ExcludePathsNotOnExpected` to a run of property assertions, and
add index assertions when order matters.
- Assert an error by its type or error ID. A message that the code owns changes more often.
Expand Down
Loading