Update documentation (#10)

* Add Policy Integration Tests documentation and configuration details

* Add comprehensive documentation and sample test cases for Azure Policy Integration Tests

- Created a global configuration document detailing properties for the policy integration test framework.
- Added a local configuration document for storing test-specific variables.
- Developed a main documentation file outlining the purpose, workflow, and execution of policy integration tests.
- Introduced a policy testing overview document summarizing various tests included in the AzPolicyFactory solution.
- Implemented sample test cases for various Azure resources including Network Security Groups, PostgreSQL, Private Endpoints, Storage Accounts, Virtual Networks, and Web Apps.

* Fix typos and improve documentation clarity across multiple files

* Add Markdown linting configuration and update documentation for policy integration tests

* Update Super-Linter version and adjust Markdown config path in CI workflows

* Fix formatting and improve clarity in documentation across multiple files

* Fix typo in markdownlint configuration for emphasis heading rule

Author: taoyangcloud

.azuredevops/pipelines/README.md

@@ -1,2 +1,3 @@
 # Introduction
-This folder contains the build and deploy pipelines in YAML format.
+
+This folder contains the build and deploy pipelines in YAML format.

.azuredevops/pipelines/validation/azure-pipelines-pr-validation.yml

@@ -24,7 +24,8 @@ stages:
               -e VALIDATE_BIOME_FORMAT=false \
               -e IGNORE_GITIGNORED_FILES=true \
               -e GITHUB_ACTIONS_ZIZMOR_CONFIG_FILE=.zizmor.yml \
+              -e MARKDOWN_CONFIG_FILE=.markdownlint.json \
               -v $(System.DefaultWorkingDirectory):/tmp/lint \
-              ghcr.io/super-linter/super-linter:v8.5.0
+              ghcr.io/super-linter/super-linter:v8.6.0
           displayName: 'GitHub Super-Linter Code Scan'
 

.github/copilot-instructions.md

@@ -1 +1 @@
-- @azure Rule - Use Azure Best Practices: When generating code for Azure, running terminal commands for Azure, or performing operations related to Azure, invoke your `get_azure_best_practices` tool if available.
+- @azure Rule - Use Azure Best Practices: When generating code for Azure, running terminal commands for Azure, or performing operations related to Azure, invoke your `get_azure_best_practices` tool if available.

.github/workflows/pr-code-scan.yml

@@ -46,3 +46,4 @@ jobs:
           VALIDATE_ARM: false
           IGNORE_GITIGNORED_FILES: true
           GITHUB_ACTIONS_ZIZMOR_CONFIG_FILE: .zizmor.yml
+          MARKDOWN_CONFIG_FILE: ../../.markdownlint.json

.markdownlint.json

@@ -39,17 +39,15 @@
   },
   "no-multiple-space-blockquote": true,
   "no-blanks-blockquote": true,
-  "ol-prefix": {
-    "style": "one_or_ordered"
-  },
+  "ol-prefix": false,
   "list-marker-space": true,
   "blanks-around-fences": true,
   "blanks-around-lists": true,
   "no-bare-urls": false,
   "hr-style": {
     "style": "---"
   },
-  "no-emphasis-as-header": true,
+  "no-emphasis-as-heading": false,
   "no-space-in-emphasis": true,
   "no-space-in-code": true,
   "no-space-in-links": true,

README.md

@@ -25,6 +25,7 @@ This repository contains the complete set of IaC solutions for deploying Azure P
   - Deploying Azure Policy Definitions, Initiatives, Assignments, and Exemptions
   - PR Validation Code Scan using GitHub Super-Linter
   - PR Validation for Azure Policy Assignment configurations between production and development environments
+  - Policy Integration Tests to test assigned policies on real resources in Azure and validate the expected results
 
 The solution automates the entire lifecycle of Azure Policy resources — from code commit through testing and validation to production deployment — ensuring quality and correctness at every stage.
 
@@ -39,7 +40,22 @@ The Azure Policy IaC solution in this repository includes the following key feat
 - Comprehensive set of tests and validation at different stages of the CI/CD pipelines to ensure the quality and correctness of the Azure Policy resources being deployed.
 - Follows industry best practices for Azure Policy management, safe deployment, code scan, and PR validation to ensure that the Azure Policy resources are deployed in a secure and compliant manner.
 - Unit tests for every policy resource being deployed.
-- Policy Integration Test (coming soon) to validate the functionality and effectiveness of the deployed Azure Policy resources in enforcing the desired governance and compliance requirements.
+- Policy Integration Test to validate the functionality and effectiveness of the deployed Azure Policy resources in enforcing the desired governance and compliance requirements.
+
+### Tests for Azure Policy
+
+The key to successfully implementing Azure Policy is to have confidence that your policies are correctly defined and will work as expected in your environment. The `AzPolicyFactory` solution is strongly focused in testing every step along the deployment process.
+
+The following Tests are included in the `AzPolicyFactory` solution:
+
+- **Policy Definitions and Initiatives Syntax Tests:** Static tests for syntax and best practices validation of policy definitions.
+- **Bicep Template PSRule Tests:** Validate Bicep templates for policy definitions using [PSRule for Azure](https://azure.github.io/PSRule.Rules.Azure/).
+- **Bicep Template Test Deployments:** Validate policy definition Bicep templates against Azure deployment engine to ensure they can be successfully deployed.
+- **Policy Assignments and Exemptions Syntax Tests:** Static tests for syntax validation of the configuration files for policy assignments and exemptions.
+- **Policy Assignments Environment Consistency Tests:** Validate that the policy assignments defined for production and development environments are consistent with each other to ensure the policies being tested in the development environment are the same as those being deployed to production.
+- **Policy Integration Tests:** Deploy real resources in Azure that are expected to either comply or violate the assigned policies, then validate the policy states and policy violation results to ensure the policies are working as expected in the Azure environment.
+
+For more details on the tests included in this solution, please refer to the [Tests for Azure Policy](./policy-testing.md) documentation.
 
 ## Recommended Architectural Approach for Azure Policy IaC