CallAnApi
An Ability that enables the Actor to call a HTTP API. If you need to connect via a proxy, check out this article.
Implements:
Examples:
import { Actor } from '@serenity-js/core';
import { CallAnApi, GetRequest, LastResponse, Send } from '@serenity-js/rest'
import { Ensure, equals } from '@serenity-js/assertions';
const actor = Actor.named('Apisit').whoCan(
CallAnApi.at('https://myapp.com/api'),
);
actor.attemptsTo(
Send.a(GetRequest.to('/users/2')),
Ensure.that(LastResponse.status(), equals(200)),
); import { Actor } from '@serenity-js/core';
import { CallAnApi, GetRequest, LastResponse, Send } from '@serenity-js/rest'
import { Ensure, equals } from '@serenity-js/assertions';
import axios from 'axios';
const axiosInstance = axios.create({
timeout: 5 * 1000,
headers: {
'X-Custom-Api-Key': 'secret-key',
},
});
const actor = Actor.named('Apisit').whoCan(
CallAnApi.using(axiosInstance),
);
actor.attemptsTo(
Send.a(GetRequest.to('/users/2')),
Ensure.that(LastResponse.status(), equals(200)),
);Tests:
- CallAnApi
- CallAnApi provides a convenient factory method to be used when no custom configuration is required
- CallAnApi provides a factory method to be used when custom configuration is required
- CallAnApi caches the last response so that it can be easily asserted on
- CallAnApi caches the last response even when the server responds with an error. As long is it responds.
- CallAnApi provides a way to determine the actual target URL the request will be sent to
- CallAnApi when dealing with errors complains if you try to retrieve the last response before making an API call
- CallAnApi when dealing with errors complains when provided with invalid Axios configuration
- CallAnApi when dealing with errors complains when the API call times out
- CallAnApi when dealing with errors complains when the a network error occurs
- CallAnApi when dealing with errors complains when the Axios client rejects its promise
Static Method Summary
| Static Public Methods | ||
| public static |
as(actor: UsesAbilities): CallAnApi Used to access the Actor's ability to CallAnApi from within the Interaction classes, such as Send. |
|
| public static |
Ability to Call and api at a specified baseUrl |
|
| public static |
using(axiosInstance: AxiosInstance): CallAnApi Ability to Call a REST API using a given axios instance. |
|
Constructor Summary
| Public Constructor | ||
| public |
constructor(axiosInstance: AxiosInstance) |
|
Method Summary
| Public Methods | ||
| public |
mapLastResponse(fn: function<T>(AxiosResponse): T): T Maps the last cached response to another type. |
|
| public |
modifyConfig(fn: function(original: AxiosRequestConfig): any): void |
|
| public |
request(config: AxiosRequestConfig): Promise<AxiosResponse> Sends a HTTP request to a specified url. |
|
| public |
resolveUrl(config: AxiosRequestConfig): string Resolves the final URL, based on the AxiosRequestConfig provided any any defaults AxiosInstance has been configured with. |
|
Static Public Methods
public static as(actor: UsesAbilities): CallAnApi source
Used to access the Actor's ability to CallAnApi from within the Interaction classes, such as Send.
Params:
| Name | Type | Attribute | Description |
| actor | UsesAbilities |
public static at(baseURL: string): CallAnApi source
Ability to Call and api at a specified baseUrl
Default timeout is set to 2s.
Default request headers:
- Accept: application/json,application/xml
Params:
| Name | Type | Attribute | Description |
| baseURL | string |
public static using(axiosInstance: AxiosInstance): CallAnApi source
Ability to Call a REST API using a given axios instance.
Useful when you need to customise Axios to make it aware of proxies, for example.
Params:
| Name | Type | Attribute | Description |
| axiosInstance | AxiosInstance |
See:
Public Constructors
public constructor(axiosInstance: AxiosInstance) source
Params:
| Name | Type | Attribute | Description |
| axiosInstance | AxiosInstance | A pre-configured instance of the Axios HTTP client |
See:
Public Methods
public mapLastResponse(fn: function<T>(AxiosResponse): T): T source
Maps the last cached response to another type. Useful when you need to extract a portion of the AxiosResponse object.
Params:
| Name | Type | Attribute | Description |
| fn | function<T>(AxiosResponse): T | mapper function |
Returns:
| T |
Tests:
- CallAnApi caches the last response so that it can be easily asserted on
- CallAnApi caches the last response even when the server responds with an error. As long is it responds.
- CallAnApi when dealing with errors complains if you try to retrieve the last response before making an API call
- LastResponse complains if the last response is attempted to be retrieved without making a request first
See:
public modifyConfig(fn: function(original: AxiosRequestConfig): any): void source
Allows for the original Axios config to be changed after the CallAnApi Ability has been instantiated and given to the Actor.
Params:
| Name | Type | Attribute | Description |
| fn | function(original: AxiosRequestConfig): any |
Returns:
| void |
public request(config: AxiosRequestConfig): Promise<AxiosResponse> source
Sends a HTTP request to a specified url. Response will be cached and available via CallAnApi#mapLastResponse
Params:
| Name | Type | Attribute | Description |
| config | AxiosRequestConfig | Axios request configuration, which can be used to override the defaults provided when the CallAnApi Ability is instantiated |
Tests:
- CallAnApi caches the last response even when the server responds with an error. As long is it responds.
- CallAnApi when dealing with errors complains when provided with invalid Axios configuration
- CallAnApi when dealing with errors complains when the API call times out
- CallAnApi when dealing with errors complains when the a network error occurs
- CallAnApi when dealing with errors complains when the Axios client rejects its promise
public resolveUrl(config: AxiosRequestConfig): string source
Resolves the final URL, based on the AxiosRequestConfig provided any any defaults AxiosInstance has been configured with.
Params:
| Name | Type | Attribute | Description |
| config | AxiosRequestConfig |
Returns:
| string |