diff --git a/docs/wiki/Contribution guide - Contribution flow.md b/docs/wiki/Contribution guide - Contribution flow.md index 6ab0ec0c97..3a33c1d384 100644 --- a/docs/wiki/Contribution guide - Contribution flow.md +++ b/docs/wiki/Contribution guide - Contribution flow.md @@ -60,6 +60,7 @@ Once the contribution is implemented and the changes are pushed to your forked r - In case you want to contribute to the documentation, you can skip this step. - In case your contribution involves changes to the library (the modules) and/or to the CI environment (the pipelines), we kindly ask you to validate your updates against your environment before requesting to merge them to the main repo. Test your code leveraging the CARML CI environment, as detailed in the [Pipeline usage](./The%20CI%20environment%20-%20Pipeline%20usage) section. + > **Note**: In case your contribution involves changes to a module, you can also optionally leverage the [Validate module locally](./Contribution%20guide%20-%20Validate%20module%20locally) utility to validate the updated module from your local host before validating it through its pipeline. # Open a PR diff --git a/docs/wiki/Contribution guide - Validate module locally.md b/docs/wiki/Contribution guide - Validate module locally.md new file mode 100644 index 0000000000..1e96695853 --- /dev/null +++ b/docs/wiki/Contribution guide - Validate module locally.md @@ -0,0 +1,34 @@ +Use this script to test a module locally. You can use it to run only the static validation (pester tests), a deployment validation (dryRun) or an actual deployment to Azure. In the latter cases the script also takes care to replace placeholder tokens in the used parameter file for you. + +--- + +### _Navigation_ + +- [Location](#location) +- [How it works](#what-it-does) +- [How to use it](#how-to-use-it) + +--- +# Location + +You can find the script under `/utilities/tools/Test-ModuleLocally.ps1` + +# How it works + +If the switch for pester tests (`-PesterTest`) is provided the script will +1. Invoke the global module test for the provided template file path and run all tests for it + +If the switch for either the validation test (`-ValidationTest`) or deployment test (`-DeploymentTest`) is provided alongside a HashTable for the token replacement (`-ValidateOrDeployParameters`), the script will +1. Either fetch all parameter files of the module's parameter folder (default) or you can specify a single parameter file by leveraging the `parameterFilePath` parameter instead. +1. Create a dictionary to replace all tokens in these parameter files with actual values. This dictionary will consist + - of the subscriptionID & managementGroupID of the provided `ValidateOrDeployParameters` object, + - add all key-value pairs of the `-AdditionalTokens` object to it, + - and optionally also add all key-value pairs specified in the `settings.json`'s `parameterFileTokens` object +1. If the `-ValidationTest` parameter was set, it runs a deployment validation using the `Test-TemplateWithParameterFile` script +1. If the `-DeploymentTest` parameter was set, it runs a deployment using the `New-ModuleDeployment` script (with no retries). +1. As a final step it rolls the parameter files back to their original state if either the `-ValidationTest` or `-DeploymentTest` parameters were provided. + +# How to use it + +For details on how to use the function please refer to the script's local documentation. +> **Note:** The script must be loaded before the function can be invoked diff --git a/docs/wiki/Contribution guide.md b/docs/wiki/Contribution guide.md index 82ecb0cfd8..c610e0ed3d 100644 --- a/docs/wiki/Contribution guide.md +++ b/docs/wiki/Contribution guide.md @@ -7,5 +7,5 @@ This section provides the step-by-step process we suggest to follow for contribu - [Contribution flow](./Contribution%20guide%20-%20Contribution%20flow) - [Generate module Readme](./Contribution%20guide%20-%20Generate%20module%20Readme) - [Get formatted RBAC roles](./Contribution%20guide%20-%20Get%20formatted%20RBAC%20roles) - +- [Validate module locally](./Contribution%20guide%20-%20Validate%20module%20locally) --- diff --git a/docs/wiki/Home.md b/docs/wiki/Home.md index ec54c68bcb..5de494d89e 100644 --- a/docs/wiki/Home.md +++ b/docs/wiki/Home.md @@ -64,6 +64,7 @@ If you're unfamiliar with Infrastructure as Code, or wonder how you can use the - [Contribution flow](./Contribution%20guide%20-%20Contribution%20flow) - [Generate module Readme](./Contribution%20guide%20-%20Generate%20module%20Readme) - [Get formatted RBAC roles](./Contribution%20guide%20-%20Get%20formatted%20RBAC%20roles) + - [Validate module locally](./Contribution%20guide%20-%20Validate%20module%20locally) - [Known issues](./Known%20issues) ---