Setting up RemoteLaunch

Perform this procedure once per remote execution machine

This requires a separate license.  Trial licenses are available.  Local Admin privileges will be required, minimally, to unblock the test extention DLL.

  1. Download and launch the MSI file to install RemoteLaunch on the computer that will serve as the remote execution agent. 
    1. Note the installation path as it will be needed when installing execution engines.
    2. Default path:  C:\Program Files (x86)\Inflectra\Spira RemoteLaunch
  2. Download the CommandLine test extension. 
    1. https://www.inflectra.com/SpiraTeam/Downloads.aspx#TestAutomation
  3. Copy the DLL from CommandLineEngine.zip to the \extentions folder under the RemoteLaunch installation path.
    2. Note that RemoteLaunch only detects installed extentions during launch. 
    3. Ensure Windows will not blocked the DLL by right-clicking on it, selecting Properties, and checking the Unblock box.  
    5. Ensure  the DLL's security settings include the "Read & execute" permission for Users and Administrators.
    6. Consider pinning RemoteLaunch to the Start Menu
  4. Update the RemoteLaunch license.
    1. Launch RemoteLaunch from the Start menu.  
    2. Ignore warnings related to extentions not being found.
    3. When first launched, you will be prompted to update the license information.  Note that RemoteLaunch is licensed separately from Spira.
    4. Fill in the Organization and License Key fields.
    5. Exit and relaunch RemoteLaunch.  It should now launch and reside in the systray.
    6. If any warnings are issued during re-launch, resolve the issue before proceeding. 
  5. Configure RemoteLaunch Client Setup.
    1. Right-click on the RemoteLaunch icon and select Configuration.
    2. Select the Client Setup tab and populate all fields.
      1. Be sure to test the SpiraTeam connection once the URL and login credentials have been entered.
      2. Be sure to change the default Automation Host Token. This will be needed when configuring automated tests in Spira.
        1. Use something descriptive and UNIQUE!
        2. Why not just use the computer name?
          1. From CMD prompt:  echo %computername%
    4. Click Save.  The Save button will be greyed out if no changed are pending.
    5. Switch to the "Setup: Command-Line Automation Engine" tab.
    6. Notice the RunAs Administrator checkbox.  Enable it only if required by the scripts to be executed.
    7. The remaining defaults are fine as-is.
    8. If any changes were made, click Save.
    9. Switch back to the Status tab.
    10. Click Force Poll.  The Next Update counter should be reset to 00:00:59:59 (assuming the polling frequency was set to 60 minutes.)
      1. If polling was not successful, resolve the issue before proceding.
    11. Click Close.  RemoteLaunch will minimize to the systray and will still be running in the background.
  6. Client-side setup is now complete.

Setting up Command-Line Test Automation Engine

Perform this procedure once inside Spira.

  1. Enable Command-Line engine.
    1. Log into Spira as an Administrator.
    2. From the System: Admin Home screen, Navigate to Test Automation (under Integration)
    3. Click Edit on the Command-Line engine.
      1. If it is not present, click Add and complete the form as follows:
        1. Name:  Command-Line
        2. Description: Engine that will execute a generic command-line executable
        3. Token: CommandLine
          1. This the one entry to get exactly right!
        4. Active: Yes
      2. Click Insert
    4. Set Active to Yes.
    5. Click Save.
  2. Add new Document Types
    1. Add a new Document Type for each type of command line script, such as PowerShell.
      1. Administration >> Documents >> Type
      2. Consider creating a "code review" approval workflow.
    2. Automated Test Scripts often rely on separate files that contain additional library functions or configuration data.  Since each Document Type can be associated with a Workflow, consider creating a Document Type for managing script configuration.
    3. Document Types are not the same was MIME types! There is no need to create a Document Type for every possible type of file that will be managed by Spira.
  3. Add Document Folders.
    1. If using Rapise with Spira, new tests are created off the Root.  
    2. For Command-Line scripts, create a new folder off the root for each type of command line script, such as PowerShell.
    3. Create any additional subfolders needed to group scripts together logically.  Perhaps mirror the Test Case folder structure?

Perform this procedure once per Automation Host per Spira Product

Don't bother adding Automation Hosts to a Template. The hosts do not appear in existing template-linked Products, nor do they appear in new template-linked Products.

  1. Log into Spira and select a Product or Product Template.
  2. Navigate to Automation Hosts (from the Artifacts drop-down.)
  3. Click New Host.
  4. Enter a Name (display name) and the exact Token specified during RemoteLaunch client configuration.
  5. Click Save.

Creating PowerShell-based Automated Test Cases

Perform this once per Automated Test Case

You have a choice of attaching or linking a script. 

  • "Attached" refers to entering (presumably via copy/paste) the script code directly into the Spira Test Case UI.  This will result in a new Document being created and is appropriate for smaller script that are self-contained.
  • "Linked" refers to using a script that was uploaded as a Document.  This method is appropriate for more complex scripts that require external files.

