---
title: "Browser tests"
description: "Simulate real user journeys in Chrome and Edge with browser tests: record or build steps, add assertions, run them on a schedule and get alerts on failures."
section: "Synthetic Monitoring"
breadcrumb: "Synthetic Testing > Browser Testing"
canonical: "https://docs.middleware.io/features/synthetic-monitoring/browser-test"
---
# Browser tests

**Browser Synthetic Monitoring** allows you to simulate real-user interactions with your web applications across various browsers, devices, and locations. These tests ensure your applications are accessible, responsive, and performing as expected under different scenarios. This guide outlines how to configure and utilize Middleware Browser Synthetic Monitoring effectively.

---

## Overview

Browser tests are scenarios executed by Middleware on your web applications. They run at configurable intervals from multiple locations worldwide, across multiple browsers and devices. These tests verify:

- Your application's uptime and response behavior.
- That predefined conditions or assertions are met.

Middleware also supports testing applications behind authentication. If this is relevant, follow the dedicated guide and share feedback with the Middleware Synthetic Monitoring team to enhance support for critical use cases.

---

## Test Configuration

You can create a test using one of the following methods:

### Build a Test from Scratch

If you prefer complete customization, you can start with a blank template:

1. **Starting URL:** Enter the URL where your test scenario begins.
   Example: `https://docs.middleware.io`
2. **Test Name:** Provide a descriptive name for your test.
3. **Environment and Tags:**

   - Specify the environment (e.g., PROD, STAGING).
   - Add additional tags in `<KEY>:<VALUE>` format for filtering and organization.

![Define test name and target URL in Middleware Browser Test setup](/images/synthetics/browser-test/Test Step 1@2x.png)

4. **Browsers and Devices:**
   Select the browsers (e.g., Chrome, Firefox, Edge) and devices (e.g., Laptop Large, Tablet, Mobile Small) to test your application on.

   - Laptop Large: 1440 x 1100 pixels
   - Tablet: 768 x 1020 pixels
   - Mobile Small: 320 x 550 pixels

![Configure test steps and interactions in Middleware Browser Test](/images/synthetics/browser-test/Test Step 3@2x.png)

5. **Test Locations:**

   - Choose from Middleware’s global locations (e.g., Americas, EMEA, APAC) for public-facing tests.

![Configure test steps and interactions in Middleware Browser Test](/images/synthetics/browser-test/Test Step 3@2x.png)

6. **Test Frequency:**
   Configure test intervals (e.g., every 5 minutes, daily, or weekly).
