



# Playwright

Module with advanced functionalities for the browser that uses Playwright instead of Selenium

*Read this in other languages: [English](Manual_Playwright.md), [Português](Manual_Playwright.pr.md), [Español](Manual_Playwright.es.md)*

![banner](imgs/Banner_Playwright.jpg)
## How to install this module

To install the module in Rocketbot Studio, it can be done in two ways:
1. Manual: __Download__ the .zip file and unzip it in the modules folder. The folder name must be the same as the module and inside it must have the following files and folders: \__init__.py, package.json, docs, example and libs. If you have the application open, refresh your browser to be able to use the new module.
2. Automatic: When entering Rocketbot Studio on the right margin you will find the **Addons** section, select **Install Mods**, search for the desired module and press install.

## How to use this module
This module is an alternative to the other web modules like WebPro where instead of using the Selenium library, it uses the Playwright library.

1. The modules depedencies are not included in the module, and they will be automatically downloaded in the libs folder after using any command for the first time.

2. If the dependencies are updated in a future version of the module, the user will need to run the command "Check Libraries" with the force download option enabled to download the updated dependencies.

3. The Playwright library may not work if the user opens a new tab manually or uses the "Click on object" command to click a button or link that opens a new tab. We recommend using the "Click link to new tab" command to click on such buttons or links. If any webpage opens a new tab without even clicking, it is recommended to use the "Wait For Object" command to update Playwright's state.

4. It is recommended to always close the browser using the "Close 
Browser" command to avoid possible issues when reusing a profile folder or a session.

5. To click on buttons or links that will download a file, it is necessary to use the "Download" command. Without this command, it will be impossible to download files.

6. To interact with an element inside a ShadowRoot, it is necessary to interact with it using the `CSS` selector type. To obtain such selector, you need to right click on the element in the webpage's html, select the Copy option and then Copy selector.

## About the Open Chrome command:
1. The command "Open Chrome" will open a new instance of the Chrome browser. A temporary profile folder will be created for each session the users opens without specifying a profile folder, and it will be deleted when the session is closed. This means that any data, such as cookies or browsing history, will not be saved after the session ends.

2. The command can only open an instance of the Chrome browser per each profile folder, so if you want to 
open multiple instances of the Chrome browser, you will to open each instance with a different profile folder. The browser may need a few seconds after closing to be able to use a profile folder that was previously in use.

## About using commands from other Web modules in the browser:
1. It is possible to use commands from other Web modules like WebPro or the native Web module, using the "Take Playwright" command from WebPro. This command allows such web modules to connect to the port set in Open Chrome's Debugging Port.

2. Since the browser was opened by Playwright, it will still be necessary to use commands like "Download" or "Click link to new tab" to download files or click on buttons or links that open a new tab.

3. The way Playwright interacts with iframes is different from other web modules. This means that if you need to enter an iframe and within it use commands from both Playwright and another module, you will need to enter the iframe using the respective command from both
 modules.


## Description of the commands

### Open Chrome

