2.5Browser

What it checks#

A browser monitor opens your site in a real browser and runs a list of steps. It can open a page, click, fill in fields, wait for an element, and check what the page shows. Your plan must include browser monitors. Chapter 7 covers them in full.

When it is up, degraded or down#

Up: every step passed.
Degraded: every step passed, but the run was slow. This happens when it is slower than a slow-response limit set through the API (degradedAfterMs). It also happens when latency anomalies is on and the run was far slower than usual.
Down: a step failed, or the whole script ran out of time.
The dashboard does not offer the slow-response limit for browser monitors. Set it through the API. The latency anomalies box on the edit page does apply.

Configuration#

Dashboard field	Default	Limits and notes
name	Empty	Required. Up to 200 characters, on one line.
check interval	60 seconds	At least 1 second. Your plan's minimum interval still applies: below it the form shows `Your plan checks at most every N seconds`.
timeout	10 seconds	The time the whole script may take.
locations	None (runs from `us-west`)	Choose from the regions shown. The check runs from each one you pick.
on failure — notify	None (all team channels)	Pick channels to limit who is alerted. Shown only when your team has channels.
start url	Empty	Required. A full `http://` or `https://` address.
device	Desktop (default)	Run the check as a phone or tablet. The list comes from the server. If it cannot load, only desktop is offered.
steps	One `goto` step	+ add step adds a `click` step.

Step kinds: goto (url), click (selector), fill (selector and value), wait_for (selector), assert_visible (selector) and assert_text (selector and expected text). A selector names an element on the page, such as #email.

Devices#

Pick a device to run the check as a phone or tablet instead of a desktop browser. The check uses that device's screen size, pixel ratio, touch and user agent.

Web vitals#

Each run records the Core Web Vitals of the page it ended on: LCP, CLS, FCP and TTFB. Open a run in Recent checks to see them. The monitor page also shows the latest run's numbers under the three main figures.

Each number is rated against Google's thresholds:

Metric	Good	Needs improvement	Poor
LCP (largest contentful paint)	2.5 s or less	4 s or less	Over 4 s
CLS (cumulative layout shift)	0.1 or less	0.25 or less	Over 0.25
FCP (first contentful paint)	1.8 s or less	3 s or less	Over 3 s
TTFB (time to first byte)	0.8 s or less	1.8 s or less	Over 1.8 s

A metric the page did not produce is left out, not shown as 0. INP is not measured: it needs a real visitor. Vitals never fail a run.

Assertions supported#

In the dashboard, the assert_visible and assert_text steps are your checks. Through the API you can also add status_code, body, response_time_ms and no_console_errors.

Example#

Step	Selector	Value or text
`goto`		`https://app.acme.io/login`
`fill`	`#email`	`ci@acme.io`
`fill`	`#password`	`${CI_PASSWORD}`
`click`	`button[type=submit]`
`assert_text`	`h1`	`Welcome`

Good to know#

In a fill step, pick a team secret from the secret… list. It works only on the secret's allowed sites.
Through the API, CreateBrowserMonitor takes startUrl and scriptJson, a JSON array of steps written as a string. It also takes device, a name from ListBrowserDevices such as BROWSER_DEVICE_IPHONE_16. Leave it out for desktop. A step's timeout_ms must be a number. A string is saved, but every run fails.
A browser script is up to 256 KiB.
Failed checks keep a screenshot for 14 days (chapter 7).