Update readme and change names

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)

__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
 ) => (

__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", {}));
 });

__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"));
 });

__tests__/html-outlook-gmail.test.ts

 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"));
 });

__tests__/html-outlook-outlook.test.ts

 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(

__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"));
 });

__tests__/htmltext-gmail-outlook.test.ts

 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"));
 });

__tests__/htmltext-outlook-gmail.test.ts

 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
   );

__tests__/htmltext-outlook-outlook.test.ts

 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
   );

__tests__/plain-gmail-gmail.test.ts

 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"));
 });

__tests__/plain-gmail-outlook.test.ts

 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"));
 });

__tests__/plain-outlook-gmail.test.ts

 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"));
 });

__tests__/plain-outlook-outlook.test.ts

 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(