|
| 1 | +--- |
| 2 | +sidebar_label: Jest |
| 3 | +sidebar_position: 6 |
| 4 | +--- |
| 5 | + |
| 6 | +# Jest |
| 7 | + |
| 8 | +**Vortex** uses [Jest](https://jestjs.io/) as a framework for JavaScript unit |
| 9 | +testing. Jest tests verify that JavaScript behaviors in custom Drupal modules |
| 10 | +work correctly in isolation, without requiring a browser or Drupal bootstrap. |
| 11 | + |
| 12 | +For running tests, configuration, and CI settings, see the |
| 13 | +[Jest tool reference](/docs/tools/jest). |
| 14 | + |
| 15 | +## Test file structure |
| 16 | + |
| 17 | +Test files are co-located with source files in the `js/` directory of each |
| 18 | +custom module: |
| 19 | + |
| 20 | +```text |
| 21 | +web/modules/custom/my_module/ |
| 22 | +└── js/ |
| 23 | + ├── my_module.js # Source file (Drupal behavior) |
| 24 | + └── my_module.test.js # Jest test file |
| 25 | +``` |
| 26 | + |
| 27 | +Jest automatically discovers `*.test.js` files in `web/modules/custom/*/js/` |
| 28 | +directories. Adding a new module with tests requires no configuration changes. |
| 29 | + |
| 30 | +## Writing tests |
| 31 | + |
| 32 | +Drupal JavaScript uses the IIFE pattern `((Drupal) => { ... })(Drupal)` where |
| 33 | +`Drupal` is a global object. Tests load these source files using `eval()` after |
| 34 | +setting up the required globals. |
| 35 | + |
| 36 | +### Test template |
| 37 | + |
| 38 | +```javascript |
| 39 | +/** |
| 40 | + * @jest-environment jsdom |
| 41 | + */ |
| 42 | + |
| 43 | +const fs = require('fs'); |
| 44 | +const path = require('path'); |
| 45 | + |
| 46 | +describe('Drupal.behaviors.myModule', () => { |
| 47 | + beforeEach(() => { |
| 48 | + localStorage.clear(); |
| 49 | + global.Drupal = { behaviors: {} }; |
| 50 | + |
| 51 | + const filePath = path.resolve(__dirname, 'my_module.js'); |
| 52 | + const code = fs.readFileSync(filePath, 'utf8'); |
| 53 | + eval(code); |
| 54 | + }); |
| 55 | + |
| 56 | + afterEach(() => { |
| 57 | + delete global.Drupal; |
| 58 | + }); |
| 59 | + |
| 60 | + it('should attach behavior to the context', () => { |
| 61 | + document.body.innerHTML = '<div data-my-module></div>'; |
| 62 | + Drupal.behaviors.myModule.attach(document); |
| 63 | + |
| 64 | + const el = document.querySelector('[data-my-module]'); |
| 65 | + expect(el.classList.contains('processed')).toBe(true); |
| 66 | + }); |
| 67 | +}); |
| 68 | +``` |
| 69 | + |
| 70 | +### Loading Drupal behaviors |
| 71 | + |
| 72 | +The `eval(fs.readFileSync(...))` pattern executes the source file's IIFE, which |
| 73 | +receives `global.Drupal` as its `Drupal` parameter and registers the behavior. |
| 74 | +After `eval()`, the behavior is accessible via `Drupal.behaviors.myModule`. |
| 75 | + |
| 76 | +### Mocking globals |
| 77 | + |
| 78 | +Set globals in `beforeEach` and clean them up in `afterEach`: |
| 79 | + |
| 80 | +| Global | Setup | When needed | |
| 81 | +|--------|-------|-------------| |
| 82 | +| `Drupal` | `global.Drupal = { behaviors: {} }` | Always — required by all Drupal behaviors | |
| 83 | +| `jQuery` | `global.jQuery = require('jquery')` or a mock | When the source file uses `jQuery` or `$` | |
| 84 | +| `drupalSettings` | `global.drupalSettings = { path: { baseUrl: '/' } }` | When the source file reads `drupalSettings` | |
| 85 | +| `localStorage` | Provided by jsdom; call `localStorage.clear()` | When the source file uses `localStorage` | |
| 86 | + |
| 87 | +### Testing DOM interactions |
| 88 | + |
| 89 | +The `jsdom` environment provides `document` and `window`. Set up HTML before |
| 90 | +each test: |
| 91 | + |
| 92 | +```javascript |
| 93 | +document.body.innerHTML = ` |
| 94 | + <div data-my-widget> |
| 95 | + <button data-action="save">Save</button> |
| 96 | + <span data-status></span> |
| 97 | + </div> |
| 98 | +`; |
| 99 | + |
| 100 | +Drupal.behaviors.myModule.attach(document); |
| 101 | +document.querySelector('[data-action="save"]').click(); |
| 102 | + |
| 103 | +expect(document.querySelector('[data-status]').textContent).toBe('Saved'); |
| 104 | +``` |
| 105 | + |
| 106 | +### Testing timed behavior |
| 107 | + |
| 108 | +Use Jest fake timers for `setTimeout` and `setInterval`: |
| 109 | + |
| 110 | +```javascript |
| 111 | +jest.useFakeTimers(); |
| 112 | + |
| 113 | +Drupal.behaviors.myModule.startPolling(); |
| 114 | +jest.advanceTimersByTime(5000); |
| 115 | + |
| 116 | +expect(fetchSpy).toHaveBeenCalledTimes(5); |
| 117 | + |
| 118 | +jest.useRealTimers(); |
| 119 | +``` |
| 120 | + |
| 121 | +### ESLint compatibility |
| 122 | + |
| 123 | +The `.eslintrc.json` includes an override for `*.test.js` files that enables |
| 124 | +the `jest` environment and allows `eval()`. No additional ESLint configuration |
| 125 | +is needed for test files. |
| 126 | + |
| 127 | +## Boilerplate |
| 128 | + |
| 129 | +**Vortex** provides a Jest test boilerplate for the [demo module](https://github.com/drevops/vortex/blob/main/web/modules/custom/ys_demo/js/ys_demo.test.js) |
| 130 | +that demonstrates testing a counter block with DOM manipulation, localStorage |
| 131 | +interaction, and event handling. |
| 132 | + |
| 133 | +This boilerplate test runs in continuous integration pipeline when you install |
| 134 | +**Vortex** and can be used as a starting point for writing your own JavaScript |
| 135 | +tests. |
0 commit comments