Switch Page

Switch Page

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

Takes a tab that is already open and returns its page session, so you can keep working on it. It is the activity for tabs the playbook didn’t open: the one that appears when you click a link that opens in another tab, a login pop-up window or a PDF viewer.

How it works

1. Among the open tabs of the same browser, it looks for the one matching url, title or index (at least one is required).
2. If it doesn’t exist yet, it keeps looking (every 200 ms) until timeout runs out: a tab opened by a click takes a moment to appear. With timeout = 0 it looks only once.
3. It brings it to the front (unless you turn off bringToFront) and returns a ZoanPageSession that represents it.

Pass that session as page to the activities that must act on the tab found. If you leave session empty inside the body of Open Browser or Attach Browser, it searches the browser of that body.

How matches are found

• url and title look for text contained in the URL or title, case-insensitive. If you use both, the tab must match both.
• With * the text becomes a pattern that must cover the whole value: "*/invoices*" finds any URL containing /invoices, but "invoices*" only one that starts with invoices.
• index is the position of the tab in opening order, counting from 1. On its own, it counts among all open tabs; together with url or title, it chooses among the matching ones.
• Without index, if several tabs match, the first in opening order is taken.

Required parameters

Parameter	Type	Default	Description
session	ZoanPageSession	—	Any page session of the browser (from Open Browser, Attach Browser, New Page…). The tab is looked up in that same browser. Empty inside a body: the browser of that body.

Optional parameters

Parameter	Type	Default	Description
url	string	—	Matches tabs whose URL contains this text. Supports * as a wildcard.
title	string	—	Matches tabs whose title contains this text. Supports * as a wildcard.
index	int	—	Tab position, starting at 1. Use it alone, or with url/title to choose among several matches.
timeout	int	10000	Maximum time in ms to wait for a matching tab to appear.
bringToFront	bool	true	Brings the tab to the front.

Output

Returns a ZoanPageSession that represents the tab found, tied to the same browser. If no tab matches in time, the activity fails (it doesn’t return an empty value).

Example

A portal link opens an invoice detail in another tab; the total is read and the tab is closed:

Open Browser   browser = chrome   url = "https://portal.example.com"   → output: page
Page Click     page = page   selector = (#verFactura)
Switch Page    session = page   url = "*/invoices/*"   → output: detalle
Page Get Text  page = detalle   selector = (.total)   → output: total
Close Page     page = detalle

Two tabs of the same report are open and you want the second one:

Switch Page   session = page   title = "Sales report"   index = 2   → output: reporte

Without url or title, position rules

Using only index is convenient but fragile: if the user or the website opens another tab, the position changes. When you can, identify the tab by its URL or title. And if the tab is opened by one of your clicks, Click with expectNewTab = true returns it directly.

Common errors

Message	Cause and fix
At least one of 'url', 'title' or 'index' is required.	You didn’t set any search criterion.
No open tab matches the given url + title (3 tab(s) open).	No tab matched before timeout. The message says which criteria you used (url, title, index=N) and how many tabs were open. Check the pattern (remember that with * it must cover the whole value) or raise timeout.
'session' must be a ZoanPageSession or ZoanBrowserSession.	session is empty outside a body, or the variable doesn’t hold a browser session.

Related activities

• Click — with expectNewTab, returns the tab the click opens directly.
• New Page — open a new tab yourself.
• Close Page — close the tab when you’re done.
• Open Browser — get the browser session.