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

package/src/{model → models}/HTTPRequest.ts

@@ -1,47 +1,39 @@
-import { Answerable, AnswersQuestions, Question, UsesAbilities } from '@serenity-js/core';
-import { formatted } from '@serenity-js/core/lib/io';
+import { Answerable, AnswersQuestions, Question, UsesAbilities, WithAnswerableProperties } from '@serenity-js/core';
+import { d } from '@serenity-js/core/lib/io';
 import { AxiosRequestConfig } from 'axios';
 
 /**
- * @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
  */
 export abstract class HTTPRequest extends Question<Promise<AxiosRequestConfig>> {
 
     private subject: string;
 
     /**
-     * @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
      */
     protected constructor(
         protected readonly resourceUri?: Answerable<string>,
         protected readonly data?: Answerable<any>,
-        protected readonly config?: Answerable<AxiosRequestConfig>,
+        protected readonly config?: Answerable<WithAnswerableProperties<AxiosRequestConfig>>,
     ) {
         super();
-        this.subject = `${ this.requestDescription() } to ${ formatted `${ this.resourceUri }` }`;
+        this.subject = `${ this.requestDescription() } to ${ 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: AnswersQuestions & UsesAbilities): Promise<AxiosRequestConfig> {
         return Promise.all([
@@ -61,7 +53,7 @@ export abstract class HTTPRequest extends Question<Promise<AxiosRequestConfig>>
         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;
@@ -70,17 +62,16 @@ export abstract class HTTPRequest extends Question<Promise<AxiosRequestConfig>>
     }
 
     /**
-     * @desc
-     *  Changes the description of this question's subject.
-     *
-     * @param {string} subject
-     * @returns {Question<T>}
+     * @inheritDoc
      */
     describedAs(subject: string): this {
         this.subject = subject;
         return this;
     }
 
+    /**
+     * @inheritDoc
+     */
     toString(): string {
         return this.subject;
     }

package/src/models/HeadRequest.ts

@@ -0,0 +1,65 @@
+import { Answerable, Question, 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 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 {
+        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: Answerable<WithAnswerableProperties<AxiosRequestConfig>>): HeadRequest {
+        return new HeadRequest(this.resourceUri, undefined, Question.fromObject(config));
+    }
+}

package/src/models/OptionsRequest.ts

@@ -0,0 +1,68 @@
+import { Answerable, Question, WithAnswerableProperties } from '@serenity-js/core';
+import { AxiosRequestConfig } from 'axios';
+
+import { HTTPRequest } from './HTTPRequest';
+
+/**
+ * The OPTIONS method requests information about the communication
+ * options available for the target resource, at either the origin
+ * server or an intervening intermediary.  This method allows a client
+ * to determine the options and/or requirements associated with a
+ * resource, or the capabilities of a server, without implying a
+ * resource action.
+ *
+ * ## File download test
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { CallAnApi, OptionsRequest, 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(OptionsRequest.to('/downloads/my-test-document.pdf')),
+ *     Ensure.that(LastResponse.status(), equals(200)),
+ *     Ensure.that(LastResponse.header('Allow'), equals('OPTIONS, GET, HEAD')),
+ *   )
+ * ```
+ *
+ * ## Learn more
+ * - https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/OPTIONS
+ * - https://tools.ietf.org/html/rfc7231#section-4.3.7
+ *
+ * @group Models
+ */
+export class OptionsRequest 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>): OptionsRequest {
+        return new OptionsRequest(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: Answerable<WithAnswerableProperties<AxiosRequestConfig>>): OptionsRequest {
+        return new OptionsRequest(this.resourceUri, undefined, Question.fromObject(config));
+    }
+}

package/src/models/PatchRequest.ts

@@ -0,0 +1,75 @@
+import { Answerable, Question, WithAnswerableProperties } from '@serenity-js/core';
+import { AxiosRequestConfig } from 'axios';
+
+import { HTTPRequest } from './HTTPRequest';
+
+/**
+ * The PATCH method requests that a set of changes described in the
+ * request entity be applied to the resource identified by the `resourceUri`.
+ *
+ * ## Add new resource to a collection
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { CallAnApi, LastResponse, PatchRequest, 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(PatchRequest.to('/books/0-688-00230-7').with({
+ *       lastReadOn: '2016-06-16',
+ *     })),
+ *     Ensure.that(LastResponse.status(), equals(204)),
+ *   )
+ * ```
+ *
+ * ## Learn more
+ * - https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PATCH
+ * - https://tools.ietf.org/html/rfc5789
+ *
+ * @group Models
+ */
+export class PatchRequest 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>): PatchRequest {
+        return new PatchRequest(resourceUri);
+    }
+
+    /**
+     * Configures the object with a request body.
+     *
+     * @param data
+     *  Data to be sent to the `resourceUri`
+     */
+    with(data: Answerable<any>): PatchRequest {
+        return new PatchRequest(this.resourceUri, data, this.config);
+    }
+
+    /**
+     * 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>>): PatchRequest {
+        return new PatchRequest(this.resourceUri, this.data, Question.fromObject(config));
+    }
+}

package/src/models/PostRequest.ts

@@ -0,0 +1,115 @@
+import { Answerable, Question, WithAnswerableProperties } from '@serenity-js/core';
+import { AxiosRequestConfig } from 'axios';
+
+import { HTTPRequest } from './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(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
+ * - https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST
+ * - https://tools.ietf.org/html/rfc7231#section-4.3.3
+ *
+ * @group Models
+ */
+export class PostRequest 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>): PostRequest {
+        return new PostRequest(resourceUri);
+    }
+
+    /**
+     * Configures the object with a request body.
+     *
+     * @param data
+     *  Data to be sent to the `resourceUri`
+     */
+    with(data: Answerable<any>): PostRequest {
+        return new PostRequest(this.resourceUri, data, this.config);
+    }
+
+    /**
+     * 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>>): PostRequest {
+        return new PostRequest(this.resourceUri, this.data, Question.fromObject(config));
+    }
+}

package/src/models/PutRequest.ts

@@ -0,0 +1,85 @@
+import { Answerable, Question, WithAnswerableProperties } from '@serenity-js/core';
+import { AxiosRequestConfig } from 'axios';
+
+import { HTTPRequest } from './HTTPRequest';
+
+/**
+ * The PUT method requests that the state of the target resource be
+ * created or replaced with the state defined by the representation
+ * enclosed in the request message payload.
+ *
+ * PUT request should be used when you want to create
+ * a new resource at a known `resourceUri` (e.g. `/books/0-688-00230-7`)
+ * or replace an existing resource at such `resourceUri`.
+ *
+ * PUT request is [idempotent](https://developer.mozilla.org/en-US/docs/Glossary/Idempotent):
+ * calling it once or several times successively has the same effect (that is no _side effect_).
+ *
+ * ## Create a new resource at a known location
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core';
+ * import { CallAnApi, LastResponse, PutRequest, Send } from '@serenity-js/rest';
+ * import { Ensure, equals } from '@serenity-js/assertions';
+ *
+ * await actorCalled('Apisit')
+ *   .whoCan(CallAnApi.at('https://api.example.org/'))
+ *   .attemptsTo(
+ *     Send.a(PutRequest.to('/books/0-688-00230-7').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)),
+ *   )
+ * ```
+ *
+ * ## Learn more
+ * - https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PUT
+ * - https://tools.ietf.org/html/rfc7231#section-4.3.4
+ *
+ * @group Models
+ */
+export class PutRequest 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>): PutRequest {
+        return new PutRequest(resourceUri);
+    }
+
+    /**
+     * Configures the object with a request body.
+     *
+     * @param data
+     *  Data to be sent to the `resourceUri`
+     */
+    with(data: Answerable<any>): PutRequest {
+        return new PutRequest(this.resourceUri, data, this.config);
+    }
+
+    /**
+     * 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>>): PutRequest {
+        return new PutRequest(this.resourceUri, this.data, Question.fromObject(config));
+    }
+}