Browser

Version: 1.0.10  ·  ID: zoan-packages-browser  ·  Author: Zoan Software

The Browser package automates a web browser the way a person would: it opens Chrome, Edge, Firefox or Chromium, navigates to a page, clicks, fills out forms, reads text and extracts tables. Under the hood it uses Playwright, a modern and robust web automation engine, but you don’t need to know any of that: you work with visual activities.

It is one of the most used packages, because a large share of business systems (ERP, portals, banking, government) are operated from the browser.

Browser or desktop?

The rule is straightforward: does the application live on a web page or in an installed window?

Use Browser (this package) if…	Use Desktop if…
The system opens in Chrome/Edge (a URL)	The program is installed on Windows (an .exe with its own window)
Web portals, online banking, SaaS, intranets	Desktop ERP, classic accounting systems, terminal apps
You see https://... in the address bar	You open it from the Start menu or a shortcut

If the same process touches both (for example, it reads data from a desktop program and enters it into a web portal), that’s fine: use both packages in the same playbook. For spreadsheets, PDF or email use neither: there are dedicated packages (Excel, PDF, Outlook…).

Before you start

Three concepts come up in almost every activity of this package: the page session (the page parameter), selectors (how you tell the bot which element to act on) and waits (how long each activity waits before failing). We explain them once below; the page of each activity assumes you already know them.

Supported browsers

Open Browser opens the browser you choose in its browser parameter (or the default browser in the project settings):

Value	Browser	Where it is looked up
chrome (default)	Google Chrome installed on the machine	C:\Program Files\Google\Chrome\Application\chrome.exe, the same path under Program Files (x86), or %LOCALAPPDATA%\Google\Chrome\Application\chrome.exe
edge	Microsoft Edge installed on the machine	C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe or the same path under Program Files
firefox	Mozilla Firefox installed on the machine	C:\Program Files\Mozilla Firefox\firefox.exe or the same path under Program Files (x86)
chromium	The Chromium bundled with the package	Nothing needs to be installed

• If nobody chose a browser (neither the activity nor the project) and Chrome is not installed, the bundled Chromium is used automatically. If you pick a browser on purpose and it is missing, the activity fails with a clear message.
• With executablePath you can point to the exact path of another Chromium-based browser (.exe, .bat or .cmd).
• Chrome and Edge open with a clean temporary profile (without the person’s cookies) that is deleted on close, with automatic downloads enabled and PDFs set to download instead of opening in the viewer. To use the person’s real profile, set userDataDir.

Concept 1: the page session (page)

When you open a browser with Open Browser, you get a page session (type ZoanPageSession): an object that represents that open tab. Every page activity (click, fill, read…) needs to know which tab to act on — that’s the page parameter.

There are two ways to work:

Option A — With body (the simplest)

Open Browser (and Attach Browser) have a body sub-flow. Activities placed inside it inherit the session automatically: you don’t need to set the page parameter on any of them. When the body finishes, the browser closes on its own.

