src/core/browser

Search:
Group by:

This module contains procedures for the Browser object type. The Browser object is used to interact with a Chrome browser instance, create new tabs, register and listen for CDP events, etc.

Procs

proc addGlobalEventCallback(browser: Browser; event: ProtocolEvent;
                            cb: EventCallback) {....raises: [], tags: [],
    forbids: [].}

Adds a callback function to the global event table for the specified event. The callback function will be called when the specified event is received.

Remove the callback via deleteGlobalEventCallback when it is no longer needed.

Note: Currently, there can only be one callback function per event in the global event table.

proc addSessionEventCallback(browser: Browser; sessionId: SessionId;
                             event: ProtocolEvent; cb: EventCallback) {.
    ...raises: [KeyError], tags: [], forbids: [].}

Adds a callback function to the session event table for the specified event. The callback function will be called when the specified event is received.

Remove the callback via deleteSessionEventCallback when it is no longer needed.

Note: Currently, there can only be one callback function per event, per session in the session event table. Meaning, for example, if you have two tabs open and you want to listen for the Page.loadEventFired event on both tabs, you can have two separate callback functions, on the same event, one for each tab (using the tab's sessionId).

proc close(browser: Browser): owned(Future[void]) {....stackTrace: false,
    raises: [Exception], tags: [RootEffect, WriteIOEffect, ReadIOEffect,
                                TimeEffect, WriteDirEffect, ReadDirEffect],
    forbids: [].}
Closes the browser instance, closes the websocket connection, deletes the user data directory, and terminates the Chrome process (if it is still running). 
proc deleteGlobalEventCallback(browser: Browser; event: ProtocolEvent) {.
    ...raises: [], tags: [], forbids: [].}
Removes the callback function from the global event table for the specified event. 
proc deleteSessionEventCallback(browser: Browser; sessionId: SessionId;
                                event: ProtocolEvent) {....raises: [KeyError],
    tags: [], forbids: [].}
Removes the callback function from the session event table for the specified event. 
proc launchBrowser(userDataDir = ""; portNo = 0; headlessMode = HeadlessMode.On;
                   chromeArguments: seq[string] = @[]): Future[Browser] {.
    ...stackTrace: false, raises: [Exception, ValueError], tags: [ReadEnvEffect,
    ReadIOEffect, WriteDirEffect, ReadDirEffect, ExecIOEffect, RootEffect,
    WriteIOEffect, TimeEffect], forbids: [].}

Launches a new Chrome browser instance and returns a Browser object.

userDataDir parameter can be used to specify a directory where the browser's user data will be stored. If an empty string is passed, a temporary directory will be created and used.

portNo parameter can be used to specify a port number for the browser to listen on. If portNo is 0, chrome will choose a random port.

headlessMode parameter can be used to specify whether the browser should be launched in headless mode or not. HeadlessMode.On (the default) will launch the new version of Chrome headless mode (for Chrome >= v112). Use `HeadlessMode.Legacy` to launch the browser in headless mode for Chrome < v112. The new headless mode is recommended as the old version of headless mode will be deprecated, and the new version is the actual browser rather than a separate browser implementation.

chromeArguments parameter can be used to pass additional arguments to the Chrome browser instance. For a list of all available arguments, see: https://peter.sh/experiments/chromium-command-line-switches/ or https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/node/ChromeLauncher.ts for a list of arguments used by Puppeteer.

The following command-line arguments are always passed to Chrome:

  • --remote-debugging-port=<portNo>
  • --user-data-dir=<userDataDir>
  • --no-first-run
  • --headless=new or --headless (if headlessMode is HeadlessMode.On (default) or HeadlessMode.Legacy)
proc newTab(browser: Browser): Future[Tab] {....stackTrace: false,
    raises: [Exception, ValueError],
    tags: [RootEffect, WriteIOEffect, ReadIOEffect, TimeEffect], forbids: [].}
Creates a new tab (Page) in the browser instance and returns a Tab object. 
proc waitForGlobalEvent(browser: Browser; event: ProtocolEvent): Future[JsonNode] {.
    ...stackTrace: false, raises: [Exception, ValueError], tags: [RootEffect],
    forbids: [].}

Returns a Future that completes when the specified global event is received.

Note: This procedure will override the callback function in the global event table if one already exists for the specified event..

proc waitForSessionEvent(browser: Browser; sessionId: string;
                         event: ProtocolEvent): Future[JsonNode] {.
    ...stackTrace: false, raises: [Exception, ValueError], tags: [RootEffect],
    forbids: [].}

Returns a Future that completes when the specified session event is received.

Note: This procedure will override the callback function in the session event table if one already exists for the specified event.


Made with Nim. Generated: 2024-04-04 04:59:47 UTC