win_share: Add integration tests and various fixes (#25691)

* win_share: Add integration tests and various fixes

* docs and comments updates based on PR review

* fixed up documentation issue with URL

test/integration/targets/win_share/aliases

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

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

@@ -0,0 +1,2 @@
+test_win_share_path: C:\ansible\win_share
+test_win_share_name: test share

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

@@ -0,0 +1,43 @@
+---
+- name: check if -SmbShare cmdlets are available
+  win_command: powershell.exe "Get-Command -Name Get-SmbShare"
+  register: module_available
+  failed_when: False
+
+- name: check that module fails with helpful message on older hosts
+  win_share:
+    name: test
+  register: module_not_supported
+  when: module_available.rc == 1
+  failed_when: module_not_supported.msg != 'The current host does not support the -SmbShare cmdlets required by this module. Please run on Server 2012 or Windows 8 and later'
+  check_mode: yes
+
+# Run the actual tests
+- block:
+  # setup for tests
+  - name: create testing folder
+    win_file:
+      path: "{{test_win_share_path}}"
+      state: directory
+
+  - name: ensure testing folder isn't shared as a baseline
+    win_share:
+      name: "{{test_win_share_name}}"
+      state: absent
+
+  - name: run tests on hosts that support it
+    include_tasks: tests.yml
+    when: module_available.rc == 0
+
+  always:
+  # cleanup
+  - name: ensure testing folder isn't shared anymore
+    win_share:
+      name: "{{test_win_share_name}}"
+      state: absent
+
+  - name: remove testing folder
+    win_file:
+      path: "{{test_win_share_path}}"
+      state: absent
+  when: module_available.rc == 0

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

@@ -0,0 +1,448 @@
+---
+- name: create share check
+  win_share:
+    name: "{{test_win_share_name}}"
+    path: "{{test_win_share_path}}"
+    state: present
+  register: create_share_check
+  check_mode: yes
+
+- name: check if share exists check
+  win_shell: Get-SmbShare | Where-Object { $_.Name -eq  '{{test_win_share_name}}' }
+  register: create_share_actual_check
+
+- name: assert create share check
+  assert:
+    that:
+    - create_share_check|changed
+    - create_share_actual_check.stdout_lines == []
+
+- name: create share
+  win_share:
+    name: "{{test_win_share_name}}"
+    path: "{{test_win_share_path}}"
+    state: present
+  register: create_share
+
+- name: check if share exists
+  win_shell: Get-SmbShare | Where-Object { $_.Name -eq  '{{test_win_share_name}}' }
+  register: create_share_actual
+
+- name: assert create share
+  assert:
+    that:
+    - create_share|changed
+    - create_share_actual.stdout_lines != []
+
+- name: create share again
+  win_share:
+    name: "{{test_win_share_name}}"
+    path: "{{test_win_share_path}}"
+    state: present
+  register: create_share_again
+
+- name: check if share exists again
+  win_shell: Get-SmbShare | Where-Object { $_.Name -eq  '{{test_win_share_name}}' }
+  register: create_share_actual_again
+
+- name: assert create share again
+  assert:
+    that:
+    - not create_share_again|changed
+    - create_share_actual_again.stdout_lines == create_share_actual.stdout_lines
+
+- name: set caching mode to Programs check
+  win_share:
+    name: "{{test_win_share_name}}"
+    state: present
+    path: "{{test_win_share_path}}"
+    caching_mode: Programs
+  register: caching_mode_programs_check
+  check_mode: yes
+
+- name: get actual caching mode check
+  win_command: powershell.exe "(Get-SmbShare -Name '{{test_win_share_name}}').CachingMode"
+  register: caching_mode_programs_actual_check
+
+- name: assert caching mode to Programs check
+  assert:
+    that:
+    - caching_mode_programs_check|changed
+    - caching_mode_programs_actual_check.stdout == "Manual\r\n"
+
+- name: set caching mode to Programs
+  win_share:
+    name: "{{test_win_share_name}}"
+    state: present
+    path: "{{test_win_share_path}}"
+    caching_mode: Programs
+  register: caching_mode_programs
+
+- name: get actual caching mode
+  win_command: powershell.exe "(Get-SmbShare -Name '{{test_win_share_name}}').CachingMode"
+  register: caching_mode_programs_actual
+
+- name: assert caching mode to Programs
+  assert:
+    that:
+    - caching_mode_programs|changed
+    - caching_mode_programs_actual.stdout == "Programs\r\n"
+
+- name: set caching mode to Programs again
+  win_share:
+    name: "{{test_win_share_name}}"
+    state: present
+    path: "{{test_win_share_path}}"
+    caching_mode: Programs
+  register: caching_mode_programs_again
+
+- name: get actual caching mode again
+  win_command: powershell.exe "(Get-SmbShare -Name '{{test_win_share_name}}').CachingMode"
+  register: caching_mode_programs_actual_again
+
+- name: assert caching mode to Programs again
+  assert:
+    that:
+    - not caching_mode_programs_again|changed
+    - caching_mode_programs_actual_again.stdout == "Programs\r\n"
+
+- name: set encryption on share check
+  win_share:
+    name: "{{test_win_share_name}}"
+    state: present
+    path: "{{test_win_share_path}}"
+    encrypt: True
+  register: encrypt_on_check
+  check_mode: yes
+
+- name: get actual encrypt mode check
+  win_command: powershell.exe "(Get-SmbShare -Name '{{test_win_share_name}}').EncryptData"
+  register: encrypt_on_actual_check
+
+- name: assert set encryption on check
+  assert:
+    that:
+    - encrypt_on_check|changed
+    - encrypt_on_actual_check.stdout == "False\r\n"
+
+- name: set encryption on share
+  win_share:
+    name: "{{test_win_share_name}}"
+    state: present
+    path: "{{test_win_share_path}}"
+    encrypt: True
+  register: encrypt_on
+
+- name: get actual encrypt mode
+  win_command: powershell.exe "(Get-SmbShare -Name '{{test_win_share_name}}').EncryptData"
+  register: encrypt_on_actual
+
+- name: assert set encryption on
+  assert:
+    that:
+    - encrypt_on|changed
+    - encrypt_on_actual.stdout == "True\r\n"
+
+- name: set encryption on share again
+  win_share:
+    name: "{{test_win_share_name}}"
+    state: present
+    path: "{{test_win_share_path}}"
+    encrypt: True
+  register: encrypt_on_again
+
+- name: get actual encrypt mode again
+  win_command: powershell.exe "(Get-SmbShare -Name '{{test_win_share_name}}').EncryptData"
+  register: encrypt_on_actual
+
+- name: assert set encryption on again
+  assert:
+    that:
+    - not encrypt_on_again|changed
+    - encrypt_on_actual.stdout == "True\r\n"
+
+- name: set description check
+  win_share:
+    name: "{{test_win_share_name}}"
+    state: present
+    path: "{{test_win_share_path}}"
+    description: description
+  register: change_decription_check
+  check_mode: yes
+
+- name: get actual description check
+  win_command: powershell.exe "(Get-SmbShare -Name '{{test_win_share_name}}').Description"
+  register: change_description_actual_check
+
+- name: assert change description check
+  assert:
+    that:
+    - change_decription_check|changed
+    - change_description_actual_check.stdout == "\r\n"
+
+- name: set description
+  win_share:
+    name: "{{test_win_share_name}}"
+    state: present
+    path: "{{test_win_share_path}}"
+    description: description
+  register: change_decription
+
+- name: get actual description
+  win_command: powershell.exe "(Get-SmbShare -Name '{{test_win_share_name}}').Description"
+  register: change_description_actual
+
+- name: assert change description
+  assert:
+    that:
+    - change_decription|changed
+    - change_description_actual.stdout == "description\r\n"
+
+- name: set description again
+  win_share:
+    name: "{{test_win_share_name}}"
+    state: present
+    path: "{{test_win_share_path}}"
+    description: description
+  register: change_decription_again
+
+- name: get actual description again
+  win_command: powershell.exe "(Get-SmbShare -Name '{{test_win_share_name}}').Description"
+  register: change_description_actual_again
+
+- name: assert change description again
+  assert:
+    that:
+    - not change_decription_again|changed
+    - change_description_actual_again.stdout == "description\r\n"
+
+- name: set allow list check
+  win_share:
+    name: "{{test_win_share_name}}"
+    state: present
+    path: "{{test_win_share_path}}"
+    list: True
+  register: allow_list_check
+  check_mode: yes
+
+- name: get actual allow listing check
+  win_command: powershell.exe "(Get-SmbShare -Name '{{test_win_share_name}}').FolderEnumerationMode"
+  register: allow_list_actual_check
+
+- name: assert allow list check
+  assert:
+    that:
+    - allow_list_check|changed
+    - allow_list_actual_check.stdout == "AccessBased\r\n"
+
+- name: set allow list
+  win_share:
+    name: "{{test_win_share_name}}"
+    state: present
+    path: "{{test_win_share_path}}"
+    list: True
+  register: allow_list
+
+- name: get actual allow listing
+  win_command: powershell.exe "(Get-SmbShare -Name '{{test_win_share_name}}').FolderEnumerationMode"
+  register: allow_list_actual
+
+- name: assert allow list
+  assert:
+    that:
+    - allow_list|changed
+    - allow_list_actual.stdout == "Unrestricted\r\n"
+
+- name: set allow list again
+  win_share:
+    name: "{{test_win_share_name}}"
+    state: present
+    path: "{{test_win_share_path}}"
+    list: True
+  register: allow_list_again
+
+- name: get actual allow listing again
+  win_command: powershell.exe "(Get-SmbShare -Name '{{test_win_share_name}}').FolderEnumerationMode"
+  register: allow_list_actual_again
+
+- name: assert allow list check again
+  assert:
+    that:
+    - not allow_list_again|changed
+    - allow_list_actual_again.stdout == "Unrestricted\r\n"
+
+- name: set deny list check
+  win_share:
+    name: "{{test_win_share_name}}"
+    state: present
+    path: "{{test_win_share_path}}"
+    list: False
+  register: deny_list_check
+  check_mode: yes
+
+- name: get actual deny listing check
+  win_command: powershell.exe "(Get-SmbShare -Name '{{test_win_share_name}}').FolderEnumerationMode"
+  register: deny_list_actual_check
+
+- name: assert deny list check
+  assert:
+    that:
+    - deny_list_check|changed
+    - deny_list_actual_check.stdout == "Unrestricted\r\n"
+
+- name: set deny list
+  win_share:
+    name: "{{test_win_share_name}}"
+    state: present
+    path: "{{test_win_share_path}}"
+    list: False
+  register: deny_list
+
+- name: get actual deny listing
+  win_command: powershell.exe "(Get-SmbShare -Name '{{test_win_share_name}}').FolderEnumerationMode"
+  register: deny_list_actual
+
+- name: assert deny list
+  assert:
+    that:
+    - deny_list|changed
+    - deny_list_actual.stdout == "AccessBased\r\n"
+
+- name: set deny list again
+  win_share:
+    name: "{{test_win_share_name}}"
+    state: present
+    path: "{{test_win_share_path}}"
+    list: False
+  register: deny_list_again
+
+- name: get actual deny listing again
+  win_command: powershell.exe "(Get-SmbShare -Name '{{test_win_share_name}}').FolderEnumerationMode"
+  register: deny_list_actual_again
+
+- name: assert deny list again
+  assert:
+    that:
+    - not deny_list_again|changed
+    - deny_list_actual_again.stdout == "AccessBased\r\n"
+
+- name: set ACLs on share check
+  win_share:
+    name: "{{test_win_share_name}}"
+    state: present
+    path: "{{test_win_share_path}}"
+    full: Administrators
+    change: Users
+    read: Guests
+    deny: Remote Desktop Users
+  register: set_acl_check
+  check_mode: yes
+
+- name: get actual share ACLs check
+  win_shell: foreach ($acl in Get-SmbShareAccess -Name '{{test_win_share_name}}') { Write-Host "$($acl.AccessRight)|$($acl.AccessControlType)|$($acl.AccountName)" }
+  register: set_acl_actual_check
+
+- name: assert set ACLs on share check
+  assert:
+    that:
+    - set_acl_check|changed
+    - set_acl_actual_check.stdout == "Full|Deny|Everyone\n"
+
+- name: set ACLs on share
+  win_share:
+    name: "{{test_win_share_name}}"
+    state: present
+    path: "{{test_win_share_path}}"
+    full: Administrators
+    change: Users
+    read: Guests
+    deny: Remote Desktop Users
+  register: set_acl
+
+- name: get actual share ACLs
+  win_shell: foreach ($acl in Get-SmbShareAccess -Name '{{test_win_share_name}}') { Write-Host "$($acl.AccessRight)|$($acl.AccessControlType)|$($acl.AccountName)" }
+  register: set_acl_actual
+
+- name: assert set ACLs on share
+  assert:
+    that:
+    - set_acl|changed
+    - set_acl_actual.stdout_lines|length == 4
+    - set_acl_actual.stdout_lines[0] == 'Full|Deny|BUILTIN\\Remote Desktop Users'
+    - set_acl_actual.stdout_lines[1] == 'Read|Allow|BUILTIN\\Guests'
+    - set_acl_actual.stdout_lines[2] == 'Change|Allow|BUILTIN\\Users'
+    - set_acl_actual.stdout_lines[3] == 'Full|Allow|BUILTIN\\Administrators'
+
+- name: set ACLs on share again
+  win_share:
+    name: "{{test_win_share_name}}"
+    state: present
+    path: "{{test_win_share_path}}"
+    full: Administrators
+    change: Users
+    read: Guests
+    deny: Remote Desktop Users
+  register: set_acl_again
+
+- name: get actual share ACLs again
+  win_shell: foreach ($acl in Get-SmbShareAccess -Name '{{test_win_share_name}}') { Write-Host "$($acl.AccessRight)|$($acl.AccessControlType)|$($acl.AccountName)" }
+  register: set_acl_actual_again
+
+- name: assert set ACLs on share again
+  assert:
+    that:
+    - not set_acl_again|changed
+    - set_acl_actual_again.stdout_lines|length == 4
+    - set_acl_actual_again.stdout_lines[0] == 'Full|Deny|BUILTIN\\Remote Desktop Users'
+    - set_acl_actual_again.stdout_lines[1] == 'Read|Allow|BUILTIN\\Guests'
+    - set_acl_actual_again.stdout_lines[2] == 'Change|Allow|BUILTIN\\Users'
+    - set_acl_actual_again.stdout_lines[3] == 'Full|Allow|BUILTIN\\Administrators'
+
+- name: remove share check
+  win_share:
+    name: "{{test_win_share_name}}"
+    state: absent
+  register: remove_share_check
+  check_mode: yes
+
+- name: check if share is removed check
+  win_shell: Get-SmbShare | Where-Object { $_.Name -eq '{{test_win_share_name}}' }
+  register: remove_share_actual_check
+
+- name: assert remove share check
+  assert:
+    that:
+    - remove_share_check|changed
+    - remove_share_actual_check.stdout_lines != []
+
+- name: remove share
+  win_share:
+    name: "{{test_win_share_name}}"
+    state: absent
+  register: remove_share
+
+- name: check if share is removed
+  win_shell: Get-SmbShare | Where-Object { $_.Name -eq '{{test_win_share_name}}' }
+  register: remove_share_actual
+
+- name: assert remove share
+  assert:
+    that:
+    - remove_share|changed
+    - remove_share_actual.stdout_lines == []
+
+- name: remove share again
+  win_share:
+    name: "{{test_win_share_name}}"
+    state: absent
+  register: remove_share_again
+
+- name: check if share is removed again
+  win_shell: Get-SmbShare | Where-Object { $_.Name -eq '{{test_win_share_name}}' }
+  register: remove_share_actual_again
+
+- name: assert remove share again
+  assert:
+    that:
+    - not remove_share_again|changed
+    - remove_share_actual_again.stdout_lines == []