Scrollcraft
Chapter 13 of 15RO

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.

Chapter 13 of 154 min read

What you will learn

By the end of this chapter
  1. 01Run a release checklist by hand before every launch.
  2. 02Write browser tests with Playwright for load, reveals and reduced motion.
  3. 03Add an automated accessibility audit with axe, and check the keyboard by hand.
  4. 04Catch visual changes with screenshot comparisons, and test on real devices.

01 · Release checklist

0 of 12 done

Ticks are saved in this browser only, so they may reset in a private window.

02 · Ask for evidence

a

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.

Prompt
List every check you actually ran, with the width or tool you used. List every check you could not run and why.
b

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.

c

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

Playwright
a

Install

Playwright drives real Chromium, Firefox and WebKit browsers, on desktop and phone sizes.

bash
npm init playwright@latest
b

Two screen sizes

playwright.config.ts
// 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' },
});
c

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.

site.spec.ts
// 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

axe
a

Automated 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.

bash
npm install -D @axe-core/playwright
a11y.spec.ts
// 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([]);
});
b

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 changes
a

Compare 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.

site.spec.ts
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 feel
1

An iPhone with Safari

Address bar resizing, 100vh versus 100svh, and momentum scrolling behave differently from Chrome.

2

A mid-range Android phone

The device most visitors actually use. If scrolling stutters here, it stutters for them.

3

A mouse wheel and a trackpad

A wheel jumps in steps, a trackpad glides. Smooth scrolling and scrubbed scenes must feel right with both.

4

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 tool

AI 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

Prompt
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

Prompt
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 compare
1

A 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.

2

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.

3

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 course

Make the site for [subject] check itself, so later changes cannot quietly break it.

  1. Go through the release checklist at the top of this chapter.
  2. Run “Set up Playwright”, then “Prove the test can fail”.
  3. Add the axe test, and a screenshot test of the hero with animations disabled.
  4. Test on an iPhone and an Android phone, with the keyboard and with reduced motion.

Practice · Test it

Check the result
  • npx playwright test passes 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 criteria

0 of 4 criteria met

Next Production and launch

Publish a static folder or a Next.js app, connect a domain, add metadata, automate checks, and keep the site healthy.

Keyboard shortcuts: [ previous chapter · ] next chapter