Open Browser

Open Browser

Type: browser-open  ·  Package: Browser v1.0.9  ·  Output: ZoanPageSession

Opens a web browser and returns a page session ready to work with. It is the starting point of all web automation: it is almost always the first browser activity in your playbook.

It uses the browser already installed on the machine (Chrome, Edge or Firefox), with no extra downloads, or the Chromium bundled with the package. With userDataDir you can load the user’s real profile (their cookies and signed-in sessions), handy to skip logins.

How it works

There are two ways to use it (explained in detail in the package introduction):

• With body: the activities inside the sub-flow inherit the session automatically and the browser closes on its own when it finishes, even if something fails inside (unless you turn on keepOpen). The simplest way.
• Without body: store the session in an output variable and pass it to the following activities; you close it with Close Browser.

When opening:

1. It picks the browser: the one in browser; if empty, the default browser from the project settings; if there is none, chrome. If nobody chose one and Chrome is not installed, it uses the bundled Chromium (and notes it in the log). See supported browsers.
2. It decides whether to show a window: the activity’s headless; if empty, the project setting; if there is none, with a window (on a machine without a display, without one).
3. It starts the browser and waits for it to respond, up to timeout.
   • Chrome and Edge open with a clean temporary profile in the system temp folder (zoan-browser-<port>), deleted on close. That profile downloads files without asking and saves PDFs instead of opening them in the viewer, which makes Wait for Download easier.
   • With userDataDir it uses that profile (cookies, sessions, passwords and extensions) and reuses its first tab. The browser must not be open with that same profile.
4. If you set url, it navigates there and waits for the page’s load event (within the same timeout).

Without a window the viewport is 1920×1080; with a window, the page takes the window size.

Required parameters

None. (All are optional: by default it opens Chrome with a blank page.)

Optional parameters

Parameter	Type	Default	Description
browser	string	"chrome"	Browser: chrome · edge · firefox · chromium. chrome, edge and firefox use the one installed on the machine; chromium, the one bundled with the package. Empty: the project setting or, if none, chrome.
url	string	—	URL to navigate to on open. If omitted, the page starts blank.
headless	bool	false	Run without a visible window (background mode). Empty: the project setting; if none, with a window except on machines without a display.
windowState	string	"maximized"	Initial window state (when not headless): maximized · normal · minimized.
timeout	number	90000	Maximum time in ms to start the browser and load url: in unattended sessions the browser takes longer to start. 0 or negative: the default. It doesn’t use the project timeout.
slowMo	number	0	Slows down each operation by N ms (useful for debugging and watching what the bot does).
userDataDir	string	—	Path to the browser profile (e.g. C:\Users\{user}\AppData\Local\Google\Chrome\User Data). Loads real cookies, sessions and passwords. The browser must be fully closed beforehand.
executablePath	string	—	Path to a Chromium-based browser executable (.exe, .bat or .cmd). Takes precedence over browser.
args	List	—	Extra browser launch arguments, e.g. ["--lang=en-US"]. Duplicates are dropped.
keepOpen	bool	false	When using body, keep the browser open when it finishes and return the session as output.

Sub-flows

body

Optional. Activities to run with this browser; they inherit the session without setting page. When it finishes (successfully or with an error) the browser closes, unless keepOpen = true. If omitted, the activity returns the session as output to use in later steps.

Output

A ZoanPageSession that represents the open tab:

Usage	What it returns
Without body	The page session (the browser stays open until Close Browser).
With body and keepOpen = true	The same session, still open, when the body finishes.
With body and keepOpen = false	Nothing: the browser is already closed.

Examples

body mode (recommended):

Open Browser   browser = chrome   url = "https://example.com"   headless = false
 └─ body:
      Page Get Text   selector = (h1)   → output: titulo
      Log             message = "Title: " + titulo

Headless mode with output (for unattended production):

Open Browser   browser = chrome   url = "https://portal.example.com"   headless = true   → output: page
Page Fill      page = page   selector = (#buscar)   value = "invoice 2026"
Close Browser  session = page

Attended vs unattended

While designing, use headless = false to see what the bot does. In unattended production (a server without a display), use headless = true, or set it once in the project settings. Trying it first with slowMo (e.g. 500) helps you follow each step visually.

Loading the real profile (userDataDir)

userDataDir lets you reuse the user’s signed-in session (without logging in again), but the browser must be completely closed before running, or it will fail. For unattended sign-in, a login with secure credentials is a better choice.

Common errors

Message	Cause and fix
chrome not found. Install it or use 'executablePath' to specify the path. (or edge, Firefox)	You chose a browser that isn’t in its standard install paths. Install it, choose another in browser or set executablePath.
Browser executable not found.	The executablePath path doesn’t exist. Fix it.
Extension '.lnk' is not allowed for executablePath. Use .exe, .bat or .cmd.	executablePath points to a shortcut or another file type. Use the path of the .exe.
[browser-open] Invalid value '…' for 'browser'. Allowed: chrome, edge, firefox, chromium.	You typed a value in browser (or in windowState) that isn’t in the list. Choose one of the allowed values.
Unrecognized browser: '…'. Use: chrome, edge, firefox, chromium.	The browser came from an expression or from the project settings with a value that isn’t one of the four allowed.
The browser debugging endpoint (port …) did not respond within 90000 ms: …	Chrome or Edge started but didn’t respond in time, or closed right after opening (the final detail says which). Raise timeout or check that the machine can open the browser.
Could not start the browser process.	Windows didn’t allow the executable to start. Check permissions or antivirus.
Error opening with userDataDir	The profile is in use by an open browser. Close it completely before running.
Timeout 90000ms exceeded while loading url	The page didn’t finish loading in time. Raise timeout, or open without url and navigate with Navigate using another waitUntil.

Related activities

• Navigate — change the URL once it’s open.
• Attach Browser — pick up later a session you already have in a variable.
• Close Browser — close the session (mode without body).
• Project settings — browser and headless mode for the whole project.