Testing and QA: prove it works.
A scroll site can look perfect on your laptop and break on a phone, with a screen reader or with motion turned off. Check by hand once, then let tests check it on every change.
What you will learn
By the end of this chapter- 01Run a release checklist by hand before every launch.
- 02Write browser tests with Playwright for load, reveals and reduced motion.
- 03Add an automated accessibility audit with axe, and check the keyboard by hand.
- 04Catch visual changes with screenshot comparisons, and test on real devices.
01 · Release checklist
0 of 12 doneTicks are saved in this browser only, so they may reset in a private window.
02 · Ask for evidence
Do not accept “tested”
AI tools sometimes report checks they did not run. Ask what was run, on which widths, and what was skipped. Then open the page and look yourself.
List every check you actually ran, with the width or tool you used. List every check you could not run and why.Measure, then fix
In Chrome DevTools, the Lighthouse tab gives performance and accessibility scores. Fix the biggest item first and run it again. The Performance tab shows what blocks the main thread while you scroll.
Common mistakes
Opening the file directly instead of through a server. Missing doctype, which breaks Lenis. Page-level scroll snap together with smooth scroll. Parallax offsets that push hero text off a phone screen. will-change on every element. Content hidden by CSS that no script ever reveals. overflow: hidden on the html or body element, which can leave two scroll contexts.
03 · Browser tests
PlaywrightInstall
Playwright drives real Chromium, Firefox and WebKit browsers, on desktop and phone sizes.
npm init playwright@latestTwo screen sizes
// playwright.config.ts
import { defineConfig, devices } from '@playwright/test';
export default defineConfig({
testDir: 'tests',
projects: [
{ name: 'desktop', use: { ...devices['Desktop Chrome'] } },
{ name: 'phone', use: { ...devices['Pixel 7'] } },
],
// serve the folder while the tests run
webServer: { command: 'npx serve -l 3000 .', url: 'http://localhost:3000' },
use: { baseURL: 'http://localhost:3000' },
});Three tests every scroll site needs
No errors on load, every hidden element revealed when you reach it, and a page that still reads with reduced motion.
// tests/site.spec.ts
import { test, expect } from '@playwright/test';
test('loads with no console errors', async ({ page }) => {
const errors: string[] = [];
page.on('console', (m) => m.type() === 'error' && errors.push(m.text()));
page.on('pageerror', (e) => errors.push(e.message));
await page.goto('/');
await expect(page.locator('h1')).toBeVisible();
expect(errors).toEqual([]);
});
test('every reveal becomes visible once scrolled to', async ({ page }) => {
await page.goto('/');
for (const el of await page.locator('.reveal').all()) {
await el.scrollIntoViewIfNeeded();
await expect(el).toHaveClass(/\bin\b/);
}
});
test('reduced motion: content is visible without scrolling effects', async ({ page }) => {
await page.emulateMedia({ reducedMotion: 'reduce' });
await page.goto('/');
await expect(page.locator('.reveal').first()).toHaveCSS('transform', 'none');
});Run them with npx playwright test. Add --ui to watch each step in a browser.
04 · Accessibility audit
axeAutomated checks
axe catches missing labels, low contrast, wrong roles and focus traps. It finds about a third of real problems, so it complements the keyboard test, it does not replace it.
npm install -D @axe-core/playwright// tests/a11y.spec.ts
import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';
test('no accessibility violations', async ({ page }) => {
// check twice: as the page loads (unlit words, content still to come), and after scrolling
// through it once. Finish running transitions first (not endless
// loops, which cannot finish), or contrast is measured mid-fade.
const finish = () => page.evaluate(() => document.getAnimations().filter((a) => a.effect?.getComputedTiming().endTime !== Infinity).forEach((a) => a.finish()));
await page.goto('/');
await finish();
expect((await new AxeBuilder({ page }).analyze()).violations).toEqual([]);
await page.evaluate(async () => {
for (let y = 0; y < document.body.scrollHeight; y += innerHeight / 2) {
scrollTo(0, y);
await new Promise((r) => setTimeout(r, 50));
}
});
await finish();
expect((await new AxeBuilder({ page }).analyze()).violations).toEqual([]);
});By hand
Tab through the whole page: focus is always visible, the order makes sense, nothing gets stuck in a pinned section. Then turn on VoiceOver or NVDA and listen to the first screen.
05 · Screenshot comparisons
Catch visual changesCompare against a saved picture
The first run saves a screenshot; later runs fail when the page looks different. Freeze animations so the picture is the same every time.
test('the hero looks the same as last time', async ({ page }) => {
await page.goto('/');
// animations are frozen at their end so the picture is stable
await expect(page).toHaveScreenshot('hero.png', { animations: 'disabled' });
});Update the saved pictures on purpose with npx playwright test --update-snapshots, after you have looked at the difference.
06 · Real devices
What tests cannot feelAn iPhone with Safari
Address bar resizing, 100vh versus 100svh, and momentum scrolling behave differently from Chrome.
A mid-range Android phone
The device most visitors actually use. If scrolling stutters here, it stutters for them.
A mouse wheel and a trackpad
A wheel jumps in steps, a trackpad glides. Smooth scrolling and scrubbed scenes must feel right with both.
Keyboard and reduced motion
Space, Page Down and the arrow keys must scroll. Turn on reduced motion in the system settings and read the whole page once.
Practice · Work with AI
The same task in your toolAI writes tests quickly, including tests that always pass. Ask it to show you each test failing before it passes.
Open a terminal in the project folder and run claude. Press Shift+Tab until plan mode is on, paste the prompt, read the plan, then approve it. Project rules go in CLAUDE.md.
Set up Playwright
Read CLAUDE.md. Set up Playwright for the site for [subject] with a desktop and a Pixel 7 project and a webServer that serves the folder on port 3000. Add three tests: no console errors on load; every .reveal element gets the in class once scrolled to; with reduced motion, reveals have no transform. Run them and show me the output.Prove the test can fail
For each test you wrote, break the page on purpose so that test fails, run it, show me the failure, then undo the break. If a test cannot fail, rewrite it.Open a terminal in the project folder and run gemini; the first time, it asks whether you trust the folder, so say yes for your project. Paste the prompt. Gemini CLI asks before it edits a file or runs a command: read each request before you accept it. Project rules go in GEMINI.md.
Set up Playwright
Read GEMINI.md. Set up Playwright for the site for [subject] with a desktop and a Pixel 7 project and a webServer that serves the folder on port 3000. Add three tests: no console errors on load; every .reveal element gets the in class once scrolled to; with reduced motion, reveals have no transform. Run them and show me the output.Prove the test can fail
For each test you wrote, break the page on purpose so that test fails, run it, show me the failure, then undo the break. If a test cannot fail, rewrite it.Open a terminal in the project folder and run codex, then paste the prompt and approve each change. In the ChatGPT app without Codex, attach the files, paste the prompt and copy the changes back yourself. Project rules go in AGENTS.md.
Set up Playwright
Read AGENTS.md. Set up Playwright for the site for [subject] with a desktop and a Pixel 7 project and a webServer that serves the folder on port 3000. Add three tests: no console errors on load; every .reveal element gets the in class once scrolled to; with reduced motion, reveals have no transform. Run them and show me the output.Prove the test can fail
For each test you wrote, break the page on purpose so that test fails, run it, show me the failure, then undo the break. If a test cannot fail, rewrite it.Practice · Exercises
Try first, then compareA test that cannot fail
What is wrong with expect(await page.locator('.reveal').count()).toBeGreaterThanOrEqual(0)?
Hint: can a count ever be negative?
Show the solution
It always passes, so it proves nothing. Test the behaviour instead: scroll each reveal into view and expect it to have the in class.
What axe cannot see
Name two accessibility problems that an automated audit will not find on a scroll site.
Hint: think about order and movement.
Show the solution
For example: a pinned section that traps keyboard focus, a focus order that jumps around the page, motion that is too fast or too large, and text that reads in the wrong order to a screen reader. They need a keyboard and a screen reader.
Stable screenshots
Your screenshot test fails on every run although nothing changed. Why?
Hint: what on the page moves by itself?
Show the solution
Animations, a marquee, a particle canvas or a date. Use animations: 'disabled', hide or mask moving parts with the mask option, and wait for fonts before taking the picture.
Practice · Course project
One site, built across the courseMake the site for [subject] check itself, so later changes cannot quietly break it.
- Go through the release checklist at the top of this chapter.
- Run “Set up Playwright”, then “Prove the test can fail”.
- Add the axe test, and a screenshot test of the hero with animations disabled.
- Test on an iPhone and an Android phone, with the keyboard and with reduced motion.
Practice · Test it
Check the resultnpx playwright testpasses on desktop and phone.- Each test fails when the behaviour it checks is broken on purpose.
- The axe test reports no violations.
- The screenshot test passes twice in a row without changes.
Practice · Assessment
Acceptance criteria0 of 4 criteria met