Skip to main content

PostRequest

The HTTP POST method requests that the origin server accepts the entity enclosed in the request as a new subordinate of the resource identified by the resourceUri.

This means that the POST should be used when you want to create a child resource under a collection of resources.

POST request is neither safe, nor idempotent. This means that if you retry a POST request N times, a correctly implemented HTTP REST API will create N resources with N different URIs.

Add new resource to a collection

import { actorCalled } from '@serenity-js/core'
import { CallAnApi, LastResponse, PostRequest, 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(PostRequest.to('/books').with({
      isbn: '0-688-00230-7',
      title: 'Zen and the Art of Motorcycle Maintenance: An Inquiry into Values',
      author: 'Robert M. Pirsig',
    })),
    Ensure.that(LastResponse.status(), equals(201)),
    Ensure.that(LastResponse.header('Location'), equals('/books/0-688-00230-7')),
  )

Submit an HTML form

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

const formData = stringify({
    name: actor.name,
    email: `${ actor.name }@example.com`,
    text: 'Your website is great! Learnt a lot :-)'
});

await actorCalled('Apisitt')
  .whoCan(CallAnApi.at('https://api.example.org/'))
  .attemptsTo(
    Send.a(PostRequest.to('/feedback').with(postData).using({
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
        'Content-Length': formData.length
      }
    })),
    Ensure.that(LastResponse.status(), equals(200)),
    Ensure.that(LastResponse.header('Location'), equals('/feedback/thank-you.html')),
  )

Learn more

Hierarchy

Index

Methods

Methods

staticto

  • Configures the object with a destination URI.

    When the resourceUri is not a fully qualified URL but a path, such as /products/2, it gets concatenated with the URL provided to the Axios instance when the ability to CallAnApi was instantiated.

    Parameters

    • resourceUri: Answerable<string>

      The URI where the Actor should send the HTTPRequest

    Returns PostRequest

as

  • as<O>(mapping: (answer: AxiosRequestConfig<any>) => O | Promise<O>): QuestionAdapter<O>

  • Maps this question to one of a different type.

    Question.about('number returned as string', actor => '42')   // returns: QuestionAdapter<string>
      .as(Number)                                                // returns: QuestionAdapter<number>

    Type parameters

    • O

    Parameters

    • mapping: (answer: AxiosRequestConfig<any>) => O | Promise<O>

    Returns QuestionAdapter<O>

answeredBy

  • answeredBy(actor: AnswersQuestions & UsesAbilities): Promise<AxiosRequestConfig<any>>
  • @inheritDoc

    Parameters

    • actor: AnswersQuestions & UsesAbilities

    Returns Promise<AxiosRequestConfig<any>>

describedAs

  • @inheritDoc

    Parameters

    • subject: string

    Returns PostRequest

toString

  • toString(): string
  • @inheritDoc

    Returns string

with

  • Configures the object with a request body.

    Parameters

    • data: any

      Data to be sent to the resourceUri

    Returns PostRequest

