Instalación de SikuliX 2.0.1

Tras unos meses sin realizar nuevas publicaciones, recupero mi actividad con este artículo en el que hablaré sobre la nueva versión 2.0.1,que incluye gran cantidad de mejoras, destacando la simplificación del proceso de instalación y la sustitución de C++ por Java.

En primer lugar detallaré los prerrequisitos, luego los pasos de instalación y, por último, los cambios incorporados desde la versión 1.x.x.

Prerrequisitos

1. Instalar Java
Se ha de tener instalado en el equipo una versión 8 o superior de Java edición 64 bits.


2. Descargar Jython y/o Jruby

Se ha de descargar el intérprete de Jython (o el de Jruby), según el lenguaje que vayamos a usar en los scripts.

Se pueden descargar desde aquí, respectivamente:
https://repo1.maven.org/maven2/org/python/jython-standalone/2.7.1/jython-standalone-2.7.1.jar
https://repo1.maven.org/maven2/org/jruby/jruby-complete/9.2.0.0/jruby-complete-9.2.0.0.jar


3. Sistemas operativos soportados
Se soportan exclusivamente ediciones de 64 bits de los siguientes sistemas operativos :
* Windows XP, 7, 8 y 10.
* Mac OSX 10.10 y superior.
* Linux/Unix : la instalación requiere algunos pasos extras. Leer más información aquí.

Pasos de la instalación

Explicaré los pasos relativos a la versión Windows.

1. Descargar el .jar que contiene Sikuli (llamado sikulix-2.0.1.jar)

2. Moverlo a la carpeta donde se desee instalarlo.

3. Copiar el .jar de Jython (o de Jruby) en la misma carpeta del paso anterior.

4. Para lanzar el IDE se puede optar por alguna de estas opciones:

a) Doble click con el ratón sobre el archivo “sikulix-2.0.1.jar”
b) Abrir un terminal y ejecutar : > java -jar  ruta-completa-a-sikulix-2.0.1.jar

La primera vez que se inicia el IDE, SikuliX mueve el .jar de Jython (o Jruby)  a la carpeta %appdata%\Sikulix\Extensions.

Cambios desde la versión 1.x.x

Los cambios más destacados desde la versión 1.x.x son los siguientes:

• Internamente ahora todo el código está escrito en Java, sustituyendo el código en C++ 
• Actualización a la v3.4 de OpenCV
• Uso de la librería Java Tess4J para las funcionalidades de texto y OCR. La versión actual está basada en  Tesseract 3.0.5. Las funcionalidades de texto se han revisado y mejorado.
• Es posible buscar imágenes con áreas transparentes (llamadas máscaras).
• Se ha implementado el soporte a Android mediante la herramienta “adb” .
• Simplificación del proceso de instalación.
• Se han hecho algunos pequeños cambios en el IDE y se han añadido algunas funcionalidades, como la posibilidad de ejecutar fragmentos de un script.
• Algunas clases/funciones de la API se han revisado y mejorado:
• La clase APP
• Las funciones que buscan imágenes
• Las funciones que buscan texto
• Las funciones FindAllXXX

Se puede encontrar una lista más detallada de los cambios aquí.   

Test 1 : ¡Hola mundo!

Con este artículo inicio una serie en la que iré mostrando las capacidades de SikuliX mediante tests de ejemplo. Como no podía ser de otra forma, comenzaremos con un “¡Hola mundo!”.

Es sorprendente ver cómo un ejemplo tan básico contiene buena parte de las principales funcionalidades necesarias para realizar un test de GUI de una aplicación. A saber:

1 – Búsqueda de una determinada imagen en pantalla. En este caso, un botón.

2 – Generar un click sobre un botón.

3 – Esperar unos segundos hasta que se complete una determinada acción.

4 – Introducir una palabra o frase en un cuadro de texto.

5 – Enviar el comando de una tecla especial. En este caso, retorno de carro.

6 – Ejecutar un flujo secuencial de acciones: las mencionadas en esta lista.

Solo con esas 6 funcionalidades se puede probar gran parte de las especificaciones de cualquier aplicación. Y todo eso en SikuliX se hace con los comandos siguientes:

click( )

wait(1)
click()

wait(1)

type("notepad"+Key.ENTER)

wait(1)

type("Hola mundo!")

En el siguiente vídeo se ve el script en acción :

