Selenium 4

Este documento describe la funcionalidad Selenium 4 del discovery de PandoraFMS.

Introducción
Prerequisitos
Parámetros y configuración
Comandos de los ficheros SIDE
Ejecución manual
Discovery
Agentes y módulos generados por el plugin

Introducción

Este plugin tiene como finalidad monitorizar transacciones de experiencia de usuario web. Se basa en la extensión para navegadores Selenium IDE, permitiendo ejecutar tests grabados con esta extensión y reproducirlos recogiendo el resultado, usando la versión 4 de Selenium.

Este plugin está desarrollado para usarse con Pandora FMS Discovery.

Prerequisitos

El principal requisito será que el servidor desde donde se ejcute el plugin sea capaz de conectar con las URLs de los sitios web que vaya a monitorizar.

Este plugin cuenta con 4 métodos distintos para ejecutarse en cada transacción, por lo que tendrá que ajustar los requisitos al modo de ejecución deseado para cada caso.

Driver local

El plugin usará los drivers para Google Chrome o Mozilla Firefox que se encuentren en el equipo donde se ejecuta el plugin. Por defecto, se buscarán estos componentes en las siguientes rutas, aunque se podrán especificar unas distintas de ser necesario:

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

Estos drivers se pueden descargar de la librería de Pandora FMS en un paquete y descomprimirlos en la ruta por defecto:

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

Para que los navegadores se puedan iniciar en este modo, también serán necesarias sus dependencias concretas instaladas en el sistema:

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

Driver remoto

El plugin se conectará a un servidor de Selenium 4 indicado mediante su URL, por lo que será necesario contar con acceso desde el servidor que ejecute el plugin hacia el servidor de Selenium 4 mediante el puerto que tenga a la escucha (por defecto 4444 TCP).

Docker local

El plugin iniciará un contenedor de Docker en el servidor donde se ejecute usando una imagen que contenga los drivers indicados para el modo "driver local", permitiendo abstraer las dependencias del equipo real.

Por defecto se usará la imagen "pandorafms/pandora_selenium_headless" (aunque será posible indicar una distinta para cada ejecución), y los drivers se buscarán dentro del docker en las siguientes rutas:

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

Docker remoto

El plugin conectará mediante SSH con usuario y contraseña a un servidor remoto, en el cual ejecutará una copia del propio plugin (copiada en el momento) en modo docker local.

Por lo tanto, junto a los requisitos del modo anterior, se debe permitir también la conectividad con el servidor remoto por SSH con las credenciales indicadas en el puerto indicado (por defecto 22 TCP).

El usuario indicado para la conexión SSH deberá contar con permisos suficientes para iniciar el contenedor de Docker y acceder los ficheros copiados en el directorio temporal.

Se usará un directorio temporal para copiar los ficheros al servidor remoto (por defecto "/tmp"), aunque se podrá indicar una ruta distinta en cada ejecución.

Requisitos opcionales

Para todos los modos de ejecución será posible hacer uso de perfiles de Google Chrome o Mozilla Firefox para cada transacción. En caso de hacer uso de esta característica, se deberá asegurar que en el servidor donde se lance la transacción (ya sea remoto o local) se encuentren las rutas a dichos perfiles.

En los modos de ejecución de Docker, será el servidor anfitrión el que deba tener las rutas a las carpetas de los perfiles, ya que el plugin montará dichas carpetas como volumenes del contenedor que inicie.

También será posible realizar una monitorización de estadísticas de conexión a la URL principal del SIDE indicado en cada ejecución. Para ello será necesario contar con el ejecutable "curl" instalado en el equipo donde se lance el plugin. Se debe tener en cuenta que si la ejecución del test se realiza en modo driver remoto, las estadísticas no se obtendrán desde el servidor de Selenium 4, si no desde el servidor que ejecuta el plugin.

Parámetros y configuración

Parámetros