using

  • using(config: Answerable<{ url?: Answerable<string>; method?: Answerable<string>; baseURL?: Answerable<string>; transformRequest?: {} | {}[]; transformResponse?: {} | {}[]; headers?: { [x: string]: any; set: {}; get: {}; has: {}; delete: {}; clear: {}; normalize: {}; concat: {}; toJSON: {}; setContentType: {}; getContentType: {}; hasContentType: {}; setContentLength: {}; getContentLength: {}; ... 13 more ...; [Symbol.iterator]: {}; } | { [x: string]: Answerable<string> | Answerable<false> | Answerable<true> | Answerable<number> | { [x: string]: any; set: {}; get: {}; has: {}; ... 23 more ...; [Symbol.iterator]: {}; } | Answerable<...>[]; ... 16 more ...; common?: { ...; }; }; params?: any; paramsSerializer?: { encode?: {}; serialize?: {}; visitor?: {}; dots?: Answerable<false> | Answerable<true>; metaTokens?: Answerable<false> | Answerable<true>; indexes?: Answerable<...> | Answerable<...>; } | {}; data?: any; timeout?: Answerable<number>; timeoutErrorMessage?: Answerable<string>; withCredentials?: Answerable<false> | Answerable<true>; adapter?: Answerable<string> | {} | (Answerable<string> | {})[]; auth?: { username: Answerable<string>; password: Answerable<string>; }; responseType?: Answerable<text> | Answerable<arraybuffer> | Answerable<blob> | Answerable<document> | Answerable<json> | Answerable<stream>; responseEncoding?: Answerable<string>; xsrfCookieName?: Answerable<string>; xsrfHeaderName?: Answerable<string>; onUploadProgress?: {}; onDownloadProgress?: {}; maxContentLength?: Answerable<number>; validateStatus?: {}; maxBodyLength?: Answerable<number>; maxRedirects?: Answerable<number>; maxRate?: Answerable<number> | [Answerable<number>, Answerable<number>]; beforeRedirect?: {}; socketPath?: Answerable<string>; transport?: any; httpAgent?: any; httpsAgent?: any; proxy?: Answerable<false> | { host: Answerable<string>; port: Answerable<number>; auth?: { username: Answerable<string>; password: Answerable<string>; }; protocol?: Answerable<...>; }; cancelToken?: { promise: Answerable<Cancel>; reason?: { message: Answerable<string>; }; throwIfRequested: {}; }; decompress?: Answerable<false> | Answerable<true>; transitional?: { silentJSONParsing?: Answerable<false> | Answerable<true>; forcedJSONParsing?: Answerable<false> | Answerable<true>; clarifyTimeoutError?: Answerable<...> | Answerable<...>; }; signal?: { readonly aborted: Answerable<false> | Answerable<true>; onabort?: {}; addEventListener?: {}; removeEventListener?: {}; }; insecureHTTPParser?: Answerable<false> | Answerable<true>; env?: { FormData?: {}; }; formSerializer?: { visitor?: {}; dots?: Answerable<false> | Answerable<true>; metaTokens?: Answerable<false> | Answerable<true>; indexes?: Answerable<false> | Answerable<...>; }; family?: Answerable<4> | Answerable<6>; lookup?: {} | {}; withXSRFToken?: Answerable<false> | Answerable<true> | {} }>): PostRequest

  • Overrides the default Axios request configuration provided when the ability to CallAnApi was instantiated.

    Learn more

    Parameters

    • config: Answerable<{ url?: Answerable<string>; method?: Answerable<string>; baseURL?: Answerable<string>; transformRequest?: {} | {}[]; transformResponse?: {} | {}[]; headers?: { [x: string]: any; set: {}; get: {}; has: {}; delete: {}; clear: {}; normalize: {}; concat: {}; toJSON: {}; setContentType: {}; getContentType: {}; hasContentType: {}; setContentLength: {}; getContentLength: {}; ... 13 more ...; [Symbol.iterator]: {}; } | { [x: string]: Answerable<string> | Answerable<false> | Answerable<true> | Answerable<number> | { [x: string]: any; set: {}; get: {}; has: {}; ... 23 more ...; [Symbol.iterator]: {}; } | Answerable<...>[]; ... 16 more ...; common?: { ...; }; }; params?: any; paramsSerializer?: { encode?: {}; serialize?: {}; visitor?: {}; dots?: Answerable<false> | Answerable<true>; metaTokens?: Answerable<false> | Answerable<true>; indexes?: Answerable<...> | Answerable<...>; } | {}; data?: any; timeout?: Answerable<number>; timeoutErrorMessage?: Answerable<string>; withCredentials?: Answerable<false> | Answerable<true>; adapter?: Answerable<string> | {} | (Answerable<string> | {})[]; auth?: { username: Answerable<string>; password: Answerable<string>; }; responseType?: Answerable<text> | Answerable<arraybuffer> | Answerable<blob> | Answerable<document> | Answerable<json> | Answerable<stream>; responseEncoding?: Answerable<string>; xsrfCookieName?: Answerable<string>; xsrfHeaderName?: Answerable<string>; onUploadProgress?: {}; onDownloadProgress?: {}; maxContentLength?: Answerable<number>; validateStatus?: {}; maxBodyLength?: Answerable<number>; maxRedirects?: Answerable<number>; maxRate?: Answerable<number> | [Answerable<number>, Answerable<number>]; beforeRedirect?: {}; socketPath?: Answerable<string>; transport?: any; httpAgent?: any; httpsAgent?: any; proxy?: Answerable<false> | { host: Answerable<string>; port: Answerable<number>; auth?: { username: Answerable<string>; password: Answerable<string>; }; protocol?: Answerable<...>; }; cancelToken?: { promise: Answerable<Cancel>; reason?: { message: Answerable<string>; }; throwIfRequested: {}; }; decompress?: Answerable<false> | Answerable<true>; transitional?: { silentJSONParsing?: Answerable<false> | Answerable<true>; forcedJSONParsing?: Answerable<false> | Answerable<true>; clarifyTimeoutError?: Answerable<...> | Answerable<...>; }; signal?: { readonly aborted: Answerable<false> | Answerable<true>; onabort?: {}; addEventListener?: {}; removeEventListener?: {}; }; insecureHTTPParser?: Answerable<false> | Answerable<true>; env?: { FormData?: {}; }; formSerializer?: { visitor?: {}; dots?: Answerable<false> | Answerable<true>; metaTokens?: Answerable<false> | Answerable<true>; indexes?: Answerable<false> | Answerable<...>; }; family?: Answerable<4> | Answerable<6>; lookup?: {} | {}; withXSRFToken?: Answerable<false> | Answerable<true> | {} }>

      Axios request configuration overrides

    Returns PostRequest