Ahora no entraré a detallar cada comando sino que daré una explicación básica para entender el test. Los detalles vendrán en futuros artículos.

El comando click() ejecuta la pulsación del botón izquierdo del ratón sobre la imagen que se le pasa como parámetro. Es decir, primeramente es capaz de reconocer un determinado patrón visual y localizarlo en la pantalla. Y, posteriormente, ejecuta una pulsación de ratón en esa posición.

El comando wait() detiene la ejecución del script durante los segundos que se pase como parámetro.  Suele ser necesario utilizar este comando porque después de cualquier acción (como la pulsación del botón "Inicio" en este script) tarda unos milisegundos en aparecer el resultado de dicha acción (en este caso, la aparición del menú desplegable). Si no esperamos un tiempo, el siguiente comando no encontrará la imagen que busca así que el test se detendría con un error.

Obviamente, esta no es una buena técnica para sincronizar eventos. Lo lógico sería esperar hasta que el menú apareciera en lugar de indicar un tiempo fijo. Esto también lo permite este comando si se le pasa como parámetro una imagen, quedándose detenido hasta que esa imagen aparezca en pantalla. Veremos ejemplos de esto en futuros artículos.

El comando type() escribe un texto o pulsa teclas especiales sobre el control que posea el foco o sobre el que se pasa como parámetro. En nuestro caso, tras hacer click sobre el opción “Ejecutar”, se muestra un diálogo cuyo control activo es un cuadro de texto. Por eso no es necesario poner el foco sobre él. Sin embargo, suele ser una buena práctica poner primero el foco (pasando como parámetro una captura del control o haciendo un click sobre él) y luego escribir el texto.

Hemos visto un ejemplo sencillo pero, a la vez, representativo del enorme abanico de acciones que se pueden llevar a cabo con un escueto script de 3 comandos y 7 líneas de código. En futuros artículos seguiremos aprendiendo los comandos de SikuliX mediante ejemplos.

Configuración de las imágenes (pattern settings)

En el anterior artículo vimos cómo introducir imágenes en el script. Ahora veremos un conjunto de parámetros fundamentales asociados a cada imagen una vez se encuentra en el código de un script.

Al clickar sobre la miniatura de cada imagen se muestra la ventana titulada “Pattern settings” que tiene 3 pestañas : “File”, “Matching Preview” y “Target Offset”.

En la pestaña “File” se puede especificar el nombre de la imagen. Es recomendable darle un nombre coherente para facilitar su posterior gestión. La ruta de la imagen no se puede modificar.

Pestaña "File"

En la pestaña “Matching Preview” se establece el grado de similaridad exigido entre la imagen que hemos referenciado en el script y la imagen que aparezca en pantalla durante la ejecución del script. Este parámetro es uno de los más importantes dentro de SikuliX.

Es una valor entre 0 y 99 representado mediante un número decimal entre 0 y 0,99 en el script. Cuanto mayor sea este número, más parecida ha de ser la imagen del script a la imagen aparecida en pantalla para encontrarla. Por defecto su valor es 0,70.

Si indicamos un valor muy alto, es posible que SikuliX no encuentre la imagen que buscamos y el script se detenga mostrando un error.

Si indicamos un valor muy bajo, es posible que SikuliX encuentre otra imagen en pantalla que es parecida a la que pretendemos utilizar y, por tanto, el script no funcione correctamente.

Pestaña "Matching Preview"

Hay que jugar con el slider que aparece en la parte inferior para comprobar qué valor es el adecuado en cada caso. Habitualmente, el valor por defecto ya lo es.

En el  siguiente vídeo vemos lo que sucede cuando lo cambiamos. En el momento en que lo bajamos por debajo de 0,47 SikuliX encuentra regiones de la pantalla que se parecen a la imagen que queremos buscar. Obviamente, esto no es lo que se pretende ya que cuando se ejecute el script es posible que la acción (un click o lo que sea) se aplique sobre otra zona de la pantalla.

 

En la pestaña “Target Offset” se indica una desviación en pixels con respecto al centro de la imagen. Valores negativos en el eje X indican un desplazamiento hacia la izquierda y en el eje Y hacia arriba. Este parámetro lo utiliza SikuliX cuando en el script se ha programado una acción de click sobre la imagen. En lugar de hacerlo en el centro, lo hará en el lugar que se indique aquí. Esto útil cuando la imagen tiene diversas zonas sensibles al click, por ejemplo, un control slider. Si queremos clickar en la parte derecha o izquierda, podemos aquí definir la desviación requerida. 

