diff --git a/README.md b/README.md index 2860ccf3dc1f9a2786eb625f50365bb3cbb1fee6..d17e8053c4c9347231bb712b194464e3f1f462c8 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 4b52c948578d04983f18fecaf4953c63378e6262..1dd32f6d14c83bfedcbb6a8b98dd97394ec2fae5 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 f12591d843558467866627d13c06068dec7ebe2f..6f2b681210cd85d30eafabdcf00880b622e7d9ca 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 884c87b53ad8b8421074eba9def4576a53b08f8b..8c03d5c54223617080c365fe5a7c89b94a7d8622 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 ebb0feba821d267b7e7edec955fb388bc7175d96..932517cc2602a73611ca6166f1c2aee96a05fdfe 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 f27a85e6d84420c60423610a170269f8752136ca..90f32830367ee1a9e05cbbb773d25b9914f5263b 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 b6d98b16baa311a39332dd9af819cb1150d9b177..e2a1fca7c35f7520802f334b5a02231e60396cb1 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 c05314d428087fa7f28402a8acc00fcf010a0f1e..bd50043f2ca34e0951df3f8edcb6ee72310ae960 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 ce451f25193b5a0fe3e8e8209ccc682a5c970af8..b32f7e3a7f3a39d386124be1f25054f7b8f03f9b 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 6d8bc5c31e70ee044882cd5d9e9c610f27b69f3e..c6e69b00fb3b19e76276febadf641c271f53cc26 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 7846313571fbb69aac70a7f9c52f89c277f1ab05..9ee86ae841e7701775b6c1df445f95a34411ecb1 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 47295e16cca772ff7a28e54b439493b4da7c289c..f1ae5d9281c7e61d926cc177fa519b5f364bd47d 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 ea3c7c98cbce9e84e6dc1d92107b5cde88c1a9c8..44cfed3499d113892d17249f9b2951043a1df4b6 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 fa6cd546461ca9a795f119cca8f1abba370423a5..f64cde40f55302d6477322c3009cc9aeb6ce456d 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(