Browser plugin

Use Browser for user journeys: open a page, fill a form, check the result and capture the screen. Combine its steps with other plugins in the same flow or use dependencies to pass values between flows.

Connect

Select your application collection during onboarding. Use its ID in the target command below.

Install the bundled plugin with reflow init Browser. A supported browser runtime must be installed on the execution machine; init checks available prerequisites. Choose Chromium, Firefox or WebKit through the private connection. The target application must already be running and reachable.

Save a private bindings.json:

{
  "site": {
    "provider": "Browser",
    "configuration": {
      "targetUrl": "http://localhost:3000",
      "browser": "chromium",
      "width": 1280,
      "height": 800
    }
  }
}

Select the application URL and the bindings file:

chmod 600 /absolute/path/to/bindings.json
reflow target http://localhost:3000 --group browser-tests --collection <collection-id> --bindings /absolute/path/to/bindings.json

For direct calls such as site.open, the binding’s targetUrl supplies the base for relative routes. Keep it aligned with the URL selected by reflow target. Absolute site.open URLs do not need a base. Optional device selects an exact Playwright device preset; executablePath selects an installed browser executable. extraHTTPHeaders is a JSON-encoded string of private request headers. Keep credentials out of flows and versioned connection files.

Write a flow

Copy this into a private draft outside your checkout, such as /tmp/team-invitation.md. Adapt the route and selectors to your application; this example expects an invitation form:

---
name: Inspect the invitation form
providers:
  site: Browser
plugins:
  - name: Browser
    sourceCommit: 5852a91f8ba9f4c73585a5984a96117a159c068f
    descriptorDigest: c86d7af94675fed13771b48b5f75f60a4988a2cf4158dd6d211e0f651006e505
---

### Inspect the invitation form

```rfl
site.open url="/settings/team"
site.click selector="[data-testid=invite-member]"
site.expect selector="[data-testid=invitation-form]"
site.snapshot name="team-invitation" selector="[data-testid=invitation-form]" timeout=5000
```

Create the test in the team’s chosen location, then run it:

reflow flows create --name team-invitation --file /tmp/team-invitation.md
reflow plan team-invitation
reflow apply team-invitation
reflow dashboard

The alias site selects the private connection with the same name. The plugin version and descriptor pins above identify its command schema, not its connection.

Commands

Command	Required arguments	Optional arguments	Result
site.open	url string	—	Navigate to an absolute or target-relative URL.
site.click	selector string	timeout number	Click one actionable target.
site.fill	selector, value strings	timeout number	Fill an editable target.
site.expect	selector string	text string, timeout number	Check visibility, or exact text when supplied.
site.snapshot	—	name, selector strings; timeout, settle, threshold numbers	Capture a viewport or one element.
site.evaluate	source string	argument string containing JSON	Run an explicit page function.

Timeouts in these plugin commands use numbers in milliseconds. Assert readiness with expect before taking a snapshot. Direct command selectors are CSS; for RFL’s role, label, text and fallback selectors, see the language reference. The two syntaxes use the same Browser provider but have different argument forms.

The installed descriptor also exposes execute (host-parsed statements), script (legacy TypeScript steps) and session (recorder, mirror and debugger operations). These support host integrations; ordinary flows should use the commands above or RFL browser statements. Use list_plugins for their installed schemas and the MCP reference for interactive browser tools.

Snapshots

The name identifies the checkpoint across runs. selector limits the screenshot to one element and scrolls it into view when needed. Omit it to capture the viewport. The selected element must be visible and have stable bounds. A missing, hidden, invalid or ambiguous selector fails the command; it never falls back to a whole-screen capture. For a scrollable element, the screenshot includes the content visible inside its box.

Snapshot arguments are ordinary named plugin arguments:

site.snapshot name="team-invitation" selector="[data-testid=invitation-form]" timeout=5000 settle=500

timeout bounds finding and capturing the element: five seconds by default, up to 300000 milliseconds, and greater than zero. settle separately waits for finite page animations: two seconds by default, or 0 to skip that wait. settle=0 still requires stable bounds for an element capture. A continuously moving element times out without a screenshot; no animation is frozen or changed. These plugin arguments use numbers in milliseconds. Assert application readiness first; animation settling does not wait for requests or application data.

To use these arguments, install the current CLI and run reflow init. In an existing flow, explicitly refresh each bundled plugin’s sourceCommit and descriptorDigest from the current Plugins page; the bundled plugins share a source revision. The pinned flow examples also show the current values. Initialization installs plugins; it does not rewrite your flow.

Snapshot selectors use native CSS syntax; Playwright engine chains and pseudo-classes such as :visible are not accepted. The timeout default also applies to viewport captures. name identifies the checkpoint. Optional threshold is retained metadata for this plugin invocation; it does not implicitly compare an approved baseline or approve a difference.

Use snapshots and review for before/after evidence and the separate explicit visual assertion contract. A new screenshot is not permission to update an expectation.

Failures and reruns

A missing or ambiguous target, failed assertion or capture timeout fails the step. Inspect the retained outcome before changing the flow. Reflow reconstructs browser state when earlier steps need rerunning; named captures are evidence, not a saved browser login. Browser isolation does not clear your application’s database. See repair and rerun.

Flows using this plugin can be saved in Reflow or in your repository. Read test storage for the team preference, private bindings and the shared plan/apply workflow.