Document -ErrorAction soft-assertion behavior on Should-* commands#2835
Merged
Conversation
Add a NOTES section to the comment-based help of every Should-* assertion explaining that the -ErrorAction common parameter controls soft-assertion behavior: - -ErrorAction Continue records the failure and lets the rest of the test run (a soft assertion) - -ErrorAction Stop fails the test immediately (e.g. to guard a precondition) - when -ErrorAction is not specified, the behavior comes from Should.ErrorAction in the configuration (default Stop) These NOTES surface on the auto-generated Command Reference pages at pester.dev (e.g. Should-Be), addressing Part 1 of pester/docs#385. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Surfaces the per-assertion meaning of
-ErrorActionon theShould-*assertions by adding a NOTES section to their comment-based help. Today-ErrorActiononly appears in the generic common-parameters boilerplate on the auto-generated Command Reference pages, with no hint that for assertions it is the knob that controls soft-assertion behavior.Each
Should-*help now explains:-ErrorAction Continue— record the failure but keep running the test (soft assertion)-ErrorAction Stop— fail the test immediately (e.g. to guard a precondition before continuing)-ErrorActionis not specified, the behavior comes fromShould.ErrorActionin the configuration (defaultStop)The note links to the dedicated https://pester.dev/docs/assertions/soft-assertions page.
Why
This is Part 1 of pester/docs#385. Part 2 (a dedicated, searchable "Soft assertions" page) already shipped in the docs repo (pester/docs#397). Part 1 has to land here because the
Should-*Command Reference pages are auto-generated from this comment-based help — so the text change can't be made in the docs repo.Scope
.NOTESsection to the 21Should-*assertions that didn't have one, and appends the same two paragraphs to the existing.NOTESof the other 20. 41 files, additive only (no logic changes).Invoke-AssertionFailed(-ErrorAction Stop→ throw; otherwise collected; falls back toShould.ErrorAction).Verification
Get-Helpshows the new NOTES on all 41 commands.tst/Help.Tests.ps1 -Tag Helppasses: 390 passed, 0 failed, 1 skipped.