Open a new chrome instance.
|Parameters|Description|example|
| --- | --- | --- |
|URL|URL that will be automatically opened once the browser and page are initialized.|https://rocketbot.com/en/|
|Browser executable|Path to the Google Chrome executable. Only needed if using that browser.|C:/Program Files/Google/Chrome/Application/chrome.exe|
|Profile folder|Path to the user profile folder used by the browser. If left empty, a temporary one will be created that will be deleted upon restarting without a profile folder or using the Close Browser command.|C:/folder/profile/|
|Proxy Server|Proxy server address (e.g., http//myproxy8080)|http://myproxy:8080|
|Proxy User|Username for proxy authentication|username|
|Proxy Password|Password for proxy authentication|password|
|Headless Mode|Run browser in headless mode (without GUI)||
|Debugging Port|it allows modules that use Selenium like Web Pro to take control of the browser. This is done using the Take Playwright command from the Web Pro module.|9222|
|Timeout (sec)|Maximum wait time (in seconds) for the initial URL to load.|30|
|Session ID|Unique ID for this Playwright session. Allows running multiple browsers or bots in parallel without interference.|1|

### Check Libraries

Checks if the necessary libraries exist for the current OS and allows forcing their download.
|Parameters|Description|example|
| --- | --- | --- |
|Force download?|If checked, it will delete existing libraries and download them again.||
|Assign result to variable|Variable where the result of the command will be stored|Variable|

### Close browser

Close browser and all tabs, and saves profile state. 
|Parameters|Description|example|
| --- | --- | --- |
|Session ID|Unique ID for this Playwright session|1|
|Assign result to variable|Variable where the result of the connection will be stored|Variable|

### Open URL

Navigate to a URL and waiting until the selected event happens.
|Parameters|Description|example|
| --- | --- | --- |
|URL|||
|Wait Until|Loaded Waits for the entire page, including images and styles, to finish loading.
DOMContentLoaded Waits for the HTML/Text to appear, without waiting for images.
Network Idle consider navigation to be finished when there are no network connections for at least 500 ms.
Commit consider navigation to be finished when the network response is received and the document started loading.||
|Open in New Tab|If checked, opens the URL in a new tab instead of the current one.||
|Session ID|Unique ID for this Playwright session|1|
|Assign result to variable|Variable where the result of the connection will be stored|Variable|

### Wait For Object

Wait for an element to be in a certain state.
|Parameters|Description|example|
| --- | --- | --- |
|Data to search|Put the selector of the element to select.|Data|
|Selector Type|||
|State|Visible wait for the element to be visible.
 Hidden wait for the element to be hidden.
 Attached wait for the element to be present in the DOM.
 Detached wait for the element to be removed from the DOM.||
|Timeout (sec)|Maximum wait time (in seconds) until the object is in the selected state.|30|
|Session ID|Unique ID for this Playwright session|1|
|Assign result to variable|Variable where the result of the connection will be stored|Variable|

### Click on object

Click an element.
|Parameters|Description|example|
| --- | --- | --- |
|Data to search|Put the selector of the element to select.|Data|
|Selector Type|||
|Timeout (sec)|Maximum wait time (in seconds) until the element can be clicked.|30|
|Force Click|Whether to force the click action, even if the element is not visible or interactable.||
|Session ID|Unique ID for this Playwright session|1|

### Clean input and send Text

Deletes the contents of an input object and sends the text.
|Parameters|Description|example|
| --- | --- | --- |
|Data to search|Put the selector of the element to select.|Data|
|Selector Type|||
|Text to Fill|||
|Special Key|Select a special key to press after the text. (Optional)|SPACE|
|Timeout (sec)|Maximum wait time (in seconds) until the element can be written on.|30|
|Session ID|Unique ID for this Playwright session|1|

### Extract Text Playwright

Get inner text of an element.
|Parameters|Description|example|
| --- | --- | --- |
|Data to search|Put the selector of the element to select.|Data|
|Selector Type|||
|Timeout (sec)|Maximum wait time (in seconds) until element's text can be extracted.|30|
|Session ID|Unique ID for this Playwright session|1|
|Assign result to variable|Variable where the result of the connection will be stored|Variable|

### Take Screenshot

Take a screenshot of the page.
|Parameters|Description|example|
| --- | --- | --- |
|Folder path||C:/Users/User/Downloads/|
|File Name|File name and extension|screenshot.jpg|
|Full Page|Check to capture the full scrollable page intead of just the viewport.||
|Session ID|Unique ID for this Playwright session|1|

### Download

Allows clicking a button to download an item.
|Parameters|Description|example|
| --- | --- | --- |
|Data to search|Put the selector of the element to click.|Data|
|Selector Type|||
|Save Directory|Folder where file will be saved. Optional.|C:/Users/User/Downloads/|
|File Name Override|Optional. If empty, uses original name.|file_name|
|Timeout (sec)|Maximum wait time (in seconds) until the element can be downloaded.|60|
|Saved File Path|Var to store the final file path||
|Saved Filename Variable|Var to store the filename||
|Session ID|Unique ID for this Playwright session|1|

### Select Option

Select one or multiple options in a dropdown element.
|Parameters|Description|example|
| --- | --- | --- |
|Data to search|Put the selector of the element to select.|Data|
|Selector Type|||
|Option|Select the labels, values, or indexes of the options to choose. If multiple, send a list ex [option1, option2].|option1|
|Select the option by|Select to choose the option by it's value, label, or index.|Select by|
|Session ID|Unique ID for this Playwright session|1|
|Timeout (sec)|Maximum wait time (in seconds) until an option from the element can be selected.|30|

### Send key combination

Command to send key combination to the active element. Shortcuts that are not part of the web page but are browser or system shortcuts are not supported.
|Parameters|Description|example|
| --- | --- | --- |
|First special Key|First special key to combine with a letter/number and/or with a second special key|SPACE|
|Second special key|Second special key to combine with the first key if necessary.|SPACE|
|Letter or number|Letter or number to combine with the special keys if necessary.|a|
|Session ID|Unique ID for this Playwright session|4|

### Check / Uncheck

Check or Uncheck a check.
|Parameters|Description|example|
| --- | --- | --- |
|Data to search|Put the selector of the element to select.|Data|
|Selector Type|||
|Check or uncheck|Check or uncheck the check.||
|Timeout (sec)|Maximum wait time (in seconds) until the element can be checked / unchecked.|30|
|Session ID|Unique ID for this Playwright session|1|

### Get Attribute

Get an Attribute's value.
|Parameters|Description|example|
| --- | --- | --- |
|Data to search|Put the selector of the element to select.|Data|
|Selector Type|||
|Attribute name|Attribute name whose value is to be obtained.|value|
|Timeout (sec)|Maximum wait time (in seconds) until the attribute of the element can be obtained.|30|
|Session ID|Unique ID for this Playwright session|1|
|Assign result to variable|Variable where the result of the connection will be stored|Variable|

### Wait for load state

Wait until page reaches a required load state.
|Parameters|Description|example|
| --- | --- | --- |
|Load state|Loaded Waits for the entire page, including images and styles, to finish loading.
DOMContentLoaded Waits for the HTML/Text to appear, without waiting for images.
 Network Idle consider navigation to be finished when there are no network connections for at least 500 ms.|Load|
|Timeout (sec)|Maximum wait time (in seconds) until the page reaches the required load state.|30|
|Session ID|Unique ID for this Playwright session|1|
|Assign result to variable|Variable where the result of the connection will be stored|Variable|

### Get tab titles

Returns a list with the titles of all open tabs in the browser.
|Parameters|Description|example|
| --- | --- | --- |
|Session ID|Unique ID for this Playwright session|1|
|Assign result to variable|Variable where the result of the command will be stored|Variable|

### Switch tab

Switch to a tab by its title or index in the current context.
|Parameters|Description|example|
| --- | --- | --- |
|Title|Title or index of the tab to close. Use '-1' to close the last tab.|Title|
|Is an index|Check to indicate that this is an index.|True|
|Session ID|Unique ID for this Playwright session|1|

### Evaluate JS

Evaluates JS code in the context of the page. Returns the result of the execution.
|Parameters|Description|example|
| --- | --- | --- |
|JS code|JS code to evaluate in the context of the page. Returns the result of the execution.|function(data) {
	return param1 * param2;
}|
|Function parameters|List of values of the parameters to be passed to the function. The values of the list are passed as strings.|[value1, value2, ...]|
|Session ID|Unique ID for this Playwright session|1|
|Assign result to variable|Variable where the result of the JS code will be stored|Variable|

### Count elements

Count how many times an element appears on the page.
|Parameters|Description|example|
| --- | --- | --- |
|Data to search|Put the selector of the elements to select.|Data|
|Selector Type|||
|Session ID|Unique ID for this Playwright session|1|
|Assign result to variable|Variable where the result of the connection will be stored|Variable|

### Change to IFRAME

Change to IFRAME and set its content as default.
|Parameters|Description|example|
| --- | --- | --- |
|Data to search|Put the selector of the iframe.|Data|
|Selector Type|||
|Session ID|Unique ID for this Playwright session|1|

### Change to body content

Leave the body of the page as the default content.
|Parameters|Description|example|
| --- | --- | --- |
|Session ID|Unique ID for this Playwright session|1|

### Click link to new tab

Clicks an element that would open a new tab.
|Parameters|Description|example|
| --- | --- | --- |
|Data to search|Put the selector of the element to select.|Data|
|Selector Type|||
|Timeout (sec)|Maximum wait time (in seconds) until the element can be clicked.|30|
|Wait Until|Loaded Waits for the entire page, including images and styles, to finish loading.
DOMContentLoaded Waits for the HTML/Text to appear, without waiting for images.
Network Idle consider navigation to be finished when there are no network connections for at least 500 ms.||
|Session ID|Unique ID for this Playwright session|1|

### Upload files

Command to upload one or more files to an input of type file. Just complete a single value depending on how many files you want to upload.
|Parameters|Description|example|
| --- | --- | --- |
|Data to search|Put the selector of the element to select.|Data|
|Selector Type|||
|Upload files|Select the file to upload|C:/Users/user/file1.pdf|
|Timeout (sec)|Maximum wait time (in seconds) until the element can be clicked.|30|
|Session ID|Unique ID for this Playwright session|1|

### Interact with alert

Interact with an alert on the page. It can be accepted or dismissed.
|Parameters|Description|example|
| --- | --- | --- |
|Data to search|Put the selector of the element to select.|Data|
|Selector Type|||
|Interaction with alert|||
|Timeout (sec)|Maximum wait time (in seconds) until the element can be clicked.|30|
|Session ID|Unique ID for this Playwright session|1|

### Print to PDF

Print the page as a PDF in Chrome. The PDF is generated based on the available content of the page. It does not represent a true copy of the site.
|Parameters|Description|example|
| --- | --- | --- |
|File path and name|Select the path and name of the file to save, without the extension .pdf|path/to/file.pdf|
|Sheet format|Select the sheet format for the PDF.||
|Landscape mode|Check to download the pdf in landscape mode (horizontal).|True|
|Session ID|Unique ID for this Playwright session|1|

### Close tab

Allows you to close a tab by its title or index.
|Parameters|Description|example|
| --- | --- | --- |
|Title|Title or index of the tab to close. Use '-1' to close the last tab.|Title|
|Is an index|Check to indicate that this is an index.|True|
|Session ID|Unique ID for this Playwright session|1|
