Skip to main content

CallAnApi

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

If you need to connect via a proxy, check out “Using Axios behind corporate proxies”.

Using the default Axios HTTP client

import { actorCalled } from '@serenity-js/core'
import { CallAnApi, GetRequest, LastResponse, Send } from '@serenity-js/rest'
import { Ensure, equals } from '@serenity-js/assertions'

await actorCalled('Apisitt')
  .whoCan(
    CallAnApi.at('https://api.example.org/')
  )
  .attemptsTo(
    Send.a(GetRequest.to('/users/2')),
    Ensure.that(LastResponse.status(), equals(200)),
  )

Using Axios client with custom configuration

import { actorCalled } from '@serenity-js/core'
import { CallAnApi, GetRequest, LastResponse, Send } from '@serenity-js/rest'
import { Ensure, equals } from '@serenity-js/assertions'

import * as axios from 'axios'

const axiosInstance = axios.create({
  timeout: 5 * 1000,
  headers: {
    'X-Custom-Api-Key': 'secret-key',
  },
});

await actorCalled('Apisitt')
  .whoCan(
    CallAnApi.using(axiosInstance),
  )
  .attemptsTo(
    Send.a(GetRequest.to('/users/2')),
    Ensure.that(LastResponse.status(), equals(200)),
  )

Learn more

Hierarchy

  • Ability
    • CallAnApi

Index

Methods

Constructors

Methods

staticat

  • Produces an ability to call a REST api at a specified baseUrl

    Default timeout is set to 2s.

    Default request headers:

    • Accept: application/json,application/xml

    Parameters

    • baseURL: string

    Returns CallAnApi

staticusing

  • using(axiosInstance: AxiosInstance): CallAnApi

modifyConfig

  • modifyConfig(fn: (original: AxiosDefaults<any>) => any): void

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

    Learn more

    Parameters

    • fn: (original: AxiosDefaults<any>) => any

    Returns void

request

  • request(config: AxiosRequestConfig<any>): Promise<AxiosResponse<any, any>>

  • Sends an HTTP request to a specified url. Response will be cached and available via mapLastResponse

    Learn more

    Parameters

    • config: AxiosRequestConfig<any>

      Axios request configuration, which can be used to override the defaults provided when the ability to CallAnApi was instantiated.

    Returns Promise<AxiosResponse<any, any>>

resolveUrl

  • resolveUrl(config: AxiosRequestConfig<any>): string

  • Resolves the final URL, based on the AxiosRequestConfig provided and any defaults that the AxiosInstance has been configured with.

    Learn more

    Parameters

    • config: AxiosRequestConfig<any>

    Returns string

mapLastResponse

  • mapLastResponse<T>(mappingFunction: (response: AxiosResponse<any, any>) => T): T

  • 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

    • mappingFunction: (response: AxiosResponse<any, any>) => T

    Returns T

Constructors

constructor

  • new CallAnApi(axiosInstance: AxiosInstance): CallAnApi

  • Learn more

    Parameters

    • axiosInstance: AxiosInstance

      A pre-configured instance of the Axios HTTP client

    Returns CallAnApi