@serenity-js/rest 3.0.0-rc.8 → 3.0.0

package/lib/screenplay/interactions/Send.d.ts

@@ -1,64 +1,47 @@
 import { Answerable, AnswersQuestions, CollectsArtifacts, Interaction, UsesAbilities } from '@serenity-js/core';
 import { AxiosRequestConfig } from 'axios';
 /**
- * @desc
- *  Sends a {@link HTTPRequest} to a specified url.
- *  The response to the request is made available via the {@link LastResponse}
- *  {@link @serenity-js/core/lib/screenplay~Question}s.
+ * Sends a {@apilink HTTPRequest} to a specified url.
  *
- * @example <caption>Send a GET request</caption>
- *  import { Actor } from '@serenity-js/core';
- *  import { CallAnApi, GetRequest, LastResponse, Send } from '@serenity-js/rest'
- *  import { Ensure, equals } from '@serenity-js/assertions';
+ * The response to the request is made available via {@apilink LastResponse}.
  *
- *  const actor = Actor.named('Apisit').whoCan(CallAnApi.at('https://myapp.com/api'));
+ * ## Send a GET request
  *
- *  actor.attemptsTo(
- *      Send.a(GetRequest.to('/books/0-688-00230-7')),
- *      Ensure.that(LastResponse.status(), equals(200)),
- *  );
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { CallAnApi, GetRequest, LastResponse, Send } from '@serenity-js/rest'
+ * import { Ensure, equals } from '@serenity-js/assertions'
  *
- * @extends {Interaction}
+ * await actorCalled('Apisit')
+ *   .whoCan(CallAnApi.at('https://api.example.org/'))
+ *   .attemptsTo(
+ *     Send.a(GetRequest.to('/books/0-688-00230-7')),
+ *     Ensure.that(LastResponse.status(), equals(200)),
+ *   )
+ * ```
+ *
+ * @group Activities
  */
 export declare class Send extends Interaction {
     private readonly request;
     /**
-     * @desc
-     *  Instantiates a new {@link Send} {@link @serenity-js/core/lib/screenplay~Interaction}.
+     * Instantiates a new {@apilink Interaction|interaction} to {@apilink Send}.
      *
-     * @param {@serenity-js/lib/core/screenplay~Answerable<AxiosRequestConfig>} request
-     * @returns {@serenity-js/core/lib/screenplay~Interaction}
+     * #### Learn more
+     * - [AxiosRequestConfig](https://github.com/axios/axios/blob/v0.27.2/index.d.ts#L75-L113)
      *
-     * @see {@link AxiosRequestConfig}
+     * @param request
      */
     static a(request: Answerable<AxiosRequestConfig>): Interaction;
     /**
-     * @param {@serenity-js/core/lib/screenplay~Answerable<AxiosRequestConfig>} request
-     *
-     * @see {@link AxiosRequestConfig}
+     * @param request
      */
-    constructor(request: Answerable<AxiosRequestConfig>);
+    protected constructor(request: Answerable<AxiosRequestConfig>);
     /**
-     * @desc
-     *  Makes the provided {@link @serenity-js/core/lib/screenplay/actor~Actor}
-     *  perform this {@link @serenity-js/core/lib/screenplay~Interaction}.
-     *
-     * @param {UsesAbilities & CollectsArtifacts & AnswersQuestions} actor
-     * @returns {Promise<void>}
-     *
-     * @see {@link @serenity-js/core/lib/screenplay/actor~Actor}
-     * @see {@link @serenity-js/core/lib/screenplay/actor~UsesAbilities}
-     * @see {@link @serenity-js/core/lib/screenplay/actor~CollectsArtifacts}
-     * @see {@link @serenity-js/core/lib/screenplay/actor~AnswersQuestions}
+     * @inheritDoc
      */
     performAs(actor: UsesAbilities & CollectsArtifacts & AnswersQuestions): Promise<void>;
-    /**
-     * @desc
-     *  Generates a description to be used when reporting this {@link @serenity-js/core/lib/screenplay~Activity}.
-     *
-     * @returns {string}
-     */
-    toString(): string;
     private responseToArtifact;
     private requestToArtifactName;
 }
