Browser & Context API

Browser Methods

browser:attach([opts])

async

Returns a Page object.

Option	Type	Default	Description
url	string	about:blank	Initial URL
reuse	boolean	true	Reuse a blank tab if available
browserContextId	string	-	Attach to a specific isolated context

local page = browser:attach()
-- or with options
local page = browser:attach({ url = "https://example.com", reuse = false })

browser:new_context()

async

Creates an isolated session. Returns a Context object.

local ctx = browser:new_context()
local page = ctx:attach("https://example.com")

browser:close()

sync

Closes the browser and kills the process.

browser:close()

browser:get_user_data_dir()

sync

Returns the profile path.

local profile = browser:get_user_data_dir()
log("Profile: " .. profile)

browser:call(method, params)

async

Raw browser-level CDP command.

browser:wait_event(event, [timeout_ms], [predicate])

async

Wait for a browser-level CDP notification.

browser:attach_session(target_id)

async

Attach to an existing target by ID. Returns a session ID.

browser:call_session(session_id, method, params)

async

Call CDP method on a specific session.

browser:wait_session_event(session_id, event, [opts])

async

Wait for session-level events.

---

Context Methods

Returned by browser:new_context().

context.id

The unique string ID of the context.

context:attach([url])

async

Creates a new page within this isolated context.

local ctx = browser:new_context()
local page = ctx:attach("https://example.com")

context:close()

sync

Closes the context and all associated pages.

ctx:close()