|
|
@@ -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).
|
|
|
+ }
|
|
|
+} );
|
|
|
+```
|