@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
209 lines • 7.42 kB
JavaScript
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.LastResponse = void 0;
const core_1 = require("@serenity-js/core");
const abilities_1 = require("../abilities");
/**
* Provides access to the properties of the last [`AxiosResponse`](https://axios-http.com/docs/res_schema) object,
* cached on the [ability](https://serenity-js.org/api/core/class/Ability/) to [`CallAnApi`](https://serenity-js.org/api/rest/class/CallAnApi/).
*
* ## Verify response to a GET request
*
* ```ts
* import { actorCalled } from '@serenity-js/core'
* import { CallAnApi, GetRequest, LastResponse, Send } from '@serenity-js/rest'
* import { Ensure, equals } from '@serenity-js/assertions'
*
* interface Book {
* title: string;
* author: string;
* }
*
* await actorCalled('Apisitt')
* .whoCan(CallAnApi.at('https://api.example.org/'))
* .attemptsTo(
* Send.a(GetRequest.to('/books/0-688-00230-7')),
* Ensure.that(LastResponse.status(), equals(200)),
* Ensure.that(LastResponse.header('Content-Type'), equals('application/json')),
* Ensure.that(LastResponse.body<Book>(), equals({
* title: 'Zen and the Art of Motorcycle Maintenance: An Inquiry into Values',
* author: 'Robert M. Pirsig',
* })),
* )
* ```
*
* ## Use Serenity/JS adapters to navigate complex response objects
*
* ```ts
* import { actorCalled } from '@serenity-js/core'
* import { CallAnApi, GetRequest, LastResponse, Send } from '@serenity-js/rest'
* import { Ensure, equals } from '@serenity-js/assertions'
*
* interface Developer {
* name: string;
* id: string;
* projects: Project[];
* }
*
* interface Project {
* name: string;
* repoUrl: string;
* }
*
* await actorCalled('Apisitt')
* .whoCan(CallAnApi.at('https://api.example.org/'))
* .attemptsTo(
* Send.a(GetRequest.to('/developers/jan-molak')),
* Ensure.that(LastResponse.status(), equals(200)),
* Ensure.that(LastResponse.body<Developer>().name, equals('Jan Molak')),
* Ensure.that(LastResponse.body<Developer>().projects[0].name, equals('Serenity/JS')),
* )
* ```
*
* ## Learn more
* - [AxiosResponse](https://axios-http.com/docs/res_schema)
*
* @group Questions
*/
class LastResponse {
/**
* Retrieves the status code of the [last response](https://serenity-js.org/api/rest/class/LastResponse/)
*
* #### Learn more
* - [HTTP response status codes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status)
*/
static status() {
return core_1.Question.about(`the status of the last response`, async (actor) => {
return abilities_1.CallAnApi.as(actor).mapLastResponse(response => response.status);
});
}
/**
* Retrieves the body of the [last response](https://serenity-js.org/api/rest/class/LastResponse/)
*
* #### A type-safe approach using generics
*
* ```ts
* import { actorCalled } from '@serenity-js/core'
* import { CallAnApi, LastResponse } from '@serenity-js/rest'
* import { Ensure, equals } from '@serenity-js/assertions'
*
* interface Book {
* title: string;
* author: string;
* }
*
* await actorCalled('Apisitt')
* .whoCan(CallAnApi.at('https://api.example.org/'))
* .attemptsTo(
* // ...
*
* // note body<T>() parameterised with type "Book"
* Ensure.that(LastResponse.body<Book>(), equals({
* title: 'Zen and the Art of Motorcycle Maintenance: An Inquiry into Values',
* author: 'Robert M. Pirsig',
* })),
* )
* ```
*
* ## A not type-safe approach using `any`
*
* ```ts
* import { actorCalled } from '@serenity-js/core'
* import { CallAnApi, LastResponse } from '@serenity-js/rest'
* import { Ensure, equals } from '@serenity-js/assertions'
*
* await actorCalled('Apisitt')
* .whoCan(CallAnApi.at('https://api.example.org/'))
* .attemptsTo(
* // ...
*
* // note body<T>() parameterised with "any" or with no parameter is not type-safe!
* Ensure.that(LastResponse.body<any>(), equals({
* title: 'Zen and the Art of Motorcycle Maintenance: An Inquiry into Values',
* author: 'Robert M. Pirsig',
* })),
* )
* ```
*
* ## Iterating over the items in the response body
*
* ```ts
* import { actorCalled } from '@serenity-js/core'
* import { CallAnApi, LastResponse } from '@serenity-js/rest'
* import { Ensure, equals } from '@serenity-js/assertions'
*
* interface Product {
* id: number;
* name: string;
* }
*
* await actorCalled('Apisitt')
* .whoCan(CallAnApi.at('https://api.example.org/'))
* .attemptsTo(
* Send.a(GetRequest.to(`/products`)),
* List.of<Product>(LastResponse.body<{ products: Product[] }>().products)
* .forEach(({ item, actor }) =>
* actor.attemptsTo(
* Send.a(GetRequest.to(`/products/${ item.id }`)),
* Ensure.that(LastResponse.body<Product>().id, equals(item.id)),
* )
* ),
* )
* ```
*/
static body() {
return core_1.Question.about(`the body of the last response`, async (actor) => {
return abilities_1.CallAnApi.as(actor).mapLastResponse(response => response.data);
});
}
/**
* Retrieves a header of the [last response](https://serenity-js.org/api/rest/class/LastResponse/), identified by `name`
*
* ## Asserting on a header
*
* ```ts
* import { actorCalled } from '@serenity-js/core'
* import { CallAnApi, LastResponse } 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(`/products`)),
* Ensure.that(LastResponse.header('Content-Type'), equals('application/json')),
* )
* ```
*
* @param name
*/
static header(name) {
return core_1.Question.about(`the '${name}' header of the last response`, async (actor) => {
return abilities_1.CallAnApi.as(actor).mapLastResponse(response => response.headers[name]);
});
}
/**
* Retrieves all the headers of the [last response](https://serenity-js.org/api/rest/class/LastResponse/).
*
* ## Asserting on a header
*
* ```ts
* import { actorCalled } from '@serenity-js/core'
* import { CallAnApi, LastResponse } 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(`/products`)),
* Ensure.that(LastResponse.headers()['Content-Type'], equals('application/json')),
* )
* ```
*/
static headers() {
return core_1.Question.about(`the headers or the last response`, async (actor) => {
return abilities_1.CallAnApi.as(actor).mapLastResponse(response => response.headers);
});
}
}
exports.LastResponse = LastResponse;
//# sourceMappingURL=LastResponse.js.map