Repository: ansible/ansible

Issue:
win_timezone: Added tests for module and updated sections of docs
##### SUMMARY
Added integration tests for win_timezone and updated docs with some more information.

##### ISSUE TYPE
 - Feature Pull Request
 - Docs Pull Request

##### COMPONENT NAME
win_timezone

##### ANSIBLE VERSION
```
ansible 2.4.0 (devel 6a3ce18e4b) last updated 2017/05/25 20:15:42 (GMT +1000)
  config file = /mnt/c/dev/module-tester/ansible.cfg
  configured module search path = [u'/home/jordan/.ansible/plugins/modules', u'/usr/share/ansible/plugins/modules']
  ansible python module location = /mnt/c/dev/linux-ansible/lib/ansible
  executable location = /mnt/c/dev/linux-ansible/bin/ansible
  python version = 2.7.13 (default, Apr 13 2017, 08:16:29) [GCC 5.4.0 20160609]
```



Discussion:
cc @schwartzmx
[click here for bot help](https://github.com/ansible/ansibullbot/blob/master/ISSUE_HELP.md)
<!--- boilerplate: notify --->
lgtm
shipit

Resolving patch:
diff --git a/lib/ansible/modules/windows/win_timezone.py b/lib/ansible/modules/windows/win_timezone.py
--- a/lib/ansible/modules/windows/win_timezone.py
+++ b/lib/ansible/modules/windows/win_timezone.py
@@ -25,28 +25,51 @@
                     '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 patch:
diff --git a/test/integration/targets/win_timezone/aliases b/test/integration/targets/win_timezone/aliases
new file mode 100644
--- /dev/null
+++ b/test/integration/targets/win_timezone/aliases
@@ -0,0 +1 @@
+windows/ci/group3
diff --git a/test/integration/targets/win_timezone/tasks/main.yml b/test/integration/targets/win_timezone/tasks/main.yml
new file mode 100644
--- /dev/null
+++ b/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
diff --git a/test/integration/targets/win_timezone/tasks/tests.yml b/test/integration/targets/win_timezone/tasks/tests.yml
new file mode 100644
--- /dev/null
+++ b/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 }}'