-v --verbose	Opcional. Muestra información acerca del progreso en la ejecución del plugin por STDERR.
-c <task_configuration_file_path> --conf <task_configuration_file_path>	Ruta al fichero de configuración de la tarea a ejecutar.
-s <side_file_path> --side <side_file_path>	Ruta al fichero SIDE a ejecutar.
-t <task_name> --task <task_name>	Nombre único de la tarea. Es usaro para generar elementos temporales que no sobrescriban los de otras tareas que puedan estar corriendo en el mismo equipo.
-i <agents_interval> --interval <agents_interval>	Opcional. Intervalo de monitorización de los agentes generados por el plugin. Por defecto: 300.
-g <group_id> --group <group_id>	Opcional. ID del grupo donde se quieran crear los agentes generados por el plugin. Por defecto: 0.
-x --xml_mode	Opcional. Si se indica, el plugin generará ficheros XML para los agentes en lugar de hacerlo mediante su salida por STDOUT.
-S <server:port> --server <server:port>	Opcional. Para la generación de agentes por XML. IP y puerto del servidor de Tentacle al que enviar los ficheros XML.
-T <temp_folder> --temp <temp_folder>	Opcional. Para la generación de agentes por XML. Directorio temporal para los fichero XML que se generen antes de enviarse al servidor de Tentacle indicado.

Archivo de configuración (--conf)

El contenido del fichero será el siguiente:

{
"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>"
}

Siendo cada elemento de la configuración:

worker_mode	Indica si la transacción se lanzará en local o remoto.
run_mode	Indica si el plugin se ejecutará con drivers o en Docker.
browser	Indica el navegador que se usará para la transacción.
driver_url	Indica la URL al servidor de Selenium 4 para ejecutar la transacción. Solo en modo "remote/driver".
ssh_address	Indica la IP del servidor al que conectará por SSH para lanzar el plugin. Solo en modo "remote/docker".
ssh_port	Opcional. Indica el puerto para la conexión SSH. Por defecto "22". Solo en modo "remote/docker".
ssh_user	Indica el usuario para la conexión SSH. Solo en modo "remote/docker".
ssh_password	Indica la contraseña del usuario anterior. Solo en modo "remote/docker".
ssh_password_encrypt	Opcional. Indica si la contraseña anterior se envia encriptada (1) o no (0). Solo en modo "remote/docker". Las contraseñas se podrán encriptar lanzando el plugin desde el Discovery server de Pandora FMS. Solo en modo "remote/docker".
ssh_temp_folder	Opcional. Indica la ruta al directorio temporal para los ficheros necesarios durante la ejecución en el servidor SSH. Por defecto "/tmp". Solo en modo "remote/docker".
docker_image	Opcional. Indica el nombre de la imagen de Docker para lanzar la transacción. Por defecto "pandorafms/pandora_selenium_headless". Solo en modo "docker".
chromedriver_path	Opcional. Indica la ruta al binario "chromedriver". Por defecto "/usr/share/pandora_server/util/selenium_headless_drivers/chromedriver". Solo en modo "local/driver"
chrome_binary_path	Opcional. Indica la ruta al binario de Google Chrome. Por defecto "/usr/share/pandora_server/util/selenium_headless_drivers/chrome/google-chrome". Solo en modo "local/driver"
chrome_user_data_dir	Opcional. Indica la ruta al directorio de datos ("data dir") de Google Chrome que se quiera utilizar.
chrome_profile	Opcional. Indica el nombre del perfil de Google Chrome que se quiera utilizar. Debe encontrarse dentro del "data_dir". Si no se indica se usará el perfil por defecto del navegador.
geckodriver_path	Indica la ruta al binario "geckodriver". Por defecto "/usr/share/pandora_server/util/selenium_headless_drivers/geckodriver". Solo en modo "local/driver"
firefox_binary_path	Indica la ruta al binario de Mozilla Firefox. Por defecto "/usr/share/pandora_server/util/selenium_headless_drivers/firefox/firefox". Solo en modo "local/driver"
firefox_profile	Opcional. Indica la ruta al directorio del perfil de Mozilla Firefox que se quiera utilizar. Si no se indica se usará el perfil por defecto del navegador.
accept_insecure_certs	Opcional. Si se indica con valor "1" se aceptarán automáticamente como válidos los certificados SSL inseguros de las URL a las que se acceda durante la transacción.
monitor_stats	Opcional. Si se indica con valor "1" se generarán módulos de estadísticas de conexión a la URL principal del fichero SIDE indicado.
browser_width	Opcional. Indica el ancho del navegador en pixels para la transacción. Por defecto "1920".
browser_height	Opcional. Indica el alto del navegador en pixels para la transacción. Por defecto "1080".
global_timeout	Opcional. Indica el timeout global en segundos para las tareas que realiza el plugin, tales como conectar al servidor de Selenium, iniciar los drivers del navegador, etc. También es el timeout usado por defecto para los comando de Selenium que se ejecuten. Por defecto "5".
wait_between_commands	Opcional. Indica el tiempo en segundos que el plugin esperará entre cada comando del SIDE que ejecute. Este valor se podrá ajustar con el propio SIDE mediante el comando "setSpeed". Por defecto "0".

