win_firewall: check-mode support, integration tests (#25127)

* win_firewall: check-mode support, integration tests

This PR includes:
- Check-mode implementation
- Documentation improvements
- Ensure module output is consistent (no matter what profiles are provided)
- Fixed indentation
- Cosmetic changes
- Integration tests

* win_firewall: check-mode support, integration tests

This PR includes:
- Check-mode implementation
- Documentation improvements
- Ensure module output is consistent (no matter what profiles are provided)
- Fixed indentation
- Cosmetic changes
- Integration tests

lib/ansible/modules/windows/win_firewall.ps1

@@ -19,50 +19,60 @@
 # WANT_JSON
 # POWERSHELL_COMMON
 
+$ErrorActionPreference = "Stop"
+$firewall_profiles = @('Domain', 'Private', 'Public')
 
-# get params
-$params = Parse-Args $args -supports_check_mode $false
+$params = Parse-Args $args -supports_check_mode $true
+$check_mode = Get-AnsibleParam -obj $params -name "_ansible_check_mode" -type "bool" -default $false
 
-$profiles = Get-AnsibleParam -obj $params -name "profiles" -type "list" -default [ "Public", "Domain", "Private" ]
-$wantedstate = Get-AnsibleParam -obj $params -name "state" -type "str" -failifempty $true -validateset 'enabled', 'disabled'
+$profiles = Get-AnsibleParam -obj $params -name "profiles" -type "list" -default @("Domain", "Private", "Public")
+$state = Get-AnsibleParam -obj $params -name "state" -type "str" -failifempty $true -validateset 'disabled','enabled'
 
 $result = @{
     changed = $false
+    profiles = $profiles
+    state = $state
+}
 
+if ($PSVersionTable.PSVersion -lt [Version]"5.0") {
+    Fail-Json $result "win_firewall requires Windows Management Framework 5 or higher."
 }
 
 Try {
 
-  ForEach($profile in $profiles)
+    ForEach ($profile in $firewall_profiles) {
 
-  {
-
-      $currentstate = (Get-NetFirewallProfile -Name $profile).Enabled
-
-      if ($wantedstate -eq 'enabled')
-      {
-        if ($currentstate -eq $false)
-        {
-            Set-NetFirewallProfile -name $profile -Enabled true
-            $result.enabled = $true
-            $result.changed = $true
-        }
-      }
-      else
-      {
-        if ($currentstate -eq $true)
-        {
-           Set-NetFirewallProfile -name $profile -Enabled false
-           $result.enabled = $false
-           $result.changed = $true
+        $currentstate = (Get-NetFirewallProfile -Name $profile).Enabled
+        $result.$profile = @{
+            enabled = ($currentstate -eq 1)
+            considered = ($profiles -contains $profile)
+            currentstate = $currentstate
         }
 
-      }
+        if ($profiles -notcontains $profile) {
+            continue
+        }
 
-  }
-}
-Catch {
+        if ($state -eq 'enabled') {
+
+            if ($currentstate -eq $false) {
+                Set-NetFirewallProfile -name $profile -Enabled true -WhatIf:$check_mode
+                $result.changed = $true
+                $result.$profile.enabled = $true
+            }
+
+        } else {
+
+            if ($currentstate -eq $true) {
+                Set-NetFirewallProfile -name $profile -Enabled false -WhatIf:$check_mode
+                $result.changed = $true
+                $result.$profile.enabled = $false
+            }
+
+        }
+    }
+} Catch {
     Fail-Json $result "an error occurred when attempting to change firewall status for profile $profile $($_.Exception.Message)"
 }
 
-Exit-Json $result
+Exit-Json $result

lib/ansible/modules/windows/win_firewall.py

@@ -28,55 +28,60 @@ ANSIBLE_METADATA = {'metadata_version': '1.0',
 DOCUMENTATION = r'''
 ---
 module: win_firewall
-version_added: "2.4"
-short_description: Manages Windows Firewall
+version_added: '2.4'
+short_description: Enable or disable the Windows Firewall
 description:
-    - Manages Windows Firewall
+- Enable or Disable Windows Firewall profiles.
 options:
-  profile:
+  profiles:
     description:
-    - specify the profile to change
+    - Specify one or more profiles to change.
     choices:
-    - Public
     - Domain
     - Private
+    - Public
+    default: [Domain, Private, Public]
   state:
     description:
-    - set state of firewall for given profile
+    - Set state of firewall for given profile.
     choices:
     - enabled
     - disabled
-
-author: "Michael Eaton (@MichaelEaton83)"
+author: Michael Eaton (@MichaelEaton83)
 '''
 
 EXAMPLES = r'''
-- name: Enable all firewalls
+- name: Enable firewall for Domain, Public and Private profiles
   win_firewall:
-      state: enabled
-      profiles:
-      - Domain
-      - Public
-      - Private
+    state: enabled
+    profiles:
+    - Domain
+    - Private
+    - Public
   tags: enable_firewall
 
 - name: Disable Domain firewall
   win_firewall:
-     state: disabled
-     profiles:
-     - Domain
+    state: disabled
+    profiles:
+    - Domain
   tags: disable_firewall
 '''
 
 RETURN = r'''
-profile:
-    description: chosen profile
-    returned: always
-    type: string
-    sample: Domain
 enabled:
     description: current firewall status for chosen profile (after any potential change)
     returned: always
     type: bool
     sample: true
+profiles:
+    description: chosen profile
+    returned: always
+    type: string
+    sample: Domain
+state:
+    description: desired state of the given firewall profile(s)
+    returned: always
+    type: list
+    sample: enabled
 '''