Menu
Unit and component testing for Umbraco backoffice extensions using @open-wc/testing
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Implement UFM (Umbraco Flavored Markdown) components in Umbraco backoffice using official docs
Add a new Umbraco extension project reference to the main Umbraco instance and solution
Understand and use localization in Umbraco backoffice (foundational concept)
Implement property editor UIs in Umbraco backoffice using official docs
Quick setup for Umbraco extension development - creates instance, extension, and registers it
Review checks reference for validating Umbraco backoffice extensions
Baseado na classificação ocupacional SOC
| name | umbraco-unit-testing |
| description | Unit and component testing for Umbraco backoffice extensions using @open-wc/testing |
| version | 1.0.0 |
| location | managed |
| allowed-tools | Read, Write, Edit, WebFetch |
Unit testing for Umbraco backoffice extensions using @open-wc/testing - a testing framework designed for Web Components and Lit elements. This is the fastest and most isolated testing approach.
Add to package.json:
{
"devDependencies": {
"@open-wc/testing": "^4.0.0",
"@web/dev-server-esbuild": "^1.0.0",
"@web/dev-server-import-maps": "^0.2.0",
"@web/test-runner": "^0.18.0",
"@web/test-runner-playwright": "^0.11.0"
},
"scripts": {
"test": "web-test-runner",
"test:watch": "web-test-runner --watch"
}
}
Then run:
npm install
npx playwright install chromium
Create web-test-runner.config.mjs in the project root:
import { esbuildPlugin } from '@web/dev-server-esbuild';
import { playwrightLauncher } from '@web/test-runner-playwright';
import { importMapsPlugin } from '@web/dev-server-import-maps';
export default {
rootDir: '.',
files: ['./src/**/*.test.ts', '!**/node_modules/**'],
nodeResolve: {
exportConditions: ['development'],
preferBuiltins: false,
browser: false,
},
browsers: [playwrightLauncher({ product: 'chromium' })],
plugins: [
importMapsPlugin({
inject: {
importMap: {
imports: {
'@umbraco-cms/backoffice/external/lit': '/node_modules/lit/index.js',
// CRITICAL: Use dist-cms, NOT dist/packages
'@umbraco-cms/backoffice/lit-element':
'/node_modules/@umbraco-cms/backoffice/dist-cms/packages/core/lit-element/index.js',
// CRITICAL: libs are at dist-cms/libs/, NOT dist-cms/packages/
'@umbraco-cms/backoffice/element-api':
'/node_modules/@umbraco-cms/backoffice/dist-cms/libs/element-api/index.js',
'@umbraco-cms/backoffice/observable-api':
'/node_modules/@umbraco-cms/backoffice/dist-cms/libs/observable-api/index.js',
'@umbraco-cms/backoffice/context-api':
'/node_modules/@umbraco-cms/backoffice/dist-cms/libs/context-api/index.js',
'@umbraco-cms/backoffice/controller-api':
'/node_modules/@umbraco-cms/backoffice/dist-cms/libs/controller-api/index.js',
'@umbraco-cms/backoffice/class-api':
'/node_modules/@umbraco-cms/backoffice/dist-cms/packages/core/class-api/index.js',
// Add other imports as needed
},
},
},
}),
esbuildPlugin({
ts: true,
tsconfig: './tsconfig.json',
target: 'auto',
json: true,
}),
],
testRunnerHtml: (testFramework) =>
`<html lang="en-us">
<head>
<meta charset="UTF-8" />
</head>
<body>
<script type="module" src="${testFramework}"></script>
</body>
</html>`,
};
| Type | Location | Example |
|---|---|---|
| Libs (low-level APIs) | dist-cms/libs/ | element-api, observable-api |
| Packages (features) | dist-cms/packages/ | core/lit-element, core/class-api |
Common mistake: Using dist/packages instead of dist-cms causes 404 errors.
For simpler unit tests that don't need the full Umbraco context system, mock the Umbraco imports entirely. This approach:
// web-test-runner.config.mjs
import { esbuildPlugin } from '@web/dev-server-esbuild';
import { importMapsPlugin } from '@web/dev-server-import-maps';
import { playwrightLauncher } from '@web/test-runner-playwright';
export default {
files: 'src/**/*.test.ts',
nodeResolve: true,
browsers: [playwrightLauncher({ product: 'chromium' })],
plugins: [
esbuildPlugin({ ts: true }),
importMapsPlugin({
inject: {
importMap: {
imports: {
// Map Umbraco imports to local mocks
'@umbraco-cms/backoffice/external/lit': '/src/__mocks__/lit.js',
'@umbraco-cms/backoffice/observable-api': '/src/__mocks__/observable-api.js',
'@umbraco-cms/backoffice/class-api': '/src/__mocks__/class-api.js',
// Add others as needed
},
},
},
}),
],
};
Create src/__mocks__/observable-api.js:
export class UmbStringState {
#value;
#subscribers = [];
constructor(initialValue) {
this.#value = initialValue;
}
getValue() { return this.#value; }
setValue(value) {
this.#value = value;
this.#subscribers.forEach(cb => cb(value));
}
asObservable() {
return {
subscribe: (callback) => {
this.#subscribers.push(callback);
callback(this.#value);
return { unsubscribe: () => {
const idx = this.#subscribers.indexOf(callback);
if (idx > -1) this.#subscribers.splice(idx, 1);
}};
}
};
}
destroy() { this.#subscribers = []; }
}
Create src/__mocks__/lit.js:
export const html = (strings, ...values) => ({ strings, values });
export const css = (strings, ...values) => ({ strings, values });
export const nothing = Symbol('nothing');
export const customElement = (name) => (target) => target;
export const state = () => (target, propertyKey) => {};
import { expect } from '@open-wc/testing';
import { OUR_ENTITY_TYPE } from './types.js';
describe('Entity Types', () => {
it('should define entity type', () => {
expect(OUR_ENTITY_TYPE).to.equal('our-entity');
});
});
| Scenario | Approach |
|---|---|
| Testing types, constants, pure functions | Mock-based (simpler) |
| Testing observable state patterns | Mock-based (simpler) |
| Testing Lit elements with shadow DOM | Full Umbraco imports |
| Testing context consumption between elements | Full Umbraco imports |
| Testing with UUI components | Full Umbraco imports |
See tree-example in umbraco-backoffice/examples/tree-example/Client/:
web-test-runner.config.mjs - Mock-based configurationsrc/__mocks__/ - Mock implementationssrc/**/*.test.ts - Unit tests using mocksmy-extension/
├── src/
│ ├── my-context.ts
│ ├── my-context.test.ts # Test alongside source
│ ├── my-element.ts
│ └── my-element.test.ts
├── web-test-runner.config.mjs
├── package.json
└── tsconfig.json
import { expect, fixture, defineCE } from '@open-wc/testing';
import { html } from 'lit';
describe('MyFeature', () => {
beforeEach(async () => {
// Setup for each test
});
afterEach(() => {
// Cleanup after each test
});
it('should do something', async () => {
// Arrange, Act, Assert
});
});
fixture() - Create and wait for element:
const element = await fixture(html`<my-element></my-element>`);
// With parent node (for context consumption)
const element = await fixture(html`<my-element></my-element>`, {
parentNode: hostElement,
});
defineCE() - Define custom element with unique tag:
import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';
class TestHostElement extends UmbLitElement {}
const testHostTag = defineCE(TestHostElement);
const host = await fixture(`<${testHostTag}></${testHostTag}>`);
expect() - Chai assertions:
expect(value).to.equal(5);
expect(value).to.be.true;
expect(array).to.have.length(3);
expect(element.shadowRoot?.textContent).to.include('Hello');
import { expect, fixture, defineCE } from '@open-wc/testing';
import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';
import { MyContext } from './my-context.js';
class TestHostElement extends UmbLitElement {}
const testHostTag = defineCE(TestHostElement);
describe('MyContext', () => {
let hostElement: UmbLitElement;
let context: MyContext;
beforeEach(async () => {
hostElement = await fixture(`<${testHostTag}></${testHostTag}>`);
context = new MyContext(hostElement);
});
it('initializes with default value', (done) => {
context.value.subscribe((value) => {
expect(value).to.equal(0);
done();
});
});
it('increments value', (done) => {
let callCount = 0;
context.value.subscribe((value) => {
callCount++;
if (callCount === 1) {
expect(value).to.equal(0);
context.increment();
} else if (callCount === 2) {
expect(value).to.equal(1);
done();
}
});
});
});
import { expect, fixture } from '@open-wc/testing';
import { html } from 'lit';
import './my-element.js';
import type { MyElement } from './my-element.js';
describe('MyElement', () => {
let element: MyElement;
beforeEach(async () => {
element = await fixture(html`<my-element></my-element>`);
});
it('renders with default content', async () => {
expect(element.shadowRoot?.textContent).to.include('Default Value');
});
it('updates display when property changes', async () => {
element.value = 'New Value';
await element.updateComplete;
expect(element.shadowRoot?.textContent).to.include('New Value');
});
});
import { expect, fixture, defineCE } from '@open-wc/testing';
import { html } from 'lit';
import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';
import { MyContext } from './my-context.js';
import './my-view.js';
class TestHostElement extends UmbLitElement {}
const testHostTag = defineCE(TestHostElement);
describe('MyView', () => {
let element: MyViewElement;
let context: MyContext;
let hostElement: UmbLitElement;
beforeEach(async () => {
// 1. Create host element
hostElement = await fixture(`<${testHostTag}></${testHostTag}>`);
// 2. Create context on host
context = new MyContext(hostElement);
// 3. Create element as child of host
element = await fixture(html`<my-view></my-view>`, {
parentNode: hostElement,
});
await element.updateComplete;
});
it('displays value from context', async () => {
expect(element.shadowRoot?.textContent).to.include('Value: 0');
});
it('updates when context changes', async () => {
context.increment();
await element.updateComplete;
expect(element.shadowRoot?.textContent).to.include('Value: 1');
});
});
UUI components use shadow DOM, so events need composed: true:
// Clicking buttons
it('button click triggers action', async () => {
const button = element.shadowRoot?.querySelector('uui-button') as HTMLElement;
button.dispatchEvent(new MouseEvent('click', { bubbles: true, composed: true }));
await element.updateComplete;
expect(element.shadowRoot?.textContent).to.include('clicked');
});
// Toggling uui-toggle
it('toggle changes state', async () => {
const toggle = element.shadowRoot?.querySelector('uui-toggle') as HTMLElement;
toggle.dispatchEvent(new Event('change', { bubbles: true }));
await element.updateComplete;
expect(element.shadowRoot?.textContent).to.include('toggled');
});
Important: State objects only emit when values change:
// This WILL emit twice (values different)
state.setValue(0);
state.setValue(1);
// This emits ONCE (same value - no second emission)
state.setValue(0);
state.setValue(0);
Testing no-op operations:
it('does not go below 0', (done) => {
let callCount = 0;
context.count.subscribe((value) => {
callCount++;
if (callCount === 1) {
expect(value).to.equal(0);
context.decrement(); // Try to go below 0
setTimeout(() => {
expect(callCount).to.equal(1); // No second emission
done();
}, 50);
}
});
});
import { expect, fixture, defineCE } from '@open-wc/testing';
import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';
import { html } from '@umbraco-cms/backoffice/external/lit';
import { CounterContext } from './counter-context.js';
import './counter-view.js';
class TestHostElement extends UmbLitElement {}
const testHostTag = defineCE(TestHostElement);
describe('CounterContext', () => {
let element: UmbLitElement;
let context: CounterContext;
beforeEach(async () => {
element = await fixture(`<${testHostTag}></${testHostTag}>`);
context = new CounterContext(element);
});
it('initializes with 0', (done) => {
context.counter.subscribe((value) => {
expect(value).to.equal(0);
done();
});
});
it('increments', (done) => {
let callCount = 0;
context.counter.subscribe((value) => {
callCount++;
if (callCount === 1) {
context.increment();
} else if (callCount === 2) {
expect(value).to.equal(1);
done();
}
});
});
it('resets to 0', (done) => {
let callCount = 0;
context.counter.subscribe((value) => {
callCount++;
if (callCount === 1) {
context.increment();
context.increment();
} else if (callCount === 3) {
context.reset();
} else if (callCount === 4) {
expect(value).to.equal(0);
done();
}
});
});
});
describe('CounterView', () => {
let element: CounterViewElement;
let context: CounterContext;
let hostElement: UmbLitElement;
beforeEach(async () => {
hostElement = await fixture(`<${testHostTag}></${testHostTag}>`);
context = new CounterContext(hostElement);
element = await fixture(html`<counter-view></counter-view>`, {
parentNode: hostElement,
});
await element.updateComplete;
});
it('shows initial value', async () => {
expect(element.shadowRoot?.textContent).to.include('Count: 0');
});
it('reflects changes', async () => {
context.increment();
await element.updateComplete;
expect(element.shadowRoot?.textContent).to.include('Count: 1');
});
});
# Run all unit tests
npm test
# Run in watch mode
npm run test:watch
# Run specific file
npx web-test-runner src/my-element.test.ts
# Run with coverage
npx web-test-runner --coverage
Check import map paths. Use dist-cms/libs/ for APIs and dist-cms/packages/ for features.
Ensure you import the element file before using it in tests:
import './my-element.js'; // Side effect import registers element
Element must be child of host with context:
element = await fixture(html`<my-element></my-element>`, {
parentNode: hostElement, // Host must have context
});
Use done() callback for async subscriptions:
it('test', (done) => {
observable.subscribe((value) => {
expect(value).to.equal(expected);
done(); // Signal completion
});
});
Ensure you await it:
element.value = 'new';
await element.updateComplete; // Must await
expect(element.shadowRoot?.textContent).to.include('new');