docs: Add example for testing a Web Component

[Zearin]

I have always hated the difficulty of browser testing vs. the (theoretically) simple, clean IO of CLI testing.

Over the years, I’ve tried getting into things like WebDriver (and many others), but I always had an issue with either:

• too much work to get started; OR
• the initial setup was okay, but it became difficult trying to write tests for the browser

This promise of this project looks like it would solve both of these issues. I love it!

…But I’m having trouble getting started again.

I have a strong sense that hTest can do what I want without a lot of work, but it’s not quite clear to me what work that is.

I suppose this gets to the stated point on the homepage:

Improve documentation — this is top priority, people keep asking for things that are already possible because they’re not documented well!

The HTML-first side where I’m scratching my head. I want to test a very simple, dumb web component that I wrote for a personal project, and I think that means it must be an HTML-first test because of the DOM.

But no matter how often I read the docs for HTML-first tests, I cannot think of how to write the setup code or tests for a custom web component.

If someone could get me started successfully on this, I’d be glad to write a short tutorial for the docs. 🙏🏽

[LeaVerou]

@Zearin Yeah, big apologies for the docs, this project is basically developed in the open but hasn't exactly launched yet, and the docs are often lagging behind the implementation.

If it helps, I have felt the pain of testing web components myself, and it's certainly in scope for hTest to improve on this. Both JS and HTML first tests could make sense for a web component depending on what you want to test, though HTML-first tests are not currently well integrated with CIs, not sure how much of the priority that is.

If you can describe a few tests you'd like to write (i.e. details of what exactly you'd like to test), I can point you in the right direction!

[Zearin]

@LeaVerou No apologies necessary! I thought open source was all about “being developed in the open”. 😉

Actually, I misspoke when I said it was a web component. I was thinking about web components, but what I actually did was just write a little subclass of DOMRect for the sake of ergonomics.

(Context: It was a personal project that I haven’t made public, but it was an SVG map, and I was using the subclass to make it easier to manipulate the root viewBox attribute.)

Since I have always struggled with how to test web-based things (i.e. web components, DOM, and everything else), I thought a neat starting point would be to try and take the tests for DOMRect from the Web Platform Tests and try to rewrite them in hTest.

Since my subclass was, uh, a subclass, it would probably pass everything without a problem. But it would make me feel more confident in the quality of my work, and I was hoping to learn how to use hTest along the way. :)

For reference, here are the WPT files I wanted to convert to hTest:

• DOMRect-001
• DOMRect-002
• DOMRect-NaN

[Zearin]

(P.S. I forgot to address your concern about CI integration. It’s not important to me for this particular project.)

[Zearin]

(P.P.S.: How would you test a constructor in hTest? The new operator complicates things, since it’s not a normal function call…)

[LeaVerou]

These are basically purely JS tests, so the JS-first API is the way to go. It doesn't matter that they're testing a DOM constructor. The HTML-first syntax is primarily for things like:

• I want to render some HTML and inspect the visual result
• I want to render some HTML and ensure certain selectors pass
• I want to render some HTML and simulate some UI events on it and then test that certain things happen
• etc

This seems pretty straightforward to convert to hTest, and I do think it would end up being a lot clearer, so thanks for the fantastic example! These are exactly the types of repetitive tests that hTest aims to simplify.

I’ll try to make a little proof of concept later today or tomorrow. Just to confirm my understanding, these tests check:

• That the two constructors work (DOMRect and DOMRectReadOnly)
• That instances created with these constructors have the expected values
• That setters on DOMRect instances actually change the returned value

Am I missing anything?

[LeaVerou]

(P.P.S.: How would you test a constructor in hTest? The new operator complicates things, since it’s not a normal function call…)

Assuming you'd want a new instance for every test, perhaps specifying the constructor itself as a data property, and the constructor args as part of each test, I'm thinking of something like this:

{
	run(...args) {
		return new this.data.constructor(...args);
	},
	tests: [
		{
			data: { constructor: DOMRect },
			tests: [
				{
					args: [1, 2, 3], 
					expect: { x: 1, y: 2, width: 3, height: 0, top: 2, right: 4, bottom: 2, left: 1 }
				},
				// ... other tests ...
			],
		},
		// similar for DOMRectReadOnly
	]
}

If you have multiple tests with the same arguments, you can nest them further.

What I can't remember is whether this would work out of the box with the default check function. @DmitrySharabin do you remember?

[DmitrySharabin]

What I can't remember is whether this would work out of the box with the default check function. @DmitrySharabin do you remember?

By default, we are using deep equality, so it should work:

htest/src/classes/Test.js

Lines 43 to 45 in d08a224

	if (!this.check) {
	this.check = check.equals;
	}