Attached Method

  1. Spira will create a new Document containing the script.  If the script requires supporting files, consider first creating a new Document folder with the same name as the Test Case.
  2. Navigate to Test Cases and select the appropriate parent Test Case folder.
  3. Create a new Test Case
    1. Click New Test Case
    2. Enter a Name and select a Test Case Type such as "Unit" or "Functional".
      1. Do not confuse this with Document Type.
    3. Click Save.
  4. Add Automation details.
    1. Click on the Name of the new Test Case.
      1. There is no need to create Test Steps. 
    2. Scroll down to the Automation section.
    3. Select "Command-Line" from the Automation Engine drop-down.
    4. Enter a new Filename. This is a bit deceptive as it actually refers to the execution engine executable and parameters.
      1. powershell.exe should exist in the remote test execution machine's default path.  If not, the path to the PowerShell executable can be determined by launch PowerShell and entering $PSHOME 
      2. The token "${filename}" will be substituted for the name of the script file downloaded from Spira by RemoteLaunch and is therefore is a required element.
      3. powershell.exe only processes script files that have a file extension of .ps1, but Spira sends the script to RemoteLaunch as a .txt file.  Fortunately, there is an easy workaround!
      4. Here is the correct Filename to use for PowerShell scripts:  
        1. powershell.exe | -command Invoke-Expression $([System.IO.File]::ReadAllText('{filename}'))
          1. So PowerShell is told to invoke a command as opposed to a file
          2. The command is Invoke-Expression which allows PowerShell to execute code within a string. 
          3. The string to be executed is being populated via the ReadAllText
    5. Accept the default Version of 1.0
    6. Select a Document Type such as "PowerShell Script".
    7. Select a Document Folder.  
    8. Click Edit Parameters and create each input parameter expected by the script.
    9. Paste the script code into the Test Script textbox.
      1. In PowerShell, Test Case parameters can be consumed using Tokens.
        1. $Param1="${Param1}"  $Param2="${Param2}"
      2. Once defined, the variables are used normally.
        1. $ParamLength
      3. Example:  
# Parameter values are being set via Test Case parameters.

$Param1="${Param1}"  

$Param2="${Param2}"

Start-Sleep -seconds 3

Write-Output ("Test Passed.  Param1 = {0}, PowerShell version: {1}" -f $Param1, (Get-Host).Version.ToString())

Write-Output ("              Param2 = {0}, PowerShell location:{1}" -f $Param2, $PSHOME)
    1. Save the Test Case.
    2. If necessary, go through the Workflow steps required to move the Test Case to the "Ready for Test" status.

Linked Method

  1. Place the script and any supporting files on the remote test execution machine or a network share accessible by the host. 
  2. Navigate to Test Cases and select the appropriate parent folder.
  3. Create a new Test Case
    1. Click New Test Case
    2. Enter a Name and select a test Type such as Unit or Functional.  
    3. Click Save.
  4. Add Automation details.
    1. Click on the Name of the new Test Case.
    2. There is no need to create Test Steps. 
    3. Scroll down to the Automation section.
    4. Select "Command-Line" from the Automation Engine drop-down.
    5. Select a Script Type of Linked. 
      1. This option can only be selected once Automation Engine is set to Command-Line.
    6. Enter a new Filename. This is a bit deceptive as it actually refers to the execution engine executable and parameters.
      1. powershell.exe should exist in the remote test execution machine's default path.  If not, the path to the PowerShell executable can be determined by launch PowerShell and entering $PSHOME 
      2. Specify the name and path of the script.
      3. Example:
        1. powershell.exe | -file "C:\scripts\hw.ps1" | -name "value"
    7. Click Edit Parameters and create each input parameter expected by the script.
      1. Here is how to add  Command Line Arguments to a PowerShell script:
      2. param (     [string]$Param1  = 'P1_Default',     [string]$Param2  = 'P2_Default')
    8. Save the Test Case.
    9. If necessary, go through the Workflow steps required to move the Test Case to the "Ready for Test" status.

Create a Test Set

  1. Navigate to Test Sets and select a Folder for the new Test Set.
  2. Click New Test Set.
  3. Enter a Name and any other needed properties such as Release.
  4. Click Save and click on the Name of the new Test Set.
  5. Select an Automation Host from the drop-down.
  6. Select a Recurrence value from the drop-down.  
    1. Notable options include One Time, Hourly, and Daily.
  7. Fill in other fields such as Description and Owner as necessary.
  8. Scroll down to the Test Cases section and click Add.
  9. Select the appropriate folder or use the Search function to find the Test Cases to be added.
  10. Check the box next to each script to be added and click Save.
  11. Add additional Test Cases as required.  You may select the same Test Case multiple times.
  12. For each Test Case, check the box next to the Test Case name and click Edit Parameters.
  13. If no parameter is specified, the default values from the Test Case will be used.
  14. Click Save.

Executing the Test Set

It's about time, right?  Make sure RemoteLaunch is running on the Automation Host specified in the Test Set and click the Execute button at the top of the Test Sets screen.

There is also an Execute Tests button located in the Test Cases section of the Test Script, but this is for executing manual tests only.  This is also the case for the Re-Run button within a Test Run.