win_say: Fix issue, add integration tests (#26089)

* win_say: Fix issue, add integration test

This PR includes:
- Make speed_speech an integer parameter
- Test for empty parameters too
- Add integration tests

* Improve the $speech_speed parameter handling

As requested

lib/ansible/modules/windows/win_say.ps1

@@ -27,44 +27,36 @@ $msg_file = Get-AnsibleParam -obj $params -name "msg_file" -type "path"
 $start_sound_path = Get-AnsibleParam -obj $params -name "start_sound_path" -type "path"
 $end_sound_path = Get-AnsibleParam -obj $params -name "end_sound_path" -type "path"
 $voice = Get-AnsibleParam -obj $params -name "voice" -type "str"
-$speech_speed = Get-AnsibleParam -obj $params -name "speech_speed" -type "str"
+$speech_speed = Get-AnsibleParam -obj $params -name "speech_speed" -type "int" -default 0
 
 $result = @{
     changed = $false
 }
 
-$speed = 0
 $words = $null
 
-if ($speech_speed -ne $null) {
+f ($speech_speed -lt -10 -or $speech_speed -gt 10) {
-   try {
+   Fail-Json $result "speech_speed needs to a integer in the range -10 to 10.  The value $speech_speed is outside this range."
-      $speed = [convert]::ToInt32($speech_speed, 10)
-   } catch {
-      Fail-Json $result "speech_speed needs to a integer in the range -10 to 10.  The value $speech_speed could not be converted to an integer."
-   }
-   if ($speed -lt -10 -or $speed -gt 10) {
-      Fail-Json $result "speech_speed needs to a integer in the range -10 to 10.  The value $speech_speed is outside this range."
-   }
 }
 
-if ($msg_file -ne $null -and $msg -ne $null) {
+if ($msg_file -and $msg) {
    Fail-Json $result "Please specify either msg_file or msg parameters, not both"
 }
 
-if ($msg_file -eq $null -and $msg -eq $null -and $start_sound_path -eq $null -and $end_sound_path -eq $null) {
+if (-not $msg_file -and -not $msg -and -not $start_sound_path -and -not $end_sound_path) {
    Fail-Json $result "No msg_file, msg, start_sound_path, or end_sound_path parameters have been specified.  Please specify at least one so the module has something to do"
 }
 
-if ($msg_file -ne $null) {
+if ($msg_file) {
-   if (Test-Path $msg_file) {
+   if (Test-Path -Path $msg_file) {
       $words = Get-Content $msg_file | Out-String
    } else {
       Fail-Json $result "Message file $msg_file could not be found or opened.  Ensure you have specified the full path to the file, and the ansible windows user has permission to read the file."
    }
 }
 
-if ($start_sound_path -ne $null) {
+if ($start_sound_path) {
-   if (Test-Path $start_sound_path) {
+   if (Test-Path -Path $start_sound_path) {
       if (-not $check_mode) {
          (new-object Media.SoundPlayer $start_sound_path).playSync()
       }
@@ -73,14 +65,14 @@ if ($start_sound_path -ne $null) {
    }
 }
 
-if ($msg -ne $null) {
+if ($msg) {
    $words = $msg
 }
 
-if ($words -ne $null) {
+if ($words) {
    Add-Type -AssemblyName System.speech
    $tts = New-Object System.Speech.Synthesis.SpeechSynthesizer
-   if ($voice -ne $null) {
+   if ($voice) {
       try {
          $tts.SelectVoice($voice)
       } catch  [System.Management.Automation.MethodInvocationException] {
@@ -89,8 +81,8 @@ if ($words -ne $null) {
    }
 
    $result.voice = $tts.Voice.Name
-   if ($speed -ne 0) {
+   if ($speech_speed -ne 0) {
-      $tts.Rate = $speed
+      $tts.Rate = $speech_speed
    }
    if (-not $check_mode) {
        $tts.Speak($words)
@@ -98,8 +90,8 @@ if ($words -ne $null) {
    $tts.Dispose()
 }
 
-if ($end_sound_path -ne $null) {
+if ($end_sound_path) {
-   if (Test-Path $end_sound_path) {
+   if (Test-Path -Path $end_sound_path) {
       if (-not $check_mode) {
          (new-object Media.SoundPlayer $end_sound_path).playSync()
       }

lib/ansible/modules/windows/win_say.py

@@ -25,7 +25,6 @@ ANSIBLE_METADATA = {'metadata_version': '1.0',
                     'status': ['preview'],
                     'supported_by': 'community'}
 
-
 DOCUMENTATION = r'''
 ---
 module: win_say
@@ -37,75 +36,73 @@ description:
 options:
   msg:
     description:
-      - The text to be spoken.  Use either msg or msg_file.  Optional so that you can use this module just to play sounds.
+      - The text to be spoken.
-    required: false
+      - Use either C(msg) or C(msg_file).
-    default: none
+      - Optional so that you can use this module just to play sounds.
   msg_file:
     description:
-      - Full path to a windows format text file containing the text to be spokend.  Use either msg or msg_file.  Optional so that you can use this module
+      - Full path to a windows format text file containing the text to be spokend.
-        just to play sounds.
+      - Use either C(msg) or C(msg_file).
-    required: false
+      - Optional so that you can use this module just to play sounds.
-    default: none
   voice:
     description:
-      - Which voice to use. See notes for how to discover installed voices.  If the requested voice is not available the default voice will be used.
+      - Which voice to use. See notes for how to discover installed voices.
-        Example voice names from Windows 10 are 'Microsoft Zira Desktop' and 'Microsoft Hazel Desktop'.
+      - If the requested voice is not available the default voice will be used.
-    required: false
+        Example voice names from Windows 10 are C(Microsoft Zira Desktop) and C(Microsoft Hazel Desktop).
     default: system default voice
   speech_speed:
     description:
-      - How fast or slow to speak the text.  Must be an integer value in the range -10 to 10.  -10 is slowest, 10 is fastest.
+      - How fast or slow to speak the text.
-    required: false
+      - Must be an integer value in the range -10 to 10.
+      - -10 is slowest, 10 is fastest.
     default: 0
   start_sound_path:
     description:
-      - Full path to a C(.wav) file containing a sound to play before the text is spoken.  Useful on conference calls to alert other speakers that ansible
+      - Full path to a C(.wav) file containing a sound to play before the text is spoken.
-        has something to say.
+      - Useful on conference calls to alert other speakers that ansible has something to say.
-    required: false
-    default: null
   end_sound_path:
     description:
-      - Full path to a C(.wav) file containing a sound to play after the text has been spoken.  Useful on conference calls to alert other speakers that
+      - Full path to a C(.wav) file containing a sound to play after the text has been spoken.
-        ansible has finished speaking.
+      - Useful on conference calls to alert other speakers that ansible has finished speaking.
-    required: false
+author:
-    default: null
+- Jon Hawkesworth (@jhawkesworth)
-author: "Jon Hawkesworth (@jhawkesworth)"
 notes:
    - Needs speakers or headphones to do anything useful.
    - |
-     To find which voices are installed, run the following powershell commands.
+     To find which voices are installed, run the following Powershell commands.
 
                  Add-Type -AssemblyName System.Speech
-
                  $speech = New-Object -TypeName System.Speech.Synthesis.SpeechSynthesizer
-
                  $speech.GetInstalledVoices() | ForEach-Object { $_.VoiceInfo }
-
                  $speech.Dispose()
 
-   - Speech can be surprisingly slow, so its best to keep message text short.
+   - Speech can be surprisingly slow, so it's best to keep message text short.
 '''
 
 EXAMPLES = r'''
-  # Warn of impending deployment
+- name: Warn of impending deployment
-- win_say:
+  win_say:
     msg: Warning, deployment commencing in 5 minutes, please log out.
-  # Using a different voice and a start sound
+
-- win_say:
+- name: Using a different voice and a start sound
+  win_say:
     start_sound_path: C:\Windows\Media\ding.wav
     msg: Warning, deployment commencing in 5 minutes, please log out.
     voice: Microsoft Hazel Desktop
-  # example with start and end sound
+
-- win_say:
+- name: With start and end sound
+  win_say:
     start_sound_path: C:\Windows\Media\Windows Balloon.wav
     msg: New software installed
     end_sound_path: C:\Windows\Media\chimes.wav
-  # text from file example
+
-- win_say:
+- name: Text from file example
+  win_say:
     start_sound_path: C:\Windows\Media\Windows Balloon.wav
     msg_file: AppData\Local\Temp\morning_report.txt
     end_sound_path: C:\Windows\Media\chimes.wav
 '''
+
 RETURN = r'''
 message_text:
     description: the text that the module attempted to speak

test/integration/targets/win_say/aliases

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

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

@@ -0,0 +1,36 @@
+- name: Warn of impending deployment
+  win_say:
+    msg: Warning, deployment commencing in 5 minutes, please log out.
+
+- name: Using a different voice and a start sound
+  win_say:
+    msg: Warning, deployment commencing in 5 minutes, please log out.
+    start_sound_path: C:\Windows\Media\ding.wav
+    voice: Microsoft Hazel Desktop
+
+- name: Example with start and end sound
+  win_say:
+    msg: New software installed
+    start_sound_path: C:\Windows\Media\Windows Balloon.wav
+    end_sound_path: C:\Windows\Media\chimes.wav
+
+- name: Create message file
+  win_copy:
+    content: Stay calm and carry on
+    dest: C:\Windows\Temp\win_say_message.txt
+
+- name: Text from file example
+  win_say:
+    msg_file: C:\Windows\Temp\win_say_message.txt
+    start_sound_path: C:\Windows\Media\Windows Balloon.wav
+    end_sound_path: C:\Windows\Media\chimes.wav
+
+- name: Remove message file
+  win_file:
+    path: C:\Windows\Temp\win_say_message.txt
+    state: absent
+
+- name: Different spech peed
+  win_say:
+    speech_speed: 5
+    msg: Stay calm and proceed to the closest fire exit.