aurelia2-testing-library

A React Testing Library–inspired helper for Aurelia 2 apps, built on top of
@aurelia/testing and @testing-library/dom.

Install

``bash
npm i -D aurelia2-testing-library @aurelia/testing @testing-library/dom
`

Test environment setup (Node + jsdom)


@aurelia/testing needs a platform instance. In a Node test runner, set it
once during setup.

`ts
import { JSDOM } from 'jsdom';
import { BrowserPlatform } from '@aurelia/platform-browser';
import { setPlatform } from '@aurelia/testing';

const jsdom = new JSDOM(, {
pretendToBeVisual: true,
});

const w = jsdom.window;
const platform = new BrowserPlatform(w, {
queueMicrotask: typeof w.queueMicrotask === 'function'
? w.queueMicrotask.bind(w)
: (cb) => Promise.resolve().then(cb),
fetch: typeof w.fetch === 'function'
? w.fetch.bind(w)
: () => { throw new Error('fetch not available'); },
});

setPlatform(platform);
BrowserPlatform.set(globalThis, platform);
`

If your test runner already provides a DOM (for example jsdom in Jest/Vitest),
you can use:

`ts
import { BrowserPlatform } from '@aurelia/platform-browser';
import { setPlatform } from '@aurelia/testing';

const platform = BrowserPlatform.getOrCreate(globalThis);
setPlatform(platform);
BrowserPlatform.set(globalThis, platform);
`

Quick start

`ts
import { renderComponent, screen, userEvent, createUserEvent, cleanup } from 'aurelia2-testing-library';
import { CustomElement } from '@aurelia/runtime-html';

afterEach(async () => {
await cleanup();
});

class HelloWorld {
public name = 'Aurelia';
}

CustomElement.define({
name: 'hello-world',
template: Name

Hello, \\${name}!

,
})(HelloWorld);

it('renders and updates', async () => {
await renderComponent(HelloWorld);

expect(screen.getByText('Hello, Aurelia!')).toBeTruthy();

await userEvent.type(screen.getByLabelText('Name'), ' Testing');

expect(screen.getByText('Hello, Testing!')).toBeTruthy();
});
`

API

$3

Creates and (by default) starts an Aurelia fixture, returning DOM Testing
Library queries plus helpful Aurelia-specific handles.

`ts
const result = await render('', {
component: MyApp,
registrations: [MyService],
autoStart: true,
appConfig: { allowActionlessForm: true },
});

result.container; // element that Aurelia renders into
result.host; // wrapper