Sfoglia il codice sorgente

Tests: Initial tests readme.

Krzysztof Krztoń 7 anni fa
parent
commit
c4f7042b08
1 ha cambiato i file con 148 aggiunte e 0 eliminazioni
  1. 148 0
      packages/ckeditor5-paste-from-office/tests/README.md

+ 148 - 0
packages/ckeditor5-paste-from-office/tests/README.md

@@ -0,0 +1,148 @@
+# Normalization and integration testing in `Paste from Office`
+
+To test if content pasted from any external application is transformed correctly by the editor the test itself needs to
+use data which is put into the native clipboard by the application. For test purpose, such data is stored in the single file
+called `fixture` file.
+
+The `fixture` file is usually a HTML file containing HTML content which was fetched from the native browser `dataTransfer`
+object (`dataTransfer.getData( 'html/text' )`) when content have been pasted to the browser which ensures that `fixture`
+file provides exactly same data as a real use scenario.
+
+## Fixture files
+
+The `fixture` files are grouped per feature (which usually corresponds to editor plugins, for example `basic-styles`, `list`, etc).
+All fixtures are stored in `tests/_data/feature-name/` directory (for example `_data/basic-style/`). Each feature (which
+will be called **group**) has a separate folder per fixture. Each fixture is used to create one normalization and one integration test.
+
+Each fixture folder contains:
+
+- original input file - `bold-with-text.docx`
+- input fixture - `input.word2016.html`
+- normalized output fixture - `normalized.word2016.html`
+- model output fixture - `model.word2016.html`
+
+In some cases, different browsers produces different input data. For such situations, additional fixtures should be added.
+For example if input data is different for Safari, additional `input.safari.word2016.html` file should be added.
+
+## Tests group index
+
+Each group of fixtures contains index file (`index.js` in group folder e.g. `_data/basic-styles/index.js`).
+Its purpose is to simply import all fixture files from its group and expose them for further use. Index file has the following structure:
+
+
+```
+// Import default/generic fixtures.
+// Input fixtures.
+import boldWithinText from './bold-within-text/input.word2016.html';
+
+// Expected normalized fixtures.
+import boldWithinTextNormalized from './bold-within-text/normalized.word2016.html';
+
+// Expected model fixtures.
+import boldWithinTextModel from './bold-within-text/model.word2016.html';
+
+// Export imported generic fixtures for future use.
+export const fixtures = {
+    input: {
+        boldWithinText: boldWithinText
+    },
+    normalized: {
+        boldWithinText: boldWithinTextNormalized
+    },
+    model: {
+        boldWithinText: boldWithinTextModel
+    }
+}
+```
+
+Such structure exports generic fixtures (the ones which are same for more than one browser and will be used if no browser specific fixtures are present).
+
+Index files must also export browser specific fixtures. In the simplest case if there are none, it exports empty object:
+
+
+```
+export browserFixtures = {};
+```
+
+If there are any browser specific fixtures, they are export in a similar manner than generic ones (apart from being grouped by a browser):
+
+
+```
+// Export imported browser-specific fixtures for future use.
+export const browserFixtures = {
+    safari: {
+        input: {
+            boldWithinText: boldWithinTextSafari
+        },
+        normalized: {
+            boldWithinText: boldWithinTextNormalizedSafari
+        },
+        model: {
+            boldWithinText: boldWithinTextModelSafari
+        }
+    }
+}
+```
+
+### What if only input or one of the expected output fixtures are different for specific browser? Could fixtures be mixed?
+
+There are cases when only some fixtures differ for a given browser. In such cases browser fixtures export reuses generic fixtures:
+
+```
+// Export imported browser-specific fixtures for future use.
+export const browserFixtures = {
+    safari: {
+        input: {
+            boldWithinText: boldWithinText // generic
+        },
+        normalized: {
+            boldWithinText: boldWithinTextNormalizedSafari // Safari specific
+        },
+        model: {
+            boldWithinText: boldWithinTextModel // generic
+        }
+    }
+}
+```
+
+## Fixtures aggregation
+
+All group indexes files are aggregated in the `fixtures` util (`_utils/fixtures.js`) and exposed for tests in a single
+`fixtures` and `browserFixtures` objects:
+
+
+```
+// Import fixtures.
+import { fixtures as basicStyles, browserFixtures as basicStylesBrowser } from '../_data/basic-styles/index.js';
+
+// Generic fixtures.
+export const fixtures = {
+	'basic-styles': basicStyles
+};
+
+// Browser specific fixtures.
+export const browserFixtures = {
+	'basic-styles': basicStylesBrowser
+};
+```
+
+## Tests generation
+
+Tests based on fixture files are generated by the special util function `generateTests()` (see `_utils/utils.js`). This function
+is specially designed to generate `normalization` (see `data/normalization.js`) or `integration` (see `data/integration.js`)
+tests using provided fixtures group, for example:
+
+
+```
+generateTests( {
+	input: 'basic-styles', // Group name.
+	type: 'integration', // Tests type (integration or normalization).
+	browsers: [ 'chrome', 'firefox', 'safari', 'edge' ], // For which browsers generate tests.
+	editorConfig: { // Editor config which will be used during editor creation which is used in tests.
+		plugins: [ Clipboard, Paragraph, Heading, Bold, Italic, Underline, Strikethrough, PasteFromOffice ]
+	},
+	skip: { // Names of fixtures which tests should be skipped (object `key` is the name of the browser for which to skip tests).
+		safari: [ 'italicStartingText', 'multipleStylesSingleLine', 'multipleStylesMultiline' ] // Skip due to spacing issue (#13).
+	}
+} );
+```