Pestaña "Target Offset"

Inserción de imágenes en el script

Aparte de las ya mencionadas en el artículo anterior, existen varias formas de introducir imágenes dentro de un script de SikuliX. Se accede a ellas a través de las opciones “Take screenshot” e “Insert image”, que se sitúan en la barra superior. Vamos a verlas :

Opciones para insertar imágenes

Take screenshot : Permite seleccionar una región de la pantalla. Al clickar sobre este botón, se pasa al modo de selección de imagen. En este modo, el IDE de SikuliX se minimiza así que se muestra la aplicación que se encuentre maximizada en ese momento. Mediante el ratón, el usuario puede enmarcar regiones de la pantalla que se convierten en imágenes introducidas en el script. En este vídeo se ve su comportamiento.  

Insert image : Permite seleccionar una imagen almacenada previamente en cualquier unidad  de almacenamiento. Solo admite los formatos .jpg y .png. En este vídeo se ve su comportamiento.

Configuración del IDE de SikuliX (II) : Auto capture

En un artículo previo ya expliqué los principales parámetros de configuración del IDE. En este artículo hablaré sobre uno que quedó pendiente. Me refiero al denominado “Auto capture”.

Se sitúa en la parte superior de la barra lateral de comandos, en la parte izquierda de la ventana principal.

Opción "Auto capture"

Su cometido es facilitar la creación de scripts reduciendo el número de clicks a realizar. No es que suponga una gran ventaja pero en scripts largos facilita la tarea.

Funciona de la siguiente manera : si está seleccionado y elegimos cualquier comando de la barra de la izquierda cuyo parámetro sea una imagen (aquellos en los que aparece una cámara) entonces automáticamente pasa al modo de captura de imagen. Veamos un vídeo donde se ve cómo se comporta con “Auto capture” seleccionado.

 

Si, por contra, no está seleccionado o introducimos el comando mediante teclado, tenemos que clickar sobre el icono que aparece para poder entrar al modo de captura de imagen. Veamos un vídeo donde se ve cómo se comporta con “Auto capture” no seleccionado.

Una vez la imagen se ha capturado, es decir, se ha seleccionado el área de la pantalla donde se encuentra lo que queremos utilizar en el script, aparece una miniatura suya en el mismo.

Estructura de un proyecto de SikuliX

Vamos a analizar la estructura en disco de un proyecto de SikuliX. Supongamos un proyecto llamado “project1”. Al crearlo se genera la siguiente estructura de archivos :

Estructura de carpetas de un proyecto

• Una carpeta contenedora cuyo nombre es el del proyecto terminado en “.sikuli”.
• Un archivo .py con el código fuente en Python. Su nombre ha de coincidir con el del proyecto.
• Las imágenes utilizadas en el script en formato .png. En este caso solo hay una con el nombre “checkbox.png”.
• Un archivo .html opcional. Se guarda si se habilita la opción “Create HTML” mencionada en el artículo anterior. Contiene una versión en html del script. Esto es útil para los casos en que se desee mostrar en una página web.

Es posible agrupar todo el proyecto en un único  archivo con extensión .skl mediante la opción “File” --> “Export packed source”. En realidad,  este archivo es un .zip con la extensión renombrada. Facilita la distribución del código al empaquetar todos los archivos en uno.

Opción "Export packed source"

 En el siguiente artículo comenzaremos a desarrollar proyectos de test.

Configuración del IDE de SikuliX

Antes de programar scripts vamos a ver los posibles parámetros que nos ofrece el IDE de SikuliX.

Primero hay que lanzar el IDE. Se puede hacer de varias formas : doble click sobre el archivo “runsikulix.cmd” o sobre el archivo “sikulix.jar”.

Para acceder a la configuración se puede usar el atajo “CTRL-P” o a través de la opción “File” --> “Preferences...”.

Opción para acceder a las preferencias

En la ventana de preferencias hay 3 pestañas y un botón con las opciones avanzadas (abajo, “more options...”). Vamos a ver una a una en detalle.

• Pestaña  “Screen Capturing”

 

Pestaña "Screen Capturing"

Quick capture hotkey: Atajo de teclas para hacer una captura de una sección de la pantalla con el objeto de insertarla en un script. Es lo mismo que hace el botón “Take screenshot”.

