How to test a local website with Playwright and pytest

Small sites and digital products break in small, embarrassing ways. A menu link goes nowhere. A form accepts an empty email. A page scrolls sideways on a phone. A download is the wrong version. None of these is hard to find, but they are tedious to check by hand, and nobody checks them on release day. The answer is a test suite that you run before every release, on your own machine, with no third party involved. This guide explains what to test, how Playwright and pytest fit together, what the checks can and cannot show, and how to read a result without fooling yourself.

Why test locally

A local test needs no account and sends nothing over the network. You point it at a folder of HTML files or a development server on your machine, and it opens the pages in a real browser and checks them. That matters for three reasons. Privacy: a draft site, a client's unreleased page or a product that is not announced yet never leaves your computer. Speed: there is no queue and no upload. Repeatability: the same suite runs the same way tomorrow, so a change in the result means a change in the site.

The tools

Playwright is a browser automation library. Its Python documentation describes it as created for end-to-end testing and says it supports all modern rendering engines, Chromium, WebKit and Firefox, on Windows, Linux and macOS, locally or on continuous integration. It can run headless, without a visible window. It recommends the official Playwright pytest plugin for writing end-to-end tests, which provides context isolation and runs on multiple browser configurations. Setup is two commands: install the pytest plugin, then run the command that installs the browsers.

pytest is the Python test runner. A test is a function whose name starts with test, and a fixture is a reusable piece of set-up, such as an open page. Together they let you write short, readable checks that you run with one command.

What to check

A useful pre-release suite covers these groups.

Navigation and links. Every link on every page leads somewhere that exists. Every anchor (a link to a section of a page) matches an element on the target page. Menus work from every page.
Forms. Required fields refuse empty values. A bad email is rejected with a clear message. A good one is accepted. Labels are connected to inputs.
Keyboard use. You can reach and operate controls with the keyboard alone, and the focus is visible.
Mobile viewports. On a narrow window, the page does not scroll sideways and nothing overlaps.
Console errors. The browser console is clean: no failed requests, no script errors.
Images and weight. Images load, and the page and its files stay under a size you decide.
Downloads. The file has the expected name, is a valid ZIP, PDF or image, is within its size limit, and matches the published checksum.
Accessibility basics. Images have alt text, form controls have labels, buttons and links have names, headings are in order, the page declares its language, and text has enough contrast.
Screenshots. A saved picture of each page to compare with the next version. Baselines must be made on your own machine, since fonts and rendering differ between systems.

What automated checks cannot do

Be honest about the limits. The W3C's overview of evaluating web accessibility says plainly that no tool alone can determine whether a site meets accessibility standards, and that knowledgeable human evaluation is required. Automated checks catch certain mechanical faults. They cannot judge whether alt text is useful, whether a heading makes sense, whether the page works with a screen reader, or whether colour contrast is acceptable for text over a picture. Treat them as the first pass, and do the easy manual checks too, such as tabbing through the page and zooming to 200 per cent.

A second limit: a test only checks what it was written to check. A site can pass every test and still be wrong. And a test can fail because the test is wrong. That is why a good suite includes a way to prove that each check can fail.

Prove the checks can fail

The most useful idea in testing is the planted defect. Keep a second copy of your sample site with known faults, such as a dead link, a missing label, an oversized image and a page that overflows on a phone, and make sure that your suite finds every one. If a detector is silent on the broken copy, it is not detecting anything, and silence on your real site means nothing. Run the suite against the clean copy and the faulty copy, and you learn two things: the checks are alive, and the real site is clean.

Downloads and checksums

Many sites sell or distribute files, and the most damaging mistake is a download that is the wrong file. Check four things: that the file name is the one you promised, that the archive opens (a ZIP that opens, a PDF with the right pages, an image of the right size), that its size is within limits, and that its checksum matches your published list.

A checksum is a short fingerprint of the file's bytes. NIST's FIPS 180-4, the Secure Hash Standard, specifies hash algorithms, including SHA-256, whose digests are used to detect whether messages have been changed since the digests were generated. A SHA-256 digest is 256 bits, shown as 64 hexadecimal characters. If the digest of the file you serve equals the digest in your list, the file is the same as the one you recorded. If it differs by a single bit, the digest changes entirely. Be clear about the limit: a checksum shows that a file has not changed. It does not show that the file is safe, and a checksum published next to a file offers no protection if an attacker can change both.

Worked example: reading a result

The numbers are invented. A suite of 307 tests runs against a site before release: 291 pass, 12 fail and 4 are skipped, because they need a baseline that does not exist yet. 291 + 12 + 4 = 307.

Of the tests that actually ran, 291 + 12 = 303, so the pass rate is 291 / 303 x 100 = 96.0 per cent. That figure looks good, and it is the wrong thing to look at. The 12 failures are what matter. One broken download link is worth more attention than 100 passing tests, because a customer will find it. Read the failures one by one, and fix or explain each. The 4 skipped tests need a decision too: make a baseline, or remove the test. A result is ready to ship when every failure is fixed or explained and no skipped test hides a real gap.

A second calculation, for page weight. Suppose your budget for a page is 1.0 MB and the page loads 1.25 MB. That is 0.25 MB over, or 25 per cent more than the budget. Find the largest file, which is often an uncompressed image, and shrink it. Budgets are a choice, not a standard: pick a number that suits your visitors, and keep to it.

Keeping the suite useful

Run it before every release, not only when you remember.
Keep settings in one file: the pages to test, the viewport sizes and the budgets.
Make failures readable. A report that names the page, the element and the problem saves time.
Do not hide failures by loosening a test until it passes. Fix the site, or change the test for a good reason you can write down.
Test on more than one engine if you can, because rendering differs between Chromium, WebKit and Firefox.

Tool that fits

The Local Browser QA Kit (EUR 24, paid once) is a pytest and Playwright suite in Python 3.10 or newer: 25 Python files, with 8 reusable helper modules, 16 test modules and conftest.py, and 307 tests in all. It checks navigation, broken links and anchors, forms, keyboard use, mobile viewports, screenshots against baselines you create, console errors and page weight, download integrity with SHA-256 against a published checksum list, and accessibility basics. It only visits localhost and other local addresses. A sample site and a second site with planted defects prove that each detector works, and every run writes a JSON report with a schema and a Markdown summary. The accessibility checks cover common basics and are not a full audit. Use it in your own and your clients' projects; the kit itself may not be resold or shared.

What to do next

The Local Browser QA Kit is a pytest and Playwright suite with 307 tests for links, forms, mobile layout, console errors, downloads with SHA-256 and accessibility basics. It runs on local addresses only. Python 3.10 or newer; €24 once, and not a full accessibility audit.

See the QA Kit

Questions people ask

Can Playwright test a site on localhost?

Yes. Playwright drives real browser engines (Chromium, WebKit and Firefox) and can open any page you can reach, including a local file or a development server on your own machine. For a site you are building, testing locally before you publish avoids sending half-finished pages anywhere.

Do automated checks prove a site meets WCAG?

No. The W3C says that no evaluation tool alone can determine whether a site meets accessibility standards, and that knowledgeable human evaluation is required. Automated checks find common basics such as missing alt text or labels, and they are worth running, but they are a first pass.

What does a SHA-256 checksum verify?

It shows whether a file's contents have changed. NIST's Secure Hash Standard specifies hash algorithms whose digests are used to detect whether messages have been changed since the digests were generated. A matching checksum means the bytes are the same as when the checksum was made. It does not show that the file is safe or who made it.

Sources

We checked each source on 17 October 2026. If a fact here is out of date, tell us at hello@hiddenway.info.