externalCallAnApi
Hierarchy
- Ability
- CallAnApi
Index
Constructors
externalconstructor
Learn more
Parameters
externalaxiosInstance: AxiosInstance
A pre-configured instance of the Axios HTTP client
Returns CallAnApi
Methods
staticexternalat
staticexternalusing
Produces an ability to call an HTTP API using the given Axios instance, or an Axios request configuration object.
When you provide an Axios configuration object, it gets shallow-merged with the following defaults:
- request timeout of 10 seconds
- automatic proxy support based on your environment variables
When you provide an Axios instance, it's enhanced with proxy support and no other modifications are made.
If you don't want Serenity/JS to augment or modify your Axios instance in any way, please use the
CallAnApi.constructor
directly.Parameters
externalaxiosInstanceOrConfig: AxiosInstance | AxiosRequestConfigDefaults
Returns CallAnApi
externalabilityType
Returns the most abstract type of this Ability instance, specifically the first class in the inheritance hierarchy that directly extends the
Ability
class.import { Ability } from '@serenity-js/core';
class MyAbility extends Ability {}
class MySpecialisedAbility extends MyAbility {}
new MyAbility().abilityType(); // returns MyAbility
new MySpecialisedAbility().abilityType(); // returns MyAbilityReturns AbilityType<Ability>
externalmodifyConfig
externalrequest
Sends an HTTP request to a specified url. Response will be cached and available via
CallAnApi.mapLastResponse
.Learn more
Parameters
externalconfig: AxiosRequestConfig<any>
Returns Promise<AxiosResponse<any, any>>
externalresolveUrl
Resolves the final URL, based on the
AxiosRequestConfig
provided and any defaults that theAxiosInstance
has been configured with.Note that unlike Axios, this method uses the Node.js WHATWG URL API to ensure URLs are correctly resolved.
Parameters
externalconfig: AxiosRequestConfig<any>
Returns string
externalmapLastResponse
Maps the last cached response to another type. Useful when you need to extract a portion of the
AxiosResponse
object.Learn more
Type parameters
- T
Parameters
externalmappingFunction: (response: AxiosResponse<any, any>) => T
Returns T
externaltoJSON
Returns SerialisedAbility
An ability that wraps axios client and enables the actor to send HTTP requests to HTTP APIs.
Configuring the ability to call an API
The easiest way to configure the ability to
CallAnApi
is to provide thebaseURL
of your HTTP API, and rely on Serenity/JS to offer other sensible defaults:Please note that the following Serenity/JS test runner adapters already provide the ability to
CallAnApi
as part of their default configuration, so you don't need to configure it yourself:Resolving relative URLs
Serenity/JS resolves request URLs using Node.js WHATWG URL API. This means that the request URL is determined using the resource path resolved in the context of base URL, i.e.
new URL(resourcePath, [baseURL])
.Consider the following example:
In the above example:
resourcePath
is defined as a full URL, it overrides the base URLresourcePath
starts with a forward slash/
, it replaces any path defined in the base URLresourcePath
is not a full URL and doesn't start with a forward slash, it gets appended to the base URLhttps://api.example.org/
/v1/users/2
https://api.example.org/v1/users/2
https://example.org/api/v1/
users/2
https://example.org/api/v1/users/2
https://example.org/api/v1/
/secure/oauth
https://example.org/secure/oauth
https://v1.example.org/api/
https://v2.example.org/
https://v2.example.org/
Using Axios configuration object
When you need more control over how your Axios instance is configured, provide an Axios configuration object. For example:
Working with proxy servers
CallAnApi
uses an approach described in "Node.js Axios behind corporate proxies" to automatically detect proxy server configuration based on your environment variables.You can override this default proxy detection mechanism by providing your own proxy configuration object.
Automatic proxy support
When the URL you're sending the request to uses the HTTP protocol, Serenity/JS will automatically detect your proxy configuration based on the following environment variables:
npm_config_http_proxy
http_proxy
andHTTP_PROXY
npm_config_proxy
all_proxy
Similarly, when the request target URL uses the HTTPS protocol, the following environment variables are used instead:
npm_config_https_proxy
https_proxy
andHTTPS_PROXY
npm_config_proxy
all_proxy
Proxy configuration is ignored for both HTTP and HTTPS target URLs matching the proxy bypass rules defined in the following environment variables:
npm_config_no_proxy
no_proxy
andNO_PROXY
Custom proxy configuration
To override the automatic proxy detection based on the environment variables, provide a proxy configuration object:
Note that Serenity/JS uses proxy-agents and the approach described in "Node.js Axios behind corporate proxies" to work around limited proxy support capabilities in Axios itself.
Bypassing proxy configuration
To bypass the proxy configuration for specific hostnames and IP addresses, you can either:
bypass
property in the proxy configuration object, orno_proxy
environment variable.The value of the
bypass
property or theno_proxy
environment variable should be a comma-separated list of hostnames and IP addresses that should not be routed through the proxy server, for example:.com, .serenity-js.org, .domain.com
.Note that setting the
bypass
property toexample.org
makes the requests to following URLs bypass the proxy server:api.example.org
sub.sub.example.org
example.org
my-example.org
Serenity/JS doesn't currently support
bypass
rules expressed using CIDR notation, like192.168.17.0/24
. Instead, it uses a simple comma-separated list of hostnames and IP addresses. If you need support for CIDR notation, please raise an issue.Using Axios instance with proxy support
To have full control over the Axios instance used by the ability to
CallAnApi
, you can create it yourself and inject it into the ability. This approach allows you to still benefit from automated proxy detection in configuration, while taking advantage of the many Axios plugins.Using raw Axios instance
If you don't want Serenity/JS to enhance your Axios instance with proxy support, instantiate the ability to
CallAnApi
using its constructor directly. Note, however, that by using this approach you're taking the responsibility for all the aspects of configuring Axios.Serenity/JS defaults
When using
CallAnApi.at
orCallAnApi.using
with a configuration object, Serenity/JS merges your Axios request configuration with the following defaults:timeout
: 10 secondsYou can override them by specifying the given property in your configuration object, for example:
Interacting with multiple APIs
Some test scenarios might require you to interact with multiple HTTP APIs. With Serenity/JS you can do this using either API-specific actors, or by specifying full URLs when performing the requests.
The following examples will assume that the test scenarios needs to interact with the following APIs:
https://testdata.example.org/api/v1/
https://shop.example.org/api/v1/
Let's also assume that the
testdata
API allows the automation to manage the test data used by theshop
API.Using API-specific actors
To create API-specific actors, configure your test runner with a cast that gives your actors appropriate abilities based, for example, on their name:
Next, retrieve the appropriate actor in your test scenario using
actorCalled
, for example:Using full URLs
If you prefer to have a single actor interacting with multiple APIs, you can specify the full URL for every request:
Learn more