toolkit

Scenario · Content and search

Set up or change a popup

“Can we get a popup for the current offer?”

A popup is a form, a promotion, a layout risk, and a performance cost all bundled into one component — and it's the piece of a page most likely to only ever get checked on a desktop browser, even though it's the one that can make a phone unusable when it goes wrong. This confirms the popup actually renders rather than showing a blank, unclosable overlay, checks that its close button is genuinely reachable on a real phone screen, and verifies its form actually submits — because a popup nobody can dismiss on mobile is an exit, not an offer.

What to ask for

Embed health checkThird-party embed health check — renders the page and asks one question per embed: did it actually paint anything? An Instagram feed, review widget, booking iframe or chat bubble that renders an empty container is invisible in the delivered HTML and visible only to the client.Form submittabilityDrives a rendered page to prove its primary form can be submitted.Layout / front-end QAFront-end / layout QA for a live page — measures the rendered DOM across device presets and flags objective layout defects: horizontal overflow, tap targets too small, text below the legible floor, skipped heading levels, DOM bloat, interactive elements whose contrast passes at rest but fails on hover or focus, a mobile nav toggle that reveals nothing, and viewport meta defects (missing or blocking zoom).Performance (Core Web Vitals)Core Web Vitals and performance scan for a live page.Promo expiry scannerPromotional expiry scanner — finds date-bearing promo copy on a page and grades what is past its date: "Holiday Specials" still up in August, "Offer ends 12/31/2025" in 2026.ScreenshotsCapture multi-device screenshots of any URL from the command line — one PNG per device preset (iPhone → Desktop 4K), headless, on a Playwright core.

See it work

A real run of Embed health check:

FAIL
      [error] Instagram feed (instagram) rendered empty: it laid out at 0×0px — nothing visible was returned
        empty    Instagram feed 0×0

  report: ./out/embed-health-check-embed-health-check.html
  text:   ./out/embed-health-check-embed-health-check.txt

The captured report, exactly as a run hands it to a client —open the full report ↗

A popup is a form, a promotion, a layout risk and a performance cost in one component, and it is the element most likely to be verified on a desktop browser and nowhere else. It is also the one that makes a mobile page unusable when it goes wrong, because a close button off-screen is not a cosmetic fault.

  1. Get the offer’s end date, and the frequency rule. A popup advertising an expired special is worse than no popup. Put the date in the visible copy so the promo expiry scan can find it later, and agree how often a visitor should see this before it stops.
  2. [manual] Build the popup. Content, trigger, frequency cap, and the form if it carries one. Publish and purge.
  3. Check it renders at all. The embed health check catches the popup container that loads and stays empty — common when a popup tool’s script is deferred or blocked by consent tooling. An empty modal is a grey overlay with no way out.
  4. Submit its form, if it has one. The submittability check exercises it properly. A popup form is the least-tested form on any site and frequently the one collecting the most leads.
  5. Check the layout on a phone, deliberately. The layout check plus screenshots across devices. What you are looking for is the close button: inside the viewport, reachable by thumb, and reachable by keyboard. A popup that cannot be dismissed on a phone is an exit, not an offer.
  6. Re-measure performance. Popup tools are frequently heavy and load on every page whether they fire or not.
  7. Run the promo expiry scan so this popup is registered as dated content with a findable end date, which is what stops it becoming next season’s stale-content ticket.

The close button is the whole safety check

Everything else about a popup being wrong costs a conversion. A close button a mobile visitor cannot reach costs the session, and the visitor’s opinion of the practice. It is the one thing in step 5 worth checking by hand as well as by tool.

What this does not cover

Whether a popup is a good idea, and how often it should appear. Frequency capping, trigger timing and suppression rules live in the popup tool's own settings and are invisible from the outside — a popup that fires on every page load for every visitor looks identical to a well-behaved one in every check here. Nothing here can tell you a popup is hurting conversions either; that needs analytics over time, not a page audit.

← All scenarios