@serenity-js/rest 3.0.0-rc.9 → 3.0.1

package/src/model/GetRequest.ts

@@ -1,78 +0,0 @@
-import { Answerable } from '@serenity-js/core';
-import { AxiosRequestConfig } from 'axios';
-
-import { HTTPRequest } from './HTTPRequest';
-
-/**
- * @desc
- *  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.
- *
- * @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';
- *
- *  interface Book {
- *      title: string;
- *      author: string;
- *  }
- *
- *  const actor = Actor.named('Apisit').whoCan(CallAnApi.at('https://myapp.com/api'));
- *
- *  actor.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',
- *      })),
- *  );
- *
- * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/GET
- * @see https://tools.ietf.org/html/rfc7231#section-4.3.1
- *
- * @extends {HTTPRequest}
- */
-export class GetRequest extends HTTPRequest {
-
-    /**
-     * @desc
-     *  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 {@link CallAnApi} {@link @serenity-js/core/lib/screenplay~Ability} was instantiated.
-     *
-     * @param {@serenity-js/core/lib/screenplay~Answerable<string>} resourceUri
-     *  The URI where the {@link @serenity-js/core/lib/screenplay/actor~Actor}
-     *  should send the {@link HTTPRequest}.
-     *
-     * @returns {GetRequest}
-     */
-    static to(resourceUri: Answerable<string>): GetRequest {
-        return new GetRequest(resourceUri);
-    }
-
-    /**
-     * @desc
-     *  Overrides the default Axios request configuration provided
-     *  when {@link CallAnApi} {@link @serenity-js/core/lib/screenplay~Ability} was instantiated.
-     *
-     * @param {@serenity-js/core/lib/screenplay~Answerable<AxiosRequestConfig>} config
-     *  Axios request configuration overrides
-     *
-     * @returns {GetRequest}
-     */
-    using(config: Answerable<AxiosRequestConfig>): GetRequest {
-        return new GetRequest(this.resourceUri, undefined, config);
-    }
-}

package/src/model/HeadRequest.ts

@@ -1,63 +0,0 @@
-import { Answerable } from '@serenity-js/core';
-import { AxiosRequestConfig } from 'axios';
-
-import { HTTPRequest } from './HTTPRequest';
-
-/**
- * @desc
- *  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.
- *
- * @example <caption>File download test</caption>
- *  import { Actor } from '@serenity-js/core';
- *  import { CallAnApi, HeadRequest, 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'));
- *
- *  actor.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
- *  );
- *
- * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD
- * @see https://tools.ietf.org/html/rfc7231#section-4.3.2
- *
- * @extends {HTTPRequest}
- */
-export class HeadRequest extends HTTPRequest {
-
-    /**
-     * @desc
-     *  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 {@link CallAnApi} {@link @serenity-js/core/lib/screenplay~Ability} was instantiated.
-     *
-     * @param {@serenity-js/core/lib/screenplay~Answerable<string>} resourceUri
-     *  The URI where the {@link @serenity-js/core/lib/screenplay/actor~Actor}
-     *  should send the {@link HTTPRequest}.
-     *
-     * @returns {HeadRequest}
-     */
-    static to(resourceUri: Answerable<string>): HeadRequest {
-        return new HeadRequest(resourceUri);
-    }
-
-    /**
-     * @desc
-     *  Overrides the default Axios request configuration provided
-     *  when {@link CallAnApi} {@link @serenity-js/core/lib/screenplay~Ability} was instantiated.
-     *
-     * @param {@serenity-js/core/lib/screenplay~Answerable<AxiosRequestConfig>} config
-     *  Axios request configuration overrides
-     *
-     * @returns {HeadRequest}
-     */
-    using(config: Answerable<AxiosRequestConfig>): HeadRequest {
-        return new HeadRequest(this.resourceUri, undefined, config);
-    }
-}

package/src/model/OptionsRequest.ts