Open Browser   browser = chrome   url = "https://example.com"
 └─ body:
      Page Fill    selector = (#usuario)    value = "ana"
      Page Click   selector = (#entrar)
      Page Get Text  selector = (.bienvenida)  → output: saludo

Option B — With an output variable (explicit control)

Open Browser stores the session in an output variable (e.g. page). Each activity then receives page = page, and at the end you close it with Close Browser. Useful when the browser must stay open across several sections of the playbook.

Open Browser   browser = chrome   → output: page
Page Navigate  page = page   url = "https://example.com"
Page Click     page = page   selector = (#entrar)
Close Browser  session = page

Which one do I use?

If all your browser logic happens in one go, use body (Option A): it’s cleaner and closes the browser for you. If you need the browser open throughout a more complex flow (with loops, sub-playbooks, etc.), use the output variable (Option B). In Option A you can turn on keepOpen to keep the session after the body.

Where each activity gets its page from

Page activities (page-*) use, in this order:

1. The session you put in their page parameter.
2. If it is empty, the page of the Open Browser or Attach Browser body that contains them.
3. If there is neither, they fail with 'page' must be a ZoanPageSession.

A ZoanPageSession represents one tab and remembers which browser it belongs to, so any page session also works for Close Browser, New Page and Switch Page. You get sessions for other tabs from New Page, from Switch Page and from Click when you turn on expectNewTab (the tab the click opens).

Concept 2: selectors

A selector tells the bot which element on the page to use (this button, that field). The recommended way to create them is by pointing with the mouse using UI Discover: Zoan Automation captures a robust reference that combines several strategies (first id, then name, aria-label, text… and CSS/XPath as a last resort), so it survives page changes better. You can also write a CSS selector by hand (#usuario, input[name="email"]).

Read this first

Selectors are the core concept of this package. Two dedicated pages are worth reading:

• Selectors — what they are, their attributes, wildcards and expressions so they don’t break, and anchors.
• UI Discover — how to capture them by pointing with the mouse, validate and adjust them.

In this documentation, when we write selector = (#usuario) we mean “the user field”, which you will have captured with UI Discover or written as CSS.

What the selector parameter accepts

Form	Example	How it is resolved
Captured selector (the one UI Discover creates)	(#usuario) in this documentation	Tries its attributes from most stable to most fragile: id, data-testid, name, aria-label, placeholder, text or accessible name (aaname), role, the node’s CSS and, as a last resort, the fallback CSS and the XPath. Supports * wildcards, /pattern/ regular expressions, iframe nodes and anchors.
Hand-written text	#usuario, input[name="email"], text=Save, xpath=//table//tr[2], #menu >> text=Sign out	Passed as-is to the Playwright engine: CSS, text=, xpath= (or a path starting with //) and steps chained with >>.

• A single element: actions (click, fill, read…) require the selector to point to exactly one element. If it matches several, the activity fails and says how many it found; narrow the selector with an index (idx), an anchor or a more specific attribute. Element Exists and the container of Extract Structured Data take the first one without failing.
• Attributes that change on their own: ids generated by the page’s framework (mat-input-0, ember123, :r1:…), hashed classes and state classes (active, is-focused…) are used only as a hint when the selector has something stable next to them. That way a recorded selector keeps working even if those values change between runs.
• With anchors, candidates are evaluated the instant the activity starts: if there are none yet, it fails right away with No elements match the selector, so the anchors cannot be applied. Before it, use Wait For on an element of the same screen that doesn’t use anchors.

Concept 3: automatic waits and timeouts

You don’t need fixed pauses before each step: activities that act on an element wait on their own until it is ready.

Activity	Before acting, it waits for the element to…
Click, Check / Uncheck	exist, be visible, be stable (not animating), be enabled and not be covered by another element; it scrolls it into view if needed
Fill Field	exist, be visible, be enabled and be editable
Type Text, Key Press with a selector	exist on the page (then it focuses it)
Hover	exist, be visible, be stable and not be covered by another element
Select Option	exist, be visible and be enabled
Get Text, Get Value, Get Attribute	exist on the page
Wait For	reach the requested state (visible, hidden, attached or detached)

How long they wait before failing:

Activity	Default timeout
Page activities with a timeout parameter (Click, Fill Field, Type Text, Check / Uncheck, Hover, Select Option, Key Press with a selector, Get Text, Get Value, Get Attribute, Wait For, Navigate, Extract Structured Data)	The activity’s timeout. Empty, 0 or negative: the timeout to find an element from the project settings; if the project doesn’t set one, 30000 ms.
Element Exists	0: immediate check (it doesn’t use the project’s).
Open Browser	90000 ms to start the browser and load the url.
Switch Page	10000 ms looking for the tab.
Click with expectNewTab	newTabTimeout: 15000 ms waiting for the new tab.
Download File, Wait for Download	30000 ms (the request, or for the download to start).
New Page with url, Screenshot of an element, Scroll to an element	No parameter: 30000 ms.

The delays before and after each action defined in the project settings also apply to the activities of this package.

When an action fails

Click, Fill Field, Type Text, Check / Uncheck, Hover, Select Option and Wait For explain the failure in the message itself, without screenshots or page data:

Click failed: Timeout 30000ms exceeded. … | selector: <button> #guardar | matches: 0 (element not found: the page may not have loaded, the element may be inside an iframe, or the selector is outdated)

matches	What it means
0	The element isn’t there: the page hadn’t finished loading, it is inside an iframe the selector doesn’t include, or the selector is outdated.
1	The element is there, but the action didn’t complete: it is hidden, disabled, covered by another element or out of view.
2 or more	The selector is ambiguous: add an index or an anchor to disambiguate.

Before starting, the engine also checks the parameters: if a required one is missing, it fails with [page-click] Required parameter 'selector' not found.; if an options parameter has a fixed value outside its list, with [page-wait-for] Invalid value '…' for 'state'. Allowed: visible, hidden, attached, detached.

Every activity in the package fails with a regular playbook error, so you can wrap them in Try / Catch or retry them with Retry.

Activities

Open and close

Activity	Type	Output	What it does
Open Browser	browser-open	ZoanPageSession	Opens the browser and returns a page session
Attach Browser	browser-attach	ZoanPageSession	Picks up a page session you already have in a variable
New Page	browser-new-page	ZoanPageSession	Opens a new tab in the same browser
Switch Page	browser-switch-page	ZoanPageSession	Takes an already open tab by URL, title or position
Close Page	page-close	—	Closes a tab
Close Browser	browser-close	—	Closes the browser with all its tabs

Navigate and interact

Activity	Type	Output	What it does
Navigate	page-navigate	—	Goes to a URL
Click	page-click	ZoanPageSession	Clicks an element; with expectNewTab, returns the tab it opens
Fill Field	page-fill	—	Writes a value into a field (fast)
Type Text	page-type	—	Types text character by character
Select Option	page-select	—	Chooses an option in a <select>
Check / Uncheck	page-check	—	Checks/unchecks a checkbox or radio button
Hover	page-hover	—	Moves the mouse over an element
Key Press	page-key-press	—	Sends a key or key combination
Scroll	page-scroll	—	Scrolls the page or brings an element into view

Read data

Activity	Type	Output	What it does
Get Text	page-get-text	string	Visible text of an element
Get Value	page-get-value	string	Value of an input/select/textarea
Get Attribute	page-get-attribute	string	Value of an HTML attribute
Element Exists	page-element-exists	bool	Does the element exist and is it visible?
Extract Structured Data	page-extract-table	DataTable	Extracts an HTML table, or any visual grid, into a DataTable

Wait, capture and advanced

Activity	Type	Output	What it does
Wait For	page-wait-for	—	Waits for an element to reach a state
Wait for Download	page-wait-for-download	string	Waits for a download to finish
Download File	page-download-file	string	Downloads a file from a URL using the browser session
Screenshot	page-screenshot	string	Saves a screenshot to a file
Evaluate JS	page-evaluate	object	Runs JavaScript on the page

A typical flow

Open Browser   browser = chrome   url = "https://portal.example.com"
 └─ body:
      Page Wait For  selector = (#usuario)   state = visible
      Page Fill      selector = (#usuario)   value = credential("portal")["user"]
      Page Fill      selector = (#clave)     value = credential("portal")["password"]
      Page Click     selector = (#entrar)
      Page Wait For  selector = (.dashboard) state = visible
      Extract Structured Data   selector = (#tablaMovimientos)   → output: movimientos

Next steps

• Open Browser — the starting point for all web automation.
• Getting started — a guided tutorial that automates a real page.
• Expressions — build URLs and dynamic values.