# Browser checks

A browser check opens one of your pages in a real browser in ShipVitals' cloud, on a schedule, and says whether what must be true was: the page loaded in time, a text is on it, nothing went wrong in its console or its own requests. You don't need a runner or CI for it. This guide covers adding a check, previewing it, reading its row, how often it runs on each plan, and the month's runs.

A browser check is data, not code: no script of yours runs in ShipVitals' cloud. To run your own Playwright tests, run them on a machine you pair or in CI: see [Run checks](run-checks.md) and [Send test results and your own metrics](ci-and-push-metrics.md).

## Find it

1. Open the project, then its **Health** tab.
2. Find **Browser checks**, under the uptime checks. It says how many of the month's runs are used, such as "12 of 1,000 cloud browser runs this month", and, before the first check, "No browser checks yet. One opens a page in a real browser on a schedule."

**Add browser check** is there for people who edit the project. **Walk the guides** beside it is a different thing: see [Walk the guides in the cloud](cloud-guide-walks.md).

Where ShipVitals is run without browser checks, Health has no **Browser checks** section. If checks were added before, the section says "Browser checks don't run on this deployment." and has no buttons.

## Add a check

1. Press **Add browser check**. The dialog says **Add a browser check** and "ShipVitals opens the page in a real browser and checks what must be true. No code of yours runs in our cloud." **Run your own Playwright tests** beside it opens [Run checks](run-checks.md).
2. Under **Page**, type the page's whole address, starting with `https://`. "An https:// address."
3. Under **What must be true**:
   - **The page loads in under (seconds)**: 5 to start with, from 1 to 25. The page's load has to finish within it.
   - **This text appears (optional)**: a text that must be on the page, such as "Sign up". Up to 200 characters.
   - **No console errors** (ticked): an error in the page's console, or an uncaught exception, fails the check.
   - **No failed requests to the same site** (ticked): a request to the page's own site that fails or answers with an error fails the check.