@@ -1,66 +0,0 @@
-import { Answerable } from '@serenity-js/core';
-import { AxiosRequestConfig } from 'axios';
-
-import { HTTPRequest } from './HTTPRequest';
-
-/**
- * @desc
- *  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.
- *
- * @example <caption>File download test</caption>
- *  import { Actor } from '@serenity-js/core';
- *  import { CallAnApi, OptionsRequest, 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'));
- *
- *  actor.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')),
- *  );
- *
- * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/OPTIONS
- * @see https://tools.ietf.org/html/rfc7231#section-4.3.7
- *
- * @extends {HTTPRequest}
- */
-export class OptionsRequest extends HTTPRequest {
-
-    /**
-     * @desc
-     *  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 {@link CallAnApi} {@link @serenity-js/core/lib/screenplay~Ability} was instantiated.
-     *
-     * @param {@serenity-js/core/lib/screenplay~Answerable<string>} resourceUri
-     *  The URI where the {@link @serenity-js/core/lib/screenplay/actor~Actor}
-     *  should send the {@link HTTPRequest}.
-     *
-     * @returns {OptionsRequest}
-     */
-    static to(resourceUri: Answerable<string>): OptionsRequest {
-        return new OptionsRequest(resourceUri);
-    }
-
-    /**
-     * @desc
-     *  Overrides the default Axios request configuration provided
-     *  when {@link CallAnApi} {@link @serenity-js/core/lib/screenplay~Ability} was instantiated.
-     *
-     * @param {@serenity-js/core/lib/screenplay~Answerable<AxiosRequestConfig>} config
-     *  Axios request configuration overrides
-     *
-     * @returns {OptionsRequest}
-     */
-    using(config: Answerable<AxiosRequestConfig>): OptionsRequest {
-        return new OptionsRequest(this.resourceUri, undefined, config);
-    }
-}

package/src/model/PatchRequest.ts

@@ -1,76 +0,0 @@
-import { Answerable } from '@serenity-js/core';
-import { AxiosRequestConfig } from 'axios';
-
-import { HTTPRequest } from './HTTPRequest';
-
-/**
- * @desc
- *  The PATCH method requests that a set of changes described in the
- *  request entity be applied to the resource identified by the `resourceUri`.
- *
- * @example <caption>Add new resource to a collection</caption>
- *  import { Actor } from '@serenity-js/core';
- *  import { CallAnApi, LastResponse, PatchRequest, Send } from '@serenity-js/rest'
- *  import { Ensure, equals } from '@serenity-js/assertions';
- *
- *  const actor = Actor.named('Apisit').whoCan(CallAnApi.at('https://myapp.com/api'));
- *
- *  actor.attemptsTo(
- *      Send.a(PatchRequest.to('/books/0-688-00230-7').with({
- *          lastReadOn: '2016-06-16',
- *      })),
- *      Ensure.that(LastResponse.status(), equals(204)),
- *  );
- *
- * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PATCH
- * @see https://tools.ietf.org/html/rfc5789
- *
- * @extends {HTTPRequest}
- */
-export class PatchRequest extends HTTPRequest {
-
-    /**
-     * @desc
-     *  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 {@link CallAnApi} {@link @serenity-js/core/lib/screenplay~Ability} was instantiated.
-     *
-     * @param {@serenity-js/core/lib/screenplay~Answerable<string>} resourceUri
-     *  The URI where the {@link @serenity-js/core/lib/screenplay/actor~Actor}
-     *  should send the {@link HTTPRequest}.
-     *
-     * @returns {PatchRequest}
-     */
-    static to(resourceUri: Answerable<string>): PatchRequest {
-        return new PatchRequest(resourceUri);
-    }
-
-    /**
-     * @desc
-     *  Configures the object with a request body.
-     *
-     * @param {@serenity-js/core/lib/screenplay~Answerable<any>} data
-     *  Data to be sent to the `resourceUri`
-     *
-     * @returns {PatchRequest}
-     */
-    with(data: Answerable<any>): PatchRequest {
-        return new PatchRequest(this.resourceUri, data, this.config);
-    }
-
-    /**
-     * @desc
-     *  Overrides the default Axios request configuration provided
-     *  when {@link CallAnApi} {@link @serenity-js/core/lib/screenplay~Ability} was instantiated.
-     *
-     * @param {@serenity-js/core/lib/screenplay~Answerable<AxiosRequestConfig>} config
-     *  Axios request configuration overrides
-     *
-     * @returns {PatchRequest}
-     */
-    using(config: Answerable<AxiosRequestConfig>): PatchRequest {
-        return new PatchRequest(this.resourceUri, this.data, config);
-    }
-}

