win_environment: Added tests and return info in document (#25064)

* win_environment: Added tests and return info in document

* fixing up some yaml issues

* some more things I should have detected

* fixing up test tag name

lib/ansible/modules/windows/win_environment.py

@@ -79,15 +79,41 @@ notes:
 '''
 
 EXAMPLES = r'''
-  # Set an environment variable for all users
+- name: Set an environment variable for all users
   win_environment:
     state: present
     name: TestVariable
     value: Test value
     level: machine
-  # Remove an environment variable for the current users
+
+- name: Remove an environment variable for the current user
   win_environment:
     state: absent
     name: TestVariable
     level: user
 '''
+
+RETURN = r'''
+before_value:
+  description:
+  - the value of the environment key before a change, this is null if it didn't
+    exist
+  returned: always
+  type: string
+  sample: C:\Windows\System32
+level:
+  description: the level set when calling the module
+  returned: always
+  type: string
+  sample: machine
+name:
+  description: the name of the environment key the module checked
+  returned: always
+  type: string
+  sample: JAVA_HOME
+value:
+  description: the value the environment key has been set to
+  returned: always
+  type: string
+  sample: C:\Program Files\jdk1.8
+'''

test/integration/targets/win_environment/aliases

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

test/integration/targets/win_environment/defaults/main.yml

@@ -0,0 +1,5 @@
+test_environment_name: TEST_VALUE
+test_machine_environment_value: "%SystemRoot%\\System32"
+test_new_machine_environment_value: C:\Windows\System32
+test_user_environment_value: C:\Program Files
+test_new_user_environment_value: C:\Program Files (x86)

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

@@ -0,0 +1,280 @@
+---
+- name: ensure test environment value is not set in all scope
+  win_environment:
+    name: "{{test_environment_name}}"
+    state: absent
+    level: "{{item}}"
+  with_items:
+  - machine
+  - process
+  - user
+
+- name: create test environment value for machine check
+  win_environment:
+    name: "{{test_environment_name}}"
+    value: "{{test_machine_environment_value}}"
+    state: present
+    level: machine
+  register: create_machine_check
+  check_mode: True
+
+- name: get value of environment key for machine after changing check
+  win_command: powershell.exe "[Microsoft.Win32.Registry]::LocalMachine.OpenSubKey('SYSTEM\CurrentControlSet\Control\Session Manager\Environment', $true).GetValue('{{test_environment_name}}', $null, 'DoNotExpandEnvironmentNames')"
+  register: create_machine_check_actual
+
+- name: assert change test environment value for machine check
+  assert:
+    that:
+    - create_machine_check|changed
+    - create_machine_check_actual.stdout == ""
+
+- name: create test environment value for machine
+  win_environment:
+    name: "{{test_environment_name}}"
+    value: "{{test_machine_environment_value}}"
+    state: present
+    level: machine
+  register: create_machine
+
+- name: get value of environment key for machine after changing
+  win_command: powershell.exe "[Microsoft.Win32.Registry]::LocalMachine.OpenSubKey('SYSTEM\CurrentControlSet\Control\Session Manager\Environment', $true).GetValue('{{test_environment_name}}', $null, 'DoNotExpandEnvironmentNames')"
+  register: create_machine_actual
+
+- name: assert test environment value for machine
+  assert:
+    that:
+    - create_machine|changed
+    - create_machine.before_value == None
+    - create_machine.level == 'machine'
+    - create_machine.name == test_environment_name
+    - create_machine.value == test_machine_environment_value
+    - create_machine_actual.stdout == "{{test_machine_environment_value}}\r\n"
+
+- name: create test environment value for machine again
+  win_environment:
+    name: "{{test_environment_name}}"
+    value: "{{test_machine_environment_value}}"
+    state: present
+    level: machine
+  register: create_machine_again
+
+- name: get value of environment key for machine after changing again
+  win_command: powershell.exe "[Microsoft.Win32.Registry]::LocalMachine.OpenSubKey('SYSTEM\CurrentControlSet\Control\Session Manager\Environment', $true).GetValue('{{test_environment_name}}', $null, 'DoNotExpandEnvironmentNames')"
+  register: create_machine_actual_again
+
+- name: assert create test environment value for machine again
+  assert:
+    that:
+    - not create_machine_again|changed
+    - create_machine_again.before_value == test_machine_environment_value
+    - create_machine_again.level == 'machine'
+    - create_machine_again.name == test_environment_name
+    - create_machine_again.value == test_machine_environment_value
+    - create_machine_actual_again.stdout == "{{test_machine_environment_value}}\r\n"
+
+- name: change test environment value for machine check
+  win_environment:
+    name: "{{test_environment_name}}"
+    value: "{{test_new_machine_environment_value}}"
+    state: present
+    level: machine
+  register: change_machine_check
+  check_mode: True
+
+- name: get value of environment key for machine after changing check
+  win_command: powershell.exe "[Microsoft.Win32.Registry]::LocalMachine.OpenSubKey('SYSTEM\CurrentControlSet\Control\Session Manager\Environment', $true).GetValue('{{test_environment_name}}', $null, 'DoNotExpandEnvironmentNames')"
+  register: change_machine_actual_check
+
+- name: assert change test environment value for machine check
+  assert:
+    that:
+    - change_machine_check|changed
+    - change_machine_check.before_value == test_machine_environment_value
+    - change_machine_check.level == 'machine'
+    - change_machine_check.name == test_environment_name
+    - change_machine_check.value == test_new_machine_environment_value
+    - change_machine_actual_check.stdout == "{{test_machine_environment_value}}\r\n"
+
+- name: change test environment value for machine
+  win_environment:
+    name: "{{test_environment_name}}"
+    value: "{{test_new_machine_environment_value}}"
+    state: present
+    level: machine
+  register: change_machine
+
+- name: get value of environment key for machine after changing
+  win_command: powershell.exe "[Microsoft.Win32.Registry]::LocalMachine.OpenSubKey('SYSTEM\CurrentControlSet\Control\Session Manager\Environment', $true).GetValue('{{test_environment_name}}', $null, 'DoNotExpandEnvironmentNames')"
+  register: change_machine_actual
+
+- name: assert change test environment value for machine
+  assert:
+    that:
+    - change_machine|changed
+    - change_machine.before_value == test_machine_environment_value
+    - change_machine.level == 'machine'
+    - change_machine.name == test_environment_name
+    - change_machine.value == test_new_machine_environment_value
+    - change_machine_actual.stdout == "{{test_new_machine_environment_value}}\r\n"
+
+- name: change test environment value for machine again
+  win_environment:
+    name: "{{test_environment_name}}"
+    value: "{{test_new_machine_environment_value}}"
+    state: present
+    level: machine
+  register: change_machine_again
+
+- name: get value of environment key for machine after changing again
+  win_command: powershell.exe "[Microsoft.Win32.Registry]::LocalMachine.OpenSubKey('SYSTEM\CurrentControlSet\Control\Session Manager\Environment', $true).GetValue('{{test_environment_name}}', $null, 'DoNotExpandEnvironmentNames')"
+  register: change_machine_actual_again
+
+- name: assert change test environment value for machine again
+  assert:
+    that:
+    - not change_machine_again|changed
+    - change_machine_again.before_value == test_new_machine_environment_value
+    - change_machine_again.level == 'machine'
+    - change_machine_again.name == test_environment_name
+    - change_machine_again.value == test_new_machine_environment_value
+    - change_machine_actual_again.stdout == "{{test_new_machine_environment_value}}\r\n"
+
+- name: create test environment value for user check
+  win_environment:
+    name: "{{test_environment_name}}"
+    value: "{{test_user_environment_value}}"
+    state: present
+    level: user
+  register: create_user_check
+  check_mode: True
+
+- name: get value of environment key for user after changing check
+  win_command: powershell.exe "[Microsoft.Win32.Registry]::CurrentUser.OpenSubKey('Environment', $true).GetValue('{{test_environment_name}}', $null, 'DoNotExpandEnvironmentNames')"
+  register: create_user_check_actual
+
+- name: assert change test environment value for user check
+  assert:
+    that:
+    - create_user_check|changed
+    - create_user_check_actual.stdout == ""
+
+- name: create test environment value for user
+  win_environment:
+    name: "{{test_environment_name}}"
+    value: "{{test_user_environment_value}}"
+    state: present
+    level: user
+  register: create_user
+
+- name: get value of environment key for user after changing
+  win_command: powershell.exe "[Microsoft.Win32.Registry]::CurrentUser.OpenSubKey('Environment', $true).GetValue('{{test_environment_name}}', $null, 'DoNotExpandEnvironmentNames')"
+  register: create_user_actual
+
+- name: assert test environment value for user
+  assert:
+    that:
+    - create_user|changed
+    - create_user.before_value == None
+    - create_user.level == 'user'
+    - create_user.name == test_environment_name
+    - create_user.value == test_user_environment_value
+    - create_user_actual.stdout == "{{test_user_environment_value}}\r\n"
+
+- name: create test environment value for user again
+  win_environment:
+    name: "{{test_environment_name}}"
+    value: "{{test_user_environment_value}}"
+    state: present
+    level: user
+  register: create_user_again
+
+- name: get value of environment key for user after changing again
+  win_command: powershell.exe "[Microsoft.Win32.Registry]::CurrentUser.OpenSubKey('Environment', $true).GetValue('{{test_environment_name}}', $null, 'DoNotExpandEnvironmentNames')"
+  register: create_user_actual_again
+
+- name: assert create test environment value for user again
+  assert:
+    that:
+    - not create_user_again|changed
+    - create_user_again.before_value == test_user_environment_value
+    - create_user_again.level == 'user'
+    - create_user_again.name == test_environment_name
+    - create_user_again.value == test_user_environment_value
+    - create_user_actual_again.stdout == "{{test_user_environment_value}}\r\n"
+
+- name: change test environment value for user check
+  win_environment:
+    name: "{{test_environment_name}}"
+    value: "{{test_new_user_environment_value}}"
+    state: present
+    level: user
+  register: change_user_check
+  check_mode: True
+
+- name: get value of environment key for user after changing check
+  win_command: powershell.exe "[Microsoft.Win32.Registry]::CurrentUser.OpenSubKey('Environment', $true).GetValue('{{test_environment_name}}', $null, 'DoNotExpandEnvironmentNames')"
+  register: change_user_actual_check
+
+- name: assert change test environment value for user check
+  assert:
+    that:
+    - change_user_check|changed
+    - change_user_check.before_value == test_user_environment_value
+    - change_user_check.level == 'user'
+    - change_user_check.name == test_environment_name
+    - change_user_check.value == test_new_user_environment_value
+    - change_user_actual_check.stdout == "{{test_user_environment_value}}\r\n"
+
+- name: change test environment value for user
+  win_environment:
+    name: "{{test_environment_name}}"
+    value: "{{test_new_user_environment_value}}"
+    state: present
+    level: user
+  register: change_user
+
+- name: get value of environment key for user after changing
+  win_command: powershell.exe "[Microsoft.Win32.Registry]::CurrentUser.OpenSubKey('Environment', $true).GetValue('{{test_environment_name}}', $null, 'DoNotExpandEnvironmentNames')"
+  register: change_user_actual
+
+- name: assert change test environment value for user
+  assert:
+    that:
+    - change_user|changed
+    - change_user.before_value == test_user_environment_value
+    - change_user.level == 'user'
+    - change_user.name == test_environment_name
+    - change_user.value == test_new_user_environment_value
+    - change_user_actual.stdout == "{{test_new_user_environment_value}}\r\n"
+
+- name: change test environment value for user again
+  win_environment:
+    name: "{{test_environment_name}}"
+    value: "{{test_new_user_environment_value}}"
+    state: present
+    level: user
+  register: change_user_again
+
+- name: get value of environment key for user after changing again
+  win_command: powershell.exe "[Microsoft.Win32.Registry]::CurrentUser.OpenSubKey('Environment', $true).GetValue('{{test_environment_name}}', $null, 'DoNotExpandEnvironmentNames')"
+  register: change_user_actual_again
+
+- name: assert change test environment value for user again
+  assert:
+    that:
+    - not change_user_again|changed
+    - change_user_again.before_value == test_new_user_environment_value
+    - change_user_again.level == 'user'
+    - change_user_again.name == test_environment_name
+    - change_user_again.value == test_new_user_environment_value
+    - change_user_actual_again.stdout == "{{test_new_user_environment_value}}\r\n"
+
+- name: cleanup test changes
+  win_environment:
+    name: "{{test_environment_name}}"
+    state: absent
+    level: "{{item}}"
+  with_items:
+  - machine
+  - process
+  - user

test/integration/test_win_group3.yml

@@ -9,3 +9,4 @@
     - { role: win_command, tags: test_win_command }
     - { role: win_reg_stat, tags: test_win_reg_stat }
     - { role: win_region, tags: test_win-region }
+    - { role: win_environment, tags: test_win-environment }