Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/roberto22palomar/pepenium

Pepenium is a Java-based test automation framework for mobile applications (Android / iOS) and web, built on top of Appium and Selenium. Allows to execute in device farms as Browserstack or AWS Device Farm with the same code. Including web responsive.
https://github.com/roberto22palomar/pepenium

android-testing appium automation aws-device-farm browserstack ci-cd framework ios-testing java mobile-testing qa selenium test-automation

Last synced: about 4 hours ago
JSON representation

Pepenium is a Java-based test automation framework for mobile applications (Android / iOS) and web, built on top of Appium and Selenium. Allows to execute in device farms as Browserstack or AWS Device Farm with the same code. Including web responsive.

Awesome Lists containing this project

README 

          


  

    Build

  

  

    Coverage

  






  

    License

  

  Java

  Maven

  JUnit

  Selenium

  Appium Client




# Pepenium





  English |

  Espanol




Pepenium es un framework de automatizacion en Java para Android, iOS y Web construido sobre Appium, Selenium y JUnit 5.



La direccion actual del proyecto es simple de entender y practica de ejecutar: los tests declaran un target funcional, los execution profiles deciden donde corren y el framework se encarga del ciclo de vida de sesion, el logging y el diagnostico de fallos.



## Empieza Aqui



Si eres nuevo en el proyecto, empieza por [START-HERE.es.md](docs/es/START-HERE.es.md).



Primeros pasos recomendados:



1. Ejecuta `mvn -q -DskipTests test-compile`

2. Ejecuta el showcase web desktop para tener tu primer exito real

3. Pasa a Android solo cuando la ruta web ya funcione



Ficheros de entorno listos para copiar:



- [`.env.web.example`](.env.web.example)

- [`.env.android.host-emulator.example`](.env.android.host-emulator.example)

- [`.env.android.docker-emulator.example`](.env.android.docker-emulator.example)



## Por Que Pepenium



- Un test por target funcional, no un test por proveedor

- Un modelo de ejecucion compartido para local, BrowserStack y AWS Device Farm

- Lifecycle de driver y sesion centralizado en una unica factoria

- Helpers reutilizables `Actions*` para Web, Android e iOS

- Capturas pensadas para flujos rapidos sin screenshots borrosos

- Logs mas limpios con contexto automatico y evidencia de fallo



Consulta [START-HERE.es.md](docs/es/START-HERE.es.md) para el camino mas rapido al primer uso, [QUICK-START.es.md](docs/es/QUICK-START.es.md) para la guia mas completa y [CHANGELOG.md](CHANGELOG.md) para el historico de versiones.

Usa [ENVIRONMENT.md](docs/ENVIRONMENT.md) como referencia central de variables de entorno y properties de runtime.

Usa el `docker-compose.yaml` de la raiz si quieres ejecutar el servidor Appium local en Docker mientras el emulador Android sigue en el host.

Usa [consumer-smoke/README.md](consumer-smoke/README.md) si quieres validar el consumo de la API publica desde un proyecto Maven separado.



El workflow principal de CI ejecuta `verify` sobre el framework y despues valida ese consumer smoke, de modo que los quality gates y el consumo externo queden comprobados de forma continua.



## Calidad



- El CI ejecuta `mvn verify` en cada push y pull request sobre `main`

- La cobertura se agrega a partir de los reportes JaCoCo generados por `pepenium-core` y `pepenium-toolkit`

- Checkstyle, SpotBugs y `japicmp` forman parte del camino normal de verificacion

- El proyecto independiente `consumer-smoke` valida el consumo de la API publica fuera del reactor principal



## Usar Pepenium Desde Otro Proyecto



Si quieres consumir Pepenium desde otro proyecto Maven, la regla corta es:



- usa `pepenium-toolkit` para proyectos normales de automatizacion

- usa `pepenium` solo si quieres intencionadamente la capa core/runtime sin los helpers del toolkit

- no anadas `pepenium-parent` en `` porque es el parent POM de Maven, no la dependencia normal para escribir tests



Dependencia tipica de consumo:



```xml



    io.github.roberto22palomar

    pepenium-toolkit

    0.9.4



```