package/src/model/PostRequest.ts

@@ -1,113 +0,0 @@
-import { Answerable } from '@serenity-js/core';
-import { AxiosRequestConfig } from 'axios';
-
-import { HTTPRequest } from './HTTPRequest';
-
-/**
- * @desc
- *  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.
- *
- * @example <caption>Add new resource to a collection</caption>
- *  import { Actor } from '@serenity-js/core';
- *  import { CallAnApi, LastResponse, PostRequest, Send } from '@serenity-js/rest'
- *  import { Ensure, equals } from '@serenity-js/assertions';
- *
- *  const actor = Actor.named('Apisit').whoCan(CallAnApi.at('https://myapp.com/api'));
- *
- *  actor.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')),
- *  );
- *
- * @example <caption>Submit a HTML form</caption>
- *  import { Actor } 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
- *      actor = Actor.named('Apisit').whoCan(CallAnApi.at('https://myapp.com')),
- *      formData = stringify({
- *          name: actor.name,
- *          email: `${ actor.name }@example.com`,
- *          text: 'Your website is great! Learnt a lot :-)'
- *      });
- *
- *  actor.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')),
- *  );
- *
- * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST
- * @see https://tools.ietf.org/html/rfc7231#section-4.3.3
- *
- * @extends {HTTPRequest}
- */
-export class PostRequest extends HTTPRequest {
-
-    /**
-     * @desc
-     *  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 {@link CallAnApi} {@link @serenity-js/core/lib/screenplay~Ability} was instantiated.
-     *
-     * @param {@serenity-js/core/lib/screenplay~Answerable<string>} resourceUri
-     *  The URI where the {@link @serenity-js/core/lib/screenplay/actor~Actor}
-     *  should send the {@link HTTPRequest}.
-     *
-     * @returns {PostRequest}
-     */
-    static to(resourceUri: Answerable<string>): PostRequest {
-        return new PostRequest(resourceUri);
-    }
-
-    /**
-     * @desc
-     *  Configures the object with a request body.
-     *
-     * @param {@serenity-js/core/lib/screenplay~Answerable<any>} data
-     *  Data to be sent to the `resourceUri`
-     *
-     * @returns {PostRequest}
-     */
-    with(data: Answerable<any>): PostRequest {
-        return new PostRequest(this.resourceUri, data, this.config);
-    }
-
-    /**
-     * @desc
-     *  Overrides the default Axios request configuration provided
-     *  when {@link CallAnApi} {@link @serenity-js/core/lib/screenplay~Ability} was instantiated.
-     *
-     * @param {@serenity-js/core/lib/screenplay~Answerable<AxiosRequestConfig>} config
-     *  Axios request configuration overrides
-     *
-     * @returns {PostRequest}
-     */
-    using(config: Answerable<AxiosRequestConfig>): PostRequest {
-        return new PostRequest(this.resourceUri, this.data, config);
-    }
-}

package/src/model/PutRequest.ts

