WUX Selenium 4

This document describes the Selenium 4 functionality of PandoraFMS discovery.

Introduction
Prerequisites
Parameters and configuration
SIDE file commands
Manual execution
Discovery
Agents and modules generated by the plugin

Introduction

This plugin is intended to monitor web user experience transactions. It is based on the Selenium IDE browser extension, allowing you to run tests recorded with this extension and play them back, recording the results, using version 4 of Selenium.

This plugin is developed to be used with Pandora FMS Discovery.

Prerequisites

The main requirement will be that the server from which the plugin is run is capable of connecting to the URLs of the websites it is going to monitor.

This plugin has 4 different methods to execute for each transaction, so you will have to adjust the requirements to the desired execution mode for each case.

Local driver

The plugin will use the drivers for Google Chrome or Mozilla Firefox that are on the computer where the plugin is running. By default, these components will be searched in the following routes, although different ones can be specified if necessary:

Google Chrome binary: /usr/share/pandora_server/util/selenium_headless_drivers/chrome/google-chrome
Chromedriver: /usr/share/pandora_server/util/selenium_headless_drivers/chromedriver
Mozilla Firefox binary: /usr/share/pandora_server/util/selenium_headless_drivers/firefox/firefox
Geckodriver: /usr/share/pandora_server/util/selenium_headless_drivers/geckodriver

These drivers can be downloaded from the Pandora FMS library in a package and unzipped to the default path:

https://pandorafms.com/library/selenium-4-discovery/

In order for browsers to start in this mode, their specific dependencies installed on the system will also be necessary:

For Mozilla Firefox: gtk3, alsa-lib, libX11-xcb
For Google Chrome: nss, libdrm, mesa-libgbm

Remote driver

The plugin will connect to a Selenium 4 server indicated by its URL, so it will be necessary to have access from the server that runs the plugin to the Selenium 4 server through the port it is listening on (by default 4444 TCP) .

Local Docker

The plugin will start a Docker container on the server where it runs using an image that contains the drivers indicated for the "local driver" mode, allowing dependencies to be abstracted from the real computer.

By default, the "pandorafms/pandora_selenium_headless" image will be used (although it will be possible to indicate a different one for each execution), and the drivers will be searched within docker in the following paths:

Google Chrome binary: /tmp/lib/chrome/google-chrome
Chromedriver: /tmp/lib/chromedriver
Mozilla Firefox binary: /tmp/lib/firefox/firefox
Geckodriver: /tmp/lib/geckodriver

Remote Docker

The plugin will connect via SSH with username and password to a remote server, where it will run a copy of the plugin itself (copied at the time) in local docker mode.

Therefore, along with the requirements of the previous mode, connectivity with the remote server via SSH must also be allowed with the credentials indicated on the indicated port (by default 22 TCP).

The user indicated for the SSH connection must have sufficient permissions to start the Docker container and access the files copied to the temporary directory.

A temporary directory will be used to copy the files to the remote server (by default "/tmp"), although a different path can be indicated in each execution.

Optional requirements

For all execution modes it will be possible to use Google Chrome or Mozilla Firefox profiles for each transaction. If you use this feature, you must ensure that the routes to said profiles are found on the server where the transaction is launched (whether remote or local).

In Docker run modes, the host server must have the paths to the profile folders, since the plugin will mount these folders as volumes of the container it starts.

It will also be possible to monitor connection statistics to the main URL of the SIDE indicated in each execution. To do this, it will be necessary to have the "curl" executable installed on the computer where the plugin is launched. It should be taken into account that if the test execution is carried out in remote driver mode, the statistics will not be obtained from the Selenium 4 server, but from the server that runs the plugin.

Parameters and configuration

Parameters

-v --verbose	Optional. Shows information about the progress of the plugin execution by STDERR.
-c <task_configuration_file_path> --conf <task_configuration_file_path>	Path to the configuration file of the task to be executed.
-s <side_file_path> --side <side_file_path>	Path to the SIDE file to execute.
-t <task_name> --task <task_name>	Unique name of the task. It is used to generate temporary elements that do not overwrite those of other tasks that may be running on the same computer.
-i <agents_interval> --interval <agents_interval>	Optional. Monitoring interval of the agents generated by the plugin. Default: 300.
-g <group_id> --group <group_id>	Optional. ID of the group where you want to create the agents generated by the plugin. Default: 0.
-x --xml_mode	Optional. If indicated, the plugin will generate XML files for the agents instead of outputting them via STDOUT.
-S <server:port> --server <server:port>	Optional. For the generation of agents by XML. IP and port of the Tentacle server to which to send the XML files.
-T <temp_folder> --temp <temp_folder>	Optional. For the generation of agents by XML. Temporary directory for the XML files that are generated before being sent to the indicated Tentacle server.

Configuration file (--conf)

The content of the file will be the following:

