import {CallAnApi} from '@serenity-js/rest/lib/screenplay/abilities'
public class | source

CallAnApi

An Ability that enables the Actor to call a HTTP API.

Implements:

Examples:

Using a default Axios HTTP client
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)),
);
Using Axios client with custom configuration
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:

Static Method Summary

Static Public Methods
public static

Used to access the Actor's ability to CallAnApi from within the Interaction classes, such as Send.

public static

at(baseURL: string): CallAnApi

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

Allows for the original Axios config to be changed after the CallAnApi Ability has been instantiated and given to the Actor.

public

request(config: AxiosRequestConfig): Promise<AxiosResponse>

Sends a HTTP request to a specified url.

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:

NameTypeAttributeDescription
actor UsesAbilities

Returns:

CallAnApi

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:

NameTypeAttributeDescription
baseURL string

Returns:

CallAnApi

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:

NameTypeAttributeDescription
axiosInstance AxiosInstance

Returns:

CallAnApi

Public Constructors

public constructor(axiosInstance: AxiosInstance) source

Params:

NameTypeAttributeDescription
axiosInstance AxiosInstance

A pre-configured instance of the Axios HTTP client

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:

NameTypeAttributeDescription
fn function<T>(AxiosResponse): T

mapper function

Returns:

T

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:

NameTypeAttributeDescription
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:

NameTypeAttributeDescription
config AxiosRequestConfig

Axios request configuration, which can be used to override the defaults provided when the CallAnApi Ability is instantiated

Returns:

Promise<AxiosResponse>

A promise of an AxiosResponse