@@ -1,86 +0,0 @@
-import { Answerable } from '@serenity-js/core';
-import { AxiosRequestConfig } from 'axios';
-
-import { HTTPRequest } from './HTTPRequest';
-
-/**
- * @desc
- *  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_).
- *
- * @example <caption>Create a new resource at a known location</caption>
- *  import { Actor } from '@serenity-js/core';
- *  import { CallAnApi, LastResponse, PutRequest, Send } from '@serenity-js/rest'
- *  import { Ensure, equals } from '@serenity-js/assertions';
- *
- *  const actor = Actor.named('Apisit').whoCan(CallAnApi.at('https://myapp.com/api'));
- *
- *  actor.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)),
- *  );
- *
- * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PUT
- * @see https://tools.ietf.org/html/rfc7231#section-4.3.4
- *
- * @extends {HTTPRequest}
- */
-export class PutRequest extends HTTPRequest {
-
-    /**
-     * @desc
-     *  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 {@link CallAnApi} {@link @serenity-js/core/lib/screenplay~Ability} was instantiated.
-     *
-     * @param {@serenity-js/core/lib/screenplay~Answerable<string>} resourceUri
-     *  The URI where the {@link @serenity-js/core/lib/screenplay/actor~Actor}
-     *  should send the {@link HTTPRequest}.
-     *
-     * @returns {PutRequest}
-     */
-    static to(resourceUri: Answerable<string>): PutRequest {
-        return new PutRequest(resourceUri);
-    }
-
-    /**
-     * @desc
-     *  Configures the object with a request body.
-     *
-     * @param {@serenity-js/core/lib/screenplay~Answerable<any>} data
-     *  Data to be sent to the `resourceUri`
-     *
-     * @returns {PutRequest}
-     */
-    with(data: Answerable<any>): PutRequest {
-        return new PutRequest(this.resourceUri, data, this.config);
-    }
-
-    /**
-     * @desc
-     *  Overrides the default Axios request configuration provided
-     *  when {@link CallAnApi} {@link @serenity-js/core/lib/screenplay~Ability} was instantiated.
-     *
-     * @param {@serenity-js/core/lib/screenplay~Answerable<AxiosRequestConfig>} config
-     *  Axios request configuration overrides
-     *
-     * @returns {PutRequest}
-     */
-    using(config: Answerable<AxiosRequestConfig>): PutRequest {
-        return new PutRequest(this.resourceUri, this.data, config);
-    }
-}

package/src/screenplay/interactions/ChangeApiUrl.ts

@@ -1,97 +0,0 @@
-import { Answerable, AnswersQuestions, CollectsArtifacts, Interaction, UsesAbilities } from '@serenity-js/core';
-
-import { CallAnApi } from '../abilities';
-
-/**
- * @desc
- *  Changes the base URL the {@link CallAnApi} {@link @serenity-js/core/lib/screenplay~Ability}
- *  has been configured with. Useful when we don't know the URL before the test is started,
- *  for example when the URL is dynamically generated and needs to be read from the website under test.
- *
- * @example <caption>Changing the API URL</caption>
- * import { Actor } from '@serenity-js/core';
- * import { Navigate, Target, Text } from '@serenity-js/protractor';
- * import { CallAnApi, GetRequest, LastResponse, Send } from '@serenity-js/rest'
- * import { protractor, by } from 'protractor';
- *
- * import axios  from 'axios';
- *
- * const actor = Actor.named('Apisit').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).
- *     ChangeApiUrl.to(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)),
- * );
- *
- * @deprecated Use ChangeApiConfig.setUrlTo(newUrl) instead
- *
- * @see {@link ChangeApiConfig}
- *
- * @extends {@serenity-js/core/lib/screenplay~Interaction}
- */
-export class ChangeApiUrl extends Interaction {
-
-    /**
-     * @desc
-     *  Instantiates a new {@link ChangeApiUrl} {@link @serenity-js/core/lib/screenplay~Interaction}.
-     *
-     * @param {@serenity-js/core/lib/screenplay~Answerable<string>} newApiUrl
-     * @returns {@serenity-js/core/lib/screenplay~Interaction}
-     */
-    static to(newApiUrl: Answerable<string>): Interaction {
-        return new ChangeApiUrl(newApiUrl);
-    }
-
-    /**
-     * @param {@serenity-js/core/lib/screenplay~Answerable<string>} newApiUrl
-     */
-    constructor(private readonly newApiUrl: Answerable<string>) {
-        super();
-    }
-
-    /**
-     * @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}
-     */
-    performAs(actor: UsesAbilities & CollectsArtifacts & AnswersQuestions): Promise<void> {
-        return actor.answer(this.newApiUrl)
-            .then(newApiUrl => CallAnApi.as(actor).modifyConfig(config => config.baseURL = newApiUrl));
-    }
-
-    /**
-     * @desc
-     *  Generates a description to be used when reporting this {@link @serenity-js/core/lib/screenplay~Activity}.
-     *
-     * @returns {string}
-     */
-    toString(): string {
-        return `#actor changes the API URL to ${ this.newApiUrl.toString() }`;
-    }
-}

package/tsconfig.eslint.json

@@ -1,10 +0,0 @@
-{
-  "extends": "./tsconfig",
-  "include": [
-    "src/**/*.ts",
-    "spec/**/*.ts"
-  ],
-  "exclude": [
-    "node_modules"
-  ]
-}