Underc0de - La Casa de los Informáticos

[Introducción]

Playc0de es un marco de automatización de pruebas, de código abierto, construido sobre el corazón de Playwright. Proporciona una solución fácil de usar, de mantener y de integrar; siendo además personalizable y robusta para la automatización de pruebas Web, de APIs o incluso de Performance.

Entre las principales características de Playc0de, puedo destacar:

- Implementación: Es fácil de implementar y de usar. Requiere conocimientos básicos de programación.
- Grabador: Permite en segundos grabar tus casos de prueba desde el navegador y convertirlas directamente a código (Javascript o TypeScript).
- Multiplataforma: Podes ejecutar tus pruebas en Desktop (Chromium, Chrome, Mozilla Firefox, Edge y Webkit) o Mobile (Chrome y Safari).
- Estructura: Construido de forma estructurada siguiendo patrones de diseño modernos y prácticos, garantizando robustez y mantenibilidad.
- Comparaciones visuales: Detecta errores de UI fácilmente gracias a las comparaciones visuales entre capturas de pantalla
- Reportería: Genera reportes visuales y atractivos con Allure Reports o integra fácilmente tu reportería personalizada favorita.
- Entornos: Gestiona sin esfuerzo diferentes datos de pruebas y configuraciones específicas para cada ambiente.
- Respaldo: Cada vez son más las empresas que utilizan Playc0de o marcos derivados de Playwright.
- Actualizaciones: mientras Playc0de recibe constantemente actualizaciones por parte de su creador @ Luca Ahumada (Mavis) (https://underc0de.org/foro/profile/?u=1501), el núcleo de Playwright está constantemente en desarrollo por parte de Microsoft.
- CI/CD: Integra fácilmente tu código con GitHub Actions, GitLab CI, Jenkins, Azure, Docker, CircleCI y otros más.

CitarTe invitamos a unirte a la comunidad de QA/Devs utilizando Playc0de y continuar haciendo crecer este proyecto. Damos la bienvenida a comentarios, informes de errores, bugs, solicitudes de características, asesoramiento, etc. Entre todos, podemos construir herramientas de automatización de pruebas que sean robustas, eficientes y que se adecúen a las necesidades de cada proyecto.

[Primeros pasos]

Antes de empezar, es importante mencionar que también vas a poder seguir la guía de "Primeros Pasos" ubicada en el archivo README.md del repositorio oficial: https://github.com/underc0delabs/playc0de

Requerimientos:

• NodeJS (https://nodejs.org/en/download/)
• Java 8 (https://www.java.com/es/download/) (o superior)
• Visual Studio Code (https://code.visualstudio.com) (o tu IDE preferido)
• Git (https://git-scm.com/download/win)

Extensiones adicionales:

• GitHub Copilot o BlackBox
• Error Lens

Si bien las recomendaciones no son obligatorias, están diseñadas para mejorar en gran medida tu experiencia automatizando.


[Puesta en marcha]

Los pasos para instalar las aplicaciones requeridas que mencioné anteriormente son los básicos y a menos que lo desees no será necesario cambiar ni realizar ningún ajuste adicional durante la instalación de cada uno de ellos.  Solo recuerda reiniciar tu dispositivo para que los cambios en tu entorno de trabajo surtan efecto. A diferencia de otros Frameworks, no será necesario que edites las variables de entorno manualmente ni realizar ninguna otra configuración adicional.


1. Clonar el repositorio

Vamos a comenzar clonando el repositorio oficial desde GitHub. Para esto, abrimos la URL del Repositorio, seleccionamos el botón de código y presionamos en "Copy"



Luego, recomiendo crear una carpeta llamada playc0de en nuestro disco local o ubicación de preferencia donde solemos almacenar los proyectos:




Ahora podemos abrir Visual Studio Code, seleccionar la opción "Clone Git Repository":




Pegamos la URL que copiamos anteriormente y seleccionamos la opción "Clone from URL":




Listo! Ahora debemos instalar todos los paquetes y dependencias que tiene el Framework. Dado que los mismos vienen listados en el archivo package.json, simplemente deberemos abrir una terminal en Visual Studio Code (Control + J si usas Windows), escribir comando "npm i" y presionar enter:



Si es la primera vez que utilizas Playc0de en tu dispositivo, Playwright Core nos permite instalar los navegadores requeridos con el comando "npx playwright install":



Ahora procedemos a verificar que la instalación se realizó correctamente. Para eso, ejecutaremos en una terminal de tipo "Git Bash" el comando "env=qa npm run test" para poner a correr todos los casos de demostración que tiene el proyecto. Ten en cuenta que según la terminal que estés usando, los comandos pueden variar (env=qa | ENV=qa | $ENV=qa | etc). Yo recomiendo desplegar la lista de terminales de Visual Studio Code y elegir "Git Bash":



Entre estos casos podremos encontrar algunos de API, Desktop Web y otros de Mobile Web:



Una vez finalizada la ejecución, para poder revisar el reporte debemos ejecutar el comando "npm run report":



El reporte de Allure debería verse similar a lo que encontrarás en las siguientes imágenes. Allure es una reportería muy completa que además permite personalizar el contenido de los reportes y sus respectivos campos para lograr los reportes personalizados que necesitamos según el proyecto:






Otros comandos

Podrás encontrar comandos adicionales en el repositorio oficial o en el archivo package.json del proyecto. A continuación mencionaré algunos de los más usados:


Para revisar o hacer debug de los test paso a paso:



Para ejecutar test con un @tag específico:



Para ejecutar los casos en un único navegador (Chrome por default, lo puedes editar en el package.json):



Para comenzar la grabación de un caso:



Ya que mencioné la grabación, les explicaré como funciona grabar su primer test automatizado. Luego de ejecutar el comando, se abrirá el navegador web y el inspector:



Todo lo que hagamos en el navegador que se abrió, desde los clicks hasta las acciones con el teclado, se irán grabando paso a paso en el inspector para poder utilizarlas luego. Antes de comenzar a grabar, te recomiendo pensar:

• ¿Qué caso de prueba vas a automatizar?
• ¿Conozco todos los pasos necesarios para reproducir el caso?

De esta manera, facilitaremos obtener una grabación limpia sin pasos erróneos que nos molestarán y deberemos remover manualmente después. Una vez decidido, ¡Manos a la obra! Para este ejemplo, navegaremos al foro de underc0de, visitaremos la sección de "Talleres de Underc0de" y verificaremos que el post con los talleres esté visible en la primer página.


1. Navegamos a la URL y buscamos la sección de talleres:



2. Luego de entrar a la sección buscamos el post correspondiente. En este caso, podemos ver que es de tipo "Link" y que contiene el texto "Listado de talleres - UNDERC0DE". Le haremos click para capturar el objeto y podremos ver en el Inspector ya tenemos nuestro test con 3 simples pasos.



3. Si bien tenemos los pasos de nuestro caso, bastante simple, no estamos validando absolutamente nada, solo estamos haciendo clicks:



Para agregar validaciones a nuestro caso, necesitamos agregar una aserción. Para este ejemplo utilizaremos el objeto Link, ya que en un principio acordamos validar que estuviera visible en la web. Dicho esto, es hora de copiar nuestro caso grabado, dirigirnos a la carpeta ./test/, crear un archivo llamado "foro.test.ts" y pegaremos el contenido de nuestro caso grabado dentro.



Editamos el código agregando la aserción que necesitamos:



Como se puede apreciar en la imagen de arriba, el tercer "await page()" pasó a convertirse en un "await expect(page())" que contiene el objeto y reemplazamos el  "click()" por un "toBeVisible()". Pero, ¿Qué significa todo esto? Vamos por partes:

• ¿Qué es un await? Sin entrar en complicaciones, los await son indicadores de que estamos esperando que se cumpla una promesa. Permite que la ejecución de un script se pause hasta que la promesa sea resuelta (o en su defecto, rechazada). En este ejemplo, cada await indica que estamos esperando que cada uno de los pasos del caso se cumpla (o falle).
• Expect(): Los expect son usados normalmente en Frameworks de Automatización para definir aserciones (también conocidas como expectations) en el comportamiento de nuestro caso. Estos nos permiten realizar diferentes tipos de validaciones (que esté visible o no, que contenga algo o no, que suceda un evento en particular, etc).
• getByRole(): Los getBy* son diferentes APIs de Playwright que consumimos para capturar elementos del sitio web. Puede ser getByRole, getByLabel, getByText, getByTestId y muchos otros más. Estos getBy* incluyen auto-esperas, scrolls automáticos y otras mejoras mas que nos ahorran tiempo y líneas de código. Sin ir más lejos, es una de las grandes razones por las cuáles el Playwright Core está siendo elegido en muchos proyectos.
• toBeVisible(): Esto no es más que un tipo de aserción, de los muchos que hay, que nos permitirá saber si el elemento que indicamos dentro del expect() se encuentra visible o no. También se asegurará de que el elemento no esté oculto, oscurecido, tapado por otro objeto y que puede ser visible para el usuario.

Hay muchos más detalles que podemos revisar y conversar sobre cómo capturar elementos y las aserciones, pero eso es una charla que dejaremos para el curso de Playc0de que estaré dictando próximamente de forma gratuita en la Fundación Underc0de.

Siguiendo con nuestro caso de prueba, ¡Llegó la hora de ejecutar nuestra pequeña creación! Para eso, debemos enviar el comando "npm run test foro" por la terminal. Esta adición "foro" al final le indicará que solo queremos correr los casos del archivo que creamos previamente, de lo contrario ejecutará todos los casos que estén en el proyecto:



Finalmente la terminal nos mostrará la ejecución de nuestros casos y sus resultados:



[Arquitectura]

Vamos a aprovechar este post para dar una introducción a la arquitectura que maneja Playc0de. A continuación, pueden observar cómo está compuesta la estructura del proyecto:



Dentro de esta estructura, podemos identificar seis capas:

• Test Layer: contiene los pasos de los casos, los escenarios de prueba y las aserciones. Esta capa interactúa con otras capas constantemente.
• Page Object Layer: contiene todos los objetos de la página. Es donde encapsulan las funcionalidades y elementos específicos de cada página o componente.
• Core Layer: Esta capa contiene el núcleo del Framework. Se encarga de extender las acciones comunes a Playwright hacia funcionalidades o utilidades más complejas o proveer asistencia para manejar la ejecución de casos.
• Data Handler Layer: Se encarga de gestionar toda la data de prueba y la configuración de los diferentes ambientes para que sea accesible desde otras capas, que luego puede ser utilizada en objetos de la página o en el contenido de casos de prueba.
• HTTP Layer: Incluye todo lo relacionado a los HTTP request que luego nos permitirán interactuar con las APIs
• API Layer: esta capa final nos provee de las abstracciones o utilidades necesarias para trabajar con APIs o servicios Backend

Separar capas en nuestro Framework de Automatización nos provee de un montón de ventajas y en la mayoría de los casos se considera una buena práctica. Son muchas las razones que puedo mencionar, pero trataré de hablar de las principales:

- Modularidad: separar capas nos provee de un diseño modular, cada capa tiene una responsabilidad específica. Cada capa nos otorga independencia y la posibilidad de desarrollar, testear o mantener de forma independiente. No solo ayuda a organizar el código, sino que lo hace reutilizable.

- Separar responsabilidades: cada capa es responsable de un aspecto específico del proceso de automatización. Por ejemplo, la Test Layer se enfoca en definir los casos y escenarios de prueba mientras que el Page Object Layer se encarga de gestionar las interacciones del usuario con el sitio web. Esto nos permitirá, por ejemplo, hacer mantenimiento de los objetos sin alterar los pasos de las pruebas.

- Reusabilidad: al dividir podemos enfocarnos en diseñar componentes que sean reutilizables. El Page Object Layer nos permite encapsular interacciones en la interfaz de usuario, que luego utilizaremos en la Test Layer. Así mismo, el Core Layer provee funciones reutilizables por el Page Object Layer a través de los Common Actions. Esta reutilización reduce la duplicación de código, mejora el mantenimiento y sobretodo nos permite realizar mejoras o modificaciones sin afectar el resto de nuestro código.

- Manejo de Test Data: crear un componente de Data Handler nos garantiza un gestor individual de toda la test data y la configuración de los ambientes. Esta capa nos provee de mecanismos para obtener y manejar información de diversas maneras, como archivos de configuración o bases de datos.

- Mantenimiento: como dijimos previamente, al tener diferentes capas, el código se vuelve mas fácil de mantener. Cada capa con responsabilidades bien definidas nos permitirá actualizarlas o modificarlas de forma independiente sin afectar otras capas. Este diseño modular también se lo conoce como "Aislamiento" y reduce el riesgo de que nuevos cambios o funcionalidades afecten nuestro Framework.

- Fácil de leer, fácil de entender: que cada capa tenga una responsabilidad específica hace que nuestro código sea mucho más fácil de leer y de entender. Tener una definición tan clara de responsabilidades nos permite modificar o ajustar el Framework fácilmente de acuerdo a las necesidades del equipo o del proyecto. Además, hace que Automatizar sea aún más fácil para principiantes o nuevos miembros del equipo.

A continuación revisaremos ejemplos de las primeras dos capas de Playc0de:




• Test Definition

El archivo "Profile.test.ts" contiene, como dice su nombre, casos relacionados al perfil del usuario del sitio web. Todos los casos que se ejecuten en este mismo contexto deberían ir incluidos en este archivo.


• Setup y Teardown

El archivo contiene una función beforeEach() y una función afterEach(). Estos bloques de código definen configuraciones o pasos previos (backgrounds) necesarios para poder ejecutar los casos del Perfil.

En estos casos de demostración que contiene Playc0de, el bloque BeforeEach() se encarga de

• Navegar a la URL del foro e iniciar sesión
• Desplegar el menú del usuario
• Acceder al perfil del usuario

Por qué? Simplemente porque todos los casos del perfil de usuario requieren que el usuario esté logeado en la plataforma y que esté posicionado en su perfil. Si miramos los nombres de los casos de prueba, encontraremos "Cambiar fecha de nacimiento", "Cambiar el texto personal", "Cambiar la firma" y "Cambiar la ubicación". Esto tiene mucho más sentido ahora.

Por otro lado, el bloque afterEach() ejecutará algunos pasos posteriores a cada uno de los casos de prueba. Si revisamos el contenido de este bloque, notaremos que hace lo siguiente:

• Guarda los cambios hechos en el perfil
• Verifica en el perfil del usuario que los cambios se hicieron correctamente
• Borra todas las modificaciones para que el usuario esté limpio para la siguiente prueba
• Cierra el navegador

Si conectamos esta información, y por poner un ejemplo más claro, podemos concluir que ejecutar el archivo de Profile.test.ts hará lo siguiente:

Caso N° 1:

• Navegar a la URL del foro e iniciar sesión
• Desplegar el menú del usuario
• Acceder al perfil del usuario
• Ejecutar el caso 1 (Cambiar fecha de nacimiento)
• Guardar los cambios
• Verificar que los cambios se hicieron correctamente
• Limpiar los cambios del perfil
• Cerrar el navegador

Caso N° 2:

• Navegar a la URL del foro e iniciar sesión
• Desplegar el menú del usuario
• Acceder al perfil del usuario
• Ejecutar el caso 2 (Cambiar el texto personal)
• Guardar los cambios
• Verificar que los cambios se hicieron correctamente
• Limpiar los cambios del perfil
• Cerrar el navegador

En resumen, lo que está arriba de la ejecución del caso es el beforeEach() y lo que está debajo de la ejecución es el afterEach(). De esta manera podemos reutilizar nuestro código para generar backgrounds o configuraciones post-ejecución sin tener que estar repitiendo líneas.

Hablemos un poco de los pasos que contiene el caso de prueba. Para este ejemplo, tomaremos el caso que está desplegado en la imagen: '@Regression Change birthdate'


El caso contiene un solo step o paso, en este ejemplo sería "Fill the user birthdate" que se encarga de completar la fecha de nacimiento del usuario en la web. Como se puede apreciar, no interactuamos con ningún objeto o elemento de la página, simplemente enviamos 3 argumentos (año, mes, día) a la función fillBirthdate() que se encuentra dentro del Page Object Layer (ProfilePage.ts)





El Page Object Layer es responsable de encapsular las interacciones con el sitio web (o los elementos del sitio web) en componentes reutilizables. Esto nos facilita la abstracción que separa los casos de prueba de los detalles de implementación relacionados al sitio web. En este ejemplo podemos encontrar:


• Page Object Definition

En el archivo "ProfilePage.ts" podemos notar varias cosas. Para empezar, ProfilePage representa una página, módulo o componente específico de nuestra web. Se encarga de extender la clase BasePage, la cual contiene los Common Actions y otras funciones que se reutilizan en diversas páginas.


• Locators Definition

Dentro de la clase "ProfilePage" are multiples propiedades u objetos que representan elementos del sitio web. Estas propiedades se definen utilizando getBy* APIs o locators clásicos (xpath, css, class, ID, etc). Los locators se encargan de identificar los elementos en el sitio web.


• Initialization

La clase constructor "ProfilePage" recibe los objetos "page" y "context" del Playwright Core. Estos objetos nos permiten interactúan con el sitio web a través del navegador. El constructor tambien inicializa los locators y les asigna un identificador que podremos utilizar luego.


• Page Actions

La clase "ProfilePage" contiene métodos que representan acciones o interacciones con el sitio web. Estos métodos encapsulan los pasos requeridos para realizar acciones específicas como hacer un click, completar un formulario o verificar el estado de algún elemento.

En la siguiente imagen, podemos ver un getByRole definido para el link que nos redirige a los detalles del perfil del usuario junto a los tres locators asociados a la fecha de nacimiento del usuario.



Y acá podemos ver como realizamos un click al link que nos lleva al perfil del usuario, o rellenamos tres campos con la fecha de nacimiento del usuario. Si te estás preguntando dónde está definido la fecha de nacimiento, recuerda que la misma está definida en la capa de los Test. Esto nos permitirá cambiar los valores directamente desde los casos de prueba, o desde la capa de Data Handler que es la encargada de gestionar toda la Test Data.



[Conclusiones]

Playwright es una librería de Automatización. Playc0de busca exprimir todo el potencial de la librería de Playwright a través de componentes diseñados en una estructura sólida, adaptable, fácil de usar y de mantener, capaz de acomodarse a cualquier tipo de proyecto con diferentes necesidades y/o requerimientos. Si aún no estás utilizando Playc0de, te recomiendo que lo pruebes y le des una oportunidad en algún proyecto que tengas disponible. Es un viaje de ida.

Vamos a repasar un poco todo lo que aprendimos hasta ahora:

• Qué es Playc0de y sus ventajas
• Cómo ponerlo en marcha
• Cómo grabar y ejecutar nuestro primer caso
• Arquitectura de Playc0de y sus ventajas
• Test Layer y Page Object Layer

Tenemos mucho más contenido para ver. Algunos de los temas interesantes que se me ocurren son:

• Convirtiendo los casos grabados en clases (Page Object Model)
• Pruebas de accessibilidad
• Pruebas de performance
• Testing de APIs
• Modificando el Playwright Core
• Integración continua y ejecuciones en paralelo

¡Deja en los comentarios qué más te gustaría saber sobre Playc0de!


Para finalizar, un último anuncio. Próximamente estaremos compartiendo el sitio web oficial de Playc0de donde se está escribiendo detalladamente toda la documentación para cada una de sus funciones e integraciones. Adicionalmente, estén atentos a un próximo curso virtual a través de Meet donde estaremos viendo Playc0de en mayor profundidad.

Los invito a utilizar esta nueva sección del foro llamada "Playc0de" para leer, aprender y preguntar más sobre Playc0de o Playwright en general. Espero que les sirva!

Luca Ahumada (Mavis)

TREMENDA guía que te armaste! 
no solo te mandaste un laburazo con Playc0de si no que además tiraste semejante documentación que tanto enriquece a la comunidad, sinceramente no sabría que más pedirte sin antes experimentar con el framework, muchas gracias!

Chicos felicito a todos los impicados al tema, al laburo realizado, la documentación y el repositorio, todo este trabajo lleva tiempo y se nota que lo han hecho con la mejor onda. A seguir creciendo y aprovechando lo que esta comunidad nos da, y a la gente que trabaja todos los dias que no se da a conocer pero estan anonimos en el tema.

Saludos y Gracias

muy bueno!

Hola hermano! Estoy siguiendo la espectacular guía que te mandaste y me trabé en ésta parte
env=qa npm run test, no me corría los test de prueba aún cuando veía que se habían descargado y viendo tu captura y los comandos siguientes noté que no se usaba
env sinó que
ENV, por lo que el comando en ese punto sería
ENV=qa npm run test.

You are not allowed to view links. You are not allowed to view links. Register or Login or You are not allowed to view links. Register or LoginHola hermano! Estoy siguiendo la espectacular guía que te mandaste y me trabé en ésta parte

Código [Seleccionar] Expandir

env=qa npm run test, no me corría los test de prueba aún cuando veía que se habían descargado y viendo tu captura y los comandos siguientes noté que no se usaba

Código [Seleccionar] Expandir

env sinó que

Código [Seleccionar] Expandir

ENV, por lo que el comando en ese punto sería

Código [Seleccionar] Expandir

ENV=qa npm run test.

Buenas! Muy buena observación. Esto se debe al tipo de terminal que estás utilizando. Si utilizas la terminal de Git Bash que provee Visual Studio Code, el comando funciona de ambas formas env/ENV, pero esto puede no funcionar en otros tipos de terminales.

Voy a añadir esta aclaración en el post. Gracias!

(https://i.imgur.com/wqZvobR.png)

Luego de ejecutar las pruebas tengo el siguiente error por falta de librería (posiblemente porque tengo Linux y no Windows):

browserType.launch:
╔══════════════════════════════════════════════════════╗
║ Host system is missing dependencies to run browsers. ║
║ Missing libraries:                                   ║
║     libgstcodecparsers-1.0.so.0                      ║
╚══════════════════════════════════════════════════════╝

busqué en muchos lados hasta que dí con éste post https://github.com/microsoft/playwright/issues/2621 (https://github.com/microsoft/playwright/issues/2621)
donde con éste simple comando se instala sudo apt-get install gstreamer1.0-plugins-bad y todo corre como seda.

Excelente Post Mavis!!!
Quedó espectacular, solo queda disfrutarlo!!
Muchas gracias por tu gran trabajo!

Muy buen post  ;)

Muy bueno, a seguir aprendiendo, gracias por darse el tiempo para tremenda guía.

Genialidad el post, unos genios!!

Increible

Pufffff, tremenda herramienta, cuando adentre en lo que es auto sin dudas lo voy a probar y a tirar feedback conforme a la experiencia, falta un tiempito pero va a llegar jaja.

Gracias por el laburo y el aporte!

Nico-

Excelente...!!

justo lo que buscaba gracias!! ;D

Buen aporte loco  8)