Add support for pester tags (#57918)

* correct argument name

* added documentation

* adding missing version_added to doc

* correcting description in docs

* change type to list

* add tests

* correct test file

lib/ansible/modules/windows/win_pester.ps1

@@ -14,6 +14,7 @@ $diff_mode = Get-AnsibleParam -obj $params -name "_ansible_diff" -type "bool" -d
 # Modules parameters
 
 $path = Get-AnsibleParam -obj $params -name "path" -type "str" -failifempty $true
+$tags = Get-AnsibleParam -obj $params -name "tags" -type "list"
 $minimum_version = Get-AnsibleParam -obj $params -name "minimum_version" -type "str" -failifempty $false
 
 $result = @{
@@ -72,6 +73,9 @@ If ($result.pester_version -ge "4.0.0") {
     }
 }
 
+if($tags.count){
+    $Parameters.Tag = $tags
+}
 # Run Pester tests
 If (Test-Path -LiteralPath $path -PathType Leaf) {
     if ($check_mode) {

lib/ansible/modules/windows/win_pester.py

@@ -26,6 +26,12 @@ options:
       - If the path is a folder, the module will consider all ps1 files as Pester tests.
     type: str
     required: true
+  tags:
+    description:
+      - Runs only tests in Describe blocks with specified Tags values.
+      - Accepts multiple comma seperated tags.
+    type: list
+    version_added: '2.9'
   version:
     description:
       - Minimum version of the pester module that has to be available on the remote host.
@@ -47,6 +53,11 @@ EXAMPLES = r'''
   win_pester:
     path: C:\Pester
 
+- name: Run the pester tests only for the tags specified.
+  win_pester:
+    path: C:\Pester\TestScript.tests
+    tags: CI,UnitTests
+
 # Run pesters tests files that are present in the specified folder
 # ensure that the pester module version available is greater or equal to the version parameter.
 - name: Run the pester test present in a folder and check the Pester module version.

test/integration/targets/win_pester/files/test03.test.ps1

@@ -0,0 +1,11 @@
+Describe -Name 'Test03 without tag' {
+    It -name 'Third Test without tag' {
+        {Get-Service} | Should Not Throw
+    }
+}
+
+Describe -Name 'Test03 with tag' -Tag tag1 {
+    It -name 'Third Test with tag' {
+        {Get-Service} | Should Not Throw
+    }
+}

test/integration/targets/win_pester/tasks/test.yml

@@ -53,9 +53,9 @@
     that:
     - dir_with_ending_slash.changed
     - not dir_with_ending_slash.failed
-    - dir_with_ending_slash.output.TotalCount == 2
+    - dir_with_ending_slash.output.TotalCount == 4
 
-- name: Run Pester test(s) located in a folder. Folder path does not end with '\' 
+- name: Run Pester test(s) located in a folder. Folder path does not end with '\'
   win_pester:
     path: '{{test_win_pester_path}}'
   register: dir_without_ending_slash
@@ -65,7 +65,7 @@
     that:
     - dir_without_ending_slash.changed
     - not dir_without_ending_slash.failed
-    - dir_without_ending_slash.output.TotalCount == 2
+    - dir_without_ending_slash.output.TotalCount == 4
 
 - name: Run Pester test(s) located in a folder and with a minimum mandatory Pester version
   win_pester:
@@ -78,4 +78,27 @@
     that:
     - dir_with_version.changed
     - not dir_with_version.failed
-    - dir_with_version.output.TotalCount == 2
+    - dir_with_version.output.TotalCount == 4
+
+- name: Run Pester test(s) specifying a test file without specifying tag
+  win_pester:
+    path: '{{test_win_pester_path}}\test03.test.ps1'
+  register: test_no_tag
+
+- name: assert Run Pester test(s) specifying a test file and all tests executed
+  assert:
+    that:
+    - test_no_tag.changed
+    - test_no_tag.output.TotalCount == 2
+
+- name: Run Pester test(s) specifying a test file with tag
+  win_pester:
+    path: '{{test_win_pester_path}}\test03.test.ps1'
+    tags: tag1
+  register: test_with_tag
+
+- name: Run Pester test(s) specifying a test file and only test with sepecified tag executed
+  assert:
+    that:
+    - test_with_tag.changed
+    - test_with_tag.output.TotalCount == 1