{
"worker_mode" : "<local | remote>",
"run_mode" : "<driver | docker>",
"browser" : "<chrome | firefox>",
"driver_url" : "http://<selenium_ip>:<selenium_port>/wd/hub",
"ssh_address" : "<ssh_ip>",
"ssh_port" : "<ssh_port>",
"ssh_user" : "<ssh_user>",
"ssh_password" : "<ssh_password>",
"ssh_password_encrypt" : "<1 | 0>",
"ssh_temp_folder" : "<ssh_temp_folder_path>",
"docker_image": "<docker_image>",
"chromedriver_path": "<chromedriver_path>",
"chrome_binary_path": "<chrome_binary_path>",
"chrome_user_data_dir" : "<chrome_user_data_dir>",
"chrome_profile" : "<chrome_profile>",
"geckodriver_path": "<geckodriver_path>",
"firefox_binary_path": "<firefox_binary_path>",
"firefox_profile" : "<firefox_profile>",
"accept_insecure_certs" : "<1 | 0>",
"monitor_stats" : "<1 | 0>",
"browser_width" : "<width>",
"browser_height" : "<height>",
"global_timeout" : "<seconds>",
"wait_between_commands" : "<seconds>"
}

Each configuration element being:

worker_mode	Indicates whether the transaction will be launched locally or remotely.
run_mode	Indicates whether the plugin will run with drivers or in Docker.
browser	Indicates the browser that will be used for the transaction.
driver_url	Provide the URL to the Selenium 4 server to execute the transaction. Only in "remote/driver" mode.
ssh_address	Indicates the IP of the server to which you will connect via SSH to launch the plugin. Only in "remote/docker" mode.
ssh_port	Optional. Indicates the port for the SSH connection. By default "22". Only in "remote/docker" mode.
ssh_user	Indicates the user for the SSH connection. Only in "remote/docker" mode.
ssh_password	Indicates the password of the previous user. Only in "remote/docker" mode.
ssh_password_encrypt	Optional. Indicates whether the previous password is sent encrypted (1) or not (0). Only in "remote/docker" mode. Passwords can be encrypted by launching the plugin from the Pandora FMS Discovery server. Only in "remote/docker" mode.
ssh_temp_folder	Optional. Indicates the path to the temporary directory for the files needed during execution on the SSH server. By default "/tmp". Only in "remote/docker" mode.
docker_image	Optional. Indicates the name of the Docker image to launch the transaction. By default "pandorafms/pandora_selenium_headless". Only in "docker" mode.
chromedriver_path	Optional. Indicates the path to the "chromedriver" binary. By default "/usr/share/pandora_server/util/selenium_headless_drivers/chromedriver". Only in "local/driver" mode
chrome_binary_path	Optional. Indicates the path to the Google Chrome binary. By default "/usr/share/pandora_server/util/selenium_headless_drivers/chrome/google-chrome". Only in "local/driver" mode
chrome_user_data_dir	Optional. Indicates the path to the Google Chrome data directory ("data dir") that you want to use.
chrome_profile	Optional. Indicates the name of the Google Chrome profile you want to use. It must be found within the "data_dir". If not indicated, the browser's default profile will be used.
geckodriver_path	Indicates the path to the "geckodriver" binary. By default "/usr/share/pandora_server/util/selenium_headless_drivers/geckodriver". Only in "local/driver" mode
firefox_binary_path	Indicates the path to the Mozilla Firefox binary. By default "/usr/share/pandora_server/util/selenium_headless_drivers/firefox/firefox". Only in "local/driver" mode
firefox_profile	Optional. Indicates the path to the Mozilla Firefox profile directory that you want to use. If not indicated, the browser's default profile will be used.
accept_insecure_certs	Optional. If indicated with a value of "1", insecure SSL certificates from URLs accessed during the transaction will automatically be accepted as valid.
monitor_stats	Optional. If it is indicated with a value of "1", connection statistics modules will be generated to the main URL of the indicated SIDE file.
browser_width	Optional. Indicates the width of the browser in pixels for the transaction. By default "1920".
browser_height	Optional. Indicates the height of the browser in pixels for the transaction. By default "1080".
global_timeout	Optional. Indicates the global timeout in seconds for the tasks performed by the plugin, such as connecting to the Selenium server, starting the browser drivers, etc. It is also the default timeout used for Selenium commands to be executed. Default "5".
wait_between_commands	Optional. Indicates the time in seconds that the plugin will wait between each SIDE command it executes. This value can be adjusted with SIDE itself using the "setSpeed" command. By default "0".

For example:

{
"worker_mode" : "local",
"run_mode" : "driver",
"browser": "chrome",
"driver_url" : "",
"ssh_address" : "",
"ssh_port" : "",
"ssh_user" : "",
"ssh_password" : "",
"ssh_password_encrypt" : "",
"ssh_temp_folder" : "",
"docker_image": "",
"chromedriver_path": "",
"chrome_binary_path": "",
"chrome_user_data_dir" : "",
"chrome_profile" : "",
"geckodriver_path": "",
"firefox_binary_path": "",
"firefox_profile" : "",
"accept_insecure_certs" : "0",
"monitor_stats" : "1",
"browser_width" : "1920",
"browser_height" : "1080",
"global_timeout" : "10",
"wait_between_commands" : "0.2"
}

