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 from Get-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