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

package/README.md

@@ -1,18 +1,16 @@
 # Serenity/JS
 
-[Serenity/JS](https://serenity-js.org) is a framework designed to make acceptance and regression testing
-of modern full-stack applications faster, more collaborative and easier to scale.
+[![Follow Serenity/JS on LinkedIn](https://img.shields.io/badge/Follow-Serenity%2FJS%20-0077B5?logo=linkedin)](https://www.linkedin.com/company/serenity-js)
+[![Watch Serenity/JS on YouTube](https://img.shields.io/badge/Watch-@serenity--js-E62117?logo=youtube)](https://www.youtube.com/@serenity-js)
+[![Join Serenity/JS Community Chat](https://img.shields.io/badge/Chat-Serenity%2FJS%20Community-FBD30B?logo=matrix)](https://matrix.to/#/#serenity-js:gitter.im)
+[![Support Serenity/JS on GitHub](https://img.shields.io/badge/Support-@serenity--js-703EC8?logo=github)](https://matrix.to/#/#serenity-js:gitter.im)
 
-Visit [serenity-js.org](https://serenity-js.org/) for the [latest tutorials](https://serenity-js.org/handbook/)
-and [API docs](https://serenity-js.org/modules/), and follow [@SerenityJS](https://twitter.com/SerenityJS) and [@JanMolak](https://twitter.com/JanMolak) on Twitter for project updates.
+[Serenity/JS](https://serenity-js.org) is an innovative framework designed to make acceptance and regression testing
+of complex software systems faster, more collaborative and easier to scale.
 
-### Learning Serenity/JS
+To get started, check out the comprehensive [Serenity/JS Handbook](https://serenity-js.org/handbook), [API documentation](https://serenity-js.org/api/core), and [Serenity/JS project templates on GitHub](https://serenity-js.org/handbook/getting-started#serenityjs-project-templates).
 
-To learn more about Serenity/JS, check out the video below, read the [tutorial](https://serenity-js.org/handbook/thinking-in-serenity-js/index.html), review the [examples](https://github.com/serenity-js/serenity-js/tree/master/examples), and create your own test suite with [Serenity/JS template projects](https://github.com/serenity-js).
-
-If you have any questions, join us on [Serenity/JS Community Chat](https://gitter.im/serenity-js/Lobby).
-
-[![Full-Stack Acceptance Testing with Serenity/JS and the Screenplay Pattern](https://img.youtube.com/vi/djPMf-n93Rw/0.jpg)](https://www.youtube.com/watch?v=djPMf-n93Rw)
+If you have any questions or just want to say hello, join the [Serenity/JS Community Chat](https://matrix.to/#/#serenity-js:gitter.im).
 
 ## Serenity/JS REST
 

package/lib/index.d.ts

@@ -1,2 +1,3 @@
-export * from './model';
+export * from './models';
 export * from './screenplay';
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

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

package/lib/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];
@@ -10,6 +14,6 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./model"), exports);
+__exportStar(require("./models"), exports);
 __exportStar(require("./screenplay"), exports);
 //# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,0CAAwB;AACxB,+CAA6B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,2CAAyB;AACzB,+CAA6B"}

package/lib/models/DeleteRequest.d.ts

@@ -0,0 +1,66 @@
+import { Answerable, WithAnswerableProperties } from '@serenity-js/core';
+import { AxiosRequestConfig } from 'axios';
+import { HTTPRequest } from './HTTPRequest';
+/**
+ * The DELETE method requests that the origin server remove the
+ * association between the target resource and its current
+ * functionality.
+ *
+ * ## Create and then remove a resource
+ *
+ * ```ts
+ *  import { actorCalled } from '@serenity-js/core'
+ *  import { CallAnApi, DeleteRequest, LastResponse, PostRequest, Send } from '@serenity-js/rest'
+ *  import { Ensure, equals, startsWith } from '@serenity-js/assertions'
+ *
+ *  await actorCalled('Apisitt')
+ *    .whoCan(CallAnApi.at('https://api.example.org/'))
+ *    .attemptsTo(
+ *      // create a new test user account
+ *      Send.a(PostRequest.to('/users').with({
+ *          login: 'tester',
+ *          password: 'P@ssword1',
+ *      }),
+ *      Ensure.that(LastResponse.status(), equals(201)),
+ *      Ensure.that(LastResponse.header('Location'), startsWith('/users')),
+ *
+ *      // delete the test user account
+ *      Send.a(DeleteRequest.to(LastResponse.header('Location'))),
+ *      Ensure.that(LastResponse.status(), equals(200)),
+ *    )
+ * ```
+ *
+ * ## Learn more
+ * - https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/DELETE
+ * - https://tools.ietf.org/html/rfc7231#section-4.3.5
+ *
+ * @group Models
+ */
+export declare class DeleteRequest extends 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 {@apilink Ability|ability} to {@apilink CallAnApi} was instantiated.
+     *
+     * @param resourceUri
+     *  The URI where the {@apilink Actor}
+     *  should send the {@apilink HTTPRequest}
+     */
+    static to(resourceUri: Answerable<string>): DeleteRequest;
+    /**
+     * Overrides the default Axios request configuration provided
+     * when the {@apilink Ability|ability} to {@apilink CallAnApi} was instantiated.
+     *
+     * #### Learn more
+     * - {@apilink Answerable}
+     * - {@apilink WithAnswerableProperties}
+     * - [AxiosRequestConfig](https://github.com/axios/axios/blob/v0.27.2/index.d.ts#L75-L113)
+     *
+     * @param {Answerable<WithAnswerableProperties<AxiosRequestConfig>>} config
+     *  Axios request configuration overrides
+     */
+    using(config: Answerable<WithAnswerableProperties<AxiosRequestConfig>>): DeleteRequest;
+}
+//# sourceMappingURL=DeleteRequest.d.ts.map

package/lib/models/DeleteRequest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DeleteRequest.d.ts","sourceRoot":"","sources":["../../src/models/DeleteRequest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAY,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AACnF,OAAO,EAAE,kBAAkB,EAAE,MAAM,OAAO,CAAC;AAE3C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,qBAAa,aAAc,SAAQ,WAAW;IAE1C;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE,CAAC,WAAW,EAAE,UAAU,CAAC,MAAM,CAAC,GAAG,aAAa;IAIzD;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,MAAM,EAAE,UAAU,CAAC,wBAAwB,CAAC,kBAAkB,CAAC,CAAC,GAAG,aAAa;CAGzF"}

package/lib/models/DeleteRequest.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeleteRequest = void 0;
+const core_1 = require("@serenity-js/core");
+const HTTPRequest_1 = require("./HTTPRequest");
+/**
+ * The DELETE method requests that the origin server remove the
+ * association between the target resource and its current
+ * functionality.
+ *
+ * ## Create and then remove a resource
+ *
+ * ```ts
+ *  import { actorCalled } from '@serenity-js/core'
+ *  import { CallAnApi, DeleteRequest, LastResponse, PostRequest, Send } from '@serenity-js/rest'
+ *  import { Ensure, equals, startsWith } from '@serenity-js/assertions'
+ *
+ *  await actorCalled('Apisitt')
+ *    .whoCan(CallAnApi.at('https://api.example.org/'))
+ *    .attemptsTo(
+ *      // create a new test user account
+ *      Send.a(PostRequest.to('/users').with({
+ *          login: 'tester',
+ *          password: 'P@ssword1',
+ *      }),
+ *      Ensure.that(LastResponse.status(), equals(201)),
+ *      Ensure.that(LastResponse.header('Location'), startsWith('/users')),
+ *
+ *      // delete the test user account
+ *      Send.a(DeleteRequest.to(LastResponse.header('Location'))),
+ *      Ensure.that(LastResponse.status(), equals(200)),
+ *    )
+ * ```
+ *
+ * ## Learn more
+ * - https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/DELETE
+ * - https://tools.ietf.org/html/rfc7231#section-4.3.5
+ *
+ * @group Models
+ */
+class DeleteRequest 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 {@apilink Ability|ability} to {@apilink CallAnApi} was instantiated.
+     *
+     * @param resourceUri
+     *  The URI where the {@apilink Actor}
+     *  should send the {@apilink HTTPRequest}
+     */
+    static to(resourceUri) {
+        return new DeleteRequest(resourceUri);
+    }
+    /**
+     * Overrides the default Axios request configuration provided
+     * when the {@apilink Ability|ability} to {@apilink CallAnApi} was instantiated.
+     *
+     * #### Learn more
+     * - {@apilink Answerable}
+     * - {@apilink WithAnswerableProperties}
+     * - [AxiosRequestConfig](https://github.com/axios/axios/blob/v0.27.2/index.d.ts#L75-L113)
+     *
+     * @param {Answerable<WithAnswerableProperties<AxiosRequestConfig>>} config
+     *  Axios request configuration overrides
+     */
+    using(config) {
+        return new DeleteRequest(this.resourceUri, undefined, core_1.Question.fromObject(config));
+    }
+}
+exports.DeleteRequest = DeleteRequest;
+//# sourceMappingURL=DeleteRequest.js.map

package/lib/models/DeleteRequest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DeleteRequest.js","sourceRoot":"","sources":["../../src/models/DeleteRequest.ts"],"names":[],"mappings":";;;AAAA,4CAAmF;AAGnF,+CAA4C;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAa,aAAc,SAAQ,yBAAW;IAE1C;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE,CAAC,WAA+B;QACrC,OAAO,IAAI,aAAa,CAAC,WAAW,CAAC,CAAC;IAC1C,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,MAAgE;QAClE,OAAO,IAAI,aAAa,CAAC,IAAI,CAAC,WAAW,EAAE,SAAS,EAAE,eAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;IACvF,CAAC;CACJ;AAhCD,sCAgCC"}

package/lib/models/GetRequest.d.ts

@@ -0,0 +1,73 @@
+import { Answerable, WithAnswerableProperties } from '@serenity-js/core';
+import { AxiosRequestConfig } from 'axios';
+import { HTTPRequest } from './HTTPRequest';
+/**
+ * The HTTP GET method requests a representation of the specified resource.
+ * It is the most frequent type of request made by consumers of a typical HTTP API.
+ * For this reason it's important to test every known endpoint that responds to GET requests and ensure that it
+ * behaves correctly.
+ *
+ * Since the GET method is used to _retrieve_ data from a server, it should be implemented
+ * as [safe](https://developer.mozilla.org/en-US/docs/Glossary/Safe)
+ * and [idempotent](https://developer.mozilla.org/en-US/docs/Glossary/Idempotent).
+ * This means that an identical request can be made once or several times in a row with the same effect while leaving
+ * the server in the same state.
+ *
+ * ## 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.body<Book>(), equals({
+ *          title: 'Zen and the Art of Motorcycle Maintenance: An Inquiry into Values',
+ *          author: 'Robert M. Pirsig',
+ *      })),
+ *    )
+ * ```
+ *
+ * ## Learn more
+ * - https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/GET
+ * - https://tools.ietf.org/html/rfc7231#section-4.3.1
+ *
+ * @group Models
+ */
+export declare class GetRequest extends 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 {@apilink Ability|ability} to {@apilink CallAnApi} was instantiated.
+     *
+     * @param resourceUri
+     *  The URI where the {@apilink Actor}
+     *  should send the {@apilink HTTPRequest}
+     */
+    static to(resourceUri: Answerable<string>): GetRequest;
+    /**
+     * Overrides the default Axios request configuration provided
+     * when the {@apilink Ability|ability} to {@apilink CallAnApi} was instantiated.
+     *
+     * #### Learn more
+     * - {@apilink Answerable}
+     * - {@apilink WithAnswerableProperties}
+     * - [AxiosRequestConfig](https://github.com/axios/axios/blob/v0.27.2/index.d.ts#L75-L113)
+     *
+     * @param {Answerable<WithAnswerableProperties<AxiosRequestConfig>>} config
+     *  Axios request configuration overrides
+     */
+    using(config: Answerable<WithAnswerableProperties<AxiosRequestConfig>>): GetRequest;
+}
+//# sourceMappingURL=GetRequest.d.ts.map

package/lib/models/GetRequest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GetRequest.d.ts","sourceRoot":"","sources":["../../src/models/GetRequest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAY,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AACnF,OAAO,EAAE,kBAAkB,EAAE,MAAM,OAAO,CAAC;AAE3C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,qBAAa,UAAW,SAAQ,WAAW;IAEvC;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE,CAAC,WAAW,EAAE,UAAU,CAAC,MAAM,CAAC,GAAG,UAAU;IAItD;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,MAAM,EAAE,UAAU,CAAC,wBAAwB,CAAC,kBAAkB,CAAC,CAAC,GAAG,UAAU;CAGtF"}

package/lib/models/GetRequest.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GetRequest = void 0;
+const core_1 = require("@serenity-js/core");
+const HTTPRequest_1 = require("./HTTPRequest");
+/**
+ * The HTTP GET method requests a representation of the specified resource.
+ * It is the most frequent type of request made by consumers of a typical HTTP API.
+ * For this reason it's important to test every known endpoint that responds to GET requests and ensure that it
+ * behaves correctly.
+ *
+ * Since the GET method is used to _retrieve_ data from a server, it should be implemented
+ * as [safe](https://developer.mozilla.org/en-US/docs/Glossary/Safe)
+ * and [idempotent](https://developer.mozilla.org/en-US/docs/Glossary/Idempotent).
+ * This means that an identical request can be made once or several times in a row with the same effect while leaving
+ * the server in the same state.
+ *
+ * ## 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.body<Book>(), equals({
+ *          title: 'Zen and the Art of Motorcycle Maintenance: An Inquiry into Values',
+ *          author: 'Robert M. Pirsig',
+ *      })),
+ *    )
+ * ```
+ *
+ * ## Learn more
+ * - https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/GET
+ * - https://tools.ietf.org/html/rfc7231#section-4.3.1
+ *
+ * @group Models
+ */
+class GetRequest 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 {@apilink Ability|ability} to {@apilink CallAnApi} was instantiated.
+     *
+     * @param resourceUri
+     *  The URI where the {@apilink Actor}
+     *  should send the {@apilink HTTPRequest}
+     */
+    static to(resourceUri) {
+        return new GetRequest(resourceUri);
+    }
+    /**
+     * Overrides the default Axios request configuration provided
+     * when the {@apilink Ability|ability} to {@apilink CallAnApi} was instantiated.
+     *
+     * #### Learn more
+     * - {@apilink Answerable}
+     * - {@apilink WithAnswerableProperties}
+     * - [AxiosRequestConfig](https://github.com/axios/axios/blob/v0.27.2/index.d.ts#L75-L113)
+     *
+     * @param {Answerable<WithAnswerableProperties<AxiosRequestConfig>>} config
+     *  Axios request configuration overrides
+     */
+    using(config) {
+        return new GetRequest(this.resourceUri, undefined, core_1.Question.fromObject(config));
+    }
+}
+exports.GetRequest = GetRequest;
+//# sourceMappingURL=GetRequest.js.map

package/lib/models/GetRequest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GetRequest.js","sourceRoot":"","sources":["../../src/models/GetRequest.ts"],"names":[],"mappings":";;;AAAA,4CAAmF;AAGnF,+CAA4C;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAa,UAAW,SAAQ,yBAAW;IAEvC;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE,CAAC,WAA+B;QACrC,OAAO,IAAI,UAAU,CAAC,WAAW,CAAC,CAAC;IACvC,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,MAAgE;QAClE,OAAO,IAAI,UAAU,CAAC,IAAI,CAAC,WAAW,EAAE,SAAS,EAAE,eAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;IACpF,CAAC;CACJ;AAhCD,gCAgCC"}

package/lib/models/HTTPRequest.d.ts

@@ -0,0 +1,48 @@
+import { Answerable, AnswersQuestions, Question, UsesAbilities, WithAnswerableProperties } from '@serenity-js/core';
+import { AxiosRequestConfig } from 'axios';
+/**
+ * HTTP Request sent by the {@apilink Actor}
+ * using the {@apilink Interaction|interaction} to {@apilink Send}
+ *
+ * @group Models
+ */
+export declare abstract class HTTPRequest extends Question<Promise<AxiosRequestConfig>> {
+    protected readonly resourceUri?: Answerable<string>;
+    protected readonly data?: Answerable<any>;
+    protected readonly config?: Answerable<WithAnswerableProperties<AxiosRequestConfig>>;
+    private subject;
+    /**
+     * @param [resourceUri]
+     *  URL to which the request should be sent
+     *
+     * @param [data]
+     *  Request body to be sent as part of the Put, Post or Patch request
+     *
+     * @param {Answerable<WithAnswerableProperties<AxiosRequestConfig>>} [config]
+     *  Axios request configuration, which can be used to override the defaults
+     *  provided when the {@apilink Ability|ability} to {@apilink CallAnApi} is instantiated
+     */
+    protected constructor(resourceUri?: Answerable<string>, data?: Answerable<any>, config?: Answerable<WithAnswerableProperties<AxiosRequestConfig>>);
+    /**
+     * @inheritDoc
+     */
+    answeredBy(actor: AnswersQuestions & UsesAbilities): Promise<AxiosRequestConfig>;
+    /**
+     * @inheritDoc
+     */
+    describedAs(subject: string): this;
+    /**
+     * @inheritDoc
+     */
+    toString(): string;
+    /**
+     * Determines the request method based on the name of the request class.
+     * For example: GetRequest => GET, PostRequest => POST, etc.
+     */
+    private httpMethodName;
+    /**
+     * A human-readable description of the request, such as "a GET request", "an OPTIONS request", etc.
+     */
+    private requestDescription;
+}
+//# sourceMappingURL=HTTPRequest.d.ts.map

package/lib/models/HTTPRequest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HTTPRequest.d.ts","sourceRoot":"","sources":["../../src/models/HTTPRequest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,QAAQ,EAAE,aAAa,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAEpH,OAAO,EAAE,kBAAkB,EAAE,MAAM,OAAO,CAAC;AAE3C;;;;;GAKG;AACH,8BAAsB,WAAY,SAAQ,QAAQ,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAgBvE,SAAS,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,UAAU,CAAC,MAAM,CAAC;IACnD,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC,GAAG,CAAC;IACzC,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC,wBAAwB,CAAC,kBAAkB,CAAC,CAAC;IAhBxF,OAAO,CAAC,OAAO,CAAS;IAExB;;;;;;;;;;OAUG;IACH,SAAS,aACc,WAAW,CAAC,EAAE,UAAU,CAAC,MAAM,CAAC,EAChC,IAAI,CAAC,EAAE,UAAU,CAAC,GAAG,CAAC,EACtB,MAAM,CAAC,EAAE,UAAU,CAAC,wBAAwB,CAAC,kBAAkB,CAAC,CAAC;IAMxF;;OAEG;IACH,UAAU,CAAC,KAAK,EAAE,gBAAgB,GAAG,aAAa,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA0BhF;;OAEG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAKlC;;OAEG;IACH,QAAQ,IAAI,MAAM;IAIlB;;;OAGG;IACH,OAAO,CAAC,cAAc;IAItB;;OAEG;IACH,OAAO,CAAC,kBAAkB;CAO7B"}

package/lib/{model → models}/HTTPRequest.js

@@ -4,40 +4,32 @@ exports.HTTPRequest = void 0;
 const core_1 = require("@serenity-js/core");
 const io_1 = require("@serenity-js/core/lib/io");
 /**
- * @desc
- *  HTTP Request sent by the {@link @serenity-js/core/lib/screenplay/actor~Actor}
- *  using the {@link Send} {@link @serenity-js/core/lib/screenplay~Interaction}
+ * HTTP Request sent by the {@apilink Actor}
+ * using the {@apilink Interaction|interaction} to {@apilink Send}
  *
- * @abstract
- * @extends {Question<Promise<AxiosRequestConfig>>}
+ * @group Models
  */
 class HTTPRequest extends core_1.Question {
     /**
-     * @protected
-     *
-     * @param {@serenity-js/core/lib/screenplay~Answerable<string>} [resourceUri]
+     * @param [resourceUri]
      *  URL to which the request should be sent
      *
-     * @param {@serenity-js/core/lib/screenplay~Answerable<any>} [data]
+     * @param [data]
      *  Request body to be sent as part of the Put, Post or Patch request
      *
-     * @param {@serenity-js/core/lib/screenplay~Answerable<AxiosRequestConfig>} [config]
+     * @param {Answerable<WithAnswerableProperties<AxiosRequestConfig>>} [config]
      *  Axios request configuration, which can be used to override the defaults
-     *  provided when the {@link CallAnApi} {@link @serenity-js/core/lib/screenplay~Ability} is instantiated
+     *  provided when the {@apilink Ability|ability} to {@apilink CallAnApi} is instantiated
      */
     constructor(resourceUri, data, config) {
         super();
         this.resourceUri = resourceUri;
         this.data = data;
         this.config = config;
-        this.subject = `${this.requestDescription()} to ${(0, io_1.formatted) `${this.resourceUri}`}`;
+        this.subject = `${this.requestDescription()} to ${(0, io_1.d) `${this.resourceUri}`}`;
     }
     /**
-     * @desc
-     *  Resolves the {@link Question} in the context of a given {@link @serenity-js/core/lib/screenplay/actor~Actor}
-     *
-     * @param {AnswersQuestions & UsesAbilities} actor
-     * @returns {Promise<AxiosRequestConfig>}
+     * @inheritDoc
      */
     answeredBy(actor) {
         return Promise.all([
@@ -49,23 +41,22 @@ class HTTPRequest extends core_1.Question {
             then(config => 
         // eslint-disable-next-line unicorn/prefer-object-from-entries
         Object.keys(config).reduce((acc, key) => {
-            if (config[key]) {
+            if (config[key] !== null && config[key] !== undefined) {
                 acc[key] = config[key];
             }
             return acc;
         }, {}));
     }
     /**
-     * @desc
-     *  Changes the description of this question's subject.
-     *
-     * @param {string} subject
-     * @returns {Question<T>}
+     * @inheritDoc
      */
     describedAs(subject) {
         this.subject = subject;
         return this;
     }
+    /**
+     * @inheritDoc
+     */
     toString() {
         return this.subject;
     }

package/lib/models/HTTPRequest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HTTPRequest.js","sourceRoot":"","sources":["../../src/models/HTTPRequest.ts"],"names":[],"mappings":";;;AAAA,4CAAoH;AACpH,iDAA6C;AAG7C;;;;;GAKG;AACH,MAAsB,WAAY,SAAQ,eAAqC;IAI3E;;;;;;;;;;OAUG;IACH,YACuB,WAAgC,EAChC,IAAsB,EACtB,MAAiE;QAEpF,KAAK,EAAE,CAAC;QAJW,gBAAW,GAAX,WAAW,CAAqB;QAChC,SAAI,GAAJ,IAAI,CAAkB;QACtB,WAAM,GAAN,MAAM,CAA2D;QAGpF,IAAI,CAAC,OAAO,GAAG,GAAI,IAAI,CAAC,kBAAkB,EAAG,OAAQ,IAAA,MAAC,EAAA,GAAI,IAAI,CAAC,WAAY,EAAG,EAAE,CAAC;IACrF,CAAC;IAED;;OAEG;IACH,UAAU,CAAC,KAAuC;QAC9C,OAAO,OAAO,CAAC,GAAG,CAAC;YACf,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAG,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YAC7E,IAAI,CAAC,MAAM,CAAM,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAQ,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;YACzE,IAAI,CAAC,IAAI,CAAQ,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAU,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;SAChF,CAAC;YACF,IAAI,CAAC,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,CAEzB,MAAM,CAAC,MAAM,CACT,EAAE,EACF,EAAE,GAAG,EAAE,IAAI,EAAE,EACb,MAAM,EACN,EAAE,MAAM,EAAE,IAAI,CAAC,cAAc,EAAE,EAAE,CACpC,CACJ;YACD,IAAI,CAAC,MAAM,CAAC,EAAE;QACV,8DAA8D;QAC9D,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;YACpC,IAAI,MAAM,CAAC,GAAG,CAAC,KAAK,IAAI,IAAI,MAAM,CAAC,GAAG,CAAC,KAAK,SAAS,EAAG;gBACpD,GAAG,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;aAC1B;YACD,OAAO,GAAG,CAAC;QACf,CAAC,EAAE,EAAE,CAAC,CACT,CAAC;IACN,CAAC;IAED;;OAEG;IACH,WAAW,CAAC,OAAe;QACvB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,OAAO,IAAI,CAAC;IAChB,CAAC;IAED;;OAEG;IACH,QAAQ;QACJ,OAAO,IAAI,CAAC,OAAO,CAAC;IACxB,CAAC;IAED;;;OAGG;IACK,cAAc;QAClB,OAAO,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;IACtE,CAAC;IAED;;OAEG;IACK,kBAAkB;QACtB,MACI,MAAM,GAAG,CAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAE,EACpC,MAAM,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC;QAEnC,OAAO,GAAI,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAI,IAAK,MAAO,UAAU,CAAC;IAC9E,CAAC;CACJ;AAtFD,kCAsFC"}

package/lib/models/HeadRequest.d.ts

@@ -0,0 +1,58 @@
+import { Answerable, WithAnswerableProperties } from '@serenity-js/core';
+import { AxiosRequestConfig } from 'axios';
+import { HTTPRequest } from './HTTPRequest';
+/**
+ * The HTTP HEAD method requests the headers that are returned if the specified resource
+ * would be requested with an HTTP GET method.
+ * Such a request can be done before deciding to download a large resource to save bandwidth, for example.
+ *
+ * ## File download test
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { CallAnApi, HeadRequest, 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(HeadRequest.to('/downloads/my-test-document.pdf')),
+ *     Ensure.that(LastResponse.status(), equals(200)),
+ *     Ensure.that(LastResponse.header('Content-Length'), equals(256)), // assuming we know the size of the document
+ *   )
+ * ```
+ *
+ * ## Learn more
+ * - https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD
+ * - https://tools.ietf.org/html/rfc7231#section-4.3.2
+ *
+ * @group Models
+ */
+export declare class HeadRequest extends 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 {@apilink Ability|ability} to {@apilink CallAnApi} was instantiated.
+     *
+     * @param resourceUri
+     *  The URI where the {@apilink Actor}
+     *  should send the {@apilink HTTPRequest}
+     */
+    static to(resourceUri: Answerable<string>): HeadRequest;
+    /**
+     * Overrides the default Axios request configuration provided
+     * when the {@apilink Ability|ability} to {@apilink CallAnApi} was instantiated.
+     *
+     * #### Learn more
+     * - {@apilink Answerable}
+     * - {@apilink WithAnswerableProperties}
+     * - [AxiosRequestConfig](https://github.com/axios/axios/blob/v0.27.2/index.d.ts#L75-L113)
+     *
+     * @param {Answerable<WithAnswerableProperties<AxiosRequestConfig>>} config
+     *  Axios request configuration overrides
+     */
+    using(config: Answerable<WithAnswerableProperties<AxiosRequestConfig>>): HeadRequest;
+}
+//# sourceMappingURL=HeadRequest.d.ts.map

package/lib/models/HeadRequest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HeadRequest.d.ts","sourceRoot":"","sources":["../../src/models/HeadRequest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAY,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AACnF,OAAO,EAAE,kBAAkB,EAAE,MAAM,OAAO,CAAC;AAE3C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,WAAY,SAAQ,WAAW;IAExC;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE,CAAC,WAAW,EAAE,UAAU,CAAC,MAAM,CAAC,GAAG,WAAW;IAIvD;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,MAAM,EAAE,UAAU,CAAC,wBAAwB,CAAC,kBAAkB,CAAC,CAAC,GAAG,WAAW;CAGvF"}

package/lib/models/HeadRequest.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HeadRequest = void 0;
+const core_1 = require("@serenity-js/core");
+const HTTPRequest_1 = require("./HTTPRequest");
+/**
+ * The HTTP HEAD method requests the headers that are returned if the specified resource
+ * would be requested with an HTTP GET method.
+ * Such a request can be done before deciding to download a large resource to save bandwidth, for example.
+ *
+ * ## File download test
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { CallAnApi, HeadRequest, 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(HeadRequest.to('/downloads/my-test-document.pdf')),
+ *     Ensure.that(LastResponse.status(), equals(200)),
+ *     Ensure.that(LastResponse.header('Content-Length'), equals(256)), // assuming we know the size of the document
+ *   )
+ * ```
+ *
+ * ## Learn more
+ * - https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD
+ * - https://tools.ietf.org/html/rfc7231#section-4.3.2
+ *
+ * @group Models
+ */
+class HeadRequest 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 {@apilink Ability|ability} to {@apilink CallAnApi} was instantiated.
+     *
+     * @param resourceUri
+     *  The URI where the {@apilink Actor}
+     *  should send the {@apilink HTTPRequest}
+     */
+    static to(resourceUri) {
+        return new HeadRequest(resourceUri);
+    }
+    /**
+     * Overrides the default Axios request configuration provided
+     * when the {@apilink Ability|ability} to {@apilink CallAnApi} was instantiated.
+     *
+     * #### Learn more
+     * - {@apilink Answerable}
+     * - {@apilink WithAnswerableProperties}
+     * - [AxiosRequestConfig](https://github.com/axios/axios/blob/v0.27.2/index.d.ts#L75-L113)
+     *
+     * @param {Answerable<WithAnswerableProperties<AxiosRequestConfig>>} config
+     *  Axios request configuration overrides
+     */
+    using(config) {
+        return new HeadRequest(this.resourceUri, undefined, core_1.Question.fromObject(config));
+    }
+}
+exports.HeadRequest = HeadRequest;
+//# sourceMappingURL=HeadRequest.js.map

package/lib/models/HeadRequest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HeadRequest.js","sourceRoot":"","sources":["../../src/models/HeadRequest.ts"],"names":[],"mappings":";;;AAAA,4CAAmF;AAGnF,+CAA4C;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAa,WAAY,SAAQ,yBAAW;IAExC;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE,CAAC,WAA+B;QACrC,OAAO,IAAI,WAAW,CAAC,WAAW,CAAC,CAAC;IACxC,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,MAAgE;QAClE,OAAO,IAAI,WAAW,CAAC,IAAI,CAAC,WAAW,EAAE,SAAS,EAAE,eAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;IACrF,CAAC;CACJ;AAhCD,kCAgCC"}