Mobile Friendliness (mobile-friendliness)

Summary

Renders the target in a mobile viewport and evaluates overflow, tap targets, font sizes, and related UX signals (Playwright).

Classification

• Category: PERFORMANCE
• Plugin id: mobile-friendliness
• Version: 1.1.0
• Target types: WEBSITE, WEBSHOP
• Weight class: MEDIUM
• Risk level: not set on plugin object
• Browser required: Yes (Playwright)
• Tier / group: Tier 2 — Browser (Playwright)

Schedule

• scheduleHints: { defaultInterval: '0 */6 * * *', priority: 5 }
• Prerequisites: None declared on this plugin.

Configurable inputs

Public keys are derived from inputSchema: z.object({ ... }) (underscore-prefixed keys are runtime-only and omitted here).

Field	Notes
timeout	Zod field in inputSchema — see source for defaults, min/max, and .describe().
minTapTarget	Zod field in inputSchema — see source for defaults, min/max, and .describe().
minFontSize	Zod field in inputSchema — see source for defaults, min/max, and .describe().
samplePages	Optional injected pages when Run on other pages is enabled on the target profile.

Multi-page mode

When Run on other pages is enabled, checks up to 5 pages (homepage + 4 samples) in one browser session. Findings use page-specific fingerprints; run score is the worst per-page score.

Runtime / injected config

• None documented beyond standard worker context (target, config, logger, reportProgress). Underscore-prefixed keys are internal.

Checks that produce findings

These checks run inside this plugin during a single test run. They are not separate tests in the database — each becomes a Finding linked to the Run for mobile-friendliness.

Check	Typical severity	Why
Missing viewport meta tag	WARNING	Without width=device-width, mobile browsers scale a desktop layout down — text and controls become unreadable and bounce rates rise.
Horizontal overflow (scrollWidth > innerWidth + 5px)	WARNING	Sideways scrolling hurts usability, counts as a mobile defect in Search, and makes checkout forms error-prone.
Fixed-width body (body width in px exceeds 375px viewport)	WARNING	Pixel-locked layouts break on phones and tablets, blocking responsive reflow even when a viewport meta tag exists.
Small tap targets (interactive element < minTapTarget, default 48px)	INFO if ≤5 issues, WARNING if >5	Undersized buttons and links cause mis-taps, failed conversions, and WCAG 2.5.5 Target Size failures on mobile.
Small fonts (computed size < minFontSize, default 12px)	INFO if ≤5 issues, WARNING if >5	Text below ~12px forces pinch-zoom, hurting readability and accessibility for aging users and outdoor viewing.
Images overflowing viewport (img right edge > viewport + 2px)	WARNING	Oversized images trigger horizontal scroll and break product galleries on narrow screens.

How each check works

1. Browser setup — Playwright opens the target URL in a 375×812 viewport with an iPhone Safari user agent (TesteBot/1.0 appended). Page load uses networkidle (default 30s timeout), then waits 1.5s for layout to settle.
2. In-page evaluation — A single page.evaluate() pass measures viewport meta, document.documentElement.scrollWidth vs innerWidth, body computed width, all interactive elements (a, button, input, etc.), text nodes in common tags, and visible img elements. Up to 20 tap-target and font examples are retained.
3. Finding rules — Each failed dimension emits one aggregated finding (not one per element). Tap-target and font findings escalate from INFO to WARNING when more than 5 distinct issues are found.
4. Artifacts and score — Saves mobile-viewport.png and mobile-checks.json. Run score starts at 100 and deducts: −30 no viewport, −20 overflow, −15 fixed width, up to −15 tap targets (−2 each), up to −10 fonts (−1 each), up to −10 images (−3 each). Run status: failed if any CRITICAL (none emitted today), else warning if any WARNING, else passed.

Caveats and concerns

• Homepage-only — Only the configured target URL is tested; inner pages with different layouts are not crawled.
• Heuristic limits — Tap-target scan skips zero-size elements; font scan deduplicates by size+snippet and skips nested containers; contrast and zoom are not measured.
• False positives — Intentionally tiny icon buttons, carousel dots, or desktop-first designs may trigger tap-target or overflow warnings.
• False negatives — Hidden off-canvas menus, lazy-loaded content after 1.5s, or overflow inside iframes are not detected.
• Requires browser worker — Returns BROWSER_UNAVAILABLE_RESULT when BROWSER_WORKER_ENABLED is not set on the worker.

Source

packages/test-plugins/src/plugins/mobile-friendliness.ts