TesterCall is a Powershell module for the import and automated testing of OpenApi specifications.
It is designed to be a cross-platform tool for use with either Powershell 5 or Powershell 7 (Core) and as such has been built on the portable .Net standard framework.
In order to use TesterCall, you will need to place the following dll files from this project into your module directory (currently located in bin/debug/netstandard2.0):
- TesterCall.dll
- Newtonsoft.Json.dll
- YamlDotNet.dll
You should then run Import-Module
from Powershell as follows:
Import-Module *Path to Module Directory*/TesterCall.dll
The test environment will provide a Base Url for testing Api endpoints against and is created using New-TestEnvironment. This requires a Host name and protocol (Http|Https) and can either be stored in a variable or set as the default environment by using the -Default flag:
New-TestEnvironment -Protocol HTTPS -Host localhost:5001 -Default
The default environment will be used by commands such as Invoke-Endpoint when a test environment
is not supplied, and can be viewed by using Get-DefaultTestEnvironment
To import all the endpoints specified in an OpenApi 3 json or yaml file, run
Import-OpenApiSpecification
:
Import-OpenApiSpecification -Path *Path to Yaml/Json spec file*
This command will return all Endpoint objects to the Powershell pipeline as well as storing them in memory. If you don't need them immediately and don't want them in your console output, you can do this without losing the information:
Import-OpenApiSpecification -Path *File path* | Out-Null
Endpoints can be retrieved later using Get-Endpoint
(see below). If you want to
distinguish these endpoints from those in another spec, you can use the -Title
parameter.
TesterCall offers multiple commands for creating an Authorisation strategy which
can be used to populate the Authorisation header used when calling Endpoints - these
strategy objects should be stored in a variable and passed as a parameter to Invoke-Endpoint
.
These are as follows:
- New-Oauth2ClientCredentials
- New-Oauth2PasswordCredentials
- New-BasicAuthCredentials
- New-BearerToken
The details of these commands can be found by running Get-Help *Command Name*
The module contains a range of options for exploring your API spec on the command line
The Get-Endpoint
command allows you to retrieve an object representing a particular endpoint,
including parameters and request/response body schema information. It also allows you to filter
endpoints either by an auto-generated "Short Name" or by the endpoint path and method, eg:
Get-Endpoint -ShortName UsersPOSTusers
may be equivalent to:
Get-Endpoint -Path /users -Method POST
Both options also have an -APIId
parameter which matches the API title set in the spec document,
unless this has been overridden with the -Title
parameter when importing the spec (see above).
The request or response type can be viewed either as a .Net object or in a json representation. I would recommend that you use the Json representation when exploring the spec interactively - the .Net object output is useful if you need to update properties in a request body dynamically before sending.
Both the Get-RequestType
and Get-ResponseType
commands take an Endpoint object either with the -Endpoint
parameter, or directly through the pipeline:
Get-Endpoint -ShortName UsersPOSTusers | Get-RequestType
Both commands also take the optional switch parameters -AsJson
, which provides a Json representation,
and -ExampleMode
which ensures that all properties are populated with example properties. I recommend you use
both when exploring interactively, to get a fuller picture of your spec's requirements.
For instance, this (using the -Endpoint
parameter this time):
Get-RequestType -Endpoint $usersPostEndpoint -AsJson -ExampleMode
might return a result like this:
{
"Title": null,
"FirstName": null,
"SecondName": null,
"Age": 0,
"CreditCards": [
{
"Type": Visa,
"Expiry": 01/01/0001T00:00:00
}
]
}
whereas the result without -ExampleMode
might look more like this:
{
"Title": null,
"FirstName": null,
"SecondName": null,
"Age": null,
"CreditCards": []
}
If you need to use the object generated by these commands in a request in testing, you should:
- Not use the
-AsJson
flag - Consider using the
-ReplaceProperties
parameter on either command to set your own property values (see below, Setting property values) - Bear in mind that
-ExampleMode
will populate any and all properties you have not specified - for arrays, it will always create one example member, unless you have specified replacement member properties
The key command that you will need to call your endpoints is Invoke-Endpoint
. This takes the following parameters:
-Endpoint
- Required, must be an Endpoint object, which can also be passed in from the pipeline-PathParams
- Required where the url contains a parameter eg /users/id. As with other HTTP parameter arguments, these parameters should be passed in as a string-string Hashtable, eg-PathParams @{"id"="100";}
.-QueryParams
- Not required, used to add query parameters to the request-HeaderParams
- Not required, used to add header parameters to the request-RequestBody
- Required where a request body is needed. This parameter takes either a .Net object of the correct type, as returned fromGet-RequestType
, or a Hashtable, array, or array of Hashtables specifying how to set properties on the request object (see below, Setting property values)
If the spec states that a parameter is required and you do not provide it, it is worth noting that Invoke-Endpoint
will throw before sending the request.
When generating a new request or response object, TesterCall takes either a Hashtable, for an object type, an array, or an array of Hashtables. For ease, dates may be represented as strings.
For example, the desired properties for the "User" example above could be built as follows:
$properties = @{
"Title" = "Mr";
"FirstName" = "Mickey";
"SecondName" = "Mouse";
"CreditCards" = @(
@{
"Type" = "Visa";
"Expiry" = "2030-02-02T12:00:00";
},
@{
"Type" = "Visa";
"Expiry" = "1995-01-01T13:00:01";
}
);
}
This property map could then be used to generate a request as follows:
$body = Get-RequestType -Endpoint $usersPostEndpoint -ReplaceProperties $properties
Invoke-Endpoint $usersPostEndpoint -RequestBody $body
or more simply:
Invoke-Endpoint $usersPostEndpoint -RequestBody $properties