cypress-mailisk 1.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+## MIT License
+
+Copyright (c) 2022 Mailisk https://mailisk.com
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,98 @@
+# cypress-mailisk
+
+## Install with npm
+
+```shell
+npm install -save-dev cypress-mailisk
+```
+
+## Install with Yarn
+
+```shell
+yarn add cypress-mailisk --dev
+```
+
+After installing the package add the following in your project's `cypress/support/e2e.js`:
+
+```js
+import 'cypress-mailisk';
+```
+
+## Setup API Key
+
+To be able to use the API you will need to add your [API key](http://docs.mailisk.com/#getting-your-api-key) to `cypress.config.js`:
+
+```js
+module.exports = defineConfig({
+  env: {
+    MAILISK_API_KEY: 'YOUR_API_KEY',
+  },
+});
+```
+
+## Usage
+
+The cypress-mailisk plugin provides additional commands which can be accessed on the cypress object, for example `cy.mailiskSearchInbox()`. These commands extend the Chainable object which allows you to use the [`then()`](https://docs.cypress.io/api/commands/then#Usage) method to chain commands.
+
+### cy.mailiskSearchInbox
+
+This is the main command to interact with Mailisk, it wraps the [Search Inbox](/api-reference/search-inbox) endpoint.
+
+```js
+cy.mailiskSearchInbox('yournamespace', { to_addr_prefix: 'test.user@' }).then((response) => {
+  const emails = response.data;
+  // ...
+});
+```
+
+This Cypress command does a few extra things out of the box compared to calling the raw API directly:
+
+- By default it uses the `wait` flag, this means the call won't timeout until at least one email is received or 5 minutes pass. This timeout is adjustable by passing `timeout` in the options array.
+  ```js
+  // timeout of 1 minute
+  cy.mailiskSearchInbox(namespace, { timeout: 1000 * 60 });
+  // disable wait entirely, may return empty emails objects immediately
+  cy.mailiskSearchInbox(namespace, { wait: false });
+  ```
+- It has a default `from_timestamp` of **current timestmap - 5 seconds**. This means that only new emails will be returned. Without this older emails would be returned, permaturely returning the results if you were waiting for a specific email to arrive.
+
+The implementation of these features is explained in the [NodeJS Guide](/guides/nodejs).
+
+## Example
+
+This example demonstrates going to a password reset page, requesting a new password, receiving reset code link via email and finally setting the new password.
+
+```js
+describe('Test password reset', () => {
+  let resetLink;
+  const namespace = 'yournamespace';
+  const testEmailAddr = `test.test@${namespace}.mailisk.net`;
+
+  it('Starts a password reset', () => {
+    cy.visit('https://example.com/password_reset');
+    cy.get('#email_field').type(testEmailAddr);
+  });
+
+  it('Gets a password reset email', () => {
+    cy.mailiskSearchInbox(namespace, {
+      to_addr_prefix: testEmailAddr,
+    }).then((response) => {
+      expect(response.data).to.not.be.empty;
+      const email = response.data[0];
+      expect(email.subject).to.equal('Please reset your password');
+      resetLink = email.text.match(/.(https:\/\/example.com\/password_reset\/.*)>\n*/)[1];
+      expect(resetLink).to.not.be.undefined;
+    });
+  });
+
+  it('Goes to password reset link', () => {
+    cy.visit(resetLink);
+    cy.title().should('contain', 'Change your password');
+    cy.get('#password').type('MyNewPassword');
+    cy.get('#password_confirmation').type('MyNewPassword');
+    cy.get('form').submit();
+  });
+});
+```
+
+See the full [Mailisk Documentation](https://docs.mailisk.com) for more examples and information.

package/index.js

@@ -0,0 +1,3 @@
+const { register } = require('./src/register');
+
+register(Cypress);

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "cypress-mailisk",
+  "version": "1.0.0",
+  "description": "Mailisk library for Cypress",
+  "keywords": [
+    "mailisk",
+    "cypress",
+    "cypress-library",
+    "email-automation",
+    "email-testing",
+    "email"
+  ],
+  "main": "index.js",
+  "types": "src/mailiskCommands.d.ts",
+  "scripts": {
+    "tsc": "node_modules/.bin/tsc src/mailiskCommands.d.ts --types node"
+  },
+  "peerDependencies": {
+    "cypress": ">= 2.1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mailisk-app/cypress-mailisk.git"
+  },
+  "files": [
+    "src"
+  ],
+  "author": "Mailisk",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/mailisk-app/cypress-mailisk/issues"
+  },
+  "homepage": "https://github.com/mailisk-app/cypress-mailisk#readme",
+  "devDependencies": {
+    "typescript": "^4.7.4"
+  }
+}

package/src/mailiskCommands.d.ts

@@ -0,0 +1,104 @@
+/// <reference types="cypress" />
+
+export interface EmailAddress {
+  /** Email address */
+  address: string;
+  /** Display name, if one is specified */
+  name?: string;
+}
+
+export interface Email {
+  /** Namespace scoped ID */
+  id: string;
+  /** Sender of email */
+  from: EmailAddress;
+  /** Recepients of email */
+  to: EmailAddress[];
+  /** Carbon-copied recipients for email message */
+  cc?: EmailAddress[];
+  /** Blind carbon-copied recipients for email message */
+  bcc?: EmailAddress[];
+  /** Subject of email */
+  subject?: string;
+  /** Email content that was sent in HTML format */
+  html?: string;
+  /** Email content that was sent in plain text format */
+  text?: string;
+  /** The datetime that this email was received */
+  received_date: Date;
+  /** The unix timestamp (s) that this email was received */
+  received_timestamp: number;
+  /** The unix timestamp (s) when this email will be deleted */
+  expires_timestamp: number;
+  /** The spam score as reported by SpamAssassin */
+  spam_score?: number;
+}
+
+export interface SearchInboxParams {
+  /**
+   * The maximum number of emails that can be returned in this request, used alongside `offset` for pagination.
+   */
+  limit?: number;
+  /**
+   * The number of emails to skip/ignore, used alongside `limit` for pagination.
+   */
+  offset?: number;
+  /**
+   * Filter emails by starting unix timestamp in seconds.
+   */
+  from_timestamp?: number;
+  /**
+   * Filter emails by ending unix timestamp in seconds.
+   */
+  to_timestamp?: number;
+  /**
+   * Filter emails by 'to' address. Address must start with this.
+   *
+   * 'foo' would return 'foobar@namespace.mailisk.net' but not 'barfoo@namespace.mailisk.net'
+   */
+  to_addr_prefix?: string;
+  /**
+   * Will keep the request going till at least one email would be returned.
+   *
+   * Default is `true`
+   */
+  wait?: boolean;
+}
+
+export interface SearchInboxResponse {
+  /**
+   * Total number of emails matching query.
+   */
+  total_count: number;
+  /**
+   * Parameters that were used for the query
+   */
+  params: SearchInboxParams;
+  /**
+   * Emails
+   */
+  data: Email[];
+}
+
+declare global {
+  namespace Cypress {
+    interface Chainable {
+      mailiskSearchInbox(
+        /**
+         * The unique namespace to search.
+         */
+        namespace: string,
+        /**
+         * Search parameters.
+         */
+        params?: SearchInboxParams,
+        /**
+         * Request options.
+         *
+         * See https://docs.cypress.io/api/commands/request#Arguments
+         */
+        options?: Cypress.RequestOptions,
+      ): Cypress.Chainable<SearchInboxResponse>;
+    }
+  }
+}

package/src/mailiskCommands.js

@@ -0,0 +1,51 @@
+const Request = require('./request');
+
+class MailiskCommands {
+  static get cypressCommands() {
+    return ['mailiskSetApiKey', 'mailiskListNamespaces', 'mailiskSearchInbox'];
+  }
+
+  constructor() {
+    const defaultApiKey = Cypress.env('MAILISK_API_KEY');
+    this.mailiskSetApiKey(defaultApiKey);
+  }
+
+  mailiskSetApiKey(apiKey) {
+    this.request = new Request({ apiKey, baseUrl: Cypress.env('MAILISK_API_URL') });
+  }
+
+  mailiskListNamespaces() {
+    return this.request.get('/api/namespaces');
+  }
+
+  mailiskSearchInbox(namespace, params, options = {}) {
+    let _params = { ...params };
+
+    // default timestamp, 5 seconds before starting this request
+    if (!params.from_timestamp) {
+      _params.from_timestamp = Math.floor(new Date().getTime() / 1000) - 5;
+    }
+
+    // by default wait for email
+    if (params.wait !== false) {
+      _params.wait = true;
+    }
+
+    const urlParams = new URLSearchParams();
+    for (const key in _params) {
+      const value = _params[key];
+      if (value) urlParams.set(key, value.toString());
+    }
+
+    let _options = { ...options };
+
+    // by default wait 5 minutes for emails
+    if (_params.wait && !options.timeout) {
+      _options.timeout = 1000 * 60 * 5;
+    }
+
+    return this.request.get(`api/emails/${namespace}/inbox?${urlParams.toString()}`, _options);
+  }
+}
+
+module.exports = MailiskCommands;

package/src/register.js

@@ -0,0 +1,12 @@
+const MailiskCommands = require('./mailiskCommands');
+
+const register = (Cypress) => {
+  const mailiskCommands = new MailiskCommands();
+  MailiskCommands.cypressCommands.forEach((commandName) => {
+    Cypress.Commands.add(commandName, mailiskCommands[commandName].bind(mailiskCommands));
+  });
+};
+
+module.exports = {
+  register,
+};

package/src/request.js

@@ -0,0 +1,86 @@
+const pkg = require('../package.json');
+
+class Request {
+  constructor(options) {
+    this.apiUrl = options.apiUrl || 'https://api.mailisk.com/';
+    this.apiKey = options.apiKey;
+    this.headers = {
+      Accept: 'application/json',
+      'X-Api-Key': `${this.apiKey}`,
+      'User-Agent': `cypress-mailisk/${pkg.version}`,
+    };
+  }
+
+  buildOptions(method, path, opts = {}) {
+    if (!this.apiKey) {
+      // CYPRESS_ prefix necessary per https://docs.cypress.io/guides/guides/environment-variables.html#Option-3-CYPRESS
+      throw new Error('You must set the CYPRESS_MAILISK_API_KEY environment variable to use the Mailisk plugin.');
+    }
+
+    return {
+      method,
+      url: `${this.apiUrl}${path}`,
+      headers: {
+        Accept: this.headers.Accept,
+        'X-Api-Key': this.headers['X-Api-Key'],
+        'User-Agent': this.headers['User-Agent'],
+      },
+      ...opts,
+    };
+  }
+
+  getResponseHandler(includeResponseMetadata = false) {
+    return (response) => {
+      if (response.isOkStatusCode) {
+        return includeResponseMetadata ? response : response.body;
+      }
+
+      let message = '';
+      switch (response.status) {
+        case 400:
+          try {
+            const json = response.body;
+            json.errors.forEach((err) => {
+              message += `(${err.field}) ${err.detail[0].description}\r\n`;
+            });
+          } catch (e) {
+            message = 'Request had one or more invalid parameters.';
+          }
+          throw new Error(message);
+        case 401:
+          throw new Error('Authentication failed, check your API key.');
+        case 403:
+          throw new Error('Insufficient permission to perform that task.');
+        case 404:
+          throw new Error('Not found, check input parameters.');
+        default:
+          throw new Error('API error occured.');
+      }
+    };
+  }
+
+  request(method, path, body, opts = {}) {
+    const options = this.buildOptions(method, path, opts);
+    options.body = body || undefined;
+    options.failOnStatusCode = false;
+    return cy.request(options).then(this.getResponseHandler());
+  }
+
+  get(path, opts) {
+    return this.request('GET', path, undefined, opts);
+  }
+
+  post(path, body, opts) {
+    return this.request('POST', path, body, opts);
+  }
+
+  put(path, body, opts) {
+    return this.request('PUT', path, body, opts);
+  }
+
+  del(path, opts) {
+    return this.request('DELETE', path, undefined, opts);
+  }
+}
+
+module.exports = Request;