Windows: Add backup parameter to modules (#50033)

* Windows: Add backup parameter to modules

This PR adds a backup infrastructure for modules.

* Fixes based on review feedback

* Various fixes to check-mode and backup

* Add integration tests

* Fix win_xml integration test

* Add backup support to copy action plugin

* Added integration tests

* Improve test efficiencies and other minor impv

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

@@ -172,6 +172,24 @@
     that:
     - copy_file_again is not changed
 
+- name: copy single file (backup)
+  win_copy:
+    content: "{{ lookup('file', 'foo.txt') }}\nfoo bar"
+    dest: '{{test_win_copy_path}}\foo-target.txt'
+    backup: yes
+  register: copy_file_backup
+
+- name: check backup_file
+  win_stat:
+    path: '{{ copy_file_backup.backup_file }}'
+  register: backup_file
+
+- name: assert copy single file (backup)
+  assert:
+    that:
+    - copy_file_backup is changed
+    - backup_file.stat.exists == true
+
 - name: copy single file to folder (check mode)
   win_copy:
     src: foo.txt

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

@@ -43,12 +43,17 @@
   win_lineinfile: dest={{win_output_dir}}/test.txt state=present line="New line at the beginning" insertbefore="BOF" backup=yes
   register: result
 
+- name: check backup_file
+  win_stat:
+    path: '{{ result.backup_file }}'
+  register: backup_file
+
 - name: assert that the line was inserted at the head of the file
   assert:
     that:
-    - "result.changed == true"
-    - "result.msg == 'line added'"
-    - "result.backup != ''"
+    - result.changed == true
+    - result.msg == 'line added'
+    - backup_file.stat.exists == true
 
 - name: stat the backup file
   win_stat: path={{result.backup}}

test/integration/targets/win_module_utils/library/backup_file_test.ps1

@@ -0,0 +1,89 @@
+#!powershell
+
+# Copyright: (c) 2019, Dag Wieers (@dagwieers) <dag@wieers.com>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+#AnsibleRequires -CSharpUtil Ansible.Basic
+#Requires -Module Ansible.ModuleUtils.Backup
+
+$module = [Ansible.Basic.AnsibleModule]::Create($args, @{})
+
+Function Assert-Equals {
+    param(
+        [Parameter(Mandatory=$true, ValueFromPipeline=$true)][AllowNull()]$Actual,
+        [Parameter(Mandatory=$true, Position=0)][AllowNull()]$Expected
+    )
+
+    $matched = $false
+    if ($Actual -is [System.Collections.ArrayList] -or $Actual -is [Array]) {
+        $Actual.Count | Assert-Equals -Expected $Expected.Count
+        for ($i = 0; $i -lt $Actual.Count; $i++) {
+            $actual_value = $Actual[$i]
+            $expected_value = $Expected[$i]
+            Assert-Equals -Actual $actual_value -Expected $expected_value
+        }
+        $matched = $true
+    } else {
+        $matched = $Actual -ceq $Expected
+    }
+
+    if (-not $matched) {
+        if ($Actual -is [PSObject]) {
+            $Actual = $Actual.ToString()
+        }
+
+        $call_stack = (Get-PSCallStack)[1]
+        $module.Result.test = $test
+        $module.Result.actual = $Actual
+        $module.Result.expected = $Expected
+        $module.Result.line = $call_stack.ScriptLineNumber
+        $module.Result.method = $call_stack.Position.Text
+        $module.FailJson("AssertionError: actual != expected")
+    }
+}
+
+$tmp_dir = $module.Tmpdir
+
+$tests = @{
+    "Test backup file with missing file" = {
+        $actual = Backup-File -path (Join-Path -Path $tmp_dir -ChildPath "missing")
+        $actual | Assert-Equals -Expected $null
+    }
+
+    "Test backup file in check mode" = {
+        $orig_file = Join-Path -Path $tmp_dir -ChildPath "file-check.txt"
+        Set-Content -Path $orig_file -Value "abc"
+        $actual = Backup-File -path $orig_file -WhatIf
+
+        (Test-Path -LiteralPath $actual) | Assert-Equals -Expected $false
+
+        $parent_dir = Split-Path -Path $actual
+        $backup_file = Split-Path -Path $actual -Leaf
+        $parent_dir | Assert-Equals -Expected $tmp_dir
+        ($backup_file -match "^file-check\.txt\.$pid\.\d{8}-\d{6}\.bak$") | Assert-Equals -Expected $true
+    }
+
+    "Test backup file" = {
+        $content = "abc"
+        $orig_file = Join-Path -Path $tmp_dir -ChildPath "file.txt"
+        Set-Content -Path $orig_file -Value $content
+        $actual = Backup-File -path $orig_file
+
+        (Test-Path -LiteralPath $actual) | Assert-Equals -Expected $true
+
+        $parent_dir = Split-Path -Path $actual
+        $backup_file = Split-Path -Path $actual -Leaf
+        $parent_dir | Assert-Equals -Expected $tmp_dir
+        ($backup_file -match "^file\.txt\.$pid\.\d{8}-\d{6}\.bak$") | Assert-Equals -Expected $true
+        (Get-Content -Path $actual -Raw) | Assert-Equals -Expected "$content`r`n"
+    }
+}
+
+foreach ($test_impl in $tests.GetEnumerator()) {
+    $test = $test_impl.Key
+    &$test_impl.Value
+}
+
+$module.Result.res = 'success'
+
+$module.ExitJson()

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

@@ -163,3 +163,13 @@
     that:
     - not add_type_test is failed
     - add_type_test.res == 'success'
+
+- name: call module with BackupFile tests
+  backup_file_test:
+  register: backup_file_test
+
+- name: assert call module with BackupFile tests
+  assert:
+    that:
+    - not backup_file_test is failed
+    - backup_file_test.res == 'success'

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

@@ -119,6 +119,39 @@
     that:
         - '"FC: no differences encountered" in diff_result.stdout'
 
+# TEST BACKUP
+- name: test backup (check_mode)
+  win_template:
+    src: foo.j2
+    dest: '{{ win_output_dir }}/foo.unix.templated'
+    backup: yes
+  register: cm_backup_result
+  check_mode: yes
+
+- name: verify that a backup_file was returned
+  assert:
+    that:
+      - cm_backup_result is changed
+      - cm_backup_result.backup_file is not none
+
+- name: test backup (normal mode)
+  win_template:
+    src: foo.j2
+    dest: '{{ win_output_dir }}/foo.unix.templated'
+    backup: yes
+  register: nm_backup_result
+
+- name: check backup_file
+  win_stat:
+    path: '{{ nm_backup_result.backup_file }}'
+  register: backup_file
+
+- name: verify that a backup_file was returned
+  assert:
+    that:
+    - nm_backup_result is changed
+    - backup_file.stat.exists == true
+
 - name: create template dest directory
   win_file:
     path: '{{win_output_dir}}\directory'

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

@@ -70,7 +70,7 @@
 - name: check attribute change result
   assert:
     that:
-    - not attribute_changed_result is changed
+    - attribute_changed_result is not changed
 
 # This testing is for https://github.com/ansible/ansible/issues/48471
 # The issue was that an .xml with no encoding declaration, but a UTF8 BOM
@@ -105,6 +105,26 @@
     that:
       - sha1_checksum.stat.checksum == 'e3e18c3066e1bfce9a5cf87c81353fa174440944'
 
+- name: change a text value in a file with UTF8 BOM and armenian characters in the description
+  win_xml:
+    path: "{{ win_output_dir }}\\plane-utf8-bom-armenian-characters.xml"
+    xpath: '/plane/year'
+    type: text
+    fragment: '1989'
+    backup: yes
+  register: test_backup
+
+- name: check backup_file
+  win_stat:
+    path: '{{ test_backup.backup_file }}'
+  register: backup_file
+
+- name: Check backup_file
+  assert:
+    that:
+    - test_backup is changed
+    - backup_file.stat.exists == true
+
 - name: change a text value in a file with UTF-16 BE BOM and Chinese characters in the description
   win_xml:
     path: "{{ win_output_dir }}\\plane-utf16be-bom-chinese-characters.xml"