Por ejemplo:

{
    "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"
}

Comandos de los ficheros SIDE

Se podrán configurar los siguientes comandos personalizados para generar módulos adicionales (todos los comandos personalizados deben comenzar con "//"):

//phase_start:<phase_name>	Indica el comienzo de una fase, que durará hasta encontrar otro comando "//phase_start" o hasta que termine el test. Esto generará un módulo con el estado de la fase y otro módulo con el tiempo que ha tomado en completar. Por ejemplo: //phase_start:Login
//getValue;<module_name>;<module_type>;<regexp>	Genera un módulo con contenido de la página web el cual se puede obtener mediante una expresión regular del código fuente de la misma. Por ejemplo: /*/getValue;Temperature;generic_data;<span class="temperature">(\d+\.\,\d).</span>* Obtendría la temepratura de una página web con esta línea en su código fuente: <p> The temperature of the solar panel is: <span class="temperature">54º C</span></p>
//getVariable;<module_name>;<module_type>;<variable>	Genera un módulo con el contenido de una variable almacenada en el SIDE con comandos "store". Por ejemplo: //getVariable;List count;generic_data;listCount
//getScreenshot;<module_name>	Genera un módulo con una captura de pantalla del navegador en ese momento. Por ejemplo: //getScreenshot;URL home

Los comandos de los ficheros SIDE habilitados para ejecutarse con el plugin son los siguientes (consulte la documentación de Selenium IDE para saber como usarlos):

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

Ejecución manual

El formato de la ejecución del plugin es el siguiente:

./pandora_selenium \
[-v]
-c <ruta al fichero de configuración> \
-s <ruta al fichero SIDE> \
-t <nombre tarea> \
[-i <intervalo de agentes>] \
[-g <ID grupo de agentes>] \
[-x] \
[-S <IP tentacle:puerto>] \
[-T <ruta al directorio temporal de XML>]

Por ejemplo:

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

Discovery

Este plugin puede integrarse con el Discovery de Pandora FMS.

Para ello se debe cargar el paquete ".disco" que puede descargar desde la librería de Pandora FMS:

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

Una vez cargado, se podrán monitorizar transacciones de Selenium 4 creando tareas de Discovery desde la sección Mangement > Discovery > Applications.

Las tareas completadas con éxito tendrán un resumen de ejecución con la siguiente información:

Tests parsed: Número total de tests comprobados en el fichero SIDE.
Tests parsed names: Lista de nombres de los tests comprobados en el fichero SIDE.
Agents count: Número total de agentes generados por el plugin.
Agents names: Lista de nombres de los agentes generados por el plugin.

Las tareas que no se completen con éxito tendrán un resumen de ejecución en el que se registrarán los errores que se hayan producido.

Agentes y módulos generados por el plugin

El plugin creará un agente para las estadísticas de la URL principal con el nombre principal del SIDE, si se indica la opción de monitorizar estadísticas. Ese agente contrendrá los siguientes módulos:

URL status	Monitoriza si se puede realizar la conexión a la URL.
URL stat TT	Monitoriza el tiempo total en acceder a la URL.
URL stat DNS	Monitoriza el tiempo en resolver el DNS de la URL.
URL stat TTCP	Monitoriza el tiempo en establecer la conexión al puerto TCP de la URL.
URL stat TSSL	Monitoriza el tiempo en cifrar la conexión SSL a la URL.
URL stat TTC	Monitoriza el tiempo total en establecer la conexión a la URL.

El plugin creará un agente por cada test distinto incluido el el fichero SIDE. Ese agente contedrá los siguientes módulos:

Global status	Monitoriza el estado global del test ejecutado.
Global time	Monitoriza el tiempo global en completar el test ejecutado.
Last error screenshot	Si el estado global es erroneo, monitorizará una captura de pantalla del navegador en el punto en que falló.
Phase <phase_name> status	Si se configuran fases en el test, monitorizará el estado de cada fase.
Phase <phase_name> time	Si se configuran fases en el test, monitorizará el tiempo en completar cada fase.

El plugin también creará un módulo dentro del agente que corresponda por cada comando personalizado configurado que genere un módulo.