Por que `pepenium-toolkit` suele ser el punto de entrada correcto:



- es el artefacto contra el que la mayoria de usuarios externos querran construir

- te da `ActionsWeb`, `ActionsApp`, `ActionsAppIOS`, `AssertionsWeb`, `AssertionsApp` y `AssertionsAppIOS`

- arrastra transitivamente el core/runtime, asi que sigues teniendo `BaseTest` y `TestTarget` sin cablear ambas capas a mano



Si quieres un ejemplo concreto de consumidor, mira [consumer-smoke/README.md](consumer-smoke/README.md).



## Autoria Plug and Play



Pepenium recomienda ahora un estilo de autoria basado en anotaciones para que el framework se sienta lo mas plug and play posible.



Forma tipica:



```java

@PepeniumTest(target = TestTarget.WEB_DESKTOP)

class LoginTest {



    @PepeniumInject

    private WebDriver driver;



    @PepeniumInject

    private LoginFlow flow;



    @Test

    void loginWorks() {

        driver.get("https://the-internet.herokuapp.com/login");

        flow.runSuccessfulLogin("tomsmith", "SuperSecretPassword!");

    }

}

```



Ese estilo recomendado soporta:



- `@PepeniumTest` en lugar de extender `BaseTest`

- `@PepeniumInject` para `WebDriver`, `DriverSession`, `Actions*`, `Assertions*`, pages y flows

- `@PepeniumPage` junto con `@FindBy` de Selenium para page objects mas ligeros

- inyeccion de `PepeniumSteps` para registrar pasos sin depender de herencia



`BaseTest` sigue totalmente soportado como ruta clasica. La via basada en anotaciones pasa a ser la forma recomendada de uso de cara a `1.0.0`.



## Reportes Nativos



Pepenium genera ahora un bundle nativo de reporting HTML y JSON listo para usar despues de cada ejecucion.



![Vista previa del reporte de Pepenium](docs/assets/reporting-preview.svg)



Que genera:



- un `index.html` a nivel de suite

- un `summary.json` a nivel de suite

- un HTML por test

- un JSON por test

- screenshots enlazadas como evidencia cuando estan disponibles



Los reportes HTML se tratan como diagnostico soportado y orientado al usuario. Los ficheros JSON estan disponibles y son utiles, pero su esquema sigue evolucionando y todavia no se promete como contrato publico versionado.



Donde lo escribe por defecto:



```text

target/pepenium-reports/

```



Por que aporta valor:



- puedes abrir un HTML limpio en vez de leer toda la consola

- los fallos muestran execution story, diagnostic focus, badges de assertions y screenshots agrupadas

- el indice de suite da tarjetas resumen, desglose por target/profile/provider e insights rapidos como los tests mas lentos

- la consola imprime enlaces directos `file:///...` al reporte individual y al indice



Usa [REPORTING.es.md](docs/es/REPORTING.es.md) para la guia especifica de reporting y sus opciones de configuracion.



## Que Aporta La Linea Actual 0.9.x



- Quality gates reales de Maven con Enforcer, JaCoCo, Checkstyle y SpotBugs

- Un camino de `verify` mas fuerte en CI para comprobar higiene de libreria de forma continua

- Metadata y packaging orientados a release con sources y Javadocs

- Workflows dedicados de preflight y publicacion por tag para release

- Comprobacion de compatibilidad de API publica y validacion mas fuerte de consumer smoke

- Endurecimiento de `core`, `toolkit`, execution profiles y reporting



## Arquitectura Actual



Modulos del repositorio:



- `pepenium-core`: motor del framework, runtime, ejecucion y configuracion de providers

- `pepenium-toolkit`: helpers reutilizables para quien escribe tests, como acciones y utilidades de soporte

- `pepenium-examples`: tests, flows y page objects de ejemplo de uso interno del repositorio, construidos sobre `pepenium` y `pepenium-toolkit`



### `core`



Piezas de runtime y ejecucion del framework:



- `PepeniumTest`

- `PepeniumInject`

- `PepeniumPage`

- `PepeniumSteps`

- `BaseTest`

- `DriverConfig`

- `DriverRequest`

- `DriverSession`

- `DriverSessionFactory`