4. Under **How often**, choose an interval. Only the intervals your plan runs are offered (see [How often it runs](#how-often-it-runs)). The hint says what it costs and your plan's most often, for example "About 720 runs a month at this interval. Indie runs browser checks every hour at most."
5. Press **Preview run** (see the next section), or go straight on.
6. Press **Save check**. The button says **Saving…**, then the dialog closes and the check's row is under **Browser checks**. Its first run starts within a minute; after that it runs at its interval.

**Save check** stays off until **Page** is an address and the load budget is between 1 and 25 seconds.

## Preview before saving

1. In the dialog, press **Preview run**. It says **Running…** while the page opens. "A preview counts as one run."
2. Under it, **Preview** shows what the check would say now: "Loaded in 1,240 ms" when everything held, or the first condition that failed (see [Read a check's row](#read-a-checks-row)).
3. It shows the browser's timings, **First byte**, **Page ready** and **Loaded**, each in milliseconds, and a screenshot of the page.

Change what must be true and press **Preview run** again until it says what you expect. Nothing is saved until you press **Save check**.

## Read a check's row

Each check has a row with:

- **The screenshot** from its last run, as a thumbnail, passing or not. Before the first run, or when a run took none, the thumbnail says **No screenshot**.
- **The page's address.**
- **How the last run went**, and when:
  - Passing: "Loaded in 1,240 ms" (or **Passing**).
  - Failing: the first condition that failed, in this order:
    - "Stopped: a request went to an address ShipVitals doesn't open"
    - "The page didn't load", or "The page answered 503"
    - "Took longer than 30 seconds" (a run's limit, whatever the budget)
    - "Loaded in 6,320 ms, over its 5,000 ms budget"
    - "“Sign up” wasn't on the page"
    - "2 console errors"
    - "1 failed request to the page's own site"
  - **Couldn't run**: ShipVitals' browser couldn't run the check. That says nothing about the page.
  - **Not run yet** before its first run.
- **Why a scheduled run was skipped**, when one was:
  - "Not run …: ShipVitals doesn't open pages on this host."
  - "Not run …: other checks of this host were running. It runs at its next interval."
- **How often it runs**, such as "Every hour". When your plan runs it less often than it was saved with (after a downgrade, say), it says both: "Every day on this plan (saved as every hour)".

**Remove**, for people who edit the project, deletes the check. If it fails, the row says "The check wasn't removed. Try again."

## How often it runs

The form offers **Every 15 minutes**, **Every hour**, **Every 6 hours** and **Every day**, down to your plan's most often:

| Plan | Most often | Cloud browser runs a month |
|---|---|---|
| Free | Every day | 100 |
| Beta | Every hour | 1,000 |
| Indie | Every hour | 1,000 |
| Studio | Every 15 minutes | 5,000 |
| Agency | Every 15 minutes | 20,000 |

No browser check runs more often than every 15 minutes. The form counts a month as 30 days, so an hourly check makes about 720 runs a month, and a daily one about 30.

## The month's runs

Every run counts toward the workspace's cloud browser runs for the month: each scheduled run and each preview. The line under **Browser checks** says how many are used: "12 of 1,000 cloud browser runs this month". Owners and admins get a notice in the bell as the month's runs run low.

When they're used up, the line becomes:

- "Monthly cloud browser runs used: 1,000 of 1,000. They reset Dec 1, or add 1,000 for $5." On Free and Beta it ends at "They reset Dec 1."
- "Scheduled browser checks pause until then. Your runners and CI keep working."

Scheduled runs start again on the first of next month, or when the workspace owner adds a pack in **Plan & billing**. Until then a preview says "This month's cloud browser runs are used, so a preview can't run."

## What it can't do

- **Run your code.** A check is a page and what must be true of it. Clicking through a flow, signing in or filling a form belongs in your own tests, on a runner or in CI: see [Run checks](run-checks.md) and [Send test results and your own metrics](ci-and-push-metrics.md). To have a browser follow your how-to guides, see [Walk the guides in the cloud](cloud-guide-walks.md).
- **Open private addresses.** The browser opens public `https://` addresses only. A page or redirect that leads to a private, local or cloud-metadata address is stopped, and the check fails with "Stopped: a request went to an address ShipVitals doesn't open". Anything else the page asks for there is stopped too, but doesn't fail the check by itself.
- **Open a blocked host.** A host ShipVitals has blocked can't be previewed or saved: "ShipVitals doesn't open pages on this host."
- **Keep anything between runs.** Each run starts a fresh browser: no cookies, no sign-in, no downloads.
- **Run longer than 30 seconds.**

## When it doesn't work

| The page says | What to do |
|---|---|
| "Browser checks open https:// pages only." | Change **Page** to an `https://` address. |
| "Your plan doesn't run browser checks this often." | Choose a longer interval under **How often**. |
| "This workspace already checks that host three times." | Remove a check of that host, or check another page somewhere else. |
| "ShipVitals doesn't open pages on this host." | Check a page on another host. |
| "That host was checked a moment ago. Try the preview again in half a minute." | Wait half a minute, then press **Preview run** again. |
| "Too many previews. Try again in a minute." | Wait a minute. |
| "This month's cloud browser runs are used, so a preview can't run." | Wait for the month to turn, or have the workspace owner add a pack in **Plan & billing**. |
| "The preview didn't run. Try again." | Press **Preview run** again. |
| "The check wasn't saved. Try again." | Press **Save check** again. |
| The plan's monitor limit, with **Choose a plan** (if you aren't the owner, "Ask …, the owner, to upgrade.") and "Or remove a check to make room." | Remove a check, or have the owner choose a bigger plan. |
| No **Browser checks** section, or "Browser checks don't run on this deployment." | This ShipVitals doesn't run them. Use a runner or CI: see [Run checks](run-checks.md). |
