@serenity-js/rest
Version:
Serenity/JS Screenplay Pattern library for interacting with REST and other HTTP-based services, supporting comprehensive API testing and blended testing scenarios
114 lines • 4.46 kB
JavaScript
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.PostRequest = void 0;
const core_1 = require("@serenity-js/core");
const HTTPRequest_1 = require("./HTTPRequest");
/**
* 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](https://developer.mozilla.org/en-US/docs/Glossary/Safe),
* nor [idempotent](https://developer.mozilla.org/en-US/docs/Glossary/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
*
* ```ts
* 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
*
* ```ts
* 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(formData).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
* - https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST
* - https://tools.ietf.org/html/rfc7231#section-4.3.3
*
* @group Models
*/
class PostRequest extends HTTPRequest_1.HTTPRequest {
/**
* 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](https://serenity-js.org/api/core/class/Ability/) to [`CallAnApi`](https://serenity-js.org/api/rest/class/CallAnApi/) was instantiated.
*
* @param resourceUri
* The URI where the [`Actor`](https://serenity-js.org/api/core/class/Actor/)
* should send the [`HTTPRequest`](https://serenity-js.org/api/rest/class/HTTPRequest/)
*/
static to(resourceUri) {
return new PostRequest(resourceUri);
}
/**
* Configures the object with a request body.
*
* @param data
* Data to be sent to the `resourceUri`
*/
with(data) {
return new PostRequest(this.resourceUri, data, this.config);
}
/**
* Overrides the default Axios request configuration provided
* when the [ability](https://serenity-js.org/api/core/class/Ability/) to [`CallAnApi`](https://serenity-js.org/api/rest/class/CallAnApi/) was instantiated.
*
* #### Learn more
* - [`Answerable`](https://serenity-js.org/api/core/#Answerable)
* - [`WithAnswerableProperties`](https://serenity-js.org/api/core/#WithAnswerableProperties)
* - [AxiosRequestConfig](https://axios-http.com/docs/req_config)
*
* @param {Answerable<WithAnswerableProperties<AxiosRequestConfig>>} config
* Axios request configuration overrides
*/
using(config) {
return new PostRequest(this.resourceUri, this.data, core_1.Question.fromObject(config));
}
}
exports.PostRequest = PostRequest;
//# sourceMappingURL=PostRequest.js.map