Browser

object

An open browser window with its tabs, driven by Selenium (`Sel.start()`) or Playwright (`Play.start()`). Both engines give you the same functions; where they behave differently, the function says so. Page-level functions (`navigate`, `back`, `switchToNextTab`, ...) return the browser itself, so calls can be chained. Work on elements goes through `locator(selector)`, which returns a Locator. **Retries and timeouts.** Every browser action is retried every 100 ms until it succeeds or the timeout has passed. The timeout is the project's Selenium timeout setting in milliseconds (10000 for new projects); `setTimeOut` changes it for this browser. On Selenium only "transient" errors are retried: element not found, click intercepted, element not interactable, stale element, missing frame, window or alert, an unexpected alert, a JavaScript error, and Lua errors such as an unresolved `?Label` selector. Anything else, such as a failed page load, fails at once. On Playwright every error is retried. The same timeout applies to Playwright operations and navigation. **When an action still fails.** By default (`stopOnFailure(true)`) the script stops with an error such as `[click: id=save] Stopped with exception -> no such element ...`. The parameters in the message have secrets masked. A screenshot and the page source are saved with the run's error details, and the browser is closed (it stays open when the run is started with `--debug on-error` or `--debug always`, so you can inspect it). The error can be caught with `pcall`. After `stopOnFailure(false)` no error is raised: locator actions return a result table whose second entry is `false`, and `text`/`attribute`/`property`/`tag` return `nil`. (`exists`, `visible`, `enabled` and `selected` never raise; they return `false` when the element is missing.) Page-level functions such as `navigate` return the browser either way, so a failure there cannot be seen from the return value. Close the browser with `close()` when you are done; `Sel.close()` / `Play.close()` close every browser the library opened.

Kind Object
Used by Play and Sel
Category Browser
Functions 20

How to get one

Sel .start()
Browser

local browser = Sel.start()

Returned by

Leads to

Locator

Functions

navigate self Loads a URL in the current tab and waits for the page's load event.
file self Opens an HTML file from the project in the current tab, as a `file://` URL.
back self Goes back one entry in the history of the current tab.
forward self Goes forward one entry in the history of the current tab.
refresh self Reloads the current page.
url string Returns the URL of the current tab, after any redirects.
source string Returns the HTML of the current page as the browser holds it right now: the live DOM including changes made by scripts, not the response the server sent.
executeJs string | nil Runs JavaScript in the current page and returns the result converted to a string, or nil when the script returns nothing.
close self Closes this browser with all its tabs.
closed boolean Returns true once this browser has been closed, either by `close()` or because an action failed and stopped the script.
locator Locator Creates a Locator for a selector.
l Locator Short alias for `locator`.
cke boolean Replaces the content of a CKEditor 4 editor with HTML.
acceptAlert self Accepts (clicks OK on) an open JavaScript alert, confirm or prompt dialog.
switchToNextTab self Makes the next open tab the current one, wrapping around from the last tab to the first.
switchToPreviousTab self Makes the previous tab the current one, wrapping around from the first tab to the last.
closeTab self Closes the current tab and makes the tab before it current (the next one when the closed tab was the first).
stopOnFailure self Decides what happens when an action still fails after its retries.
autoAcceptAlerts self Switches automatic handling of JavaScript alert, confirm and prompt dialogs.
setTimeOut self Sets how long actions of this browser are retried before they count as failed, in milliseconds.

`navigate()`

browser.navigate(url: string)→self

Loads a URL in the current tab and waits for the page's load event. The URL is used as given, so include the scheme (`https://`). Selenium waits with the WebDriver's default page load timeout; Playwright gives up after the project timeout. A failed load is retried until the timeout (Playwright) or fails at once (Selenium).

Parameters

url string: Absolute URL including the scheme, for example `https://example.com/login`

Returns

self chainable The browser itself, so calls can be chained.

Example

local browser = Sel.start()
browser.navigate("https://example.com")
print(browser.url())
browser.close()

`file()`

browser.file(file: string)→self

Opens an HTML file from the project in the current tab, as a `file://` URL. Use it for local test pages and generated reports. If the file is not in the run's workspace yet, it is fetched from the project on the server first.

Parameters

file string: Path of the HTML file, relative to the project directory

Returns

self chainable The browser itself, so calls can be chained.

`back()`

browser.back()→self

Goes back one entry in the history of the current tab.

Returns

self chainable The browser itself, so calls can be chained.

`forward()`

browser.forward()→self

Goes forward one entry in the history of the current tab.

Returns

self chainable The browser itself, so calls can be chained.

`refresh()`

browser.refresh()→self

Reloads the current page.

Returns

self chainable The browser itself, so calls can be chained.

`url()`

browser.url()→string

Returns the URL of the current tab, after any redirects. This is a plain read: it is not retried, and a browser that has gone away raises an error.

Returns

string

`source()`

browser.source()→string

Returns the HTML of the current page as the browser holds it right now: the live DOM including changes made by scripts, not the response the server sent. The content of shadow roots is not included. On Selenium this is the frame the last element lookup ended in, which is an iframe after an element was found inside one. This is a plain read and is not retried.

Returns

string

`executeJs()`

browser.executeJs(script: string)→string | nil

Runs JavaScript in the current page and returns the result converted to a string, or nil when the script returns nothing. Selenium runs the script as a function body, so write `return document.title` to get a value. Playwright first evaluates the script as an expression (`document.title`) and, when that throws, runs it again as a function body. `return ...` therefore works on both engines, but on Playwright a script that fails at run time executes twice. Numbers and booleans come back as strings (`"42"`, `"true"`). Objects and arrays are not converted to JSON but to their Java text form, so return `JSON.stringify(value)` and decode it with `Json.decode` for structured data. A script that throws is retried until the timeout, so side effects can be repeated. To run a script against one element, use `locator.execute`.

