Skip to content

netresearch/typo3-testing-skill / skills/typo3-testing

typo3-testing

Flagged

Use 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.

FileKindSize
SKILL.mdskill md6.8 KB
assets/.php-cs-fixer.dist.phpscript7.0 KB
assets/AGENTS.mdmarkdown5.0 KB
assets/Build/Scripts/runTests.shexecutablescript27.5 KB
assets/Build/playwright/.nvmrcother6 B
assets/Build/playwright/package.jsonmanifest535 B
assets/Build/playwright/playwright.config.tsscript1.3 KB
assets/Build/playwright/tests/playwright/accessibility/modules.spec.tsscript2.0 KB
assets/Build/playwright/tests/playwright/config.tsscript712 B
assets/Build/playwright/tests/playwright/e2e/backend-module.spec.tsscript1.9 KB
assets/Build/playwright/tests/playwright/fixtures/setup-fixtures.tsscript2.7 KB
assets/Build/playwright/tests/playwright/helper/login.setup.tsscript975 B
assets/FunctionalTests.xmlconfig1.4 KB
assets/FunctionalTestsBootstrap.phpscript1.6 KB
assets/Makefileother2.3 KB
assets/UnitTests.xmlconfig890 B
assets/UnitTestsBootstrap.phpscript2.1 KB
assets/bootstrap.phpscript1.4 KB
assets/codecov.ymlconfig1.6 KB
assets/docker/codeception.ymlconfig979 B
assets/docker/docker-compose.ymlconfig1.4 KB
assets/example-tests/ExampleAcceptanceCest.phpscript2.2 KB
assets/example-tests/ExampleFunctionalTest.phpscript2.4 KB
assets/example-tests/ExampleUnitTest.phpscript1.6 KB
assets/fixtures/README.mdmarkdown2.0 KB
assets/fixtures/be_users.csvother361 B
assets/fixtures/pages.csvother257 B
assets/fixtures/sys_category.csvother228 B
assets/fixtures/tt_content.csvother338 B
assets/github-actions-e2e.ymlconfig8.8 KB
assets/github-actions-tests.ymlconfig6.3 KB
assets/infection.json5other2.8 KB
assets/phpat.neonother330 B
assets/phpat.phpscript8.4 KB
assets/phpstan-baseline.neonother365 B
assets/phpstan.neonother1.4 KB
assets/rector.phpscript2.9 KB
checkpoints.yamlconfig61.7 KB
references/accessibility-testing.mdmarkdown7.6 KB
references/architecture-testing.mdmarkdown4.4 KB
references/asset-templates-guide.mdmarkdown3.4 KB
references/backend-module-render-verification.mdmarkdown9.7 KB
references/backend-user-access-testing.mdmarkdown9.5 KB
references/captainhook-setup.mdmarkdown2.4 KB
references/ci-cd.mdmarkdown39.5 KB
references/ci-debugging.mdmarkdown20.0 KB
references/ci-workflows-meta-package.mdmarkdown11.6 KB
references/crash-and-concurrency-testing.mdmarkdown4.8 KB
references/crypto-testing.mdmarkdown16.6 KB
references/datahandler-silent-rewrites.mdmarkdown7.2 KB
references/ddev-testing.mdmarkdown1.3 KB
references/e2e-testing.mdmarkdown53.0 KB
references/enforcement-rules.mdmarkdown5.7 KB
references/event-dispatch-testing.mdmarkdown2.8 KB
references/framework-compat-gate.mdmarkdown4.9 KB
references/functional-test-patterns.mdmarkdown11.0 KB
references/functional-testing.mdmarkdown46.3 KB
references/fuzz-testing.mdmarkdown8.6 KB
references/integration-testing.mdmarkdown14.1 KB
references/javascript-testing.mdmarkdown29.3 KB
references/live-instance-verification.mdmarkdown8.6 KB
references/mock-validity.mdmarkdown15.7 KB
references/mutation-testing.mdmarkdown36.0 KB
references/performance-testing.mdmarkdown11.2 KB
references/quality-tools.mdmarkdown25.5 KB
references/release-workflow-validation.mdmarkdown3.6 KB
references/sonarcloud.mdmarkdown18.8 KB
references/synthetic-secret-fixtures.mdmarkdown3.8 KB
references/tdd-discipline.mdmarkdown9.1 KB
references/test-environment-guards.mdmarkdown18.5 KB
references/test-runners.mdmarkdown24.6 KB
references/typo3-ci-config-patterns.mdmarkdown9.0 KB
references/typo3-v14-final-classes.mdmarkdown16.5 KB
references/unit-testing.mdmarkdown59.1 KB
scripts/generate-test.shexecutablescript6.0 KB
scripts/setup-testing.shexecutablescript6.3 KB
scripts/validate-setup.shexecutablescript4.0 KB

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/)
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall