Scripting API#

This is the reference documentation of the scripting API, a TypeScript API that you can use to write browser scripts.

For usage examples, see Browser script examples.

Using the scripting API#

The smartbrowser-core-interactions module provides classes and functions that you can use to implement browser scripts.

You can import those classes and functions from smartbrowser-core-interactions/index.ts. For example:

import { BaseInteraction, Page } from "smartbrowser-core-interactions/index.ts";

Below you can find the reference documentation of the complete scripting API.

BaseInteraction and Page#

BaseInteraction() and Page() are the base of the scripting API.

class BaseInteraction()#

Base class for browser scripts.

abstract

exported from base_classes.Base

BaseInteraction.do(page, args)#

Entry point of a browser script.

Arguments
Returns

Promise<void> –

class Page()#

The webpage currently loaded.

interface

exported from api.page

Page.click(selector)#

Click the first element matching selector.

Arguments
Returns

Promise<void> –

Page.evaluate(source)#

Executes JavaScript code within page context.

Arguments

  • source (string) – string with JavaScript source to be executed in page context

Returns

Promise<any> – Promise that resolves to data returned by the evaluated code, if any.

Page.fetch(url, options)#

Send a request for url within the current browsing context and return a promise that resolves to a FetchResponse() object.

Note that the browsing context may limit what requests can be made, e.g. through CORS.

Arguments

  • url (string) – URL to fetch

  • options (FetchOptions) – Fetch options

Returns

Promise<FetchResponse> – FetchResponse object

Page.getIframe(selector)#

Get the first Iframe matching selector.

Arguments
Returns

Promise<Page> –

Page.goto(url, options)#

Navigate to url.

By default, the returned promise resolves once url loads. See GotoOptions.waitUntil for other options.

Arguments

  • url (string) – Target URL

  • options (GotoOptions) – Navigation options

Returns

Promise<void> –

Page.hide(selector)#

Hide all elements matching selector.

Arguments
Returns

Promise<void> –

Page.hover(selector)#

Hover over the first element matching selector.

Arguments
Returns

Promise<void> –

Page.keyPress(key)#

Press key.

Supported key IDs are:

Key Group

Key

Key IDs

Letters

A

"a", "A", "KeyA"

B

"b", "B", "KeyB"

C

"c", "C", "KeyC"

D

"d", "D", "KeyD"

E

"e", "E", "KeyE"

F

"f", "F", "KeyF"

G

"g", "G", "KeyG"

H

"h", "H", "KeyH"

I

"i", "I", "KeyI"

J

"j", "J", "KeyJ"

K

"k", "K", "KeyK"

L

"l", "L", "KeyL"

M

"m", "M", "KeyM"

N

"n", "N", "KeyN"

O

"o", "O", "KeyO"

P

"p", "P", "KeyP"

Q

"q", "Q", "KeyQ"

R

"r", "R", "KeyR"

S

"s", "S", "KeyS"

T

"t", "T", "KeyT"

U

"u", "U", "KeyU"

V

"v", "V", "KeyV"

W

"w", "W", "KeyW"

X

"x", "X", "KeyX"

Y

"y", "Y", "KeyY"

Z

"z", "Z", "KeyZ"

Digits

0

"0", "Digit0"

1

"1", "Digit1"

2

"2", "Digit2"

3

"3", "Digit3"

4

"4", "Digit4"

5

"5", "Digit5"

6

"6", "Digit6"

7

"7", "Digit7"

8

"8", "Digit8"

9

"9", "Digit9"

Symbols

Ampersand

"&"

Asterisk

"*"

At sign

"@"

Backslash

"Backslash", "\\"

Backtick

"Backquote", "`"

Caret

"^"

Closing brace

"}"

Closing bracket

"BracketRight", "]"

Closing parenthesis

")"

Colon

":"

Comma

"Comma", ","

Dollar sign

"$"

Double quote

'"'

Equal

"Equal", "="

Exclamation mark

"!"

Greater-than sign

">"

Hash

"#"

Interrogation mark

"?"

Less-than sign

"<"

Minus sign

"Minus", "-"

Opening brace

"{"

Opening bracket

"BracketLeft", "["

Opening parenthesis

")"

Percent sign

"%"

Period

"Period", "."

Plus sign

"+"

Semicolon

"Semicolon", ";"

Single quote

"Quote", "'"

Slash

"Slash", "/"

Tilde

"~"

Underscore

"_"

Vertical bar

"|"

Whitespace

Enter

"Enter", "\n"

Space

"Space", " "

Tab

"Tab"

Editing

Backspace

"Backspace", "\r"

Delete

"Delete"

Insert

"Insert"

Navigation

Down arrow

"ArrowDown"

Left arrow

"ArrowLeft"

Page down

"PageDown"

Page up

"PageUp"

Right arrow

"ArrowRight"

Up arrow

"ArrowUp"

Modifier

Alt

"Alt"

Caps Lock

"CapsLock"

Left Alt

"AltLeft"

Left Control

"ControlLeft"

Left Shift

"ShiftLeft"

Right Alt

"AltRight"

Right Control

"ControlRight"

Right Shift

"ShiftRight"

Shift

"Shift"

Numpad

0

"Numpad0"

1

"Numpad1"

2

"Numpad2"

3

"Numpad3"

4

"Numpad4"

5

"Numpad5"

6

"Numpad6"

7

"Numpad7"

8

"Numpad8"

Add sign

"NumpadAdd"

Decimal sign

"NumpadDecimal"

Divide sign

"NumpadDivide"

Enter

"NumpadEnter"

Equal

"NumpadEqual"

Multiply sign

"NumpadMultiply"

Substract sign

"NumpadSubtract"

UI

Break key

"Pause"

Composition

Non-conversion

"NonConvert"

Other

Null

"\u0000"
Arguments

  • key (string) – Key ID.

Returns

Promise<void> –

Page.querySelector(selector)#

Query the DOM for an element matching selector and return first element found.

If no element matches selector, the return value resolves to null.

If multiple elements match selector, only the first element is returned. To get all elements, use querySelectorAll() instead.

This method throws an error if selector is invalid.

Arguments
Returns

Promise<ElementHandle|undefined> – Promise that resolves to an ElementHandle() object for the first element matching selector.

Page.querySelectorAll(selector)#

Query the DOM for all elements matching selector.

If no elements match selector, the return value resolves to [].

This method throws an error if selector is invalid.

Arguments
Returns

Promise<ElementHandle[]> – Promise that resolves to an array of all ElementHandle() objects matching selector.

Page.reload(options)#

Refresh the current page.

Arguments
Returns

Promise<void> –

Page.scrollBottom(options)#

Scroll to given position in a page.

Arguments
Returns

Promise<void> –

Page.scrollTo(options)#

Scroll to a given position in the document.

Arguments
Returns

Promise<void> –

Page.select(selector, values)#

Selects an option in a select element.

Arguments
Returns

Promise<void> –

Page.type(selector, text, delay)#

Type text into the first element matching selector.

Arguments

  • selector (Selector|string) –

    Selector() instance or CSS selector string.

  • text (string) – Input text.

  • delay (number) – Time to wait between key presses in seconds, defaults to 0.

Returns

Promise<void> –

Page.url()#

Returns a string with the URL of the current page.

Returns

Promise<string> – Promise that resolves to the URL of the page.

Page.waitForNavigation(timeout, waitUntil)#

Wait for navigation to finish.

Arguments

  • timeout (number) – Maximum time to wait, in seconds. Defaults to 30 seconds.

  • waitUntil ("load"|"domcontentloaded"|"networkidle0") – When to consider that navigation has finished. One of: "load" (load event, default), "domcontentloaded" (DOMContentLoaded event), or "networkidle0" (no ongoing network connections for at least 0.5 seconds).

Returns

Promise<Response> – Promise that resolves to a Response object.

Page.waitForSelector(selector, timeout)#

Wait for selector to match an item in the DOM.

If there is already a match by the time the method is called, the returned promise resolves immediately.

Arguments

  • selector (Selector|string) –

    Selector() instance or CSS selector string.

  • timeout (number) – Maximum wait time, in seconds. Defaults to 30 seconds.

Returns

Promise<void> –

Page.waitForTimeout(timeout)#

Return a promise that resolves after timeout.

Arguments

  • timeout (number) – Wait time, in seconds.

Returns

Promise<void> –

Selector and ElementHandle#

class Selector()#

Expression that aims to match one or more DOM elements.

interface

exported from api.page

Selector.allElements?#

type: boolean

Whether to match all possible elements (true) or only the first one (false, default).

Selector.state?#

type: “attached”|”visible”|”hidden”

Visibility required for an element to match.

Possible values are:

  • "visible" (default): only visible elements are matched.

    An element is visible if it has a non-empty bounding box and does not have visibility set to hidden.

    Note that elements with display set to none have an empty bounding box, and are hence not considered visible.

  • "hidden": only non-visible elements are matched.

  • "attached": any element may be matched, regardless of its visibility.

Selector.type#

type: “css”|”xpath”

Whether value is a CSS selector expression or an XPath 1.0 expression.

You can find some resources to learn about these selector languages in the parsel documentation.

Selector.value#

type: string

Expression.

class ElementHandle()#

DOM element.

interface

exported from api.page

ElementHandle.getAttribute(name)#

Return the value of the element attribute with the specified name, or null if the attribute does not exist.

Arguments

  • name (string) –

Returns

Promise<string|null> –

ElementHandle.getText()#

Return the text between the element start tag and end tag.

Returns

Promise<string> –

ElementHandle.querySelector(selector)#

Return a nested element matching selector.

Arguments
Returns

Promise<ElementHandle|null> –

FetchResponse#

class FetchResponse()#

Response from Page.fetch().

Its API is a subset of the Response API.

interface

FetchResponse.headers#

type: Record<string, string>

FetchResponse.ok#

type: boolean

FetchResponse.status#

type: number

FetchResponse.statusText#

type: string

FetchResponse.type#

type: string

FetchResponse.url#

type: string

FetchResponse.bytes()#
Returns

Uint8Array –

FetchResponse.json()#
Returns

any –

FetchResponse.text()#
Returns

string –

Option classes#

class FetchOptions()#

Options for Page.fetch().

It is a subset of RequestInit.

interface

FetchOptions.body?#

type: string

FetchOptions.cache?#

type: “default”|”reload”|”no-cache”|”force-cache”|”only-if-cached”

FetchOptions.headers?#

type: Record<string, string>

FetchOptions.method?#

type: “GET”|”POST”|”PUT”|”DELETE”|”PATCH”|”OPTIONS”|”HEAD”

FetchOptions.mode?#

type: “same-origin”|”no-cors”|”cors”

FetchOptions.redirect?#

type: “follow”|”error”|”manual”

FetchOptions.referrer?#

type: string

class GotoOptions()#

Options for Page.goto().

interface

exported from api.page

GotoOptions.timeout?#

type: number

Maximum wait time, in seconds.

Defaults to 30 seconds.

Use 0 to disable the timeout.

GotoOptions.waitUntil#

type: “load”|”networkidle0”

When to consider that navigation has finished.

Possible values:

  • "load" (load event, default).

  • "networkidle0" (no ongoing network connections for at least 0.5 seconds).

class ScrollBottomOptions()#

interface

exported from api.page

ScrollBottomOptions.maxPageHeight?#

type: number

ScrollBottomOptions.maxScrollCount?#

type: number

ScrollBottomOptions.maxScrollDelay?#

type: number

ScrollBottomOptions.timeout?#

type: number

class ScrollToOptions()#

interface

exported from api.page

ScrollToOptions.left?#

type: number

ScrollToOptions.top#

type: number

Special action interactions#

Zyte maintains a set of subclasses of BaseInteraction() that all Zyte API users may use as special actions.

When implementing a custom interaction, instead of extending BaseInteraction(), you can extend one of these special action interaction classes:

class SearchKeywordArgs()#

Argument interface for SearchKeywordInteraction().

interface

exported from base_classes.SearchKeyword

SearchKeywordArgs.keyword#

type: string

Keyword or keywords to search for.

class SearchKeywordInteraction()#

Interaction that uses the search box of a page.

See SearchKeywordArgs() for the interface of the args parameter of the do() method of this class.

abstract

exported from base_classes.SearchKeyword

Extends:

  • BaseInteraction()

SearchKeywordInteraction.keywordCssSelector#

type: Selector|string

Selector() instance or CSS selector string to find the input field where the search keywords must be typed.

SearchKeywordInteraction.typeKeyword(page, keyword)#

Type keyword into the search field on page, start the search, and wait for the results page to load.

Arguments

  • page (Page) – Current page.

  • keyword (string) – Search keywords.

Returns

Promise<void> –

class SetLocation.Address()#

Postal address.

interface

exported from base_classes.SetLocation

SetLocation.Address.city#

type: string

SetLocation.Address.country#

type: string

ISO 3166-1 alpha-2 country code.

SetLocation.Address.postalCode#

type: string

Postal code.

SetLocation.Address.region#

type: string

Country subdivision of relevance for the postal address.

SetLocation.Address.streetAddress#

type: string

Street address.

class SetLocationArgs()#

Argument interface for SetLocationInteraction().

interface

exported from base_classes.SetLocation

SetLocationArgs.address#

type: Address

Postal address.

class SetLocationInteraction()#

Interaction to fill fields on the address form of a page.

See SetLocationArgs() for the interface of the args parameter of the do() method of this class.

abstract

exported from base_classes.SetLocation

Extends:

  • BaseInteraction()

SetLocationInteraction.postalCodeCssSelector#

type: Selector|string

Selector() instance or CSS selector string to find the input field of the postal code.

SetLocationInteraction.typePostalCode(page, postalCode)#

Type postalCode into the postal code field on page.

Arguments
Returns

Promise<void> –

Versioning#

Every new version of the smartbrowser-core-interactions module is backward-compatible, and is automatically made available to every instance of the Zyte IDE, and to code already deployed to Zyte API.

In the future, we may implement a versioning system to make it possible to introduce backward-incompatible changes into the smartbrowser-core-interactions module without breaking existing code.