- `DefaultDriverSessionFactory`

- `ExecutionProfile`

- `ExecutionProfiles`

- `ExecutionProfileResolver`

- `FailureContextReporter`

- `LoggingContext`

- `PepeniumBanner`

- `StepTracker`

- `TestTarget`

- `core/config/browserstack`: modelos de configuracion de BrowserStack

- `core/config/yaml`: loaders YAML para catalogos de BrowserStack



Los builders de request especificos de proveedor viven actualmente en:



- `core/configs/local`

- `core/configs/browserstack`

- `core/configs/aws`



### `toolkit`



Bloques reutilizables:



- `toolkit/actions`: `ActionsWeb`, `ActionsApp`, `ActionsAppIOS`

- `toolkit/assertions`: `AssertionsWeb`, `AssertionsApp`, `AssertionsAppIOS`

- `toolkit/support`: helpers reutilizables de settle y scroll



### `examples`



Tests de ejemplo que muestran el patron de uso previsto:



- `pepenium-examples/src/test/java/.../tests/myProjectExample/android`

- `pepenium-examples/src/test/java/.../tests/myProjectExample/ios`

- `pepenium-examples/src/test/java/.../tests/myProjectExample/web`



Ahora los examples estan agrupados por target funcional y no por entorno.

Este modulo es intencionadamente solo para el repositorio: no es un artefacto de consumo publicado ni forma parte del contrato de compatibilidad de la API publica.



## Modelo de Ejecucion



La forma recomendada es declarar el `TestTarget` mediante `@PepeniumTest`:



```java

@PepeniumTest(target = TestTarget.ANDROID_NATIVE)

public class ExampleAndroidNativeTest {



    @PepeniumInject

    private ExampleAndroidShowcaseFlow flow;

}

```



La forma clasica con `BaseTest` sigue estando soportada si un equipo prefiere autoria basada en herencia.



En runtime, Pepenium resuelve un execution profile:



- desde `-Dpepenium.profile=...`

- o desde `PEPENIUM_PROFILE`

- o desde el perfil por defecto del target cuando existe

- con la metadata de perfiles cargada desde `pepenium-core/src/main/resources/execution-profiles.yml`



Eso permite ejecutar el mismo test en varios entornos sin tocar su codigo.



## Targets Soportados



- `ANDROID_NATIVE`

- `ANDROID_WEB`

- `IOS_NATIVE`

- `IOS_WEB`

- `WEB_DESKTOP`



## Execution Profiles Incluidos



- `local-android`

- `local-android-web`

- `local-web`

- `local-web-firefox`

- `local-web-edge`

- `aws-android`

- `aws-android-web`

- `aws-ios`

- `browserstack-android`

- `browserstack-android-web`

- `browserstack-ios`

- `browserstack-ios-web`

- `browserstack-windows-web`

- `browserstack-mac-web`



El catalogo de perfiles incluido se define en:



- `pepenium-core/src/main/resources/execution-profiles.yml`



Los ids de perfil forman parte del contrato soportado de lanzamiento. Los valores internos de `configKey` que hay detras de ese catalogo siguen siendo detalles internos del framework y pueden evolucionar antes de `1.0.0`.



## Tests de Ejemplo



- Android nativo: [ExampleAndroidNativeTest.java](pepenium-examples/src/test/java/io/github/roberto22palomar/pepenium/tests/myProjectExample/android/ExampleAndroidNativeTest.java)

- Android web: [ExampleAndroidWebTest.java](pepenium-examples/src/test/java/io/github/roberto22palomar/pepenium/tests/myProjectExample/android/ExampleAndroidWebTest.java)

- iOS nativo: [ExampleIOSNativeTest.java](pepenium-examples/src/test/java/io/github/roberto22palomar/pepenium/tests/myProjectExample/ios/ExampleIOSNativeTest.java)

- iOS web: [ExampleIOSWebTest.java](pepenium-examples/src/test/java/io/github/roberto22palomar/pepenium/tests/myProjectExample/ios/ExampleIOSWebTest.java)

- Web desktop: [ExampleDesktopWebTest.java](pepenium-examples/src/test/java/io/github/roberto22palomar/pepenium/tests/myProjectExample/web/ExampleDesktopWebTest.java)