7. **Save and Record:**
   Click `Save & Edit Recording` to save your test and proceed to add steps. You can record steps with the Middleware extension, or [import a recording from Chrome Recorder](#import-from-chrome-recorder).

---

## Advanced Options

### Request Options

- **Disable CORS/CSP:**
  Prevent browser test failures caused by CORS (Cross-Origin Resource Sharing) or CSP (Content Security Policy) restrictions. Enable `Disable CORS` or `Disable CSP` as needed.
- **Request Headers:**
  Add or override default headers. Example: Specify a custom `User-Agent` for your browser tests.
- **Cookies:**
  Add custom cookies in the format `Set-Cookie`. Define one cookie per line.
- **HTTP Authentication:**
  Use Basic, Digest, or NTLM authentication by providing a username and password. Credentials are used in all steps of the test.

![Advanced options for customizing test settings in Middleware Browser Test](/images/synthetics/browser-test/Advanced Options@2x.png)

---

## Alert Conditions

Define the conditions under which a test sends notifications.
For example:

- An alert triggers if a specific assertion fails for `X` minutes in `n` out of `N` locations.
- Retry a failing test `X` times before marking it as failed for a location.
  Use the Middleware API to customize retry intervals or conditions further.

### Notifications

- Customize alert messages using Markdown.
- Specify renotification intervals or disable renotifications.
- Notify specific team members or services using Slack, Gmail, Opsgenie, etc.

---

## Recording Test Steps

Middleware provides tools to record browser interactions as test steps. If you already recorded the journey in Chrome DevTools, you can [import it instead](#import-from-chrome-recorder).

1. **Download Test Recorder Extension:**
   Install the Middleware Test Recorder extension for Google Chrome. Use this link to install the extension.
   Link: [Middleware Synthetic Recorder](https://chromewebstore.google.com/detail/middleware-synthetic-reco/bkkinepabioiaodjjmkiegpmfhdmjfhe)
2. **Start Recording:**
   Use the extension to capture clicks, inputs, and other interactions.
3. **Switch Tabs:**
   Record interactions across tabs for multi-tab user journeys. Middleware automatically replays these steps during execution.
4. **Assertions:**
   End your browser test by adding an assertion to verify that the desired state is achieved (e.g., checking for specific text or an element).
5. **Special Actions:**
   Enhance your test accuracy by incorporating special actions like scroll, hover, and wait. Additionally, use key events to make the test more precise.

![Recording user interactions for test steps in Middleware Browser Test](/images/synthetics/browser-test/Recording Steps@2x.png)

---

## Import from Chrome Recorder

If you've recorded a user journey with the **Recorder** panel in Chrome DevTools, you can import it as the steps of a browser test instead of recording it again. Importing doesn't need the Middleware Synthetic Recorder extension.

For a full walkthrough of the Recorder panel, see Google's [Record, replay, and measure user flows](https://developer.chrome.com/docs/devtools/recorder) guide.

### Export the recording from Chrome

1. In Chrome, open the page where the journey starts and open DevTools.
2. Open the **Recorder** panel. If it isn't visible, open the DevTools **⋮** menu and go to **More tools** > **Recorder**.
3. Click **Create a new recording**, give it a name, and click **Start recording**. Complete the journey in the page, then click **End recording**.
4. Open the **Export** menu on the recording, choose **JSON**, and save the file.

> **Warning:** Choose **JSON** when you export. The **Puppeteer** and **@puppeteer/replay** options produce JavaScript files, which Middleware can't import.

### Import the file into a browser test

1. Create a browser test, or open an existing one, and go to the **Edit Recording Steps** tab.
2. Click **Import JSON** next to **Record Steps**. If the extension isn't installed, or the test has no steps yet, click **Import Chrome Recorder JSON** instead. You can also drag the `.json` file onto the page.

![Import Chrome Recorder JSON button in the empty recorded steps list](/images/synthetics/browser-test/Import Recorder Empty State@2x.png)

3. Drop the file into the dialog, or click to choose it. Middleware lists the steps it found so you can check them before importing.

![Import from Chrome Recorder dialog with a drop zone and export instructions](/images/synthetics/browser-test/Import Recorder Dialog@2x.png)

4. If the test already has steps, choose one:

   - **Replace current steps** removes the existing steps and uses the recording.
   - **Add after current steps** keeps the existing steps and adds the recording to the end.
5. Click **Import** to add the steps, or **Add** if you chose to add after current steps. The steps appear in the recorded steps list, where you can edit, reorder, or delete them like recorded steps.
6. Add assertions, then click `Save` or `Save & Launch`.

### How recorder steps are imported

| Chrome Recorder step | In Middleware |
| --- | --- |
| `navigate` | The first navigate step becomes the test's start URL. Later navigate steps become **Navigate to URL** steps. |
| `click` | A click step, named after the element's accessible name when Chrome recorded one (for example, **Add to cart**). |
| `change` | A **Change value** step that types the recorded value into the field. |
| `keyDown` / `keyUp` | Combined into one **Press Key** step per key press. Modifier keys are kept, so `Meta` + `a` becomes `Meta a`. |
| `doubleClick`, `hover`, `scroll`, `waitForElement`, `waitForExpression` | Imported as the matching step, with the recorded selectors and options. |
| `setViewport` | Not imported. The test runs on the devices you choose under **Browsers & Devices**. |

> **Note:** When you replace the steps, the test's start URL changes to the first URL in the recording. When you add steps after existing ones, the start URL stays the same.

### Troubleshooting imports

- **"This file isn't valid JSON"**: the file was changed or isn't a Recorder export. Export the recording again and choose **JSON**.
- **"No recorder steps found in this file"**: the JSON doesn't contain a `steps` list. This usually means the file is a Puppeteer script or a different JSON file.
- **"This recording only opens a page"**: the recording has no clicks or input. Record the journey again, interacting with the page before you end the recording.
- **Steps fail on the first run**: Chrome Recorder records the selectors your browser saw. If the page differs by location or signed-in state, edit the failing step's selector, or add a **Wait** special action before it.

---

## Best Practices

1. **Global Test Locations:**
   Use Middleware's managed locations to test public websites from key regions (e.g., Americas, EMEA, APAC).
2. **Private Networks:**
   Use private locations to test internal-facing applications securely.
3. **Frequent Testing:**
   Configure tests at shorter intervals for mission-critical applications.
4. **Error Debugging:**
   Use recorded test results, screenshots, and logs to debug issues effectively.

---

## Locations

Middleware supports the following managed locations for public website testing:

- **Americas:**
  Examples: Northern Virginia (AWS), São Paulo (AWS), Northern California (AWS).
- **APAC:**
  Examples: Tokyo (AWS), Sydney (AWS), Mumbai (AWS).
- **EMEA:**
  Examples: London (AWS), Frankfurt (AWS), Cape Town (AWS).