Page

You can obtain a Page instance using any of these Device methods:

• device.newPage() - Create a new page
• device.listPages() - Get all pages
• device.getPage(pageId) - Get a specific page by ID

Properties

id

The unique identifier for the page (tab) in the browser. This is a number that uniquely identifies the tab.

url

The current URL of the page. Returns an empty string if the page hasn’t loaded any URL yet.

title

The current title of the page. Returns an empty string if the page hasn’t loaded or has no title.

active

Whether this page is currently the active tab in the browser window.

Methods

goto(url[, options])

Navigates the page to the specified URL.

// Navigate to a URL and wait for network to be idle
await page.goto('https://example.com');

// Navigate with custom options
await page.goto('https://example.com', {
    waitForNavigation: 'load' // Wait for load event instead of network idle
});

Options:

• waitForNavigation: When to consider navigation complete
  • 'load': Wait for load event
  • 'domcontentloaded': Wait for DOMContentLoaded event
  • 'networkidle0': Wait for network to be idle (0 connections for 500ms)
  • 'networkidle2': Wait for network to be idle (≤ 2 connections for 500ms)

querySelector(selector)

Finds the first element matching the CSS selector. Returns a Node object that can be used for further interactions.

const element = await page.querySelector('.submit-button');
if (element) {
    console.log('Element found:', element.textContent);
}

querySelectorAll(selector)

Finds all elements matching the CSS selector. Returns an array of Node objects.

const elements = await page.querySelectorAll('li.item');
for (const element of elements) {
    console.log('Item text:', element.textContent);
}

dom()

Returns the DOM of the page as a JSDOM object for ultimate flexibility. This is useful for extracting data by walking the DOM and finding elements manually. Note: This is a read-only view of the DOM, so you cannot trigger events or modify the DOM this way.

const dom = await page.dom();
console.log(dom);

waitForElement(selector[, options])

Waits for an element matching the selector to appear or disappear on the page.

// Wait for an element to be visible
await page.waitForElement('#loading-indicator'); // or the following which is equivalent 
await page.waitForElement('#loading-indicator', { state: 'visible' });

// Wait for an element to be hidden
await page.waitForElement('#loading-indicator', { state: 'hidden' });

// Wait for an element to be attached to DOM
await page.waitForElement('.dynamic-content', { state: 'attached' });

// Wait for an element to be detached from DOM
await page.waitForElement('.old-content', { state: 'detached' });

// Wait with timeout
await page.waitForElement('.dynamic-content', { 
    state: 'visible',
    timeout: 10000 // 10 seconds (default is 5 seconds)
});

Options:

• state: The state to wait for
  • 'visible': Wait for element to be visible (default)
  • 'hidden': Wait for element to be hidden
  • 'attached': Wait for element to be attached to DOM
  • 'detached': Wait for element to be detached from DOM
• timeout: Maximum time to wait in milliseconds (default: 5000)

waitForSelector(selector[, options])

Alias for waitForElement. Waits for an element matching the selector to appear or disappear.

// Wait for a selector to be visible
await page.waitForSelector('.search-results', { state: 'visible' });

// Wait for a selector to be detached
await page.waitForSelector('.loading-spinner', { state: 'detached', timeout: 5000 });

waitForNavigation(condition)

Waits for navigation to complete based on the specified condition.

// Wait for page load event
await page.waitForNavigation('load');

// Wait for network to be idle
await page.waitForNavigation('networkidle0');

// Wait for URL change
await page.waitForNavigation('change');

Conditions:

• 'load': Wait for load event
• 'domcontentloaded': Wait for DOMContentLoaded event
• 'change': Wait for URL change
• 'networkidle0': Wait for network to be idle (0 connections for 500ms)
• 'networkidle2': Wait for network to be idle (≤ 2 connections for 500ms)

click(selector[, options])

Clicks an element that matches the selector.

// Simple click
await page.click('#submit-button');

// Click with navigation wait
await page.click('a.link', { waitForNavigation: 'networkidle2' });

type(selector, text[, options])

Types text into an input element.

// Type into an input field
await page.type('#search-input', 'search query');

// Type with navigation wait (for auto-submit forms)
await page.type('#search-input', 'search query', {
    waitForNavigation: 'networkidle2'
});

focus(selector[, options])

Focuses an element on the page.

await page.focus('#email-input');

hover(selector[, options])

Hovers over an element.

await page.hover('.dropdown-trigger');

press(key[, options])

Presses a keyboard key.

await page.press('Enter');

scroll(x, y[, options])

Scrolls the page by the specified amount.

// Scroll down 500 pixels
await page.scroll(0, 500);

scrollIntoView(selector[, options])

Scrolls an element into view.

await page.scrollIntoView('#bottom-content');

back([options])

Navigates back in the browser history.

await page.back({ waitForNavigation: 'networkidle2' });

forward([options])

Navigates forward in the browser history.

await page.forward({ waitForNavigation: 'networkidle2' });

reload([options])

Reloads the current page.

await page.reload({ waitForNavigation: 'networkidle2' });

activate()

Activates the page (makes it the active tab).

await page.activate();

close()

Closes the page (tab).

await page.close();

Example Usage

Here’s a complete example showing how to use the Page class:

// Create a new page
const page = await device.newPage();

// Navigate to a URL
await page.goto('https://example.com');

// Fill out a form
await page.type('#username', 'myuser');
await page.type('#password', 'mypass');
await page.click('#submit-button', { waitForNavigation: 'networkidle2' });

// Extract some data
const title = await page.evaluate(() => document.title);
console.log('Page title:', title);

// Close the page when done
await page.close();