Delay before capture: Tiempo de espera desde que se pulsa el botón “Take screenshot” hasta que permite realizar la captura.

Automatic Naming: El nombre por defecto que se le da a la imagen capturada. Ofrece 3 opciones :

• time stamp : el número de milisegundos desde 1970 (Unix timestamp).
• text in the image : si la captura contiene un texto, intenta reconocerlo mediante el OCR y lo establece como nombre de imagen. Esto solo es posible si durante la instalación se eligió la opción 3 (instalación de Tesseract).
• off (manual input) : no propone ninguno y te lo pregunta mediante un diálogo modal.

Independientemente de la opción elegida, siempre es recomendable darle a todas las capturas un nombre coherente y relacionado con el contenido de la imagen. Facilitará la comprensión de los scripts y la reutilización de esas imágenes.

• Pestaña  “Text Editing”    

 

Pestaña "Text Editing"

Tab key inserts spaces instead of tab : Permite elegir si se desea que la tecla “tab” inserte espacios en blanco o una tabulación. En el primer caso, permite elegir el número de espacios en blanco.

Font name / Size : Tipo de fuente y tamaño utilizada dentro del IDE.

•  Pestaña  “General Settings"   

 

Pestaña "General Settings"

 

Updates : Permite habilitar las actualizaciones automáticas.
Language : El idioma en el que se muestra la interfaz del IDE.

• More options...

Si se pulsa el botón “more options...” se nos muestra esta ventana con opciones avanzadas.

Preferencias: more Options

- Options on Save

Create HTML: Al grabar el script crea un archivo HTML que lo contiene. Puede ser útil si se desea publicar el script en una página web.

Delete not used images: Si se activa, al grabar el script borra aquellas imágenes que se encuentren en la carpeta donde está almacenado pero que no se referencien a lo largo del código del script. Esto es útil para evitar que el disco se llene con imágenes que no se usan. Pero es peligroso si temporalmente quitamos una imagen de un script y elegimos la opción de grabar (“CTRL-S” o “File” --> “Save”).

- Options on Run

Autosave all : Permite que justo antes de ejecutarse un script todo el código se grabe a disco. Esto es útil en los casos que el IDE se cierre debido a una excepción no controlada durante la ejecución  del script, con lo que perdemos los últimos cambios no grabados.

Always hightlight : Si se activa esta opción, las imágenes aparecen resaltadas con un marco según van apareciendo a lo largo de la ejecución del script.

- IDE Layout

Message area at bottom: Permite elegir dónde se situa el panel de mensajes : o bien abajo o bien a la derecha. Esta opción no se puede elegir de forma individualizada sino que depende de si la opción “Activate the new layout” está activa o no.

CommandBar (old style): Permite elegir si se desea mostrar el panel de comandos de la izquierda. Esta opción no se puede elegir de forma individualizada sino que depende de si la opción “Activate the new layout” está activa o no.

- Messages to show

Permite elegir los tipos de mensajes que se muestran en el panel de mensajes según se va ejecutando el script.

Actions: Mensajes que contienen las acciones ejecutadas (click de ratón, pulsación de una tecla, etc.).

Info: Mensajes con trazas de nivel “Info”. Ya hablaremos del nivel de logs en futuros artículos.

Debug: Mensajes con trazas de nivel “Debug”. Ya hablaremos del nivel de logs en futuros artículos.

- TextSearch and OCR

Allow searching for text: Habilita la búsqueda de texto en imágenes. Requiere la instalación del OCR Tesseract. En el artículo anterior se explicaban las opciones de instalación.

Allow OCR: Habilita la extracción de texto contenido en imágenes. Requiere la instalación del OCR Tesseract. En el artículo anterior se explicaban las opciones de instalación.

- Activate the new layout

Habilita un layout diferente del IDE en el que el panel de mensajes aparece a la derecha y desaparece el panel con los comandos de la izquierda.

- ImageThumbs (on) / ImageLabels (off)

Permite elegir cómo se muestran las imágenes en los scripts. Si se habilita, se mostrará una miniatura de la imagen. Sino, se mostrará una miniatura que contiene el nombre de la imagen.

- Show script as plain text

Si se habilita esta opción, en lugar de las miniaturas de las imágenes aparece su nombre como texto plano.

Y con esto termino este artículo sobre las preferencias del IDE de SikuliX.