win_wait_for_process: Fixes and integration tests (#44801)

* win_wait_for_process: Add integration tests

* Disable reporting changes

* Added more tests checking PID

* Various improvements

This PR includes:
- Use Get-Process instead of CIM Win32_Process
- Rewrite of process filter logic (speedup)
- Fix error messages
- Fixes to documentation, examples and return output

* win_wait_for_process: Limit to PowerShell 4 and higher

* Improve RESULT documentation

* Last minute fixes for CI

* Catch Powershell exceptions

* Increase timeout to make tests more stable

lib/ansible/modules/windows/win_wait_for_process.py

@@ -17,29 +17,50 @@ module: win_wait_for_process
 version_added: '2.7'
 short_description: Waits for a process to exist or not exist before continuing.
 description:
-- Waiting for a process to start or stop is useful when Windows services
-  behave poorly and do not enumerate external dependencies in their
-  manifest.
+- Waiting for a process to start or stop.
+- This is useful when Windows services behave poorly and do not enumerate external dependencies in their manifest.
 options:
   process_name_exact:
     description:
-      - The name of the process(es) for which to wait.
-      - Must inclue the file extension of the process binary (.exe)
+    - The name of the process(es) for which to wait.
+    type: str
   process_name_pattern:
-     description:
-      - RegEx pattern matching desired process(es)
+    description:
+    - RegEx pattern matching desired process(es).
+    type: str
   sleep:
     description:
     - Number of seconds to sleep between checks.
     - Only applies when waiting for a process to start.  Waiting for a process to start
       does not have a native non-polling mechanism. Waiting for a stop uses native PowerShell
       and does not require polling.
+    type: int
     default: 1
   process_min_count:
     description:
       - Minimum number of process matching the supplied pattern to satisfy C(present) condition.
       - Only applies to C(present).
+    type: int
     default: 1
+  pid:
+    description:
+    - The PID of the process.
+    type: int
+  owner:
+    description:
+    - The owner of the process.
+    - Requires PowerShell version 4.0 or newer.
+    type: str
+  pre_wait_delay:
+    description:
+    - Seconds to wait before checking processes.
+    type: int
+    default: 0
+  post_wait_delay:
+    description:
+    - Seconds to wait after checking for processes.
+    type: int
+    default: 0
   state:
     description:
     - When checking for a running process C(present) will block execution
@@ -52,12 +73,14 @@ options:
     - If, while waiting for C(absent), new processes matching the supplied
       pattern are started, these new processes will not be included in the
       action.
+    type: str
     default: present
-    choices: [ absent,  present ]
+    choices: [ absent, present ]
   timeout:
     description:
     - The maximum number of seconds to wait for a for a process to start or stop
       before erroring out.
+    type: int
     default: 300
 author:
 - Charles Crossan (@crossan007)
@@ -66,34 +89,43 @@ author:
 EXAMPLES = r'''
 - name: Wait 300 seconds for all Oracle VirtualBox processes to stop. (VBoxHeadless, VirtualBox, VBoxSVC)
   win_wait_for_process:
-    process_name: "v(irtual)?box(headless|svc)?"
+    process_name: 'v(irtual)?box(headless|svc)?'
     state: absent
     timeout: 500
 
-
 - name: Wait 300 seconds for 3 instances of cmd to start, waiting 5 seconds between each check
   win_wait_for_process:
-    process_name: "cmd\\.exe"
+    process_name_exact: cmd
     state: present
     timeout: 500
     sleep: 5
     process_min_count: 3
-
 '''
 
 RETURN = r'''
 elapsed:
-  description: The elapsed seconds between the start of poll and the end of the
-    module.
+  description: The elapsed seconds between the start of poll and the end of the module.
   returned: always
   type: float
   sample: 3.14159265
-changed:
-  description: True if a process was started or stopped during the module execution.
-  returned: always
-  type: bool
 matched_processes:
-  description: Count of processes stopped or started.
+  description: List of matched processes (either stopped or started)
   returned: always
-  type: int
+  type: complex
+  contains:
+    name:
+      description: The name of the matched process
+      returned: always
+      type: str
+      sample: svchost
+    owner:
+      description: The owner of the matched process
+      returned: when supported by PowerShell
+      type: str
+      sample: NT AUTHORITY\SYSTEM
+    pid:
+      description: The PID of the matched process
+      returned: always
+      type: int
+      sample: 7908
 '''