docs: Add example for “sequential” testing

[Zearin]

Note about this Issue’s title: I don’t think “sequential” is the right word, but it’s the closest I can think of at the moment.

---

I’m trying to learn hTest by rewriting some tests for DOMRect as specified in the WPT.

Here’s some of those tests (viewable in the link ↑). It demonstrates the “sequential” problem I’m having with the rewrite:

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')

In the above, it’s easy to rewrite the tests for x and y for hTest in isolation:

1. Set someAttribute to a value
2. Check that someAttribute, and its dependents, are equal to the same value

But by the time the tests arrive at width, there’s a problem. This test suite is manipulating a single DOMRect instance. That means that the tests for width are expecting x and y to be 5 (which is why they expect r.right to equal 10).

(That’s what I’m trying to describe when I said “sequential” in the Issue title. hTest’s tests arrays are also “sequential” because, um, they are arrays…but they’re also isolated. Each test in tests is not modifying the result of the previous test.)

How would you rewrite this kind of test structure in hTest?

[Zearin]

Maybe looking at the icky attempt at a rewrite will give some additional context.

Prepare some ugly code! 🫣

hTest (problematic) rewrite:

{

	data: {
		readOnlyAttrs:	['top',	'right',	'bottom',	'left'],
		writeableAttrs:	['x', 	'y',		'width',	'height'],
		dependents: {
			'x':		['left', 'right'],
			'y':		['top', 'bottom'],
			'width':	['left', 'right'],
			'height':	['top', 'bottom'],
		}
	},

	tests: [
		//	DOMRect: Set read-only attributes
		//	( omitted here to focus on the specific tests I mentioned )
		//{ … },

		//	DOMRect: Set attributes
		{
			name: 'testSetAttributes',

			// skip: true,

			tests: ['x', 'y', 'width', 'height'].map( attr => ({

				getName() { return `Setting: ${attr}` },

				run(attr, setToValue) {
					const rect = new DOMRect()
					rect[attr] = setToValue
					return rect
				},

				check(result, expected) {
					// console.debug(this)
					
					const attrsToCheck = [ attr, ...this.data.dependents[attr] ]
					// console.debug({ result, expected, attrsToCheck })

					for (const [idx, attr] of attrsToCheck.entries()) {
						if (result[attr] !== expected[idx]) return false
					}
					return true
				},

				args: [attr, 5],

				// ↓ this weirdness is because of my difficulty rewriting the original in hTest’s structure
				expect: [5, 5, (attr === 'width' || attr === 'height') ? 10 : 5],
			})),
		},
	]
}

[LeaVerou]

Happy new year!

First, I agree we should support something for this, if anything to ease migration. Will need to think how to best expose it though.

But to answer the question of what's the hTest way to do this, I'd say probably beforeAll(). Perhaps something like:

export default {
	run (prop) {
		return this.data.r[prop];
	},
	beforeAll() {
		this.data.r = new DOMRect();
	},
	tests: [
		{
			beforeAll() {
				// I think this.data inherits that way, but you should check to make sure
				this.data.r.x = 5;
			},
			tests: [
				{arg: 'x', expect: 5},
				{arg: 'left', expect: 5},
				{arg: 'right', expect: 5}
			]
		},
		{
			beforeAll() {
				this.data.r.y = 5;
			},
			tests: [
				{arg: 'y', expect: 5},
				{arg: 'top', expect: 5},
				{arg: 'bottom', expect: 5}
			]
		},
		// ...
	],
}

I have not tested it so it could uncover a variety of bugs, but I think the core logic should work.

You could even make the property setting more declarative, though the gains are questionable. Remember the whole point is that tests should be easy to read or write by abstracting away boilerplate that gets in the way, . not DRY for DRY's sake.

[Zearin]

@LeaVerou : That’s a significant improvement over my attempt! Thank you! 🙏🏽

not DRY for DRY's sake.

Of course not.

Honestly, I actually don’t mind the sometimes-necessary repetition of Mocha-style or Node.js-style tests. I found hTest because it offered a way to write front-end tests that looked significantly simpler than any alternative. And the minimalist syntax looked pretty cool, too!

So I guess one could paraphrase the above as, “I came for the front-end tests, but I stayed for the syntax.” :P