Puppeteer is a Node.js library that offers high-level browser automation through an intuitive API. With Catchpoint's Puppeteer test type, you can create multi-step browser transaction tests using Puppeteer.
This article provides several examples to assist you in developing your own Puppeteer scripts for monitoring purposes.
To get the most out of this guide, we recommend having an understanding of CSS Selectors.
Catchpoint-Specific Commands
Catchpoint-specific commands have been added to enhance Puppeteer's capabilities. Here is a list of commands that are exclusively available with Puppeteer in Catchpoint.
Catchpoint.startStep()
Used to create and name a step in your Puppeteer transaction script.
opt_disableAutoMatchRequests(boolean)
Optional parameter that controls the assignment of specific HTTP/S requests to a previous step under certain circumstances in web-browser test monitors. The default value is false.
Syntax:
await Catchpoint.startStep(stepName, [opt_disableAutoMatchRequests<Optional>]);
Example:
await Catchpoint.startStep('1. Homepage');
Catchpoint.username()
This method returns the username value by the credential name saved in the credential library.
Syntax:
Catchpoint.username(LibraryCredentialName);
Example:
const u1 = Catchpoint.username("user1");
Catchpoint.password()
This method returns the password value by the credential name saved in the credential library.
Syntax:
Catchpoint.password(LibraryCredentialName);
Example:
const p1 = Catchpoint.password("user1");
Catchpoint.token()
This method returns the token value by the credential name that is saved in the credential library.
Syntax:
Catchpoint.token(LibraryCredentialName);
Example:
const p1 = Catchpoint.token('token1');
Catchpoint.setTracepoint()
Tracepoints capture strings. This method helps in creating, storing, and updating tracepoints. Read more about Tracepoints and Indicators here.
Syntax:
await Catchpoint.setTracepoint(token, value);
Example:
//Setting Tracepoint
await Catchpoint.setTracepoint("t600", "tracepointValue");
Catchpoint.setIndicator()
Indicators capture numerical values. This method helps in creating, storing and updating indicators. Read more about Tracepoints and Indicators here.
Syntax:
await Catchpoint.setIndicator(token, numericValue);
Example:
//Setting Indicator
await Catchpoint.setIndicator("t600", 20);
Catchpoint.storeGlobalVariable()
This method helps in creating, storing and updating a global variable that can be later consumed using the global variable macro in other tests. Read more about global variables here
Syntax:
await Catchpoint.storeGlobalVariable(value, variableName);
Example:
//Store
await Catchpoint.storeGlobalVariable("google.com", "domain");
${GlobalVariable()}
This macro helps in retrieving the global variable set by Catchpoint.storeGlobalVariable(). Read more about global variables here
Syntax:
${GlobalVariable(variableName)}
Example:
const name1 = ${globalVariable("domain")};
Puppeteer Page Class
Page provides functions to interact with a single tab in the browser. In this section, we will only cover the essential functions. For a complete list of functions, please see the Puppeteer documentation.
Page.goto()
A Puppeteer transaction must have at least one page.goto() command. This is used to load a webpage. It will automatically create a new step in Catchpoint.
Syntax:
await page.goto(URL, options<Optional>);
Example:
// Navigate to 'https://www.google.com/'.
await page.goto('https://www.google.com/');
Page.type()
Used to simulate typing text into an input field or a text area on a web page. Sends a keydown, keypress/input, and keyup event for each character in the text.
Syntax:
await page.type(selector, text, options<Optional>);
Example:
// Type the string 'book' in a textarea element with name “q”.
await page.type('textarea[name="q"]', 'book');
Page.click()
Used to simulate a mouse click on an element specified by a CSS selector, scrolls it into view if needed, and then uses Page.mouse to click in the center of the element. If there's no element matching selector, the method throws an error.
Syntax:
await page.click(selector, options<Optional>);
Example:
// Click on the search button.
await page.click('input[name="btnK"]');
Page.focus()
This method fetches an element using a selector and focuses it. If there's no element matching the selector then the method throws an error.
Syntax:
await page.focus(selector);
Example:
// Focus on the text area.
await page.focus('textarea[name="q"]');
Page.select()
Used to select <option> elements in a <select> dropdown menu. Triggers a change and input event as well. If there is no <select> element matching the selector, the method throws an error.
Syntax:
await page.select(selector, value);
Example:
// Select Apple from the dropdown.
await page.select('#fruits', 'Apple');
Page.waitForNavigation()
Used to wait for a page to load when a new URL is loaded. This method is crucial in scenarios where actions are taken on a page, such as clicking a link or submitting a form that triggers navigation, and you need to ensure the content of the page is loaded before proceeding with the script.
The available parameters are:
timeout- Default timeout is 30,000 ms (30 seconds).
waitUntilload: Waits for the load event, which signifies that the entire page including resources like images and stylesheets is fully loaded.
domcontentloaded: Waits for the DOMContentLoaded event to fire, indicating that the initial HTML has been loaded and parsed.networkidle0: Considers navigation finished when there are no more than 0 active network connections for at least 500 milliseconds.networkidle2: Considers navigation finished when there are no more than 2 active network connections for at least 500 milliseconds.
Syntax:
await page.waitForNavigation([options<Object>]);
Example:
// Wait until no requests are downloading.
await page.waitForNavigation({ waitUntil: 'networkidle0' });
Page.waitForSelector()
Used to wait for a specific element to exist in the DOM of a web page. If the selector already exists, the method will return immediately. If the selector doesn't appear after the timeout period, the function will throw an error.
The available parameters are:
optionstimeout: Maximum time to wait in milliseconds. Defaults to 30,000 (30 seconds). Pass 0 to disable timeout.visible: Boolean. If true, wait for the element to be present in DOM and to be visible, i.e., to not havedisplay: noneor “visibility: hidden” CSS properties. Defaults to false.hidden: Wait for element to not be found in the DOM or to be hidden, i.e. have display: none or visibility: hidden CSS properties. Defaults to false.
Syntax:
await page.waitForSelector(selector, options<Optional>);
Example:
// Wait for a particular element to be loaded.
await page.waitForSelector('textarea[name="q"]');
await page.waitForSelector('textarea[name="q"]', { visible: true });
Page.evaluate()
Allows you to execute JavaScript code within the context of the currently loaded page. This method is crucial for interacting with and manipulating the DOM or extracting data.
Syntax:
await page.evaluate(pageFunction, …args);
Example:
// Extract the page title and store in a variable named “title”.
const title = await page.evaluate(() => { return document.title; });
// Change the elements inner text to "Hello" using JavaScript.
await page.evaluate(() => { document.querySelector("h1"). innerText="Hello"; });
Page.setExtraHTTPHeaders()
It is used to set extra HTTP headers that will be included in all requests initiated by the page. This can be useful for various purposes, including authentication or custom user agents.
Syntax:
await page.setExtraHTTPHeaders(headers);
Example:
// Set the required custom headers.
await page.setExtraHTTPHeaders({
'Authorization': 'Bearer JKFHKJDFHKAJSDO9FAHL',
'User-Agent': 'Mozilla/5.0'
});
Sample Script
Example 1: Google Search
The following script loads google and searches for book. The whole script is written using the Page object, which supports multiple functions that can be used to perform various actions on the page.
// Create 1st Step and name it "1.Homepage".
await Catchpoint.startStep('1.Homepage');
// Navigate to 'https://www.google.com/'.
await page.goto('https://www.google.com/');
// Validate a particular element is loaded.
await page.waitForSelector('textarea[name="q"]');
// Create 2nd Step and name it "2.Enter Search String".
await Catchpoint.startStep('2.Enter Search String');
// Focus on the text area.
await page.focus('textarea[name="q"]');
// Type the string 'book'.
await page.type('textarea[name="q"]', 'book');
// Create 3rd Step and name it "3.Search Result Page".
await Catchpoint.startStep('3.Search Result Page');
// Click on the search button.
await page.click('input[name="btnK"]');
// Wait until no requests are downloading.
await page.waitForNavigation({ waitUntil: 'networkidle0' });
Tips
The following are some essential insights and practical advice to help you optimize your workflow.
Local variables
Local variables can refer to variables defined within the context of a specific function or scope in your script. These variables are used to store temporary data, state, or references to elements that you may want to manipulate or interact with as your script runs.
Example:
// Local Variable to store the URL
const url = 'https://www.example.com';
// Using the local variable navigate to the URL
await page.goto(url);
Use Locators
Utilize the page.locator() function for more reliable element interactions. This reduces failures in tests as locators automatically wait for elements to be visible and can handle multiple matches.
It also supports functions that are like the Page object. A few are listed below:
locator.click();locator.fill('New text');locator.type('Hello');
Example:
// Store the element reference in a variable.
const submitButton = page.locator('button#submit');
// Click the button using the variable.
await submitButton.click();
Unsupported Functions
The following functions are not supported in Catchpoint Puppeteer.
Page Class
Page.browser()Page.browserContext()Page.close()Page.createCDPSession()Page.createPDFStream()Page.pdf()Page. routeFromHAR()Page.screencast()Page.screenshot()Page.screenshot_1()Page.setDefaultNavigationTimeout()Page.setDefaultTimeout()Page.setDragInterception()Page.waitForFileChooser()Page.workers()