From 6393503c02e752e5199d9ea365e06e9a3e714003 Mon Sep 17 00:00:00 2001
From: igor <igor.markin@vereign.com>
Date: Tue, 29 Dec 2020 16:10:27 +0300
Subject: [PATCH] Update readme and change names

---
 README.md                                  | 90 +++++++++++++++++-----
 __tests__/helpers/index.ts                 |  9 +--
 __tests__/html-gmail-gmail.test.ts         |  4 +-
 __tests__/html-gmail-outlook.test.ts       |  4 +-
 __tests__/html-outlook-gmail.test.ts       | 10 +--
 __tests__/html-outlook-outlook.test.ts     |  7 +-
 __tests__/htmltext-gmail-gmail.test.ts     |  7 +-
 __tests__/htmltext-gmail-outlook.test.ts   |  7 +-
 __tests__/htmltext-outlook-gmail.test.ts   |  4 +-
 __tests__/htmltext-outlook-outlook.test.ts |  4 +-
 __tests__/plain-gmail-gmail.test.ts        |  4 +-
 __tests__/plain-gmail-outlook.test.ts      |  4 +-
 __tests__/plain-outlook-gmail.test.ts      |  4 +-
 __tests__/plain-outlook-outlook.test.ts    |  4 +-
 14 files changed, 99 insertions(+), 63 deletions(-)

diff --git a/README.md b/README.md
index 2860ccf..d17e805 100644
--- a/README.md
+++ b/README.md
@@ -16,25 +16,77 @@ https://code.vereign.com/light/documentation/-/blob/master/Validation.md#normali
 
 ## Testing
 