### Showcase Web Funcional



Los ejemplos web ahora son examples funcionales reales sobre [The Internet](https://the-internet.herokuapp.com/), no solo plantillas de estructura.



El modulo `pepenium-examples` esta pensado como showcase ejecutable dentro de este repositorio. Sus tests son opt-in y permanecen desactivados por defecto en los builds normales del reactor.



El showcase actual de desktop/mobile-web demuestra:



- ejecucion por profile reutilizando la misma clase de test

- uso de `ActionsWeb` y `AssertionsWeb`

- trazabilidad semantica con `StepTracker`

- screenshots como evidencia

- page objects y orquestacion mediante flows

- un flujo publico real de varias pantallas:

  - login

  - validacion del area segura

  - interaccion con dropdown

  - validacion de estados en checkboxes

  - navegacion al example de add/remove elements



Valores por defecto del example funcional:



- `PEPENIUM_BASE_URL=https://the-internet.herokuapp.com/login`

- `PEPENIUM_WEB_USERNAME=tomsmith`

- `PEPENIUM_WEB_PASSWORD=SuperSecretPassword!`



Puedes ejecutar el showcase desktop web con:



```text

mvn -pl pepenium-examples -am "-Dpepenium.examples.skip.tests=false" "-Dpepenium.excludedTags=" "-Dtest=ExampleDesktopWebTest" "-Dsurefire.failIfNoSpecifiedTests=false" test

```



### Showcase Template De Android Nativo



El ejemplo Android nativo queda ahora planteado como un showcase template mas serio, no como un example funcional contra una app publica.



Ese showcase Android pone el foco en:



- pasos semanticos mediante `StepTracker`

- uso reutilizable de `ActionsApp` y `AssertionsApp`

- limites de carga de pagina explicitos

- screenshots como evidencia

- un flujo corto pero representativo de busqueda y bottom navigation, pensado para adaptarse a una app real



Asi el ejemplo Android sigue siendo honesto y util sin depender de una app publica de terceros que no sea lo bastante estable como carta de presentacion oficial del framework.



### Showcase Template De iOS Nativo



El ejemplo iOS nativo sigue la misma estrategia que Android nativo: queda planteado como un showcase template mas serio, no como un example funcional contra una app publica.



Ese showcase iOS pone el foco en:



- pasos semanticos mediante `StepTracker`

- uso reutilizable de `ActionsAppIOS` y `AssertionsAppIOS`

- limites de carga de pagina explicitos

- screenshots como evidencia

- un flujo corto pero representativo de busqueda y bottom navigation, pensado para adaptarse a una app real



Asi el ejemplo iOS queda alineado con Android y deja una historia mas coherente para la parte mobile del framework.



## Ejecucion Desde el IDE



El flujo recomendado es:



1. Mantener un test por target.

2. Crear una run configuration del IDE por cada execution profile que te interese.

3. Apuntar todas esas configuraciones a la misma clase de test.



Ejemplo para un mismo test Android nativo:



- `Android Native - Local`

- `Android Native - BrowserStack`

- `Android Native - AWS`



Cada run configuration solo cambia `pepenium.profile`.



Asi consigues ejecucion de un click sin editar el test.



## Ejecucion Local



### Android Nativo



Perfil por defecto de `ANDROID_NATIVE`: `local-android`



Variables utiles:



```text

APPIUM_URL=http://localhost:4723

ANDROID_UDID=emulator-5554

ANDROID_DEVICE_NAME=Android Device

APP_PATH=C:\ruta\app.apk

APP_PACKAGE=com.example.app

APP_ACTIVITY=com.example.MainActivity

```



Appium dockerizado con emulador en host:



```text

docker compose up -d appium

APPIUM_URL=http://localhost:4723

ANDROID_UDID=host.docker.internal:5555

ANDROID_DEVICE_NAME=Android Emulator

```



Stack experimental totalmente dockerizado con emulador:



```text

docker compose -f docker-compose.yaml -f docker-compose.emulator.yaml up -d

APPIUM_URL=http://localhost:4723

ANDROID_UDID=android-emulator:5555

ANDROID_DEVICE_NAME=Android Emulator

```



Esta modalidad de emulador queda como experimental y encaja mejor en Linux o en Windows 11 + WSL2 cuando `/dev/kvm` esta disponible.



### Android Web



Perfil por defecto de `ANDROID_WEB`: `local-android-web`



Variables utiles:



```text

APPIUM_URL=http://localhost:4723

ANDROID_UDID=emulator-5554

ANDROID_DEVICE_NAME=Android Device

PEPENIUM_BASE_URL=https://example.com

```



### Web Desktop



Perfil por defecto de `WEB_DESKTOP`: `local-web`



Variables utiles:



```text

PEPENIUM_BASE_URL=https://the-internet.herokuapp.com/login

PEPENIUM_WEB_USERNAME=tomsmith

PEPENIUM_WEB_PASSWORD=SuperSecretPassword!

```



## BrowserStack y AWS



Los perfiles de BrowserStack se apoyan en los YAML de ejemplo de:



- `pepenium-core/src/main/resources/browserstackExamples/browserstackAndroid.yml.example`

- `pepenium-core/src/main/resources/browserstackExamples/browserstackAndroidWEB.yml.example`

- `pepenium-core/src/main/resources/browserstackExamples/browserstackIOS.yml.example`

- `pepenium-core/src/main/resources/browserstackExamples/browserstackIOSWEB.yml.example`

- `pepenium-core/src/main/resources/browserstackExamples/browserstack.yml.example`



Las credenciales reales de BrowserStack no deben vivir en `src/main/resources`.

Usa `.pepenium/browserstack/` para los YAML reales locales, o pasa una ruta externa explicita.

Los ficheros de `browserstackExamples` son solo templates seguros y fallback de ejemplo.



Los perfiles de AWS Device Farm siguen el mismo modelo de `TestTarget` que el resto del framework, mientras que los examples del repositorio se mantienen como material showcase local y no como artefacto de consumo empaquetado.



El catalogo de execution profiles ahora esta externalizado en `pepenium-core/src/main/resources/execution-profiles.yml`, asi que los ids y descripciones disponibles se pueden consultar sin entrar al codigo Java.



## Screenshots, Logging y Diagnostico de Fallos



Pepenium incluye:



- `takeScreenshot()` para capturas mas seguras

- `takeScreenshotFast()` para checkpoints mas ligeros

- fallback al directorio temporal cuando `DEVICEFARM_SCREENSHOT_PATH` no esta definido

- un banner ASCII de Pepenium al arrancar una sesion

- logs compactos con profile, target, driver y sesion corta

- reporte automatico de fallo con screenshot y contexto de runtime

- tracking de pasos recientes dentro del resumen de fallo



El contexto automatico de fallo incluye:



- profile, target, driver y session id

- URL y titulo en sesiones web

- package, activity o contexto en sesiones mobile cuando estan disponibles

- un resumen de capabilities en lugar de dumps crudos y ruidosos

- los ultimos pasos del framework antes del fallo



Comportamiento del step tracking:



- registra automaticamente operaciones comunes de `Actions*`

- conserva solo los ultimos `10` pasos por defecto

- se puede ajustar con `PEPENIUM_STEP_TRACKER_LIMIT` o `-Dpepenium.step.tracker.limit=...`

- se puede enriquecer manualmente desde tests o flows con `step("Abrir buscador")`



Si necesitas mas detalle tecnico del framework, activa:



```text

PEPENIUM_DETAIL_LOGGING=true

```



o:



```text

-Dpepenium.detail.logging=true

```



## Estado Actual



Pepenium ya es util para trabajo real de automatizacion. Se ha ejercitado contra flujos reales de apps Android, emuladores locales, caminos de configuracion remota y capas reutilizables de actions. La siguiente linea importante es seguir mejorando la preparacion como libreria reusable y los diagnosticos de mas alto nivel.



## Documentacion



- Quick start en ingles: [QUICK-START.md](docs/QUICK-START.md)

- Quick start en espanol: [QUICK-START.es.md](docs/es/QUICK-START.es.md)

- README en ingles: [README.md](README.md)

- Referencia de entorno: [ENVIRONMENT.md](docs/ENVIRONMENT.md)