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

package/src/screenplay/abilities/CallAnApi.ts

@@ -1,72 +1,74 @@
-import { Ability, ConfigurationError, LogicError, TestCompromisedError, UsesAbilities } from '@serenity-js/core';
-import axios, { AxiosError, AxiosInstance, AxiosPromise, AxiosRequestConfig, AxiosResponse } from 'axios';
-const mergeConfig = require('axios/lib/core/mergeConfig');      // eslint-disable-line @typescript-eslint/no-var-requires
-const buildFullPath = require('axios/lib/core/buildFullPath');  // eslint-disable-line @typescript-eslint/no-var-requires
+import { Ability, ConfigurationError, LogicError, TestCompromisedError } from '@serenity-js/core';
+import axios, { AxiosDefaults, AxiosError, AxiosInstance, AxiosPromise, AxiosRequestConfig, AxiosResponse } from 'axios';
 
 /**
- * @desc
- *  An {@link @serenity-js/core/lib/screenplay~Ability} that enables the {@link Actor} to call a HTTP API.
- *  If you need to connect via a proxy, check out [this article](https://janmolak.com/node-js-axios-behind-corporate-proxies-8b17a6f31f9d).
+ * An {@apilink Ability} that enables the {@apilink Actor} to call an HTTP API.
  *
- * @example <caption>Using a default Axios HTTP client</caption>
- *  import { Actor } from '@serenity-js/core';
- *  import { CallAnApi, GetRequest, LastResponse, Send } from '@serenity-js/rest'
- *  import { Ensure, equals } from '@serenity-js/assertions';
+ * If you need to connect via a proxy, check out ["Using Axios behind corporate proxies"](https://janmolak.com/node-js-axios-behind-corporate-proxies-8b17a6f31f9d).
  *
- *  const actor = Actor.named('Apisit').whoCan(
- *      CallAnApi.at('https://myapp.com/api'),
- *  );
+ * ## Using the default Axios HTTP client
  *
- *  actor.attemptsTo(
- *      Send.a(GetRequest.to('/users/2')),
- *      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'
  *
- * @example <caption>Using Axios client with custom configuration</caption>
- *  import { Actor } from '@serenity-js/core';
- *  import { CallAnApi, GetRequest, 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(GetRequest.to('/users/2')),
+ *     Ensure.that(LastResponse.status(), equals(200)),
+ *   )
+ * ```
  *
- *  import axios from 'axios';
+ * ## Using Axios client with custom configuration
  *
- *  const axiosInstance = axios.create({
- *      timeout: 5 * 1000,
- *      headers: {
- *          'X-Custom-Api-Key': 'secret-key',
- *      },
- *  });
+ * ```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.using(axiosInstance),
- *  );
+ * import * as axios from 'axios'
  *
- *  actor.attemptsTo(
- *      Send.a(GetRequest.to('/users/2')),
- *      Ensure.that(LastResponse.status(), equals(200)),
- *  );
+ * const axiosInstance = axios.create({
+ *   timeout: 5 * 1000,
+ *   headers: {
+ *     'X-Custom-Api-Key': 'secret-key',
+ *   },
+ * });
  *
- * @see https://github.com/axios/axios
- * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods
+ * await actorCalled('Apisitt')
+ *   .whoCan(
+ *     CallAnApi.using(axiosInstance),
+ *   )
+ *   .attemptsTo(
+ *     Send.a(GetRequest.to('/users/2')),
+ *     Ensure.that(LastResponse.status(), equals(200)),
+ *   )
+ * ```
  *
- * @public
- * @implements {@link @serenity-js/core/lib/screenplay~Ability}
+ * ## Learn more
+ * - https://github.com/axios/axios
+ * - https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods
+ *
+ * @group Abilities
  */
