product:ui-audit

Introduction
What it looks for
Configuring it
Looking at one thing
Auditing your production site
Reading the report
Reference
See also

Introduction

product:ui-audit opens every page of your product in a real browser and looks for what tests cannot see, such as a table too wide for a phone or grey text on a dark card.

splent product:ui-audit

  Auditing http://my_first_app_web:5000

     public: 14 pages
     public: light at 1440 done
     ...

  Text too faint to read (1)
     a.card-link #1f6fa3 on #0f1014 3.50:1
       [dark 1440,390] /about  "someone@example.org"

  14 pages measured, 98 measurements.
  Report and screenshots in /workspace/.splent_cache/ui_audit/my_first_app
  The audit found problems.

It fails when it finds anything. It audits the active product, which has to be running, with splent product:up and splent product:run --dev. The browser is the Selenium grid of the product’s development stack.

What it looks for

It walks the links from the first page and opens one page per route, at 1440, 1024, 768, 390 and 320 pixels in the light theme and at 1440 and 390 in the dark one.

Heading	What it means
Pages that answer with an error	A link or a start page answers 404 or a 5xx
Pages wider than the screen	The page scrolls sideways
Leaves the screen	Something passes the edge with nothing to scroll it into view
Cut off by its container	A container hides part of it, without an ellipsis
Overflows the box that holds it	It sticks out of its card, button or table cell
Squeezed to one word per line	Text in a column too narrow to read
A control under something else	A tap on a link or a button would hit what covers it
Text too faint to read	Below 4.5:1, or 3:1 for large text, as WCAG AA asks
A light box on a dark page	A large light background the dark theme did not reach
Pictures that fail or fade away	An image that did not load, or a logo that disappears into its background

Disabled controls may be faint, and text over a picture or a gradient is not judged, because no single colour can be named behind it.

Configuring it

Add a table to the product’s pyproject.toml. Everything in it is optional.

[tool.splent.ui_audit]
start = ["/", "/account", "/admin"]
logins = ["user1@example.com:1234"]
theme_key = "my-theme"
skip = ["/reports/.*/raw"]
ignore = [".code-editor"]

Key	What it does
`start`	Where to begin walking. Name the pages no link leads to.
`logins`	Accounts your seeders create, as `email:password`, to see the pages behind a login.
`theme_key`	The `localStorage` key your product keeps its theme under, so the page draws itself dark. Without it the audit sets `data-bs-theme` on the page already drawn.
`skip`	Regular expressions of addresses not to open. Logout, downloads and anything named delete are never opened.
`ignore`	CSS selectors nobody needs to measure.
`min_contrast`	The ratio text must reach, 4.5 unless you say otherwise.

The table is also what makes product:test run the audit.

Logins are test accounts, so they are only ever used on the development app. Never write the password of a real account here.

Looking at one thing

splent product:ui-audit --width 390 --theme dark
splent product:ui-audit --public-only --max-pages 10
splent product:ui-audit --start /about --max-pages 1

Auditing your production site

splent product:ui-audit --url https://www.example.org

It walks the site as an anonymous visitor and never logs in. The browser has to reach that address from your machine.

Reading the report

The report and a screenshot of every page with a problem are in .splent_cache/ui_audit/<product>/. --screenshots keeps one of every page, which is the quickest way to look over a theme by eye. Screenshot names say who, which theme and which width, such as public_dark_390_about.png.

Reference

Option	Description
`--url <address>`	Audit this address as an anonymous visitor
`--start <path>`	Start from this path instead of the configured ones. Can be repeated
`--width <pixels>`	Only this width, in both themes. Can be repeated
`--theme light\\|dark\\|both`	Which theme to look at. Both by default
`--public-only`	Skip the pages behind a login
`--screenshots`	Keep a screenshot of every page
`--max-pages <n>`	Stop discovering pages after this many, per visitor. 70 by default