Parameters

script string: JavaScript to run, with `return` for the value you want

Returns

string | nil can be nil The script's result as a string, nil when it returned nothing

Example

local browser = Sel.start()
browser.navigate("https://example.com")
local title = browser.executeJs("return document.title")
print(title)
browser.close()

`close()`

browser.close()→self

Closes this browser with all its tabs. Calling it again, or on a browser that was already closed because an action failed, does nothing.

Returns

self chainable The browser itself, so calls can be chained.

`closed()`

browser.closed()→boolean

Returns true once this browser has been closed, either by `close()` or because an action failed and stopped the script.

Returns

boolean

`locator()`

browser.locator(selector: string)→Locator

Creates a Locator for a selector. Nothing is looked up yet: the element is searched again every time you call a function on the locator. See Locator for the selector syntax, shadow DOM, iframes and `?Label` selectors from `locators.yaml`.

Parameters

selector string: Selector such as `id=username`, `css=.menu a` or `xpath=//button`, or a `?Label` from locators.yaml

Returns

Locator A handle on one element, or a group of elements, on the page, found by a selector.

Example

local browser = Sel.start()
browser.navigate("https://example.com/login")
browser.locator("id=username").fill("alice")
browser.locator("css=button[type=submit]").click()
print(browser.locator("css=h1").text())
browser.close()

`l()`

browser.l(selector: string)→Locator

Short alias for `locator`.

Parameters

selector string: Selector, see `locator`

Returns

Locator A handle on one element, or a group of elements, on the page, found by a selector.

`cke()`

browser.cke(val: string)→boolean

Replaces the content of a CKEditor 4 editor with HTML. It finds the first iframe with the class `cke_wysiwyg_frame`, sets the inner HTML of its `.cke_editable` body and scrolls the editor into view. Returns true on success; failures honour `stopOnFailure`.

Parameters

val string: HTML to put in the editor, for example `<p>Hello</p>`

Returns

boolean True on success, false after a failure when stopOnFailure is off

`acceptAlert()`

browser.acceptAlert()→self

Accepts (clicks OK on) an open JavaScript alert, confirm or prompt dialog. Nothing happens when no dialog is open. You only need this after `autoAcceptAlerts(false)`; by default dialogs are accepted automatically.

Returns

self chainable The browser itself, so calls can be chained.

`switchToNextTab()`

browser.switchToNextTab()→self

Makes the next open tab the current one, wrapping around from the last tab to the first. Does nothing when only one tab is open. Later actions run in the current tab. Playwright switches to a tab opened by the page (a popup or `target=_blank` link) by itself; Selenium stays on the old tab until you switch.

Returns

self chainable The browser itself, so calls can be chained.

`switchToPreviousTab()`

browser.switchToPreviousTab()→self

Makes the previous tab the current one, wrapping around from the first tab to the last. Does nothing when only one tab is open.

Returns

self chainable The browser itself, so calls can be chained.

`closeTab()`

browser.closeTab()→self

Closes the current tab and makes the tab before it current (the next one when the closed tab was the first). Does nothing when it is the only tab; use `close()` to end the browser.

Returns

self chainable The browser itself, so calls can be chained.

`stopOnFailure()`

browser.stopOnFailure()→selfbrowser.stopOnFailure(stop: boolean)→self

Decides what happens when an action still fails after its retries. With `true` (the default) the script stops with an error, a screenshot and the page source are saved and the browser is closed. With `false` no error is raised and the script continues: locator actions return a result table whose second entry is `false`, and `text`/`attribute`/`property`/`tag` return nil. The setting stays in effect for this browser until you change it again. Calling it without an argument is the same as `stopOnFailure(true)`.

Parameters

stop boolean optional: `true` stops the script on a failed action, `false` lets it continue

Returns

self chainable The browser itself, so calls can be chained.

Example

local browser = Sel.start()
browser.navigate("https://example.com")
browser.stopOnFailure(false)
local result = browser.locator("id=cookie-banner-close").click()
if not result[2] then
  print("no cookie banner, continuing")
end
browser.stopOnFailure(true)
browser.close()

`autoAcceptAlerts()`

browser.autoAcceptAlerts()→selfbrowser.autoAcceptAlerts(enabled: boolean)→self

Switches automatic handling of JavaScript alert, confirm and prompt dialogs. When on (the default), an open dialog is accepted by itself: Selenium accepts it before each action, Playwright as soon as it opens. When off, the dialog stays open until you call `acceptAlert()`; on Selenium every action in between fails with an unexpected-alert error, on Playwright the page is blocked. Calling it without an argument is the same as `autoAcceptAlerts(true)`.

Parameters

enabled boolean optional: `true` accepts dialogs automatically, `false` leaves them open

Returns

self chainable The browser itself, so calls can be chained.

`setTimeOut()`

browser.setTimeOut()→selfbrowser.setTimeOut(milliseconds: number)→self

Sets how long actions of this browser are retried before they count as failed, in milliseconds. This is the default for locator waits (`exists`, `visible`, `wait`, ...) too. Without an argument it goes back to the project's timeout setting. Also updates Playwright's per-operation and navigation timeouts.

Parameters

milliseconds number optional: Timeout in milliseconds

Returns

self chainable The browser itself, so calls can be chained.

Example

local browser = Sel.start()
browser.setTimeOut(30000) -- slow page: retry for up to 30 seconds
browser.navigate("https://example.com/report")
browser.locator("id=result").wait()
browser.setTimeOut() -- back to the project default
browser.close()