+//# sourceMappingURL=Send.d.ts.map

package/lib/screenplay/interactions/Send.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Send.d.ts","sourceRoot":"","sources":["../../../src/screenplay/interactions/Send.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEhH,OAAO,EAAgB,kBAAkB,EAAgE,MAAM,OAAO,CAAC;AAIvH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,IAAK,SAAQ,WAAW;IAiBX,OAAO,CAAC,QAAQ,CAAC,OAAO;IAf9C;;;;;;;OAOG;IACH,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,UAAU,CAAC,kBAAkB,CAAC,GAAG,WAAW;IAI9D;;OAEG;IACH,SAAS,aAA8B,OAAO,EAAE,UAAU,CAAC,kBAAkB,CAAC;IAI9E;;OAEG;IACH,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,iBAAiB,GAAG,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBrF,OAAO,CAAC,kBAAkB;IA0B1B,OAAO,CAAC,qBAAqB;CAGhC"}

package/lib/screenplay/interactions/Send.js

@@ -3,61 +3,51 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Send = void 0;
 const core_1 = require("@serenity-js/core");
 const model_1 = require("@serenity-js/core/lib/model");
+const axios_1 = require("axios");
 const abilities_1 = require("../abilities");
 /**
- * @desc
- *  Sends a {@link HTTPRequest} to a specified url.
- *  The response to the request is made available via the {@link LastResponse}
- *  {@link @serenity-js/core/lib/screenplay~Question}s.
+ * Sends a {@apilink HTTPRequest} to a specified url.
  *
- * @example <caption>Send a GET request</caption>
- *  import { Actor } from '@serenity-js/core';
- *  import { CallAnApi, GetRequest, LastResponse, Send } from '@serenity-js/rest'
- *  import { Ensure, equals } from '@serenity-js/assertions';
+ * The response to the request is made available via {@apilink LastResponse}.
  *
- *  const actor = Actor.named('Apisit').whoCan(CallAnApi.at('https://myapp.com/api'));
+ * ## Send a GET request
  *
- *  actor.attemptsTo(
- *      Send.a(GetRequest.to('/books/0-688-00230-7')),
- *      Ensure.that(LastResponse.status(), equals(200)),
- *  );
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { CallAnApi, GetRequest, LastResponse, Send } from '@serenity-js/rest'
+ * import { Ensure, equals } from '@serenity-js/assertions'
  *
- * @extends {Interaction}
+ * await actorCalled('Apisit')
+ *   .whoCan(CallAnApi.at('https://api.example.org/'))
+ *   .attemptsTo(
+ *     Send.a(GetRequest.to('/books/0-688-00230-7')),
+ *     Ensure.that(LastResponse.status(), equals(200)),
+ *   )
+ * ```
+ *
+ * @group Activities
  */
 class Send extends core_1.Interaction {
     /**
-     * @param {@serenity-js/core/lib/screenplay~Answerable<AxiosRequestConfig>} request
+     * Instantiates a new {@apilink Interaction|interaction} to {@apilink Send}.
      *
-     * @see {@link AxiosRequestConfig}
-     */
-    constructor(request) {
-        super();
-        this.request = request;
-    }
-    /**
-     * @desc
-     *  Instantiates a new {@link Send} {@link @serenity-js/core/lib/screenplay~Interaction}.
-     *
-     * @param {@serenity-js/lib/core/screenplay~Answerable<AxiosRequestConfig>} request
-     * @returns {@serenity-js/core/lib/screenplay~Interaction}
+     * #### Learn more
+     * - [AxiosRequestConfig](https://github.com/axios/axios/blob/v0.27.2/index.d.ts#L75-L113)
      *
-     * @see {@link AxiosRequestConfig}
+     * @param request
      */
     static a(request) {
         return new Send(request);
     }
     /**
-     * @desc
-     *  Makes the provided {@link @serenity-js/core/lib/screenplay/actor~Actor}
-     *  perform this {@link @serenity-js/core/lib/screenplay~Interaction}.
-     *
-     * @param {UsesAbilities & CollectsArtifacts & AnswersQuestions} actor
-     * @returns {Promise<void>}
-     *
-     * @see {@link @serenity-js/core/lib/screenplay/actor~Actor}
-     * @see {@link @serenity-js/core/lib/screenplay/actor~UsesAbilities}
-     * @see {@link @serenity-js/core/lib/screenplay/actor~CollectsArtifacts}
-     * @see {@link @serenity-js/core/lib/screenplay/actor~AnswersQuestions}
+     * @param request
+     */
+    constructor(request) {
+        super(`#actor sends ${request.toString()}`);
+        this.request = request;
+    }
+    /**
+     * @inheritDoc
      */
     performAs(actor) {
         const callAnApi = abilities_1.CallAnApi.as(actor);
@@ -67,26 +57,22 @@ class Send extends core_1.Interaction {
             actor.collect(this.responseToArtifact(resolvedUrl, response), this.requestToArtifactName(response.config.method, resolvedUrl));
         }));
     }