htest/src/check.js

Line 152 in d08a224

export const equals = deep(shallowEquals());

[LeaVerou]

By default, we are using deep equality, so it should work:

That I do remember, what I'm not sure about is whether we error if there are properties present in the result that are not present in expect and whether we test that the constructor is equal (or at least has the same name), both of which would make that test fail.

[Zearin]

@LeaVerou Thanks so much! You are super helpful.

The only thing I still don’t quite understand is how the testing environment will have access to the built-in DOM objects. Is it that they are JS-tests, but the tests will still run in the browser? 🤔

[LeaVerou]

@LeaVerou Thanks so much! You are super helpful.

The only thing I still don’t quite understand is how the testing environment will have access to the built-in DOM objects. Is it that they are JS-tests, but the tests will still run in the browser? 🤔

When I was talking about JS-first tests, I was referring to the syntax of writing the tests. HTML-first tests are tests written in HTML. Because hTest is declarative, the UI you use to display the test results and the syntax you use to write the tests are entirely decoupled. I.e. you can still use the HTML UI to display the test results, even if you've used the JS syntax to write them (theoretically and vice versa).

So, currently, to access DOM APIs, you'd need to use the HTML test runner, in a browser. There's an open issue (#74) about being able to use the CLI and run tests in a headless browser, as yes, it's sorely needed. I don't think it would be tremendously hard to implement, though it would probably need to live in a separate package to avoid having to add Puppeteer as a dependency of hTest as a whole.

[Zearin]

I understand. Thank you 🙏🏽

though it would probably need to live in a separate package to avoid having to add Puppeteer as a dependency of hTest as a whole.

Yes, please don’t add a giant dependency!

Part of the appeal of this project is how lean it is, and how much it can do with that small codebase.

[Zearin]

Edit (2025-12-06): Ignore this one. I’ve finally got a little bit of traction running the constructor tests in the browser! 🎉

I’m working on a conversion for the WPT DOMRect-001. I don’t have it working yet—but maybe the problems I’m having might help for future improvements to the docs?

WIP hTest conversion of WPT DOMRect-001:

import htest from '../node_modules/htest.dev/htest.js'
export default {

tests: [{

name: 'Constructor',
	data: {
		constructors: [ DOMRect, DOMRectReadOnly ]
	},

	tests: [
		{

			//	FIXME: Use `getName()` instead of computing `prefix` inside `run()`
			run(...args) {
				const prefix = constructor === DOMRect ? 'testConstructor' : 'testReadOnlyConstructor'
				for (const constructor of this.data.constructors) {
					return new constructor(...args)
				}
			},

			tests: [
				{
					name: 'no args',
					args: [],
					expect: { x: 0, y: 0, width: 0, height: 0, top: 0, right: 0, bottom: 0, left: 0 }
				},
				{
					name: '1 arg',
					arg: 1,
					expect: { x: 1, y: 0, width: 0, height: 0, top: 0, right: 1, bottom: 0, left: 1 }
				},
				{
					name: '2 args',
					args: [1, 2],
					expect: { x: 1, y: 2, width: 0, height: 0, top: 2, right: 1, bottom: 2, left: 1 }
				},
				{
					name: '3 args',
					args: [1, 2, 3],
					expect: { x: 1, y: 2, width: 3, height: 0, top: 2, right: 4, bottom: 2, left: 1 }
				},
				{
					name: '4 args',
					args: [1, 2, 3, 4],
					expect: { x: 1, y: 2, width: 3, height: 4, top: 2, right: 4, bottom: 6, left: 1 }
				},
				{
					name: '5 args',
					args: [1, 2, 3, 4, 5],
					expect: { x: 1, y: 2, width: 3, height: 4, top: 2, right: 4, bottom: 6, left: 1 }
				},
				{
					name: 'NegativeWidth',
					args: [2, 2, -4, 4],
					expect: { x: 2, y: 2, width: -4, height: 4, top: 2, right: 2, bottom: 6, left: -2 }
				},
				{
					name: 'NegativeHeight',
					args: [2, 2, 4, -4],
					expect: { x: 2, y: 2, width: 4, height: -4, top: -2, right: 6, bottom: 2, left: 2 }
				},
				{
					name: 'NegativeWidthHeight',
					args: [2, 2, -4, -4],
					expect: { x: 2, y: 2, width: -4, height: -4, top: -2, right: 2, bottom: 2, left: -2 }
				},
				{
					name: 'Undefined1',
					args: [0, 0, undefined, 4],
					expect: { x: 0, y: 0, width: 0, height: 4, top: 0, right: 0, bottom: 4, left: 0 }
				},
				{
					name: 'Undefined2',
					args: [NaN, Number.NEGATIVE_INFINITY, Number.POSITIVE_INFINITY, null],
					expect: { x: NaN, y: -Infinity, width: Infinity, height: 0, top: -Infinity, right: NaN, bottom: -Infinity, left: NaN }
				},
				{
					name: 'String1',
					args: ['1', '2', '3', '4'],
					expect: { x: 1, y: 2, width: 3, height: 4, top: 2, right: 4, bottom: 6, left: 1 }
				},
				{
					name: 'String2',
					args: ['a', 'b', 'c', 'd'],
					expect: { x: NaN, y: NaN, width: NaN, height: NaN, top: NaN, right: NaN, bottom: NaN, left: NaN }
				}
			]

		},

		{
			name: 'testSetReadOnlyAttributes',
			//	FIXME: Rewrite for hTest
			// tests: [{
			// 	var r = new DOMRect()
			// 	r.top = 5
			// 	assert_equals(r.top, 0, "Expected value for top is 0")
			// 	r.right = 5
			// 	assert_equals(r.right, 0, "Expected value for right is 0")
			// 	r.bottom = 5
			// 	assert_equals(r.bottom, 0, "Expected value for bottom is 0")
			// 	r.left = 5
			// 	assert_equals(r.left, 0, "Expected value for left is 0")
			// }]
		},
		{
			name: 'testSetAttributes',
		},
		{
			name: 'testReadOnlySetReadOnlyAttributes',
		},
		{
			name: 'testReadOnlySetAttributes'
		}
	],
}]

}
//	MARK: WPT original code ↓ ---------------------------------------
function testConstructor(constructor) {

var prefix = constructor === DOMRect ? 'testConstructor' : 'testReadOnlyConstructor'
test(
	function() {
		checkDOMRect(
			new constructor(),
			{ x: 0, y: 0, width: 0, height: 0, top: 0, right: 0, bottom: 0, left: 0 }
		)
	},
	prefix + '0'
)

test(function() {
	checkDOMRect(new constructor(1),
		{ x: 1, y: 0, width: 0, height: 0, top: 0, right: 1, bottom: 0, left: 1 })
}, prefix + '1')

test(function() {
	checkDOMRect(new constructor(1, 2),
		{ x: 1, y: 2, width: 0, height: 0, top: 2, right: 1, bottom: 2, left: 1 })
}, prefix + '2')

test(function() {
	checkDOMRect(new constructor(1, 2, 3),
		{ x: 1, y: 2, width: 3, height: 0, top: 2, right: 4, bottom: 2, left: 1 })
}, prefix + '3')

test(function() {
	checkDOMRect(new constructor(1, 2, 3, 4),
		{ x: 1, y: 2, width: 3, height: 4, top: 2, right: 4, bottom: 6, left: 1 })
}, prefix + '4')

test(function() {
	checkDOMRect(new constructor(1, 2, 3, 4, 5),
		{ x: 1, y: 2, width: 3, height: 4, top: 2, right: 4, bottom: 6, left: 1 })
}, prefix + '5')

test(function() {
	checkDOMRect(new constructor(2, 2, -4, 4),
		{ x: 2, y: 2, width: -4, height: 4, top: 2, right: 2, bottom: 6, left: -2 })
}, prefix + 'NegativeWidth')

test(function() {
	checkDOMRect(new constructor(2, 2, 4, -4),
		{ x: 2, y: 2, width: 4, height: -4, top: -2, right: 6, bottom: 2, left: 2 })
}, prefix + 'NegativeHeight')

test(function() {
	checkDOMRect(new constructor(2, 2, -4, -4),
		{ x: 2, y: 2, width: -4, height: -4, top: -2, right: 2, bottom: 2, left: -2 })
}, prefix + 'NegativeWidthHeight')

test(function() {
	checkDOMRect(new constructor(0, 0, undefined, 4),
		{ x: 0, y: 0, width: 0, height: 4, top: 0, right: 0, bottom: 4, left: 0 })
}, prefix + 'Undefined1')

test(function() {
	checkDOMRect(new constructor(NaN, Number.NEGATIVE_INFINITY, Number.POSITIVE_INFINITY, null),
		{ x: NaN, y: -Infinity, width: Infinity, height: 0, top: -Infinity, right: NaN, bottom: -Infinity, left: NaN })
}, prefix + 'Undefined2')

test(function() {
	checkDOMRect(new constructor("1", "2", "3", "4"),
		{ x: 1, y: 2, width: 3, height: 4, top: 2, right: 4, bottom: 6, left: 1 })
}, prefix + 'String1')

test(function() {
	checkDOMRect(new constructor("a", "b", "c", "d"),
		{ x: NaN, y: NaN, width: NaN, height: NaN, top: NaN, right: NaN, bottom: NaN, left: NaN })
}, prefix + 'String2')

}
/** Checks x,y,width,height,top,right,bottom, and left values for r. */

function checkDOMRect(r, exp) {

assert_equals(r.x, exp.x, "Expected value for x is " + exp.x)

assert_equals(r.y, exp.y, "Expected value for y is " + exp.y)

assert_equals(r.width, exp.width, "Expected value for width is " + exp.width)

assert_equals(r.height, exp.height, "Expected value for height is " + exp.height)

assert_equals(r.top, exp.top, "Expected value for top is " + exp.top)

assert_equals(r.left, exp.left, "Expected value for left is " + exp.left)

assert_equals(r.bottom, exp.bottom, "Expected value for bottom is " + exp.bottom)

assert_equals(r.right, exp.right, "Expected value for right is " + exp.right)

}
// testConstructor(DOMRect)

// testConstructor(DOMRectReadOnly)
test(function() {

var r = new DOMRect()

r.top = 5

assert_equals(r.top, 0, "Expected value for top is 0")

r.right = 5

assert_equals(r.right, 0, "Expected value for right is 0")

r.bottom = 5

assert_equals(r.bottom, 0, "Expected value for bottom is 0")

r.left = 5

assert_equals(r.left, 0, "Expected value for left is 0")

},'testSetReadOnlyAttributes')

test(function() {

var r = new DOMRect()

r.x = 5

assert_equals(r.x, 5, "Expected value for x is 5")

assert_equals(r.left, 5, "Expected value for left is 5")

assert_equals(r.right, 5, "Expected value for right is 5")

r.y = 5

assert_equals(r.y, 5, "Expected value for y is 5")

assert_equals(r.top, 5, "Expected value for top is 5")

assert_equals(r.bottom, 5, "Expected value for bottom is 5")

r.width = 5

assert_equals(r.width, 5, "Expected value for width is 5")

assert_equals(r.left, 5, "Expected value for left is 5")

assert_equals(r.right, 10, "Expected value for right is 10")

r.height = 5

assert_equals(r.height, 5, "Expected value for height is 5")

assert_equals(r.top, 5, "Expected value for top is 5")

assert_equals(r.bottom, 10, "Expected value for bottom is 10")

},'testSetAttributes')
test(function() {

var r = new DOMRectReadOnly()

r.top = 5

assert_equals(r.top, 0, "Expected value for top is 0")

assert_equals(r.y, 0, "Expected value for y is 0")

assert_equals(r.bottom, 0, "Expected value for bottom is 0")

r.right = 5

assert_equals(r.right, 0, "Expected value for right is 0")

assert_equals(r.x, 0, "Expected value for x is 0")

assert_equals(r.left, 0, "Expected value for left is 0")

r.bottom = 5

assert_equals(r.bottom, 0, "Expected value for bottom is 0")

assert_equals(r.y, 0, "Expected value for y is 0")

assert_equals(r.top, 0, "Expected value for top is 0")

r.left = 5

assert_equals(r.left, 0, "Expected value for left is 0")

assert_equals(r.x, 0, "Expected value for x is 0")

assert_equals(r.right, 0, "Expected value for right is 0")

},'testReadOnlySetReadOnlyAttributes')

test(function() {

var r = new DOMRectReadOnly()

r.x = 0

assert_equals(r.x, 0, "Expected value for x is 0")

assert_equals(r.left, 0, "Expected value for left is 0")

assert_equals(r.right, 0, "Expected value for right is 0")

r.y = 0

assert_equals(r.y, 0, "Expected value for y is 0")

assert_equals(r.top, 0, "Expected value for top is 0")

assert_equals(r.bottom, 0, "Expected value for bottom is 0")

r.width = 0

assert_equals(r.width, 0, "Expected value for width is 0")

assert_equals(r.x, 0, "Expected value for x is 0")

assert_equals(r.right, 0, "Expected value for right is 0")

r.height = 0

assert_equals(r.height, 0, "Expected value for height is 0")

assert_equals(r.y, 0, "Expected value for y is 0")

assert_equals(r.bottom, 0, "Expected value for bottom is 0")

},'testReadOnlySetAttributes')

[DmitrySharabin]

So, currently, to access DOM APIs, you'd need to use the HTML test runner, in a browser. There's an open issue (#74) about being able to use the CLI and run tests in a headless browser, as yes, it's sorely needed.

We already have a draft PR (#92) which adds such functionality to hTest. @Zearin, you might be interested in giving it a try (and even helping us improve it). I started working on it a while ago, and I'm not even sure if it works. It's high time to breathe new life into this PR. 😊