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

2 files changed, 99 insertions, 0 deletions

diff --git a/test/integration/targets/win_module_utils/library/backup_file_test.ps1 b/test/integration/targets/win_module_utils/library/backup_file_test.ps1
new file mode 100644
index 0000000000..5f920ab2bd
--- /dev/null
+++ b/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()
diff --git a/test/integration/targets/win_module_utils/tasks/main.yml b/test/integration/targets/win_module_utils/tasks/main.yml
index 18fca76ccd..4e0735402e 100644
--- a/test/integration/targets/win_module_utils/tasks/main.yml
+++ b/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'