feat: make Help tests runnable standalone via build.ps1

[tablackburn]

Summary

Makes tests/Help.tests.ps1 runnable standalone (e.g. Invoke-Pester tests/Help.tests.ps1 straight from an editor, or an agent running a single test) by having its build-bootstrap guard delegate to build.ps1 — the canonical build entry point — instead of partially re-implementing the build.

Problem

When $Env:BHBuildOutput is unset, Help.tests.ps1 bootstraps the module itself. The original bootstrap called Invoke-psake against build.psake.ps1 directly, but psake's properties block needs BuildHelpers vars (BHProjectName, BHPSModuleManifest) that are normally populated by ./build.ps1 before psake runs. Running the Help tests in isolation skipped build.ps1, so those vars were empty and the standalone build path was broken.

Fix

Replace the inline Set-BuildEnvironment + Invoke-psake block in both BeforeDiscovery and BeforeAll with a single call to build.ps1:

$buildScript = Join-Path -Path (Split-Path -Path $PSScriptRoot -Parent) -ChildPath 'build.ps1'
& $buildScript -Task 'Build' -Bootstrap

• Delegates to the canonical entry point — dependency bootstrap, BuildHelpers environment setup (Set-BuildEnvironment), and module staging all run through build.ps1 itself, rather than a partial copy of its preamble that can drift. This also closes the dependency-bootstrap gap CodeRabbit flagged on the earlier revision (the standalone path no longer assumes BuildHelpers is already imported — -Bootstrap installs/imports deps).
• exit-safe — build.ps1 ends in exit ([int](-not $psake.build_success)). It's invoked with the call operator (&), not dot-sourced, so the exit is contained to the script boundary and does not terminate the Pester run. Verified on Windows PowerShell 5.1 and PowerShell 7.
• PowerShell 5.1-safe path — single two-argument Join-Path over Split-Path -Parent; avoids -AdditionalChildPath (PS 6+ only) and platform-specific ..\ child paths.
• No effect on the build pipeline / CI — the guard only fires when BHBuildOutput is unset, which is never the case under ./build.ps1.
• ASCII-clean — comments use plain hyphens; no new PSUseBOMForUnicodeEncodedFile surface.

Provenance

Surfaced by a cross-repo audit against a consumer module (tablackburn/PlexAutomationToolkit) whose inherited Help.tests.ps1 needed to run standalone. This contributes the capability back so new modules get standalone-runnable Help tests by default — using the more maintainable delegate-to-build.ps1 approach rather than re-implementing the build preamble in the test file.

Scope note

Only tests/Help.tests.ps1 is touched here. tests/Manifest.tests.ps1 and the tests/Unit/ templates use the same bootstrap pattern and could get the same treatment in a follow-up; left out to keep this PR focused.

Test plan

• tests/Help.tests.ps1 parses with no syntax errors
• PSScriptAnalyzer clean on the file; file stays pure ASCII
• Bootstrap mechanism verified end-to-end: standalone Invoke-Pester invokes build.ps1 via &, deps bootstrap, psake Build runs, and exit does not terminate Pester
• exit-containment of &-invoked scripts confirmed on Windows PowerShell 5.1 and PowerShell 7
• CI green (build pipeline path unaffected)

Note: the Help tests cannot reach green when run against the un-initialized template repo itself, because the placeholder source manifest has GUID = '{{GUID}}', which Import-Module rejects. This is the same pre-existing limitation the CI workflow already guards against (is_template check), and is unrelated to the bootstrap mechanism. Standalone runs reach green in an initialized module (real GUID/name), which is the consumer scenario this targets.

🤖 Generated with Claude Code

[coderabbitai]

📝 Walkthrough

Walkthrough

The Help test file now explicitly initializes BuildHelpers environment variables using Set-BuildEnvironment -Force in both test setup blocks (BeforeDiscovery and BeforeAll) when the build environment variable BHBuildOutput is not set. This allows tests to run standalone while remaining skipped during build-pipeline execution. The changelog documents this change.

Changes

Help Test Standalone Execution

Layer / File(s)	Summary
Populate BuildHelpers environment in test bootstrap tests/Help.tests.ps1, CHANGELOG.md	Set-BuildEnvironment -Force is inserted inside the BHBuildOutput-missing guard in both BeforeDiscovery (lines 51–56) and BeforeAll (lines 108–113) to populate required variables (BHPSModuleManifest, BHProjectName). This enables isolated test execution without the full build pipeline. The CHANGELOG documents the new behavior and idempotency guarantee.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Possibly related PRs

• tablackburn/PowerShellModuleTemplate#19: Updates build.psake.ps1 to compute coverage globs from BHPSModuleManifest and staged output path, which directly depends on the environment variables now populated by this PR's test setup.

Poem

🐰 A test that stands alone,
No pipeline need be known,
With environment set just right,
Help tests shine in solo flight,
BuildHelpers now in harmony bright! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: making Help tests runnable standalone via Set-BuildEnvironment, which is the core objective of the PR.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/help-test-standalone-buildenvironment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

Makes tests/Help.tests.ps1 runnable standalone by calling Set-BuildEnvironment inside the existing bootstrap guard, so BuildHelpers vars required by build.psake.ps1's properties block are populated when tests are invoked without first running ./build.ps1.

Changes:

• Add Set-BuildEnvironment -Path ... -Force inside the $Env:BHBuildOutput null guard in both BeforeDiscovery and BeforeAll.
• Document the change in CHANGELOG.md under Added.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
tests/Help.tests.ps1	Populates BuildHelpers env vars before invoking psake in the standalone-bootstrap path.
CHANGELOG.md	Notes the new standalone-runnable Help tests behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@tests/Help.tests.ps1`:
- Around line 51-56: The tests/Help.tests.ps1 calls Set-BuildEnvironment without
ensuring the BuildHelpers module is available; before the Set-BuildEnvironment
invocation (both occurrences) bootstrap dependencies or import BuildHelpers: run
the existing ./build.ps1 dependency bootstrap (e.g. invoke the script or its
bootstrap function) or explicitly ensure BuildHelpers is installed and
Import-Module BuildHelpers (matching the version pinned by build.depend.psd1) so
Set-BuildEnvironment is defined when the test runs standalone.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 1242274b-5c92-4c3b-9a0c-0471a8a0d036

📥 Commits

Reviewing files that changed from the base of the PR and between 329ca92 and f85f512.

📒 Files selected for processing (2)

• CHANGELOG.md
• tests/Help.tests.ps1