-    /**
-     * @desc
-     *  Generates a description to be used when reporting this {@link @serenity-js/core/lib/screenplay~Activity}.
-     *
-     * @returns {string}
-     */
-    toString() {
-        return `#actor sends ${this.request.toString()}`;
-    }
     responseToArtifact(targetUrl, response) {
-        const request = response.config, requestAndResponse = {
+        const request = response.config;
+        const axiosRequestHeaders = request.headers;
+        const requestHeaders = axios_1.AxiosHeaders.from(axiosRequestHeaders).toJSON(true);
+        const axiosResponseHeaders = response.headers;
+        const responseHeaders = axios_1.AxiosHeaders.from(axiosResponseHeaders).toJSON(false);
+        const requestAndResponse = {
             request: {
                 method: request.method,
                 url: targetUrl,
-                headers: request.headers,
+                headers: requestHeaders,
                 data: request.data,
             },
             response: {
                 status: response.status,
-                headers: response.headers,
+                headers: responseHeaders,
                 data: response.data,
             },
         };

package/lib/screenplay/interactions/Send.js.map

@@ -1 +1 @@
-{"version":3,"file":"Send.js","sourceRoot":"","sources":["../../../src/screenplay/interactions/Send.ts"],"names":[],"mappings":";;;AAAA,4CAAgH;AAChH,uDAAsG;AAGtG,4CAAyC;AAEzC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAa,IAAK,SAAQ,kBAAW;IAejC;;;;OAIG;IACH,YAA6B,OAAuC;QAChE,KAAK,EAAE,CAAC;QADiB,YAAO,GAAP,OAAO,CAAgC;IAEpE,CAAC;IApBD;;;;;;;;OAQG;IACH,MAAM,CAAC,CAAC,CAAC,OAAuC;QAC5C,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC,CAAC;IAC7B,CAAC;IAWD;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,KAA2D;QACjE,MAAM,SAAS,GAAG,qBAAS,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;QAEtC,OAAO,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC;aAC5B,IAAI,CAAC,MAAM,CAAC,EAAE,CACX,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,QAAuB,EAAE,EAAE;YACvD,MAAM,WAAW,GAAG,SAAS,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;YAEjD,KAAK,CAAC,OAAO,CACT,IAAI,CAAC,kBAAkB,CAAC,WAAW,EAAE,QAAQ,CAAC,EAC9C,IAAI,CAAC,qBAAqB,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAClE,CAAC;QACN,CAAC,CAAC,CACL,CAAC;IACV,CAAC;IAED;;;;;OAKG;IACH,QAAQ;QACJ,OAAO,gBAAiB,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAG,EAAE,CAAC;IACvD,CAAC;IAEO,kBAAkB,CAAC,SAAiB,EAAE,QAAuB;QACjE,MACI,OAAO,GAAuB,QAAQ,CAAC,MAAM,EAC7C,kBAAkB,GAAuB;YACrC,OAAO,EAAE;gBACL,MAAM,EAAM,OAAO,CAAC,MAAM;gBAC1B,GAAG,EAAS,SAAS;gBACrB,OAAO,EAAK,OAAO,CAAC,OAAO;gBAC3B,IAAI,EAAQ,OAAO,CAAC,IAAI;aAC3B;YACD,QAAQ,EAAE;gBACN,MAAM,EAAM,QAAQ,CAAC,MAAM;gBAC3B,OAAO,EAAK,QAAQ,CAAC,OAAO;gBAC5B,IAAI,EAAQ,QAAQ,CAAC,IAAI;aAC5B;SACJ,CAAC;QAEN,OAAO,2BAAmB,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAC;IAC5D,CAAC;IAEO,qBAAqB,CAAC,MAAc,EAAE,GAAW;QACrD,OAAO,IAAI,YAAI,CAAC,GAAI,MAAM,CAAC,WAAW,EAAG,IAAK,GAAI,EAAE,CAAC,CAAC;IAC1D,CAAC;CACJ;AAtFD,oBAsFC"}
+{"version":3,"file":"Send.js","sourceRoot":"","sources":["../../../src/screenplay/interactions/Send.ts"],"names":[],"mappings":";;;AAAA,4CAAgH;AAChH,uDAAsG;AACtG,iCAAuH;AAEvH,4CAAyC;AAEzC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAa,IAAK,SAAQ,kBAAW;IAEjC;;;;;;;OAOG;IACH,MAAM,CAAC,CAAC,CAAC,OAAuC;QAC5C,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC,CAAC;IAC7B,CAAC;IAED;;OAEG;IACH,YAAuC,OAAuC;QAC1E,KAAK,CAAC,gBAAiB,OAAO,CAAC,QAAQ,EAAG,EAAE,CAAC,CAAC;QADX,YAAO,GAAP,OAAO,CAAgC;IAE9E,CAAC;IAED;;OAEG;IACH,SAAS,CAAC,KAA2D;QACjE,MAAM,SAAS,GAAG,qBAAS,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;QAEtC,OAAO,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC;aAC5B,IAAI,CAAC,MAAM,CAAC,EAAE,CACX,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,QAAuB,EAAE,EAAE;YACvD,MAAM,WAAW,GAAG,SAAS,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;YAEjD,KAAK,CAAC,OAAO,CACT,IAAI,CAAC,kBAAkB,CAAC,WAAW,EAAE,QAAQ,CAAC,EAC9C,IAAI,CAAC,qBAAqB,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAClE,CAAC;QACN,CAAC,CAAC,CACL,CAAC;IACV,CAAC;IAEO,kBAAkB,CAAC,SAAiB,EAAE,QAAuB;QACjE,MAAM,OAAO,GAAuB,QAAQ,CAAC,MAAM,CAAC;QAEpD,MAAM,mBAAmB,GAAG,OAAO,CAAC,OAAO,CAAC;QAC5C,MAAM,cAAc,GAA8C,oBAAY,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC,MAAM,CAAC,IAAI,CAA8C,CAAC;QAEnK,MAAM,oBAAoB,GAAmD,QAAQ,CAAC,OAAO,CAAC;QAC9F,MAAM,eAAe,GAAG,oBAAY,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC,MAAM,CAAC,KAAK,CAA4B,CAAC;QAEzG,MAAM,kBAAkB,GAAuB;YAC3C,OAAO,EAAE;gBACL,MAAM,EAAM,OAAO,CAAC,MAAM;gBAC1B,GAAG,EAAS,SAAS;gBACrB,OAAO,EAAK,cAAc;gBAC1B,IAAI,EAAQ,OAAO,CAAC,IAAI;aAC3B;YACD,QAAQ,EAAE;gBACN,MAAM,EAAM,QAAQ,CAAC,MAAM;gBAC3B,OAAO,EAAK,eAAkF;gBAC9F,IAAI,EAAQ,QAAQ,CAAC,IAAI;aAC5B;SACJ,CAAC;QAEF,OAAO,2BAAmB,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAC;IAC5D,CAAC;IAEO,qBAAqB,CAAC,MAAc,EAAE,GAAW;QACrD,OAAO,IAAI,YAAI,CAAC,GAAI,MAAM,CAAC,WAAW,EAAG,IAAK,GAAI,EAAE,CAAC,CAAC;IAC1D,CAAC;CACJ;AArED,oBAqEC"}

package/lib/screenplay/interactions/index.d.ts

@@ -1,3 +1,3 @@
 export * from './ChangeApiConfig';
-export * from './ChangeApiUrl';
 export * from './Send';
+//# sourceMappingURL=index.d.ts.map

package/lib/screenplay/interactions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/screenplay/interactions/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,QAAQ,CAAC"}

package/lib/screenplay/interactions/index.js

@@ -1,7 +1,11 @@
 "use strict";
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
-    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
 }) : (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     o[k2] = m[k];
@@ -11,6 +15,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./ChangeApiConfig"), exports);
-__exportStar(require("./ChangeApiUrl"), exports);
 __exportStar(require("./Send"), exports);
 //# sourceMappingURL=index.js.map

package/lib/screenplay/interactions/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/screenplay/interactions/index.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,oDAAkC;AAClC,iDAA+B;AAC/B,yCAAuB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/screenplay/interactions/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,oDAAkC;AAClC,yCAAuB"}

package/lib/screenplay/questions/LastResponse.d.ts

@@ -1,135 +1,189 @@
 import { QuestionAdapter } from '@serenity-js/core';
+import { RawAxiosResponseHeaders } from 'axios';
 /**
- * @desc
- *  Provides access to the properties of the last {@link AxiosResponse} object,
- *  cached on the {@link CallAnApi} {@link @serenity-js/core/lib/screenplay~Ability}.
+ * Provides access to the properties of the last {@apilink AxiosResponse} object,
+ * cached on the {@apilink Ability|ability} to {@apilink CallAnApi}.
  *
- * @example <caption>Verify response to a GET request</caption>
- *  import { Actor } from '@serenity-js/core';
- *  import { CallAnApi, GetRequest, LastResponse, Send } from '@serenity-js/rest'
- *  import { Ensure, equals } from '@serenity-js/assertions';
+ * ## Verify response to a GET request
  *
- *  interface Book {
- *      title: string;
- *      author: string
- *  }
+ * ```ts
+ * import { actorCalled } 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'));
+ * interface Book {
+ *     title: string;
+ *     author: string;
+ * }
  *
- *  actor.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',
- *      })),
- *  );
+ * await actorCalled('Apisit')
+ *   .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',
+ *     })),
+ *   )
+ * ```
  *
- * @example <caption>Use Serenity/JS adapters to navigate complex response objects</caption>
- *  import { Actor } from '@serenity-js/core';
- *  import { CallAnApi, GetRequest, LastResponse, Send } from '@serenity-js/rest'
- *  import { Ensure, equals } from '@serenity-js/assertions';
+ * ## Use Serenity/JS adapters to navigate complex response objects
  *
- *  interface Developer {
- *      name: string;
- *      id: string;
- *      projects: Project[];
- *  }
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { CallAnApi, GetRequest, LastResponse, Send } from '@serenity-js/rest'
+ * import { Ensure, equals } from '@serenity-js/assertions'
  *
- *  interface Project {
- *      name: string;
- *      repoUrl: string;
- *  }
+ * interface Developer {
+ *     name: string;
+ *     id: string;
+ *     projects: Project[];
+ * }
  *
- *  const actor = Actor.named('Apisit').whoCan(CallAnApi.at('https://myapp.com/api'));
+ * interface Project {
+ *     name: string;
+ *     repoUrl: string;
+ * }
  *
- *  actor.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')),
- *  );
+ * 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://github.com/axios/axios/blob/v0.27.2/index.d.ts#L133-L140)
+ *
+ * @group Questions
  */
 export declare class LastResponse {
     /**
-     * @desc
-     *  Enables asserting on the {@link LastResponse} status
+     * Retrieves the status code of the {@apilink LastResponse|last response}
      *
-     * @returns {@serenity-js/core/lib/screenplay~Question<number>}
+     * #### Learn more
+     * - [HTTP response status codes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status)
      */
     static status(): QuestionAdapter<number>;
     /**
-     * @desc
-     *  Enables asserting on the {@link LastResponse} body
+     * Retrieves the body of the {@apilink LastResponse|last response}
+     *
+     * #### A type-safe approach using generics
      *
-     * @example <caption>A type-safe approach using generics</caption>
-     *  interface Book {
-     *      title: string;
-     *      author: string
-     *  }
+     * ```ts
+     * import { actorCalled } from '@serenity-js/core'
+     * import { CallAnApi, LastResponse } from '@serenity-js/rest'
+     * import { Ensure, equals } from '@serenity-js/assertions'
      *
-     *  actor.attemptsTo(
+     * 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',
+     *        title: 'Zen and the Art of Motorcycle Maintenance: An Inquiry into Values',
+     *        author: 'Robert M. Pirsig',
      *      })),
-     *  );
+     *   )
+     * ```
      *
-     * @example <caption>A non-type-safe approach using `any`</caption>
-     *  actor.attemptsTo(
+     * ## 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',
+     *        title: 'Zen and the Art of Motorcycle Maintenance: An Inquiry into Values',
+     *        author: 'Robert M. Pirsig',
      *      })),
-     *  );
-     *
-     * @example <caption>Retrieving an item at path using Property.of</caption>
-     *  import { Property } from '@serenity-js/core';
-     *
-     *  actor.attemptsTo(
-     *      Ensure.that(
-     *          Property.of(LastResponse.body<Book>()).title,
-     *          equals('Zen and the Art of Motorcycle Maintenance: An Inquiry into Values'),
-     *      )
-     *  )
-     *
-     * @example <caption>Filtering response body using List</caption>
-     *  import { Property } from '@serenity-js/core';
-     *  import { property, startsWith } from '@serenity-js/assertions';
-     *
-     *  actor.attemptsTo(
-     *      Ensure.that(
-     *          // imagine the API returns an array of books
-     *          List.of(LastResponse.body<Book[]>())
-     *              .where(Property.at<Book>().author, equals('Robert M. Pirsig'))
-     *              .first(),
-     *          property('title', startsWith('Zen and the Art of Motorcycle Maintenance')),
-     *      )
-     *  )
-     *
-     * @returns {@serenity-js/core/lib/screenplay~Question<any>}
-     *
-     * @see {@link @serenity-js/core/lib/screenplay/questions~Property}
-     * @see {@link @serenity-js/core/lib/screenplay/questions~List}
+     *   )
+     * ```
+     *
+     * ## 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<T = any>(): QuestionAdapter<T>;
     /**
-     * @desc
-     *  Enables asserting on one of the {@link LastResponse}'s headers
+     * Retrieves a header of the {@apilink LastResponse|last response}, identified by `name`
+     *
+     * ## Asserting on a header
      *
-     * @param {string} name
-     * @returns {@serenity-js/core/lib/screenplay~Question<string>}
+     * ```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: string): QuestionAdapter<string>;
     /**
-     * @desc
-     *  Enables asserting on all of the {@link LastResponse}'s headers,
-     *  returned as an object where the keys represent header names.
+     * Retrieves all the headers of the {@apilink LastResponse|last response}.
+     *
+     * ## 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'
      *
-     * @returns {@serenity-js/core/lib/screenplay~Question<Record<string, string>>}
+     * 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(): QuestionAdapter<Record<string, string>>;
+    static headers(): QuestionAdapter<RawAxiosResponseHeaders>;
 }
+//# sourceMappingURL=LastResponse.d.ts.map

package/lib/screenplay/questions/LastResponse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LastResponse.d.ts","sourceRoot":"","sources":["../../../src/screenplay/questions/LastResponse.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAC9D,OAAO,EAAE,uBAAuB,EAAE,MAAM,OAAO,CAAC;AAIhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,qBAAa,YAAY;IAErB;;;;;OAKG;IACH,MAAM,CAAC,MAAM,IAAI,eAAe,CAAC,MAAM,CAAC;IAMxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAyEG;IACH,MAAM,CAAC,IAAI,CAAC,CAAC,GAAG,GAAG,KAAK,eAAe,CAAC,CAAC,CAAC;IAM1C;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAAC,MAAM,CAAC;IAMpD;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,OAAO,IAAI,eAAe,CAAC,uBAAuB,CAAC;CAK7D"}