netresearch/typo3-testing-skill / skills/typo3-testing
typo3-testing
FlaggedUse when reproducing defects as failing tests, testing template or rendered output changes, confirming changes on a running TYPO3 instance, or setting up TYPO3 extension tests: unit/functional/E2E, PHPUnit 11-13, mutation testing, final-class mocks (v14), CI matrix across TYPO3 12/13/14.3 LTS, typo3-ci-workflows meta-package, CI failures. Also: transaction rollback, worker crashes, competing requests, testing-framework setup, test matrix, integration/e2e testing, coverage, test generation.
references/javascript-testing.md
View on GitHub<!-- SPDX-License-Identifier: CC-BY-SA-4.0 -->
<!-- SPDX-FileCopyrightText: Netresearch DTT GmbH -->
# JavaScript and CKEditor Testing
**Purpose:** Testing patterns for TYPO3 CKEditor plugins, JavaScript functionality, and frontend code
## Overview
While TYPO3 extensions are primarily PHP, many include JavaScript for:
- CKEditor custom plugins and features
- Backend module interactions
- Frontend enhancements
- RTE (Rich Text Editor) extensions
This guide covers testing patterns for JavaScript code in TYPO3 extensions.
## CKEditor Plugin Testing
### Testing Model Attributes
CKEditor plugins define model attributes that must be properly handled through upcast (view→model) and downcast (model→view) conversions.
**Example — an RTE image plugin:**
The plugin added a `noScale` attribute to prevent image processing. This requires testing:
1. **Attribute schema registration**
2. **Upcast conversion** (HTML → CKEditor model)
3. **Downcast conversion** (CKEditor model → HTML)
4. **UI interaction** (dialog checkbox)
### Test Structure Pattern
```javascript
// Resources/Public/JavaScript/Plugins/__tests__/typo3image.test.js
import { typo3image } from '../typo3image';
describe('TYPO3 Image Plugin', () => {
let editor;
beforeEach(async () => {
editor = await createTestEditor();
});
afterEach(() => {
return editor.destroy();
});
describe('Model Schema', () => {
it('should allow noScale attribute', () => {
const schema = editor.model.schema;
expect(schema.checkAttribute('typo3image', 'noScale')).toBe(true);
});
});
describe('Upcast Conversion', () => {
it('should read data-noscale from HTML', () => {
const html = '<img src="test.jpg" data-noscale="true" />';
editor.setData(html);
const imageElement = editor.model.document.getRoot()
.getChild(0);
expect(imageElement.getAttribute('noScale')).toBe(true);
});
it('should handle missing data-noscale attribute', () => {
const html = '<img src="test.jpg" />';
editor.setData(html);
const imageElement = editor.model.document.getRoot()
.getChild(0);
expect(imageElement.getAttribute('noScale')).toBe(false);
});
});
describe('Downcast Conversion', () => {
it('should write data-noscale to HTML when enabled', () => {
editor.model.change(writer => {
const imageElement = writer.createElement('typo3image', {
src: 'test.jpg',
noScale: true
});
writer.insert(imageElement, editor.model.document.getRoot(), 0);
});
const html = editor.getData();
expect(html).toContain('data-noscale="true"');
});
it('should omit data-noscale when disabled', () => {
editor.model.change(writer => {
const imageElement = writer.createElement('typo3image', {
src: 'test.jpg',
noScale: false
});
writer.insert(imageElement, editor.model.document.getRoot(), 0);
});
const html = editor.getData();
expect(html).not.toContain('data-noscale');
});
});
});
```
### Testing data-* Attributes
Many TYPO3 CKEditor plugins use `data-*` attributes to pass information from editor to server-side rendering.
**Common Patterns:**
```javascript
describe('data-* Attribute Handling', () => {
it('should preserve TYPO3-specific attributes', () => {
const testCases = [
{ attr: 'data-htmlarea-file-uid', value: '123' },
{ attr: 'data-htmlarea-file-table', value: 'sys_file' },
{ attr: 'data-htmlarea-zoom', value: 'true' },
{ attr: 'data-noscale', value: 'true' },
{ attr: 'data-alt-override', value: 'false' },
{ attr: 'data-title-override', value: 'true' }
];
testCases.forEach(({ attr, value }) => {
const html = `<img src="test.jpg" ${attr}="${value}" />`;
editor.setData(html);
// Verify upcast preserves attribute
const output = editor.getData();
expect(output).toContain(`${attr}="${value}"`);
});
});
it('should handle boolean data attributes', () => {
// Test true value
editor.setData('<img src="test.jpg" data-noscale="true" />');
let imageElement = editor.model.document.getRoot().getChild(0);
expect(imageElement.getAttribute('noScale')).toBe(true);
// Test false value
editor.setData('<img src="test.jpg" data-noscale="false" />');
imageElement = editor.model.document.getRoot().getChild(0);
expect(imageElement.getAttribute('noScale')).toBe(false);
// Test missing attribute
editor.setData('<img src="test.jpg" />');
imageElement = editor.model.document.getRoot().getChild(0);
expect(imageElement.getAttribute('noScale')).toBe(false);
});
});
```
### Testing Dialog UI
CKEditor dialogs require testing user interactions:
```javascript
describe('Image Dialog', () => {
let dialog, $checkbox;
beforeEach(() => {
dialog = createImageDialog(editor);
$checkbox = dialog.$el.find('#checkbox-noscale');
});
it('should display noScale checkbox', () => {
expect($checkbox.length).toBe(1);
expect($checkbox.parent('label').text())
.toContain('Use original file (noScale)');
});
it('should set noScale attribute when checkbox checked', () => {
$checkbox.prop('checked', true);
dialog.save();
const imageElement = getSelectedImage(editor);
expect(imageElement.getAttribute('noScale')).toBe(true);
});
it('should remove noScale attribute when checkbox unchecked', () => {
// Start with noScale enabled
const imageElement = getSelectedImage(editor);
editor.model.change(writer => {
writer.setAttribute('noScale', true, imageElement);
});
// Uncheck and save
$checkbox.prop('checked', false);
dialog.save();
expect(imageElement.getAttribute('noScale')).toBe(false);
});
it('should load checkbox state from existing attribute', () => {
const imageElement = getSelectedImage(editor);
editor.model.change(writer => {
writer.setAttribute('noScale', true, imageElement);
});
dialog = createImageDialog(editor);
$checkbox = dialog.$el.find('#checkbox-noscale');
expect($checkbox.prop('checked')).toBe(true);
});
});
```
## JavaScript Test Frameworks
### Jest
For new TypeScript plugin tests use Vitest (below); Jest remains documented for existing suites such as the CKEditor plugin tests above.
**Installation:**
```bash
npm install --save-dev jest @babel/preset-env
```
**Configuration (jest.config.js):**
```javascript
module.exports = {
testEnvironment: 'jsdom',
transform: {
'^.+\\.js$': 'babel-jest'
},
moduleNameMapper: {
'\\.(css|less|scss)$': 'identity-obj-proxy'
},
collectCoverageFrom: [
'Resources/Public/JavaScript/**/*.js',
'!Resources/Public/JavaScript/**/*.test.js',
'!Resources/Public/JavaScript/**/__tests__/**'
],
coverageThreshold: {
global: {
branches: 70,
functions: 70,
lines: 70,
statements: 70
}
}
};
```
### Mocha + Chai
Alternative for projects already using Mocha:
```javascript
// test/javascript/typo3image.test.js
const { expect } = require('chai');
const { JSDOM } = require('jsdom');
describe('TYPO3 Image Plugin', function() {
let editor;
beforeEach(async function() {
const dom = new JSDOM('<!DOCTYPE html><html><body></body></html>');
global.window = dom.window;
global.document = window.document;
editor = await createTestEditor();
});
it('should handle noScale attribute', function() {
// Test implementation
});
});
```
### Vitest: Cross-directory Coverage (production at `../../../Resources/...`)
TYPO3 extensions place JS tests under `Tests/JavaScript/` while
production code lives in `Resources/Public/JavaScript/`. Tests grouped
into subdirectories (e.g. `Tests/JavaScript/Plugins/foo.test.ts`)
import production via relative paths such as
`../../../Resources/Public/JavaScript/Plugins/foo.js`.
By default, **Vitest's v8 coverage provider silently drops files
outside the test workspace** — `lcov.info` ends up empty even though
all tests pass. Symptom: SonarCloud (or any lcov consumer) reports 0%
JS coverage despite imports working and tests asserting against the
production code.
This recipe assumes `vitest.config.ts` lives in `Tests/JavaScript/`
and Vitest runs from that directory (so `reportsDirectory: './coverage'`
resolves to `Tests/JavaScript/coverage/`, matching the Sonar path
below). The fix is `coverage.allowExternal: true`:
```ts
import { defineConfig } from 'vitest/config';
export default defineConfig({
test: {
globals: true,
environment: 'jsdom',
include: ['**/*.test.ts', '**/*.test.js'],
coverage: {
provider: 'v8',
reporter: ['text', 'json', 'html', 'lcov'],
reportsDirectory: './coverage',
// Production code lives outside this workspace
// (../../../Resources/Public/JavaScript/), so v8 needs
// allowExternal to instrument it — without this,
// lcov.info is empty.
allowExternal: true,
include: ['**/Resources/Public/JavaScript/**/*.js'],
exclude: ['**/node_modules/**', '**/Tests/**', '**/mocks/**'],
},
},
});
```
Note that the `coverage.include` glob uses a suffix pattern
(`**/Resources/...`) rather than the relative-path form
(`../../../Resources/...`). v8 matches file paths anywhere in the
project tree, not relative to Vitest's working directory; the relative
form silently produces 0/0 even with `allowExternal` enabled.
Coverage is opt-in: Vitest only writes `lcov.info` when invoked with
`--coverage` (or with `coverage.enabled: true` in the config). Wire it
into a script so CI and local runs match:
```json
{
"scripts": {
"test": "vitest run",
"test:coverage": "vitest run --coverage"
}
}
```
For SonarCloud upload (paths are repository-root-relative), point at
the resulting lcov:
```properties
sonar.javascript.lcov.reportPaths=Tests/JavaScript/coverage/lcov.info
```
### Vitest for Frontend Plugins: happy-dom, a Shared Setup, fast-check
Sitepackages and frontend-heavy extensions ship small TypeScript or jQuery
plugins (accordion, sticky header, search field). Test one plugin per test
file, mirroring the source path, in a DOM environment. This layout keeps the
config in `Build/` and the tests in `Tests/Unit/TypeScript/`; the
cross-directory recipe above keeps both in `Tests/JavaScript/`. Pick the one the
extension already uses, and for a new one the layout of its PHP tests
(`Tests/Unit/...`).
```ts
// Build/vitest.config.ts
import { fileURLToPath } from 'node:url';
import { defineConfig } from 'vitest/config';
export default defineConfig({
// Resolve paths against the extension root, not against the directory
// vitest was started from: `root: '..'` is resolved against the working
// directory and finds no tests when run from the extension root.
root: fileURLToPath(new URL('..', import.meta.url)),
resolve: {
alias: {
// TYPO3 backend modules are not installed in node_modules; point
// each one a plugin imports at a stub so vi.mock can replace it.
'@typo3/core/ajax/ajax-request.js':
fileURLToPath(new URL('../Tests/Unit/TypeScript/Support/stubs/ajax-request.ts', import.meta.url)),
},
},
test: {
globals: true,
include: ['Tests/Unit/TypeScript/**/*.test.ts'],
environment: 'happy-dom',
setupFiles: ['Tests/Unit/TypeScript/Support/setup.ts'],
coverage: {
provider: 'v8',
include: ['Resources/Private/TypeScript/**/*.ts'],
exclude: ['**/*.entry.ts', '**/*.d.ts'],
reporter: ['text', 'cobertura'],
},
},
});
```
Create the stub the alias points to; an empty file is enough, because the setup
file below replaces it with `vi.mock`. Then run Vitest from the extension root:
`npx vitest run --config Build/vitest.config.ts`.
- `globals: true` makes `describe`, `it`, `expect`, `vi` and `afterEach`
available without imports, as in the snippets below. Without it, import them
from `vitest`.
- `happy-dom` is faster than `jsdom`; switch to `jsdom` only for an API
happy-dom lacks.
- Keep DOM builders and the cleanup in the setup file, so every test starts
with an empty `document.body`:
```ts
// Tests/Unit/TypeScript/Support/setup.ts
vi.mock('@typo3/core/ajax/ajax-request.js', () => ({ default: vi.fn() }));
// Fixture markup is a constant in the test, never user input.
export function createElementFromTemplate(className: string, markup: string): HTMLElement {
const el = document.createElement('div');
el.className = className;
el.append(document.createRange().createContextualFragment(markup));
document.body.append(el);
return el;
}
afterEach(() => {
document.body.replaceChildren();
});
```
**Property-based tests with fast-check** belong where a plugin transforms
input (sanitising, formatting, parsing). They run inside the normal Vitest
suite. A plain `fc.string()` almost never produces the dangerous input, so a
property built on it passes even for a function that does nothing; mix the
tokens the property is about into the generated strings:
```ts
import * as fc from 'fast-check';
import { sanitizeInput } from '../../../../Resources/Private/TypeScript/Plugins/search';
const dangerous = fc.constantFrom('<script>', '<SCRIPT src=x>', 'javascript:', 'JaVaScRiPt:');
const input = fc.tuple(fc.string(), dangerous, fc.string()).map(([a, d, b]) => a + d + b);
it('never produces script-capable output', () => {
fc.assert(fc.property(input, (value) => {
const result = sanitizeInput(value).toLowerCase();
expect(result).not.toContain('<script');
expect(result).not.toContain('javascript:');
}));
});
```
Before trusting such a property, run it once against an identity function
(`(s) => s`): it must fail.
### Legacy jQuery Plugins (IIFE)
An IIFE plugin captures `jQuery` when the file is evaluated. Build a fake `$`
per test, set it on `globalThis`, then import the plugin fresh:
```js
async function importPluginWith($) {
globalThis.jQuery = $;
globalThis.$ = $;
vi.resetModules();
await import('../../../../Resources/Private/JavaScript/Plugins/my-plugin.js');
}
```
The fake answers the calls the plugin makes (`$.fn`, `$.extend`, a
`$(fn)` ready callback, chained `attr`/`find`/`on` returning mocks). Test the
lifecycle (init, destroy), configuration handling and `dataLayer` pushes this
way.
### Unit Test or E2E Spec
| What the code does | Unit test | E2E spec |
|---|:---:|:---:|
| Pure logic: validation, formatting, arithmetic | yes | |
| Plugin lifecycle (init/destroy), configuration, `dataLayer` pushes | yes | |
| DOM manipulation through jQuery chains | | yes |
| Browser APIs: cookies, `scrollTo`, `IntersectionObserver` | | yes |
| Third-party widgets: maps, date pickers, AJAX reloads | | yes |
| CSS transitions and animations | | yes |
Rule of thumb: when one DOM interaction needs more than about 20 lines of mock
setup, write the E2E spec instead.
## Unit Tests Do Not Prove UI Works
Vitest/Jest unit tests around DOM helpers, event handlers, or "controller" JS classes verify **logic in isolation**. They do **not** exercise:
- TYPO3's real `Modal` component (lives in `@typo3/backend/modal.js`)
- Real browser event dispatch / bubbling
- Backend page chrome (iframes, top frame, module router in v14)
- Network round-trips against actual TYPO3 endpoints
**Rule:** never claim a UI/JS change "works" on the basis of green unit tests alone. For any change that touches the rendered backend UI, do one of:
1. Write a Playwright E2E spec under `Tests/E2E/` and run it against DDEV.
2. Look at it yourself on a running instance and report what you saw, with a screenshot (`live-instance-verification.md`).
3. Push the branch and ask the human to verify in a real browser.
A passing unit test is evidence that the function under test does what its tests assert -- not that the feature works for a backend user. Skipping this distinction is the single most common cause of "you said it worked, but it doesn't" feedback on PRs.
## TYPO3 Modal API: Per-Button `trigger` Callbacks
The backend `Modal` renders into the light DOM: `ModalElement.createRenderRoot()` returns the element itself (`Build/Sources/TypeScript/backend/modal.ts`, v13.4.35 and v14.3.7). A click on a modal button first calls that button's `trigger` callback, then dispatches a bubbling `button.clicked` event from the button; core's own `Modal.confirm()` listens for it on the modal element. Both hooks therefore work, but the per-button `trigger` callback keeps the action next to the button it belongs to. `Modal.show(title, content, severity, buttons)` takes positional arguments; a configuration object goes to `Modal.advanced()`:
```javascript
import Modal from '@typo3/backend/modal.js';
import Severity from '@typo3/backend/severity.js';
Modal.advanced({
title: 'Confirm',
content: 'Delete this passkey?',
severity: Severity.warning,
buttons: [
{ text: 'Cancel', btnClass: 'btn-default', trigger: () => { /* dismissed */ } },
{ text: 'Delete', btnClass: 'btn-warning', trigger: () => { performDelete(); } },
],
});
```
Page Object Models in `references/e2e-testing.md` test the rendered modal from the outside via `.modal` selectors; because the modal has no shadow root, Playwright locators reach its buttons directly.
## Testing Best Practices
### 1. Isolate Editor Instance
Each test should use a fresh editor instance:
```javascript
async function createTestEditor() {
const div = document.createElement('div');
document.body.appendChild(div);
const editor = await ClassicEditor.create(div, {
plugins: [Typo3Image, /* other plugins */],
typo3image: {
/* plugin config */
}
});
return editor;
}
```
### 2. Clean Up After Tests
Prevent memory leaks and DOM pollution:
```javascript
afterEach(async () => {
if (editor) {
await editor.destroy();
editor = null;
}
// Clean up any test DOM elements
document.body.innerHTML = '';
});
```
### 3. Test Both Happy Path and Edge Cases
```javascript
describe('Attribute Validation', () => {
it('should handle valid boolean values', () => {
// Happy path
});
it('should handle invalid attribute values', () => {
const html = '<img src="test.jpg" data-noscale="invalid" />';
editor.setData(html);
// Should default to false
const imageElement = editor.model.document.getRoot().getChild(0);
expect(imageElement.getAttribute('noScale')).toBe(false);
});
it('should handle malformed HTML', () => {
const html = '<img src="test.jpg" data-noscale>'; // Missing value
// Test graceful handling
});
});
```
### 4. Mock Backend Interactions
For plugins that communicate with TYPO3 backend:
```javascript
beforeEach(() => {
global.fetch = jest.fn(() =>
Promise.resolve({
json: () => Promise.resolve({ success: true })
})
);
});
afterEach(() => {
global.fetch.mockRestore();
});
it('should fetch image metadata from backend', async () => {
await plugin.fetchImageMetadata(123);
expect(fetch).toHaveBeenCalledWith(
'/typo3/ajax/image/metadata/123',
expect.any(Object)
);
});
```
## Integration with PHP Tests
JavaScript tests complement PHP unit tests:
**PHP Side (Backend):**
```php
// Tests/Unit/Controller/ImageRenderingControllerTest.php
public function testNoScaleAttribute(): void
{
$attributes = ['data-noscale' => 'true'];
$result = $this->controller->render($attributes);
// Verify noScale parameter passed to imgResource
$this->assertStringContainsString('noScale=1', $result);
}
```
**JavaScript Side (Frontend):**
```javascript
// Resources/Public/JavaScript/__tests__/typo3image.test.js
it('should generate data-noscale attribute', () => {
// Verify attribute is created in editor
editor.model.change(writer => {
const img = writer.createElement('typo3image', {
noScale: true
});
writer.insert(img, editor.model.document.getRoot(), 0);
});
expect(editor.getData()).toContain('data-noscale="true"');
});
```
**Together:** These tests ensure end-to-end functionality from editor UI → HTML attribute → PHP backend processing.
## CI/CD Integration
Add JavaScript tests to your CI pipeline:
**package.json:**
```json
{
"scripts": {
"test": "jest",
"test:coverage": "jest --coverage",
"test:watch": "jest --watch"
},
"devDependencies": {
"jest": "^29.0.0",
"@babel/preset-env": "^7.20.0"
}
}
```
**GitHub Actions:**
```yaml
- name: Run JavaScript tests
run: |
npm install
npm run test:coverage
- name: Upload JS coverage
uses: codecov/codecov-action@v3
with:
files: ./coverage/lcov.info
flags: javascript
```
## Example: Complete Test Suite
A TYPO3 extension shipping a CKEditor plugin lays its two suites out like this:
```
<extension>/
├── Resources/Public/JavaScript/
│ └── Plugins/
│ ├── typo3image.js # Main plugin
│ └── __tests__/
│ └── typo3image.test.js # JavaScript tests
└── Tests/Unit/
└── Controller/
└── ImageRenderingControllerTest.php # PHP tests
```
**Key Lessons:**
1. Test attribute schema registration
2. Test upcast/downcast conversions separately
3. Test UI interactions (checkboxes, inputs)
4. Test data-* attribute preservation
5. Clean up editor instances to prevent leaks
6. Mock backend API calls
7. Coordinate with PHP tests for full coverage
## Troubleshooting
### Tests Pass Locally but Fail in CI
**Cause:** DOM environment differences
**Solution:**
```javascript
// jest.config.js
module.exports = {
testEnvironment: 'jsdom',
testEnvironmentOptions: {
url: 'http://localhost'
}
};
```
### Memory Leaks in Test Suite
**Cause:** Editor instances not properly destroyed
**Solution:**
```javascript
afterEach(async () => {
if (editor && !editor.state === 'destroyed') {
await editor.destroy();
}
editor = null;
});
```
### Async Test Failures
**Cause:** Not waiting for editor initialization
**Solution:**
```javascript
beforeEach(async () => {
editor = await ClassicEditor.create(/* ... */);
// ☝️ await is critical
});
```
## JavaScript Migration Testing
When migrating jQuery code to native JavaScript (ES modules), specific testing patterns
are critical to catch subtle scoping and security bugs that static analysis often misses.
### Variable Scoping Bug in `$.each` to `for...of` Migration
**The Problem:** jQuery's `$.each(array, function(key, value) { ... })` creates a
**function scope** per iteration. Every `var` declaration inside the callback is unique
to that iteration. When migrating to native `for (const [key, value] of Object.entries(obj))`,
the loop body is only a **block scope**. Any `var` declarations are **hoisted** to the
enclosing function and **shared** across all iterations.
This silently breaks closures that capture loop variables (event handlers, callbacks,
`setTimeout`, etc.).
**A bug this produced in practice:**
A dialog's aspect-ratio handler iterated over `{width, height}` with `$.each`.
Inside the callback, `var el` and `var max` were captured by a `constrainDimensions`
closure attached as an event handler. After converting `$.each` to `for...of` without
also converting `var` to `let`/`const`, `el` and `max` were shared across width/height
iterations. The height handler always referenced the width element, so changing width
never triggered height auto-adjustment.
E2E symptom: `toBeLessThanOrEqual` expected height ratio <=1, received 300 (the raw
pixel value instead of the computed ratio).
**Before (jQuery -- works correctly):**
```javascript
$.each({width: maxWidth, height: maxHeight}, function (dimension, max) {
var el = document.getElementById('dimension-' + dimension);
var constrainDimensions = function () {
// `el` and `max` are unique per iteration (function scope)
if (parseInt(el.value, 10) > max) {
el.value = max;
}
};
el.addEventListener('input', constrainDimensions);
});
```
**After (broken -- `var` hoisted to function scope):**
```javascript
for (const [dimension, max] of Object.entries({width: maxWidth, height: maxHeight})) {
var el = document.getElementById('dimension-' + dimension); // BUG: shared!
var constrainDimensions = function () {
// `el` always points to LAST iteration's element (height)
// `max` is always the LAST iteration's value
};
el.addEventListener('input', constrainDimensions);
}
```
**After (fixed -- `let` creates block scope):**
```javascript
for (const [dimension, max] of Object.entries({width: maxWidth, height: maxHeight})) {
const el = document.getElementById('dimension-' + dimension); // unique per iteration
const constrainDimensions = function () {
// `el` and `max` are correctly captured per iteration
if (parseInt(el.value, 10) > max) {
el.value = max;
}
};
el.addEventListener('input', constrainDimensions);
}
```
**Rule:** When migrating `$.each` to `for...of`, convert ALL `var` declarations inside
the loop body to `let`/`const` at the SAME TIME as the loop conversion. Never split
these into separate commits.
### Testing Intermediate Commits in Migration PRs
When a jQuery removal PR has multiple commits (e.g., "convert loops" then "convert var
to let/const"), CI may test intermediate commits where `$.each` is already converted
but `var` has not yet been changed. This intermediate state has the scoping bug described
above.
**Best practice:**
- Squash loop conversion and `var` to `let`/`const` conversion into a single atomic commit
- If separate commits are needed for review clarity, mark intermediate commits as
`[skip ci]` or ensure the PR's merge strategy squashes them
- E2E tests that exercise closure behavior (event handlers, callbacks) will catch this
class of bug -- add them before the migration
### `insertAdjacentHTML` and CodeQL XSS Warnings
When replacing jQuery's `$.append()` or `$.html()` with native DOM methods, avoid
`insertAdjacentHTML` with template literals:
```javascript
// TRIGGERS CodeQL js/xss-through-dom
el.insertAdjacentHTML('beforeend', `<span>${userInput}</span>`);
```
**Fix:** Use `createElement` + `textContent` for user-controlled content:
```javascript
// SAFE -- textContent auto-escapes
const span = document.createElement('span');
span.textContent = userInput;
el.appendChild(span);
```
For static HTML without user input, `insertAdjacentHTML` is acceptable but CodeQL may
still flag it. Prefer `createElement` chains to avoid false positives and keep the
codebase consistently safe.
### E2E Test Patterns for JS Migration Verification
When testing that a jQuery-to-native-JS migration preserves behavior, focus on:
1. **Closure-dependent behavior:** Event handlers registered inside loops must still
reference the correct variables. Test each iteration's handler independently.
2. **DOM manipulation timing:** jQuery's `.ready()` vs native `DOMContentLoaded` or
ES module top-level execution can shift when code runs.
3. **Event delegation:** jQuery's `.on(selector, handler)` delegation must be replaced
with explicit `addEventListener` on the correct target or a manual delegation pattern.
4. **AJAX/fetch migration:** jQuery's `$.ajax` coerces responses differently than
`fetch`. Verify response parsing in E2E tests.
```typescript
// E2E test verifying aspect ratio constraint survives migration
test('changing width auto-adjusts height to maintain aspect ratio', async ({ page }) => {
// ... navigate to image dialog ...
const widthInput = page.locator('#image-width');
const heightInput = page.locator('#image-height');
// Get original dimensions
const originalWidth = await widthInput.inputValue();
const originalHeight = await heightInput.inputValue();
const aspectRatio = parseInt(originalHeight, 10) / parseInt(originalWidth, 10);
// Change width
await widthInput.fill('200');
await widthInput.dispatchEvent('input');
// Height must auto-adjust
const newHeight = parseInt(await heightInput.inputValue(), 10);
const expectedHeight = Math.round(200 * aspectRatio);
expect(newHeight).toBeLessThanOrEqual(expectedHeight + 1);
expect(newHeight).toBeGreaterThanOrEqual(expectedHeight - 1);
});
```
## References
- [CKEditor 5 Testing](https://ckeditor.com/docs/ckeditor5/latest/framework/guides/contributing/testing-environment.html)
- [Jest Documentation](https://jestjs.io/docs/getting-started)
- [MDN: var hoisting](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/var#hoisting)
- [MDN: let block scope](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/let)
- [CodeQL js/xss-through-dom](https://codeql.github.com/codeql-query-help/javascript/js-xss-through-dom/)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |