docs: document jest troubleshooting (#382)

README.md

@@ -84,3 +84,15 @@ It will also configure the editor to be viewable in the gallery view. Adding the
 5. Activate the flag.
 6. Follow steps 4 to 6 from [above](#how-to-set-up-development-workflow-of-v2-content-editors-in-studio-and-course-authoring-mfe)
 
+# Installing into a project
+
+- `npm install @edx/frontend-lib-content-components`
+- For the Jest tests to work, a few config options are necessary. In jest.config.js, include:
+```js
+  moduleNameMapper: {
+    '^lodash-es$': 'lodash',
+  },
+```
+- Some mocks for test setup are also necessary, specifically replacing `window.matchMedia`.
+- To make this easier, we provide example files for `jest.config.js` and `setupTest.js` that are known to work.
+You can find them in the example/ folder.

example/jest.config.example.js

@@ -0,0 +1,30 @@
+const { createConfig } = require('@edx/frontend-build');
+
+module.exports = createConfig('jest', {
+  setupFiles: [
+    '<rootDir>/src/setupTest.js',
+  ],
+  setupFilesAfterEnv: [
+    '<rootDir>/src/setupTestEnv.js',
+  ],
+  collectCoverageFrom: [
+    "**/*.{js,jsx}",
+  ],
+  testMatch: [
+    '**/specs/**/*.spec.(js|jsx)|**/__tests__/*.(js|jsx)|**/specs/*.spec.(js|jsx)',
+  ],
+  roots: [
+    '<rootDir>src/',
+  ],
+  coveragePathIgnorePatterns: [
+    'src/setupTestEnv.js',
+    'src/setupTest.js',
+    'jest.config.js',
+    'src/i18n',
+    '/node_modules/',
+    '/specs/'
+  ],
+  moduleNameMapper: {
+    '^lodash-es$': 'lodash',
+  },
+});

example/setupTest.example.js

@@ -0,0 +1,55 @@
+/* eslint-disable import/no-extraneous-dependencies */
+import 'core-js/stable';
+import 'regenerator-runtime/runtime';
+import Enzyme from 'enzyme';
+import Adapter from '@wojtekmaj/enzyme-adapter-react-17';
+import MutationObserver from '@sheerun/mutationobserver-shim';
+import { mergeConfig } from '@edx/frontend-platform';
+
+Enzyme.configure({ adapter: new Adapter() });
+
+/* need to mock window for tinymce on import, as it is JSDOM incompatible */
+
+Object.defineProperty(window, 'matchMedia', {
+  writable: true,
+  value: jest.fn().mockImplementation(query => ({
+    matches: false,
+    media: query,
+    onchange: null,
+    addListener: jest.fn(), // Deprecated
+    removeListener: jest.fn(), // Deprecated
+    addEventListener: jest.fn(),
+    removeEventListener: jest.fn(),
+    dispatchEvent: jest.fn(),
+  })),
+});
+
+mergeConfig({
+  STUDIO_BASE_URL: process.env.STUDIO_BASE_URL,
+  BLOCKSTORE_COLLECTION_UUID: process.env.BLOCKSTORE_COLLECTION_UUID,
+  SECURE_ORIGIN_XBLOCK_BOOTSTRAP_HTML_URL: process.env.SECURE_ORIGIN_XBLOCK_BOOTSTRAP_HTML_URL,
+});
+
+window.MutationObserver = MutationObserver;
+
+let store = {};
+
+const mockStorage = {
+  getItem: (key) => {
+    if (key in store) {
+      return store[key];
+    }
+    return null;
+  },
+  setItem: (key, value) => {
+    store[key] = `${value}`;
+  },
+  removeItem: (key) => {
+    delete store[key];
+  },
+  reset() {
+    store = {};
+  },
+};
+
+Object.defineProperty(window, 'localStorage', { value: mockStorage });