xn--mxaac v0.1.1

:flying_saucer: ABA (:warning: WIP :building_construction:)

Test runner for browser libraries.

ABA allows you to run tests for browser libraries isolated and in parallel. This is made possible by playwright, rollup, and some magic glue.

The end goal is to replicate AVA's experience for browser libraries, with tests happening in real browsers. The only alternatives I know of are jest's jsdom polyfilling, but that is not a real browser, or setting up everything by hand which is better done once correctly.

:warning: Caveats

• In its current state, ABA is best suited to test non-graphical libraries, those that do not touch the DOM, but still rely on browser-only features such as localStorage, and indexeddb.

• Tests really run isolated. There is no way with the current implementation to have test functions interact with each other in any way (localStorage, indexeddb, and cache in general are not shared). This is counter-intuitive coming from AVA, where disk writes do persist. Browser contexts provide a real sandbox from which you cannot escape, and those are discarded once the test function returns or throws. It may be interesting to provide solutions to this new problem in the future (for instance to test the behavior of a browser library when running in multiple tabs).

:woman_teacher: Example

Install ABA

yarn add --dev xn--mxaac

Declaring tests

:warning: Currently support is only guaranteed for tests written in TypeScript and all tests are expected to be async.

// myTestFile.ts
import test from 'xn--mxaac';

test('title', async () => {
	// do something with the browser API
	// throw an Error to fail the test
});

Running tests

aba myTestFile.ts

:bulb: Any number of glob expressions is supported, for instance aba '*.ts' (see globby).

:sparkles: Features

• Basic browser/device selection
• Basic filter/match
• Basic timeout
• Basic fatal error catching
• TAP reporter

:pencil: TODO

• Use proper logger for debugging instead of console.error
• Coverage (using c8/ts-node/babel?)
• GitHub actions coverage
• "nice" tasklist-like reporter
• HTTP polling instead of DOM polling if available
• Websocket instead of DOM polling if available (see https://playwright.dev/docs/network#websockets or better https://masteringjs.io/tutorials/node/websocket-server)
• Multi browser/device matrix run
• Config file
• Watch mode (this should be easy through rollup's watch mechanism)
• Inspect mode (HTTP server only) to manually open generated HTML files
• Make parsing grow linearly with test file size (currently sends a test file containing N tests N times to a browser context, each browser context reads all the tests code).

:woman_juggling: How does it work?

A use-once duplex communication channel is established through:

1. Sending arbitrary data to the browser through pointing it to a URL with an arbitrary location hash.
2. Sending arbitrary data back to the test runner through writing arbitrary content to the DOM.

import test from 'xn--mxaac';

import {assert} from 'chai';

for (const myTitle of 'ABCDEFGHIJKLMNOPQRSTUVWXYZ') {
	test(myTitle, async () => {
		// breaking through abstraction, you are not supposed to do this
		const startEvents = document.querySelector('#events')
			.filter(({type}) => type === 'test-start')

		const myStartEvents = startEvents
			.filter(({title}) => title === myTitle);

		assert(myStartEvents.length === 1);

		const otherStartEvents = startEvents
			.filter(({title}) => title !== myTitle);

		assert(otherStartEvents.length === 0);
	});
}

In the future we will implement a multi-use duplex communication channel through websockets or HTTP long-polling.