Prove nothing covers your embedded player at any scroll position

  • testing
  • playwright
  • accessibility

One of my side projects is a study app built around an embedded third-party video player. The player is the whole point of the page, and the provider’s terms are clear that nothing of mine may sit on top of it. No overlays, no badges, no popups, nothing that hides part of the video.

That is an easy rule to follow on the day you build the page. It is a hard rule to keep. Every new feature is a chance to break it: a sticky header, a toast, a promo link, a “you finished!” banner. Recently I added a small text link to a sister site, and before I shipped it I wanted proof, not a feeling, that the link could never end up over the player.

Here is the test pattern I landed on, and why each part is there.

Why a screenshot check is not enough

My first instinct was a visual check: load the page, take a screenshot, look at it. That catches the obvious case and misses almost everything else.

Overlap bugs are usually conditional. A sticky element only covers the player after you scroll. A banner only appears after an action. A layout that is fine at desktop width wraps on a phone and pushes a footer up into the video. A single screenshot at one size and one scroll position tests one state out of hundreds.

So I wanted a check that is cheap enough to run at every state I care about, and precise enough to tell me exactly which element is in the way.

Two questions, asked in the browser

The check runs inside the page and asks two different questions.

The first is geometric: does any element’s box intersect the player’s box? That catches things that overlap even when they are transparent or currently hidden behind the player.

The second is about what is actually on top: at a grid of points across the player, what element does the browser say is there? If the answer is anything other than the player itself, something is covering it. That catches the case the first question cannot, like a fixed element whose box I would not have thought to check.

export async function playerOverlaps(page: Page) {
	return page.evaluate(() => {
		const player = document.querySelector('[data-testid=player-host] iframe');
		if (!player) throw new Error('player not found');
		const p = player.getBoundingClientRect();
		const hits: string[] = [];

		for (const el of Array.from(document.body.querySelectorAll('*'))) {
			if (el === player || el.contains(player)) continue; // the player and its wrappers
			const r = el.getBoundingClientRect();
			if (r.width === 0 || r.height === 0) continue;
			const w = Math.min(r.right, p.right) - Math.max(r.left, p.left);
			const h = Math.min(r.bottom, p.bottom) - Math.max(r.top, p.top);
			if (w > 0 && h > 0) hits.push(el.tagName.toLowerCase());
		}

		const vw = document.documentElement.clientWidth;
		const vh = document.documentElement.clientHeight;
		for (let i = 1; i < 10; i++) {
			for (let j = 1; j < 10; j++) {
				const x = p.left + (p.width * i) / 10;
				const y = p.top + (p.height * j) / 10;
				if (x < 0 || y < 0 || x >= vw || y >= vh) continue; // off screen right now
				const top = document.elementFromPoint(x, y);
				if (top && top !== player) hits.push(`on top at ${x},${y}`);
			}
		}
		return { hits };
	});
}

A few details that matter:

  • Skip the player’s own ancestors. The wrapper that holds the player obviously overlaps it. Without that contains check, every run fails on the container.
  • Skip zero size elements. Hidden and collapsed elements report empty boxes and would only add noise.
  • Only sample visible points. elementFromPoint returns nothing useful for coordinates outside the viewport, so points that are scrolled off screen are skipped, not counted.
  • Return names, not a boolean. When it fails, I want the failure message to say which element is in the way. A bare false sends me to the debugger.

Ask it at every scroll position

The helper answers the question for one moment. The test’s job is to ask it at all the moments that matter. For scrolling, that means walking the whole page in small steps, plus the very top and the very bottom:

async function expectClearWhileScrolling(page: Page) {
	const max = await page.evaluate(
		() => document.documentElement.scrollHeight - document.documentElement.clientHeight,
	);
	const positions = new Set<number>([0, max]);
	for (let y = 0; y < max; y += 60) positions.add(y);
	for (const y of positions) {
		await page.evaluate((top) => window.scrollTo(0, top), y);
		expect((await playerOverlaps(page)).hits, `scrollY=${y} of ${max}`).toEqual([]);
	}
}

I use a 60 pixel step. It is small enough that a sticky header cannot slip between two samples, and large enough that a long page still runs in a few seconds. The scroll position goes into the assertion message, so a failure reads like “scrollY=480 of 1320”, which is usually all I need to reproduce it.

Then I run the same walk at a few screen sizes: a phone width, a normal laptop, and a short laptop window. The short window was the one I almost skipped, and it is the one most likely to push content up against the player.

Check the states, not just the page

Scrolling covers layout. It does not cover behavior. The new link was only supposed to appear in the footer and on the “session complete” summary, never while a question or its feedback was on screen. So the test walks a full study session, answers every card, and asserts the link is absent at each step. Only after the last card does it check that the link shows up exactly once, then runs the scroll walk again in that final state.

I also assert the boring things about the link itself, because they are the things someone “improves” later:

  • No ancestor has position: fixed or sticky. A plain inline link in normal flow cannot float over anything.
  • There is no dialog on the page.
  • It opens in a new tab with rel="noopener", and screen readers hear “(opens in a new tab)” as part of its name. That last one came out of review, and it is now a test so it stays.

The tradeoffs

This is not free. Walking every 60 pixels at three sizes adds real seconds to the suite, so I run the full walk once per viewport instead of once per browser project. The geometric check can also be stricter than the rule: an element that touches the player’s edge by a pixel will fail. I treat that as a feature. If something is that close to the video, I want to know before the provider does.

The real cost is that it makes the page a little harder to change casually. A designer who wants a floating “next lesson” button will hit a red test. That is the point. The rule was already there; the test just makes it impossible to forget.

The short version

When a rule is “nothing may ever cover this element”, do not test it with one screenshot. Measure overlap in the browser with both box intersection and point sampling, return the names of anything in the way, and ask that question at every scroll step, at a few screen sizes, and in every state where new UI can appear. It is a small helper, and it turns a promise into something CI checks on every pull request.