win_timezone: Add diff support, integration tests (#25284)

* win_timezone: Add diff support, integration tests

This PR includes:

- Diff support
- Returns both previous_timezone and timezone
- Adds integration tests
- More examples
- Improved documentation

* Merged the changes from jborean93's PR

lib/ansible/modules/windows/win_timezone.ps1

@@ -21,55 +21,66 @@
 
 $params = Parse-Args $args -supports_check_mode $true
 $check_mode = Get-AnsibleParam -obj $params -name "_ansible_check_mode" -type "bool" -default $false
+$diff_support = Get-AnsibleParam -obj $params -name "_ansible_diff" -type "bool" -default $false
 
 $timezone = Get-AnsibleParam -obj $params -name "timezone" -type "str" -failifempty $true
 
 $result = @{
     changed = $false
+    previous_timezone = $timezone
+    timezone = $timezone
 }
 
 Try {
     # Get the current timezone set
-    $currentTZ = $(tzutil.exe /g)
+    $result.previous_timezone = $(tzutil.exe /g)
     If ($LASTEXITCODE -ne 0) {
         Throw "An error occurred when getting the current machine's timezone setting."
     }
 
-    If ( $currentTZ -eq $timezone ) {
+    if ( $result.previous_timezone -eq $timezone ) {
-        Exit-Json $result "$timezone is already set on this machine"
+        Exit-Json $result "Timezone '$timezone' is already set on this machine"
     } Else {
-        $tzExists = $false
+        # Check that timezone is listed as an available timezone to the machine
-        #Check that timezone can even be set (if it is listed from tzutil as an available timezone to the machine)
         $tzList = $(tzutil.exe /l)
         If ($LASTEXITCODE -ne 0) {
             Throw "An error occurred when listing the available timezones."
         }
+
+        $tzExists = $false
         ForEach ($tz in $tzList) {
             If ( $tz -eq $timezone ) {
                 $tzExists = $true
                 break
             }
         }
+        if (-not $tzExists) {
+            Fail-Json $result "The specified timezone: $timezone isn't supported on the machine."
+        }
+
+        if ($check_mode) {
+            $result.changed = $true
+        } else {
+            tzutil.exe /s "$timezone"
+            if ($LASTEXITCODE -ne 0) {
+                Throw "An error occurred when setting the specified timezone with tzutil."
+            }
 
-        If ( $tzExists ) {
+            $new_timezone = $(tzutil.exe /g)
-            if (-not $check_mode) {
+            if ($LASTEXITCODE -ne 0) {
-                tzutil.exe /s "$timezone"
+                Throw "An error occurred when getting the current machine's timezone setting."
-                If ($LASTEXITCODE -ne 0) {
+            }
-                    Throw "An error occurred when setting the specified timezone with tzutil."
-                }
-                $newTZ = $(tzutil.exe /g)
-                If ($LASTEXITCODE -ne 0) {
-                    Throw "An error occurred when getting the current machine's timezone setting."
-                }
 
-                If ( $timezone -eq $newTZ ) {
+            if ($timezone -eq $new_timezone) {
-                    $result.changed = $true
-                }
-            } else {
                 $result.changed = $true
             }
-        } Else {
+        }
-            Fail-Json $result "The specified timezone: $timezone isn't supported on the machine."
+
+        if ($diff_support) {
+            $result.diff = @{
+                before = "$($result.previous_timezone)`n"
+                after = "$timezone`n"
+            }
         }
     }
 } Catch {

lib/ansible/modules/windows/win_timezone.py

@@ -25,28 +25,51 @@ ANSIBLE_METADATA = {'metadata_version': '1.0',
                     'status': ['preview'],
                     'supported_by': 'community'}
 
-
 DOCUMENTATION = r'''
 ---
 module: win_timezone
-version_added: "2.1"
+version_added: '2.1'
 short_description: Sets Windows machine timezone
 description:
-    - Sets machine time to the specified timezone, the module will check if the provided timezone is supported on the machine.
+- Sets machine time to the specified timezone.
 options:
   timezone:
     description:
-      - Timezone to set to.  Example Central Standard Time
+    - Timezone to set to. Example Central Standard Time
     required: true
-
+notes:
+- The module will check if the provided timezone is supported on the machine.
+- A list of possible timezones is available from C(tzutil.exe /l) and from
+  U(https://msdn.microsoft.com/en-us/library/ms912391.aspx)
+- If running on Server 2008 the hotfix
+  U(https://support.microsoft.com/en-us/help/2556308/tzutil-command-line-tool-is-added-to-windows-vista-and-to-windows-server-2008)
+  needs to be installed to be able to run this module.
 author: Phil Schwartz
 '''
 
-
 EXAMPLES = r'''
-  # Set machine's timezone to Central Standard Time
+- name: Set timezone to 'Romance Standard Time' (GMT+01:00)
+  win_timezone:
+    timezone: Romance Standard Time
+
+- name: Set timezone to 'GMT Standard Time' (GMT)
+  win_timezone:
+    timezone: GMT Standard Time
+
+- name: Set timezone to 'Central Standard Time' (GMT-06:00)
   win_timezone:
-    timezone: "Central Standard Time"
+    timezone: Central Standard Time
 '''
 
-RETURN = r'''# '''
+RETURN = r'''
+previous_timezone:
+    description: The previous timezone if it was changed, otherwise the existing timezone
+    returned: success
+    type: string
+    sample: Central Standard Time
+timezone:
+    description: The current timezone (possibly changed)
+    returned: success
+    type: string
+    sample: Central Standard Time
+'''

test/integration/targets/win_timezone/aliases

@@ -0,0 +1 @@
+windows/ci/group3

test/integration/targets/win_timezone/tasks/main.yml

@@ -0,0 +1,19 @@
+- name: Determine if server has tzutil.exe installed
+  win_command: tzutil.exe /l
+  register: tzutil
+  ignore_errors: yes
+
+- name: Only run tests if tzutil.exe is installed
+  when: tzutil.rc == 0
+  block:
+
+  - name: Test in normal mode
+    include: tests.yml
+    vars:
+      in_check_mode: no
+
+  - name: Test in check-mode
+    include: tests.yml
+    vars:
+      in_check_mode: yes
+    check_mode: yes

test/integration/targets/win_timezone/tasks/tests.yml

@@ -0,0 +1,89 @@
+# NOTE: Set to a known starting value, store original
+- name: Change starting timezone to GMT
+  win_timezone:
+    timezone: GMT Standard Time
+  register: original
+
+# NOTE: We don't know if it changed, we don't care
+- name: Test GMT timezone
+  assert:
+    that:
+    - original.timezone == 'GMT Standard Time'
+
+- name: Change timezone to GMT+1
+  win_timezone:
+    timezone: Romance Standard Time
+  register: romance
+
+- name: Test GMT+1 timezone
+  assert:
+    that:
+    - romance|changed
+    - romance.previous_timezone == 'GMT Standard Time'
+    - romance.timezone == 'Romance Standard Time'
+  when: not in_check_mode
+
+- name: Test GMT+1 timezone
+  assert:
+    that:
+    - romance|changed
+    - romance.previous_timezone == original.timezone
+    - romance.timezone == 'Romance Standard Time'
+  when: in_check_mode
+
+- name: Change timezone to GMT+1 again
+  win_timezone:
+    timezone: Romance Standard Time
+  register: romance
+
+- name: Test GMT+1 timezone
+  assert:
+    that:
+    - not romance|changed
+    - romance.previous_timezone == 'Romance Standard Time'
+    - romance.timezone == 'Romance Standard Time'
+  when: not in_check_mode
+
+- name: Test GMT+1 timezone
+  assert:
+    that:
+    - romance|changed
+    - romance.previous_timezone == original.timezone
+    - romance.timezone == 'Romance Standard Time'
+  when: in_check_mode
+
+- name: Change timezone to GMT+6
+  win_timezone:
+    timezone: Central Standard Time
+  register: central
+
+- name: Test GMT-6 timezone
+  assert:
+    that:
+    - central|changed
+    - central.previous_timezone == 'Romance Standard Time'
+    - central.timezone == 'Central Standard Time'
+  when: not in_check_mode
+
+- name: Test GMT+1 timezone
+  assert:
+    that:
+    - central|changed
+    - central.previous_timezone == original.timezone
+    - central.timezone == 'Central Standard Time'
+  when: in_check_mode
+
+- name: Change timezone to GMT+666
+  win_timezone:
+    timezone: Dag's Standard Time
+  register: dag
+  ignore_errors: yes
+
+- name: Test GMT+666 timezone
+  assert:
+    that:
+    - dag|failed
+
+- name: Restore original timezone
+  win_timezone:
+    timezone: '{{ original.timezone }}'