-- `yarn test`
-- `yarn test:watch`
-
-`eml` files with test cases provided in `__tests__/files`
-
-- `sent.eml` corresponds to the MIME string extract by integrator application
-- `received.eml` - corresponds to the raw MIME message extracted manually from email client
-
-If you are going to create a new test case, please follow the structure inside this directory.
-
-_Important note: MIME normaliser does not cover all provided test cases.
-Some of them explicitly ignored to indicate which tests has to be fixed. Please refer to `failingCases` arrays inside the test files._
-
-Tests are using both JSDOM and custom Vereign [DOM parser](https://code.vereign.com/code/js-toolbox/gsdom).
-Vereign DOM parser has been developed to support MIME normalisation in Google Add-on and is a must for testing.
-
-Whenever you develop a new normalisation logic, ensure that Vereign DOM parser and Google Add-on support functions you apply.
-
-## Coverage
+### Running
+
+- `yarn test` - runs tests once
+- `yarn test:watch` - runs tests in watch mode
+  - use `p` key to run cases by regular expression, e.g.
+    `html-`
+    `.*-outlook-outlook`
+    `plain-gmail-`
+
+### Test cases generation
+
+- Create a directory for .eml files. Use the next structure as an example `__tests__/files/outlook-gmail/chrome-chrome/<test-case-dir>`.
+- Put `sent.eml` and `received.eml` files into the `<test-case-dir>`
+  - `sent.eml` contains MIME string logged by integrator application during the sending routine.
+  - `received.eml` contains MIME string extracted manually from email client or logged by the integrator application.
+    For outlook.com - extract MIME string by logging it in the application itself.
+    _Do not do export MIME via the web client using `Show message source` action.
+    It breaks spacing of the quoted-printable parts and parsing/validation of such MIME might fail._
+    For mail.google.com - use `Show original` -> `Download original` actions in web client.
+    _Don't copy contents provided by just `Show original` action because they miss base64 strings of the attachments_
+- Create three test suites to cover html, plain and htmltext (pseudoplain) normalisation. E.g:
+  - `html-outlook-gmail.test.ts`
+  - `plain-outlook-gmail.test.ts`
+  - `htmltext-outlook-gmail.test.ts`
+- For every test suite, use built in functions to automate running of test cases.
+  ```
+  const testsPath = path.resolve(__dirname, `./files/outlook-gmail`);
+
+  // in html-outlook-gmail.test.ts
+  const runTests = createHtmlTestsRunner(testsPath, EMAIL_VENDORS.OUTLOOK);
+  describe("Chrome-Chrome", runTests("chrome-chrome"));
+  ...
+  // in plain-outlook-gmail.test.ts
+  const runTests = createPlainTestsRunner(testsPath);
+  describe("Chrome-Chrome", runTests("chrome-chrome"));
+  ...
+  // in htmltext-outlook-gmail.test.ts
+  const runTests = createPseudoplainTestsRunner(testsPath, EMAIL_VENDORS.OUTLOOK);
+  describe("Chrome-Chrome", runTests("chrome-chrome"));
+  ```
+
+### Important clues
+
+- MIME normaliser does not cover all provided test cases. Some of them pending to be fixed and ignored explicitly.  
+  Example:
+
+  ```javascript
+  describe(
+    "MacOS-MacOS",
+    runTests("macos-macos", { ignore: ["03", "04", "05", "08", "09"] })
+  );
+  ```
+
+  _Details about valid/failing cases presented in [coverage](#coverage) section._
+
+- To debug specific test cases, please first isolate a desired test file using the regexp in watch mode
+  and then use `checkExclusively` filter of the describe function.
+
+  ```javascript
+  describe(
+    "MacOS-MacOS",
+    runTests("macos-macos", { checkExclusively: ["03", "08", "09"] })
+  );
+  ```
+
+- Tests are using both JSDOM and custom Vereign [DOM parser](https://code.vereign.com/code/js-toolbox/gsdom).
+  Vereign DOM parser has been developed to support MIME normalisation in Google Add-on and is a must for testing.
+
+      Whenever you develop a new normalisation logic, ensure that Vereign DOM parser support functions that you are applying.
+
+### Coverage
 
 - GMail-GMail
   - [Chrome-Chrome](__tests__/files/gmail-gmail/chrome-chrome/README.md)
diff --git a/__tests__/helpers/index.ts b/__tests__/helpers/index.ts
index 4b52c94..1dd32f6 100644
--- a/__tests__/helpers/index.ts
+++ b/__tests__/helpers/index.ts
@@ -52,10 +52,7 @@ expect.extend({
   },
 });
 
-export const createDescribeHtmlTestCases = (
-  testsPath: string,
-  vendor: string
-) => (
+export const createHtmlTestsRunner = (testsPath: string, vendor: string) => (
   casesGroupName: string,
   filteringOptions?: CasesFilteringOptions
 ) => (): void => {
@@ -89,7 +86,7 @@ export const createDescribeHtmlTestCases = (
   );
 };
 
-export const createDescribePlainTestCases = (testsPath: string) => (
+export const createPlainTestsRunner = (testsPath: string) => (
   casesGroupName: string,
   filteringOptions?: CasesFilteringOptions
 ) => (): void => {
@@ -122,7 +119,7 @@ export const createDescribePlainTestCases = (testsPath: string) => (
   );
 };
 
-export const createDescribePseudoPlainTestCases = (
+export const createPseudoplainTestsRunner = (
   testsPath: string,
   vendor: string
 ) => (
diff --git a/__tests__/html-gmail-gmail.test.ts b/__tests__/html-gmail-gmail.test.ts
index f12591d..6f2b681 100644
--- a/__tests__/html-gmail-gmail.test.ts
+++ b/__tests__/html-gmail-gmail.test.ts
@@ -2,13 +2,13 @@ import { EMAIL_VENDORS } from "../src";
 
 const path = require("path");
 import { describe } from "@jest/globals";
-import { createDescribeHtmlTestCases } from "./helpers";
+import { createHtmlTestsRunner } from "./helpers";
 
 const TESTS_GLOBAL_PATH = "/files/gmail-gmail";
 const testsPath = path.resolve(__dirname, `.${TESTS_GLOBAL_PATH}`);
 
 describe("[HTML] GMail-GMail", () => {
-  const runTests = createDescribeHtmlTestCases(testsPath, EMAIL_VENDORS.GMAIL);
+  const runTests = createHtmlTestsRunner(testsPath, EMAIL_VENDORS.GMAIL);
 
   describe("Chrome-Chrome", runTests("chrome-chrome", {}));
 });
diff --git a/__tests__/html-gmail-outlook.test.ts b/__tests__/html-gmail-outlook.test.ts
index 884c87b..8c03d5c 100644
--- a/__tests__/html-gmail-outlook.test.ts
+++ b/__tests__/html-gmail-outlook.test.ts
@@ -2,13 +2,13 @@ import { EMAIL_VENDORS } from "../src";
 
 const path = require("path");
 import { describe } from "@jest/globals";
-import { createDescribeHtmlTestCases } from "./helpers";
+import { createHtmlTestsRunner } from "./helpers";
 
 const TESTS_GLOBAL_PATH = "/files/gmail-outlook";
 const testsPath = path.resolve(__dirname, `.${TESTS_GLOBAL_PATH}`);
 
 describe("[HTML] GMail-Outlook", () => {
-  const runTests = createDescribeHtmlTestCases(testsPath, EMAIL_VENDORS.GMAIL);
+  const runTests = createHtmlTestsRunner(testsPath, EMAIL_VENDORS.GMAIL);
 
   describe("Chrome-Chrome", runTests("chrome-chrome"));
 });
diff --git a/__tests__/html-outlook-gmail.test.ts b/__tests__/html-outlook-gmail.test.ts
index ebb0feb..932517c 100644
--- a/__tests__/html-outlook-gmail.test.ts
+++ b/__tests__/html-outlook-gmail.test.ts
@@ -1,16 +1,12 @@
 import { describe } from "@jest/globals";
 import { EMAIL_VENDORS } from "../src";
-import { createDescribeHtmlTestCases } from "./helpers";
+import { createHtmlTestsRunner } from "./helpers";
 const path = require("path");
 
-const TESTS_GLOBAL_PATH = "/files/outlook-gmail";
-const testsPath = path.resolve(__dirname, `.${TESTS_GLOBAL_PATH}`);
+const testsPath = path.resolve(__dirname, `./files/outlook-gmail`);
 
 describe("[HTML] Outlook-GMail emails normalization", () => {
-  const runTests = createDescribeHtmlTestCases(
-    testsPath,
-    EMAIL_VENDORS.OUTLOOK
-  );
+  const runTests = createHtmlTestsRunner(testsPath, EMAIL_VENDORS.OUTLOOK);
 
   describe("Chrome-Chrome", runTests("chrome-chrome"));
 });
diff --git a/__tests__/html-outlook-outlook.test.ts b/__tests__/html-outlook-outlook.test.ts
index f27a85e..90f3283 100644
--- a/__tests__/html-outlook-outlook.test.ts
+++ b/__tests__/html-outlook-outlook.test.ts
@@ -1,16 +1,13 @@
 import { describe } from "@jest/globals";
 import { EMAIL_VENDORS } from "../src";
-import { createDescribeHtmlTestCases } from "./helpers";
+import { createHtmlTestsRunner } from "./helpers";
 const path = require("path");
 
 const TESTS_GLOBAL_PATH = "/files/outlook-outlook";
 const testsPath = path.resolve(__dirname, `.${TESTS_GLOBAL_PATH}`);
 
 describe("[HTML] Outlook-Outlook emails normalization", () => {
-  const runTests = createDescribeHtmlTestCases(
-    testsPath,
-    EMAIL_VENDORS.OUTLOOK
-  );
+  const runTests = createHtmlTestsRunner(testsPath, EMAIL_VENDORS.OUTLOOK);
 
   describe("Chrome-Chrome", runTests("chrome-chrome"));
   describe(
diff --git a/__tests__/htmltext-gmail-gmail.test.ts b/__tests__/htmltext-gmail-gmail.test.ts
index b6d98b1..e2a1fca 100644
--- a/__tests__/htmltext-gmail-gmail.test.ts
+++ b/__tests__/htmltext-gmail-gmail.test.ts
@@ -2,16 +2,13 @@ import { EMAIL_VENDORS } from "../src";
 
 const path = require("path");
 import { describe } from "@jest/globals";
-import { createDescribePseudoPlainTestCases } from "./helpers";
+import { createPseudoplainTestsRunner } from "./helpers";
 
 const TESTS_GLOBAL_PATH = "/files/gmail-gmail";
 const testsPath = path.resolve(__dirname, `.${TESTS_GLOBAL_PATH}`);
 
 describe("[Pseudo PLAIN] GMail-GMail", () => {
-  const runTests = createDescribePseudoPlainTestCases(
-    testsPath,
-    EMAIL_VENDORS.GMAIL
-  );
+  const runTests = createPseudoplainTestsRunner(testsPath, EMAIL_VENDORS.GMAIL);
 
   describe("Gmail-Gmail", runTests("chrome-chrome"));
 });
diff --git a/__tests__/htmltext-gmail-outlook.test.ts b/__tests__/htmltext-gmail-outlook.test.ts
index c05314d..bd50043 100644
--- a/__tests__/htmltext-gmail-outlook.test.ts
+++ b/__tests__/htmltext-gmail-outlook.test.ts
@@ -1,5 +1,5 @@
 import { describe } from "@jest/globals";
-import { createDescribePseudoPlainTestCases } from "./helpers";
+import { createPseudoplainTestsRunner } from "./helpers";
 import { EMAIL_VENDORS } from "../src";
 const path = require("path");
 
@@ -8,9 +8,6 @@ const TESTS_GLOBAL_PATH = "/files/gmail-outlook";
 const testsPath = path.resolve(__dirname, `.${TESTS_GLOBAL_PATH}`);
 
 describe("[Pseudo PLAIN] Gmail-Outlook normalization", () => {
-  const runTests = createDescribePseudoPlainTestCases(
-    testsPath,
-    EMAIL_VENDORS.GMAIL
-  );
+  const runTests = createPseudoplainTestsRunner(testsPath, EMAIL_VENDORS.GMAIL);
   describe("Chrome-Chrome", runTests("chrome-chrome"));
 });
diff --git a/__tests__/htmltext-outlook-gmail.test.ts b/__tests__/htmltext-outlook-gmail.test.ts
index ce451f2..b32f7e3 100644
--- a/__tests__/htmltext-outlook-gmail.test.ts
+++ b/__tests__/htmltext-outlook-gmail.test.ts
@@ -1,5 +1,5 @@
 import { describe } from "@jest/globals";
-import { createDescribePseudoPlainTestCases } from "./helpers";
+import { createPseudoplainTestsRunner } from "./helpers";
 import { EMAIL_VENDORS } from "../src";
 
 const path = require("path");
@@ -8,7 +8,7 @@ const TESTS_GLOBAL_PATH = "/files/outlook-gmail";
 const testsPath = path.resolve(__dirname, `.${TESTS_GLOBAL_PATH}`);
 
 describe("[Pseudo PLAIN] Outlook-Gmail normalization", () => {
-  const runTests = createDescribePseudoPlainTestCases(
+  const runTests = createPseudoplainTestsRunner(
     testsPath,
     EMAIL_VENDORS.OUTLOOK
   );
diff --git a/__tests__/htmltext-outlook-outlook.test.ts b/__tests__/htmltext-outlook-outlook.test.ts
index 6d8bc5c..c6e69b0 100644
--- a/__tests__/htmltext-outlook-outlook.test.ts
+++ b/__tests__/htmltext-outlook-outlook.test.ts
@@ -1,5 +1,5 @@
 import { describe } from "@jest/globals";
-import { createDescribePseudoPlainTestCases } from "./helpers";
+import { createPseudoplainTestsRunner } from "./helpers";
 import { EMAIL_VENDORS } from "../src";
 
 const path = require("path");
@@ -8,7 +8,7 @@ const TESTS_GLOBAL_PATH = "/files/outlook-outlook";
 const testsPath = path.resolve(__dirname, `.${TESTS_GLOBAL_PATH}`);
 
 describe("[Pseudo PLAIN] Outlook-Outlook normalization", () => {
-  const runTests = createDescribePseudoPlainTestCases(
+  const runTests = createPseudoplainTestsRunner(
     testsPath,
     EMAIL_VENDORS.OUTLOOK
   );
diff --git a/__tests__/plain-gmail-gmail.test.ts b/__tests__/plain-gmail-gmail.test.ts
index 7846313..9ee86ae 100644
--- a/__tests__/plain-gmail-gmail.test.ts
+++ b/__tests__/plain-gmail-gmail.test.ts
@@ -1,12 +1,12 @@
 const path = require("path");
 import { describe } from "@jest/globals";
-import { createDescribePlainTestCases } from "./helpers";
+import { createPlainTestsRunner } from "./helpers";
 
 const TESTS_GLOBAL_PATH = "/files/gmail-gmail";
 const testsPath = path.resolve(__dirname, `.${TESTS_GLOBAL_PATH}`);
 
 describe("[Plain] GMail-GMail", () => {
-  const runTests = createDescribePlainTestCases(testsPath);
+  const runTests = createPlainTestsRunner(testsPath);
 
   describe("Chrome-Chrome", runTests("chrome-chrome"));
 });
diff --git a/__tests__/plain-gmail-outlook.test.ts b/__tests__/plain-gmail-outlook.test.ts
index 47295e1..f1ae5d9 100644
--- a/__tests__/plain-gmail-outlook.test.ts
+++ b/__tests__/plain-gmail-outlook.test.ts
@@ -1,5 +1,5 @@
 import { describe } from "@jest/globals";
-import { createDescribePlainTestCases } from "./helpers";
+import { createPlainTestsRunner } from "./helpers";
 const path = require("path");
 
 const TESTS_GLOBAL_PATH = "/files/gmail-outlook";
@@ -7,6 +7,6 @@ const TESTS_GLOBAL_PATH = "/files/gmail-outlook";
 const testsPath = path.resolve(__dirname, `.${TESTS_GLOBAL_PATH}`);
 
 describe("[Plain] Gmail-Outlook normalization", () => {
-  const runTests = createDescribePlainTestCases(testsPath);
+  const runTests = createPlainTestsRunner(testsPath);
   describe("Chrome-Chrome", runTests("chrome-chrome"));
 });
diff --git a/__tests__/plain-outlook-gmail.test.ts b/__tests__/plain-outlook-gmail.test.ts
index ea3c7c9..44cfed3 100644
--- a/__tests__/plain-outlook-gmail.test.ts
+++ b/__tests__/plain-outlook-gmail.test.ts
@@ -1,5 +1,5 @@
 import { describe } from "@jest/globals";
-import { createDescribePlainTestCases } from "./helpers";
+import { createPlainTestsRunner } from "./helpers";
 const path = require("path");
 
 const TESTS_GLOBAL_PATH = "/files/outlook-gmail";
@@ -7,6 +7,6 @@ const TESTS_GLOBAL_PATH = "/files/outlook-gmail";
 const testsPath = path.resolve(__dirname, `.${TESTS_GLOBAL_PATH}`);
 
 describe("[Plain] Outlook-Gmail normalization", () => {
-  const runTests = createDescribePlainTestCases(testsPath);
+  const runTests = createPlainTestsRunner(testsPath);
   describe("Chrome-Chrome", runTests("chrome-chrome"));
 });
diff --git a/__tests__/plain-outlook-outlook.test.ts b/__tests__/plain-outlook-outlook.test.ts
index fa6cd54..f64cde4 100644
--- a/__tests__/plain-outlook-outlook.test.ts
+++ b/__tests__/plain-outlook-outlook.test.ts
@@ -1,5 +1,5 @@
 import { describe } from "@jest/globals";
-import { createDescribePlainTestCases } from "./helpers";
+import { createPlainTestsRunner } from "./helpers";
 const path = require("path");
 
 const TESTS_GLOBAL_PATH = "/files/outlook-outlook";
@@ -7,7 +7,7 @@ const TESTS_GLOBAL_PATH = "/files/outlook-outlook";
 const testsPath = path.resolve(__dirname, `.${TESTS_GLOBAL_PATH}`);
 
 describe("[Plain] Outlook-Outlook normalization", () => {
-  const runTests = createDescribePlainTestCases(testsPath);
+  const runTests = createPlainTestsRunner(testsPath);
   describe("Chrome-Chrome", runTests("chrome-chrome"));
   describe("MacOS-MacOS", runTests("macos-macos"));
   describe(
-- 
GitLab