SIDE file commands

The following custom commands can be configured to generate additional modules (all custom commands must begin with "//"):

//phase_start:<phase_name>	Indicates the start of a phase, which will last until another "//phase_start" command is found or until the test ends. This will generate a module with the status of the phase and another module with the time it took to complete. For example: //phase_start:Login process
//getValue;<module_name>;<module_type>;<regexp>	Generates a module with content from the web page which can be obtained through a regular expression from its source code. For example: *//getValue;Temperature;generic_data;<span class="temperature">(\d+\.\,\d).</span>* You would get the temperature of a web page with this line in its source code: <p> The temperature of the solar panel is: <span class="temperature">54º C</span></p>
//getVariable;<module_name>;<module_type>;<variable>	Generate a module with the content of a variable stored in the SIDE with "store" commands. For example: //getVariable;List count;generic_data;listCount
//getScreenshot;<module_name>	Generates a module with a screenshot of the current browser. For example: //getScreenshot;URL home

The commands of the SIDE files enabled to be executed with the plugin are the following (see the Selenium IDE documentation to know how to use them):

addSelection

answerOnNextPrompt

assert

assertAlert

assertChecked

assertConfirmation

assertEditable

assertElementPresent

assertElementNotPresent

assertNotChecked

assertNotEditable

assertNotSelectedValue

assertNotText

assertPrompt

assertSelectedValue

assertSelectedLabel

assertText

assertTitle

assertValue

check

chooseCancelOnNextConfirmation

chooseCancelOnNextPrompt

chooseOkOnNextConfirmation

click

clickAt

close

doubleClick

doubleClickAt

dragAndDropToObject

editContent

else

elseIf

executeScript

executeAsyncScript

forEach

mouseDown

mouseDownAt

mouseMoveAt

mouseOut

mouseOver

mouseUp

mouseUpAt

open

pause

removeSelection

run

runScript

select

selectFrame

selectWindow

sendKeys

setSpeed

setWindowSize

store

storeAttribute

storeJson

storeText

storeTitle

storeValue

storeWindowHandle

storeXpathCount

submit

times

type

uncheck

verify

verifyChecked

verifyEditable

verifyElementPresent

verifyElementNotPresent

verifyNotChecked

verifyNotEditable

verifyNotSelectedValue

verifyNotText

verifySelectedLabel

verifySelectedValue

verifyText

verifyTitle

verifyValue

waitForElementEditable

waitForElementNotEditable

waitForElementNotPresent

waitForElementNotVisible

waitForElementPresent

waitForElementVisible

waitForText

webdriverAnswerOnVisiblePrompt

webdriverChooseCancelOnVisibleConfirmation

webdriverChooseCancelOnVisiblePrompt

webdriverChooseOkOnVisibleConfirmation

while

Manual execution

The plugin execution format is as follows:

./pandora_selenium \
[-v]
-c <path to configuration file> \
-s <path to SIDE file> \
-t <task name> \
[-i <agent interval>]\
[-g <agent group ID>] \
[-x] \
[-S <IP tentacle:port>] \
[-T <path to XML temp directory>]

For example:

./pandora_selenium \
-c /tmp/selenium_test.conf \
-s /tmp/selenium_test.side \
-t selenium_test

Discovery

This plugin can be integrated with Pandora FMS Discovery.

To do this, you must load the ".disco" package that you can download from the Pandora FMS library:

https://pandorafms.com/library/selenium-4-discovery/

Once loaded, Selenium 4 transactions can be monitored by creating Discovery tasks from the Mangement > Discovery > Applications section.

Successfully completed tasks will have a run summary with the following information:

Tests parsed: Total number of tests checked in the SIDE file.
Tests parsed names: List of names of the tests parsed in the SIDE file.
Agents count: Total number of agents generated by the plugin.
Agents names: List of agent names generated by the plugin.

Tasks that do not complete successfully will have a run summary recording any errors that occurred.

Agents and modules generated by the plugin

The plugin will create an agent for the statistics of the main URL with the main name of the SIDE, if the option to monitor statistics is indicated. That agent will contain the following modules:

URL status	Monitors whether the connection to the URL can be made.
URL stat TT	Monitors the total time to access the URL.
URL stat DNS	Monitors the time to resolve the DNS of the URL.
URL stat TTCP	Monitors the time to establish the connection to the TCP port of the URL.
URL stat TSSL	Monitors the time to encrypt the SSL connection to the URL.
URL stat TTC	Monitors the total time to establish the connection to the URL.

The plugin will create an agent for each different test included in the SIDE file. That agent will contain the following modules:

Global status	Monitors the global status of the executed test.
Global time	Monitors the overall time to complete the executed test.
Last error screenshot	If the global state is failed, it will monitor a screenshot of the browser at the point where it failed.
Phase <phase_name> status	If phases are configured in the test, it will monitor the status of each phase.
Phase <phase_name> time	If phases are configured in the test, it will monitor the time to complete each phase.

The plugin will also create a module within the agent corresponding to each configured custom command that generates a module.