First, import the module:
PS> Import-Module .\PSTestRail
Use the Initialize-TestRailSession
to initialise the module with your TestRail API credentials (you must have API access enabled). There are two equivalent parameter sets for the Initialize-TestRailSession
PS> Initialize-TestRailSession [-Uri] <uri> [-User] <string> [-Password] <string>
and
PS> Initialize-TestRailSession [-Uri] <uri> [-User] <string> [-ApiKey] <string>
Since the TestRail API doesn't distinguish between your normal login password and a configured API Key, -ApiKey
is just an alias for -Password
, but helps to make your intentions clear when scripting.
There's no return value here - it just sets up an internal instance of the .Net TestRail API Client. This means you won't get an error if you pass bogus information until the first time you try an API operation.
If you have a hosted TestRail subscription, your Uri will be https://<tenantname>.testrail.net/
. The API endpoint suffix is added by the client.
Initialise the TestRail session
PS> Initialize-TestRailSession -Uri https://tenant.testrail.net/ -User someuser -ApiKey myapikey
Enumerate completed projects (-IsCompleted
defaults to $false
)
PS> Get-TestRailProjects -IsCompleted $true
Enumerate Test Suites associated with a project
PS> Get-TestRailSuites -ProjectId 76
or even
PS> Get-TestRailProject -ProjectId 76 | Get-TestRailSuites
or perhaps
PS> Get-TestRailProjects | Where name -eq "My Project" | Get-TestRailSuites
PS> $project = Get-TestRailProjects | Where name -eq "My Project"
PS> $suite = Get-TestRailSuites -ProjectId $project.id | Where name -eq "Test Suite"
PS> $run = Start-TestRailRun -ProjectId $project.id -SuiteId $suite.id -Name "My Test Run" -AssignedTo 1 -Description "A test run where I test things" -CaseId 17,36,142,86
# Do some tests
PS> $results = @()
PS> $results += New-TestRailResult -CaseId 17 -StatusId 1 -Comment "Everything was fine" -Elapsed "3m" -CustomFields @{ "custom_colour" = "Blue" }
PS> $results += New-TestRailResult -CaseId 36 -StatusId 2 -Comment "Something useful about the test case" -CustomFields @{ "detail" = "The custom_ prefix will be added automatically"; colour = "Yellow" }
PS> Add-TestRailResultsForCases -RunId $run.id -Results $results
PS> Stop-TestRailRun -RunId $run.id
To call the TestRail Api I am using Invoke-RestMethod
and I am just returning the results from this call forward. (https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/invoke-restmethod?view=powershell-7#outputs).
Credits to original owner of this: https://github.com/wermspowke/PSTestRail
This module tries to use Powershell Verbs properly. If the TestRail API method conflicts with the Powershell meaning of the Verb then I've used the Powershell convention. This hopefully makes it less confusing to people already familiar with Powershell.
For example: The TestRail API has update_run
for changing the properties of an existing Test Run definition, but the Powershell Set
verb is more appropriate than the Update
verb in my opinion; hence Set-TestRailRun
.
Likewise, the API operation add_run
creates a new Test Run, but New-TestRailRun
is more appropriate.
Generally:
Add-
to create a new instance or instances of a thing in TestRail, e.g.Add-TestRailResult
,Add-TestRailResultsForCases
Start/Stop-
to start/begin or conclude/end a session (e.g. Test Run), e.g.Start-TestRailRun
,Stop-TestRailRun
Get-
to retrieve a resource, e.g.Get-TestRailProjects
,Get-TestRailTests
New-
create a new instance of a resource, e.g.New-TestRailResult
Set-
change the data associated with an existing resource, e.g.Set-TestRailRun
This is still a work in progress, so there are going to be bugs. To help with bug reports please use the module like this and include the information in your issue report:
PS> Import-Module .\PSTestRail
PS> Set-TestRailDebug -Enabled:$true
PS> $DebugPreference = "Continue"
# Now use as normal
To disable debugging simply set debug mode to disabled:
PS> Set-TestRailDebug -Enabled:$false
though thanks to the $DebugPreference
setting you might continue to see debug information from other cmdlets outside of the PSTestRail
module. The normal state of $DebugPreference
is SilentlyContinue
so set it back to that to completely unwind changes made above.
PS> $DebugPreference = "SilentlyContinue"
While debugging is enabled you will see some more verbose output including the full request URI and the parsed response:
PS> Get-TestRailProjects
DEBUG: Invoke-TestRailGetRequest: Uri: get_projects
DEBUG: Invoke-TestRailGetRequest: Result: @{id=1; name=Test Project; show_announcement=False; is_completed=False; completed_on=; suite_mode=1; url=https://tenant.testrail.net/index.php?/projects/overview/1}
I'm in two minds with Start-
/Stop-TestRailRun
. There's an argument that it should be Open-
/Close-TestRailRun
instead, except that once you stop (or close) a Test Run in TestRail you can't re-open it to make changes. TestRail's own nomenclature talks about closing Runs down, but then it's confused because you create a new run with add_run
and anyway I've already said I'm ignoring TestRail's verbs in favour of doing the right thing by PowerShell. Start-
and Stop-
are Lifecycle verbs so I'll stick with those semantics for now.