-export class CallAnApi implements Ability {
+export class CallAnApi extends Ability {
 
     /** @private */
     private lastResponse: AxiosResponse;
 
     /**
-     * @desc
-     *  Ability to Call and api at a specified baseUrl
+     * Produces an {@apilink Ability|ability} to call a REST api at a specified baseUrl
      *
-     *  Default timeout is set to 2s.
+     * Default timeout is set to 2s.
      *
-     *  Default request headers:
-     *  - Accept: application/json,application/xml
+     * Default request headers:
+     * - `Accept`: `application/json,application/xml`
      *
-     * @param {string} baseURL
-     * @returns {CallAnApi}
+     * @param baseURL
      */
     static at(baseURL: string): CallAnApi {
         return new CallAnApi(axios.create({
@@ -77,111 +79,91 @@ export class CallAnApi implements Ability {
     }
 
     /**
-     * @desc
-     *  Ability to Call a REST API using a given axios instance.
+     * Produces an {@apilink Ability|ability} to call a REST API using a given axios instance.
      *
-     *  Useful when you need to customise Axios to
-     *  [make it aware of proxies](https://janmolak.com/node-js-axios-behind-corporate-proxies-8b17a6f31f9d),
-     *  for example.
+     * Useful when you need to customise Axios to
+     * [make it aware of proxies](https://janmolak.com/node-js-axios-behind-corporate-proxies-8b17a6f31f9d),
+     * for example.
      *
-     * @param {AxiosInstance} axiosInstance
-     * @returns {CallAnApi}
+     * #### Learn more
+     * - [AxiosInstance](https://github.com/axios/axios/blob/v0.27.2/index.d.ts#L235-L238)
      *
-     * @see {@link AxiosInstance}
+     * @param axiosInstance
      */
     static using(axiosInstance: AxiosInstance): CallAnApi {
         return new CallAnApi(axiosInstance);
     }
 
     /**
-     * @desc
-     *  Used to access the Actor's ability to {@link CallAnApi}
-     *  from within the {@link @serenity-js/core/lib/screenplay~Interaction} classes,
-     *  such as {@link Send}.
+     * #### Learn more
+     * - [AxiosInstance](https://github.com/axios/axios/blob/v0.27.2/index.d.ts#L235-L238)
      *
-     * @param {UsesAbilities} actor
-     * @return {CallAnApi}
-     */
-    static as(actor: UsesAbilities): CallAnApi {
-        return actor.abilityTo(CallAnApi);
-    }
-
-    /**
-     * @param {AxiosInstance} axiosInstance
+     * @param axiosInstance
      *  A pre-configured instance of the Axios HTTP client
-     *
-     * @see {@link AxiosInstance}
      */
     constructor(private readonly axiosInstance: AxiosInstance) {
+        super();
     }
 
     /**
-     * @desc
-     *  Allows for the original Axios config to be changed after
-     *  the {@link CallAnApi} {@link @serenity-js/core/lib/screenplay~Ability}
-     *  has been instantiated and given to the {@link Actor}.
+     * Allows for the original Axios config to be changed after
+     * the {@apilink Ability|ability} to {@apilink CallAnApi}
+     * has been instantiated and given to the {@apilink Actor}.
      *
-     * @param {function (original: AxiosRequestConfig): any} fn
-     * @returns {void}
+     * #### Learn more
+     * - [AxiosRequestConfig](https://github.com/axios/axios/blob/v0.27.2/index.d.ts#L75-L113)
      *
-     * @see {@link AxiosRequestConfig}
+     * @param fn
      */
-    modifyConfig(fn: (original: AxiosRequestConfig) => any): void {
+    modifyConfig(fn: (original: AxiosDefaults<any>) => any): void {
         fn(this.axiosInstance.defaults);
     }
 
     /**
-     * @desc
-     *  Sends a HTTP request to a specified url.
-     *  Response will be cached and available via {@link CallAnApi#mapLastResponse}
-     *
-     * @param {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
+     * Sends an HTTP request to a specified url.
+     * Response will be cached and available via {@apilink mapLastResponse}
      *
-     * @returns {Promise<AxiosResponse>}
-     *  A promise of an AxiosResponse
+     * #### Learn more
+     * - [AxiosRequestConfig](https://github.com/axios/axios/blob/v0.27.2/index.d.ts#L75-L113)
+     * - [AxiosResponse](https://github.com/axios/axios/blob/v0.27.2/index.d.ts#L133-L140)
      *
-     * @see {@link AxiosRequestConfig}
-     * @see {@link AxiosResponse}
+     * @param config
+     *  Axios request configuration, which can be used to override the defaults
+     *  provided when the {@apilink Ability|ability} to {@apilink CallAnApi} was instantiated.
      */
     request(config: AxiosRequestConfig): Promise<AxiosResponse> {
         return this.captureResponseOf(this.axiosInstance.request(config));
     }
 
     /**
-     * @desc
-     *  Resolves the final URL, based on the {@link AxiosRequestConfig} provided
-     *  any any defaults {@link AxiosInstance} has been configured with.
+     * Resolves the final URL, based on the {@apilink AxiosRequestConfig} provided
+     * and any defaults that the {@apilink AxiosInstance} has been configured with.
      *
-     * @param {AxiosRequestConfig} config
-     * @returns {string}
+     * #### Learn more
+     * - [AxiosRequestConfig](https://github.com/axios/axios/blob/v0.27.2/index.d.ts#L75-L113)
+     * - [AxiosInstance](https://github.com/axios/axios/blob/v0.27.2/index.d.ts#L235-L238)
      *
-     * @see {@link AxiosRequestConfig}
-     * @see {@link AxiosInstance}
+     * @param config
      */
     resolveUrl(config: AxiosRequestConfig): string {
-        const merged = mergeConfig(this.axiosInstance.defaults, config);
-
-        return buildFullPath(merged.baseURL, merged.url);
+        return this.axiosInstance.getUri(config);
     }
 
     /**
-     * @desc
-     *  Maps the last cached response to another type.
-     *  Useful when you need to extract a portion of the {@link AxiosResponse} object.
+     * Maps the last cached response to another type.
+     * Useful when you need to extract a portion of the {@apilink AxiosResponse} object.
      *
-     * @param {function<T>(AxiosResponse): T} fn - mapper function
-     * @returns {T}
+     * #### Learn more
+     * - [AxiosResponse](https://github.com/axios/axios/blob/v0.27.2/index.d.ts#L133-L140)
      *
-     * @see {@link AxiosResponse}
+     * @param mappingFunction
      */
-    mapLastResponse<T>(fn: (response: AxiosResponse) => T): T {
+    mapLastResponse<T>(mappingFunction: (response: AxiosResponse) => T): T {
         if (!this.lastResponse) {
             throw new LogicError(`Make sure to perform a HTTP API call before checking on the response`);
         }
 
-        return fn(this.lastResponse);
+        return mappingFunction(this.lastResponse);
     }
 
     private captureResponseOf(promisedResponse: AxiosPromise): AxiosPromise {

package/src/screenplay/interactions/ChangeApiConfig.ts

@@ -1,123 +1,123 @@
-import { Answerable, AnswersQuestions, CollectsArtifacts, Interaction, LogicError, UsesAbilities } from '@serenity-js/core';
+import { Answerable, AnswersQuestions, CollectsArtifacts, d, Interaction, LogicError, UsesAbilities } from '@serenity-js/core';
 import { URL } from 'url';
 
 import { CallAnApi } from '../abilities';
 
 /**
- * @desc
- *  Changes configuration of the {@link CallAnApi} {@link @serenity-js/core/lib/screenplay~Ability}
- *  the {@link @serenity-js/core/lib/screenplay/actor~Actor}
- *  executing this {@link @serenity-js/core/lib/screenplay~Interaction} has been configured with.
- *
- * @example <caption>Changing API URL for all subsequent requests</caption>
- *  import { actorCalled } from '@serenity-js/core';
- *  import { Navigate, Target, Text } from '@serenity-js/protractor';
- *  import { CallAnApi, ChangeApiConfig, GetRequest, LastResponse, Send } from '@serenity-js/rest'
- *  import { Ensure, equals } from '@serenity-js/assertions';
- *  import { protractor, by } from 'protractor';
- *
- *  import axios from 'axios';
- *
- *  const actor = actorCalled('Apisitt').whoCan(
- *      BrowseTheWeb.using(protractor.browser),
- *
- *      // Note: no default base URL is given when the axios instance is created
- *      CallAnApi.using(axios.create()),
- *  );
- *
- *  // Let's imagine that the website under test displays
- *  // a dynamically generated API URL we'd like to use
- *  const ApiDetailsWidget = {
- *      Url: Target.the('API URL').located(by.id('api-url')),
- *  }
- *
- *  actor.attemptsTo(
- *      Navigate.to('/profile'),
- *
- *      // We change the API URL based on the text displayed in the widget
- *      // (although we could change it to some arbitrary string too).
- *      ChangeApiConfig.setUrlTo(Text.of(ApiDetailsWidget.Url)),
- *
- *      // Any subsequent request will be sent to the newly set URL
- *      Send.a(GetRequest.to('/projects')),
- *      Ensure.that(LastResponse.status(), equals(200)),
- *  );
- *
- * @example <caption>Changing API port for all subsequent requests</caption>
- *  import { actorCalled } from '@serenity-js/core';
- *  import { LocalServer, ManageALocalServer, StartLocalServer } from '@serenity-js/local-server';
- *  import { CallAnApi, ChangeApiConfig, GetRequest, LastResponse, Send } from '@serenity-js/rest'
- *  import { Ensure, equals } from '@serenity-js/assertions';
- *
- *  const actor = actorCalled('Apisitt').whoCan(
- *      ManageALocalServer.runningAHttpListener(someServer),
- *      CallAnApi.at('http://localhost'),
- *  );
- *
- *  actor.attemptsTo(
- *      StartALocalServer.onRandomPort(),
- *      ChangeApiConfig.setPortTo(LocalServer.port()),
- *      Send.a(GetRequest.to('/api')),
- *      Ensure.that(LastResponse.status(), equals(200)),
- *  );
- *
- * @example <caption>Setting a header for all subsequent requests</caption>
- *  import { actorCalled, Question } from '@serenity-js/core';
- *  import { CallAnApi, ChangeApiConfig, GetRequest, LastResponse, Send } from '@serenity-js/rest';
- *  import { Ensure, equals } from '@serenity-js/assertions';
- *
- *  const actor = actorCalled('Apisitt').whoCan(
- *      CallAnApi.at('http://localhost'),
- *  );
- *
- *  // A sample Question reading Node process environment variable
- *  const EnvVar = (var_name: string) =>
- *      Question.about(`${ name } environment variable`, actor => process.env[var_name]);
- *
- *  actor.attemptsTo(
- *      ChangeApiConfig.setHeader('Authorization', EnvVar('TOKEN')),
- *      Send.a(GetRequest.to('/api')),
- *      Ensure.that(LastResponse.status(), equals(200)),
- *  );
+ * Changes configuration of the {@apilink Ability|ability} to {@apilink CallAnApi}
+ * that the {@apilink Actor|actor} executing this {@apilink Interaction|interaction} has been configured with.
+ *
+ * ## Changing API URL for all subsequent requests
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core';
+ * import { By Navigate, PageElement, Text } from '@serenity-js/web';
+ * import { CallAnApi, ChangeApiConfig, GetRequest, LastResponse, Send } from '@serenity-js/rest'
+ * import { Ensure, equals } from '@serenity-js/assertions';
+ *
+ * import * as axios from 'axios';
+ *
+ * // Let's imagine that the website under test displays
+ * // a dynamically generated API URL that we would like to use
+ * const ApiDetailsWidget = {
+ *   url: () => PageElement.located(By.id('api-url')).describedAs('API URL'),
+ * }
+ *
+ * await actorCalled('Apisitt')
+ *   .whoCan(
+ *     BrowseTheWeb.using(protractor.browser),
+ *
+ *     // Note: no default base URL is given when the axios instance is created
+ *     CallAnApi.using(axios.create()),
+ *   )
+ *   .attemptsTo(
+ *     Navigate.to('/profile'),
+ *
+ *     // We change the API URL based on the text displayed in the widget
+ *     // (although we could change it to some arbitrary string too).
+ *     ChangeApiConfig.setUrlTo(Text.of(ApiDetailsWidget.url())),
+ *
+ *     // Any subsequent request will be sent to the newly set URL
+ *     Send.a(GetRequest.to('/projects')),
+ *     Ensure.that(LastResponse.status(), equals(200)),
+ *   )
+ * ```
+ *
+ * ## Changing API port for all subsequent requests
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { LocalServer, ManageALocalServer, StartLocalServer } from '@serenity-js/local-server'
+ * import { CallAnApi, ChangeApiConfig, GetRequest, LastResponse, Send } from '@serenity-js/rest'
+ * import { Ensure, equals } from '@serenity-js/assertions'
+ *
+ * await actorCalled('Apisitt')
+ *   .whoCan(
+ *     ManageALocalServer.runningAHttpListener(someServer),
+ *     CallAnApi.at('http://localhost'),
+ *   )
+ *   .attemptsTo(
+ *     StartALocalServer.onRandomPort(),
+ *     ChangeApiConfig.setPortTo(LocalServer.port()),
+ *     Send.a(GetRequest.to('/api')),
+ *     Ensure.that(LastResponse.status(), equals(200)),
+ *   )
+ * ```
+ *
+ * ## Setting a header for all subsequent requests
+ *
+ * ```ts
+ * import { actorCalled, Question } from '@serenity-js/core'
+ * import { CallAnApi, ChangeApiConfig, GetRequest, LastResponse, Send } from '@serenity-js/rest'
+ * import { Ensure, equals } from '@serenity-js/assertions'
+ *
+ * // A sample Question reading a Node process environment variable
+ * const EnvVar = (var_name: string) =>
+ *     Question.about(`${ name } environment variable`, actor => process.env[var_name]);
+ *
+ * await actorCalled('Apisitt')
+ *   .whoCan(
+ *     CallAnApi.at('http://localhost'),
+ *   )
+ *   .attemptsTo(
+ *     ChangeApiConfig.setHeader('Authorization', EnvVar('TOKEN')),
+ *     Send.a(GetRequest.to('/api')),
+ *     Ensure.that(LastResponse.status(), equals(200)),
+ *   )
+ * ```
+ *
+ * @group Activities
  */
 export class ChangeApiConfig {
 
     /**
-     * @desc
-     *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor}
-     *  to change the base URL of their {@link CallAnApi} {@link @serenity-js/core/lib/screenplay~Ability}
+     * Instructs the {@apilink Actor|actor} to change the base URL
+     * of their {@apilink Ability|ability} to {@apilink CallAnApi}
      *
-     * @param {@serenity-js/core/lib/screenplay~Answerable<string>} newApiUrl
-     * @returns {@serenity-js/core/lib/screenplay~Interaction}
+     * @param newApiUrl
      */
     static setUrlTo(newApiUrl: Answerable<string>): Interaction {
         return new ChangeApiConfigSetUrl(newApiUrl);
     }
 
     /**
-     * @desc
-     *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor}
-     *  to change the port configured in the base URL of their {@link CallAnApi} {@link @serenity-js/core/lib/screenplay~Ability}
+     * Instructs the {@apilink Actor|actor} to change the port configured in the base URL
+     * of their {@apilink Ability|ability} to {@apilink CallAnApi}
      *
-     * @param {@serenity-js/core/lib/screenplay~Answerable<string>} newApiPort
-     * @returns {@serenity-js/core/lib/screenplay~Interaction}
+     * @param newApiPort
      */
     static setPortTo(newApiPort: Answerable<number>): Interaction {
         return new ChangeApiConfigSetPort(newApiPort)
     }
 
     /**
-     * @desc
-     *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor}
-     *  to modify the configuration of the {@link AxiosInstance}
-     *  used by {@link CallAnApi} {@link @serenity-js/core/lib/screenplay~Ability}
-     *  and set a HTTP request header for any subsequent {@link HTTPRequest}
-     *  issued via {@link Send}.
+     * Instructs the {@apilink Actor|actor} to change the configuration of the {@apilink AxiosInstance}
+     * used by their {@apilink Ability|ability} to {@apilink CallAnApi}
+     * and set an HTTP request header for any subsequent {@apilink HTTPRequest|HTTPRequests}
+     * issued via {@apilink Send}.
      *
-     * @param {@serenity-js/core/lib/screenplay~Answerable<string>} name
-     * @param {@serenity-js/core/lib/screenplay~Answerable<string>} value
-     *
-     * @returns {@serenity-js/core/lib/screenplay~Interaction}
+     * @param name
+     * @param value
      */
     static setHeader(name: Answerable<string>, value: Answerable<string>): Interaction {
         return new ChangeApiConfigSetHeader(name, value);
@@ -129,17 +129,13 @@ export class ChangeApiConfig {
  */
 class ChangeApiConfigSetUrl extends Interaction {
     constructor(private readonly newApiUrl: Answerable<string>) {
-        super();
+        super(d`#actor changes API url configuration to ${ newApiUrl }`);
     }
 
     performAs(actor: UsesAbilities & CollectsArtifacts & AnswersQuestions): Promise<void> {
         return actor.answer(this.newApiUrl)
             .then(newApiUrl => CallAnApi.as(actor).modifyConfig(config => config.baseURL = newApiUrl));
     }
-
-    toString(): string {
-        return `#actor changes API URL configuration to ${ this.newApiUrl }`;
-    }
 }
 
 /**
@@ -147,7 +143,7 @@ class ChangeApiConfigSetUrl extends Interaction {
  */
 class ChangeApiConfigSetPort  extends Interaction {
     constructor(private readonly newPort: Answerable<number | string>) {
-        super();
+        super(`#actor changes API port configuration to ${ newPort }`);
     }
 
     performAs(actor: UsesAbilities & CollectsArtifacts & AnswersQuestions): Promise<void> {
@@ -167,10 +163,6 @@ class ChangeApiConfigSetPort  extends Interaction {
                 }
             }));
     }
-
-    toString(): string {
-        return `#actor changes API port configuration to ${ this.newPort }`;
-    }
 }
 
 /**
@@ -184,7 +176,7 @@ class ChangeApiConfigSetHeader extends Interaction {
         private readonly name: Answerable<string>,
         private readonly value: Answerable<string>
     ) {
-        super();
+        super(`#actor changes API URL and sets header "${ name }" to "${ value }"`);
     }
 
     performAs(actor: UsesAbilities & CollectsArtifacts & AnswersQuestions): Promise<void> {
@@ -205,8 +197,4 @@ class ChangeApiConfigSetHeader extends Interaction {
             });
         });
     }
-
-    toString(): string {
-        return `#actor changes API URL and sets header "${ this.name }" to "${ this.value }"`;
-    }
 }