Development Guide¶
This guide provides instructions for building, testing, and developing the PSReddit module.
Prerequisites¶
Before you begin, ensure you have the following installed:
- PowerShell 7+: The module and build scripts require PowerShell 7 or later.
- Invoke-Build Module: Used for automating build tasks. Install it using:
- Pester Module: Used for running tests. The build script requires a version between 5.2.2 and 5.99.99. Install a compatible version (e.g., 5.5.0):
- (Optional) Reddit API Credentials: For running integration tests, you need a Reddit application Client ID and Secret. Set these as environment variables:
Build Process¶
The build process is managed by Invoke-Build
using the src/PSReddit.build.ps1
script. All build commands should be run from the src/
directory.
Full Build¶
Runs the default sequence: Clean, Validate Requirements, Import Module Manifest, Formatting Check, Analyze, Test (Unit), Create Help, Build, Integration Test, Archive.
The final module output will be placed in the src/Artifacts/PSReddit/
directory, and a zipped archive in src/Archive/
.
Build Without Integration Tests¶
Runs the full build process except for the integration tests.
Testing¶
Run Unit Tests¶
Runs static analysis (PSScriptAnalyzer) and Pester unit tests located in src/Tests/Unit/
. Also generates code coverage reports.
src/Artifacts/
.
Run Integration Tests¶
Runs Pester integration tests located in src/Tests/Integration/
. These tests interact with the live Reddit API and require the REDDIT_CLIENT_ID
and REDDIT_CLIENT_SECRET
environment variables to be set.
Code Coverage (for VSCode)¶
To generate a cov.xml
file at the project root compatible with the "Coverage Gutters" VSCode extension:
Documentation¶
Generate Help Files¶
To regenerate the markdown documentation and external help XML file (used by Get-Help
):
Clean
, ImportModuleManifest
, and CreateHelpStart
tasks, including markdown and external help generation. The generated markdown files are placed in src/Artifacts/docs/
and the XML help file in src/Artifacts/en-US/
.
Preview Documentation Site¶
This project uses MkDocs with the Material theme. To preview the documentation site locally:
- Ensure you have Python and pip installed.
- Install MkDocs and the Material theme:
- Navigate to the project root directory (where
mkdocs.yml
is located). - Run the MkDocs development server:
- Open your browser to
http://127.0.0.1:8000
.
Cleaning¶
To remove the src/Artifacts
and src/Archive
directories:
```powershell Invoke-Build Clean