ZIO IV: modulación por capas

Finalizamos la serie de entradas de ZIO con la presente entrada, ZIO IV: modulación por capas, en la cual presentaré cómo la librería ZIO permite definir módulos funcionales conectados horizontal o verticalmente. Las entradas publicadas hasta la fecha son las siguientes:

El ejemplo práctico ha realizar consistirá en resolver un problema básico de ingeniero de datos del ámbito de BigData. Todo ingeniero de datos debe de dar solución a una ingesta de datos, transformar los datos conforme a unas reglas de negocio y, para finalizar, almacenar o cargar los datos transformados en un data lake o cualquier tipo de almacén de datos; este proceso, se denomina ETL (Extract, Transform and Load). Así, el caso de uso consiste en realizar un proceso de extracción, transformación y carga de datos solicitado por un actor el cual puede ser un sistema o una persona física.

La solución está compuesta por cuatro elementos: el primero, un módulo con la funcionalidad encargada de la extracción de datos; el segundo, el módulo transformador, encargado de transformar los datos en función de unas reglas de negocio; el tercero, el módulo cargador, encargado de realizar la carga de los datos transformados al almacén de datos; y, para finalizar, el elemento coordinador de las operaciones de los módulos el cual contendrá la definición de las secuencias del programa ETL. En el ejemplo, los procesos de extracción y carga son tareas simbólicas ya que el objetivo del ejercicio reside en el desarrollo de los módulos. Desde un punto de vista gráfico la vista de elementos y los intercambios de mensajes entre ellos queda definido en el siguiente diagrama de secuencia UML siguiente:

El diagrama de secuencia anterior define los elementos que intervienen desde un punto de vista del intercambio de mensajes los cuales son: Extractor, el cual realiza las operaciones de extracción con la función extractData(); Transformed, el cual realiza la transformación de los datos con la función doTransformer(); Loader, el cual realiza las operaciones de carga con la función doLoader(); ModuleLayer, el cual contiene el programa que define las operaciones de coordinación del resto de elementos utilizados en la función run(); y, por último, un actor que activa el inicio de las operaciones.

Una vez identificados las entidades abstractas y el intercambio de mensajes, estamos en disposición de profundizar en los elementos físicos que intervienen en la solución y, para ello, emplearemos un diagrama de clases UML para definir la vista estática de la solución. Así, el diagrama de clases con la arquitectura software es la siguiente:

Comenzando en la parte superior del diagrama, tenemos los elementos que definen el extractor. Se define un objeto con nombre Extractor el cual tiene una relación de composición por valor con un trait llamado Service el cual define la operación de extracción con la función extractData; esta función, retorna un elemento de la librería ZIO de tipo IO el cual tiene los siguientes tipos: como valor erróneo, retorna una excepción de tipo ExtractException; y, como retorno de éxito, retorna un ADT de tipo ExtractDataResult. El objeto Extractor tiene un atributo con nombre live el cual define el módulo de ZIO ZLayer asociado a la clase que implementa el servicio ExtractorImpl. Para finalizar, se define un objeto de paquete para enlazar las funciones del objeto Extractor. El snippet del código es el siguiente:

  type Extractor = Has[Extractor.Service]
  object Extractor {
    trait Service {
      def extractData(): IO[ExtractorException, ExtractDataResult]
    }

    case class ExtractorImpl() extends Extractor.Service {
      override def extractData(): IO[ExtractorException, ExtractDataResult] =
        ZIO.succeed(OkExtract(id = 1, name = "Test1", result = true))
    }

    val live: ZLayer[Any, Nothing, Extractor] = ZLayer.succeed(ExtractorImpl())
  }
[...]
 import ModuleLayerExample4Module.Extractor
 package object extractor {
   def extractData = ZIO.accessM[Extractor](_.get.extractData())
 }

Continuando en la parte media del diagrama tenemos los elementos que definen el transformador Transformer. Se define un objeto con nombre Transformer el cual tiene una relación de composición por valor con un trait llamado Service el cual define la operación de transformación con la función doTransformer; esta función, retorna un elemento de la librería ZIO de tipo IO el cual tiene los siguientes tipos: como valor erróneo, retorna una excepción de tipo TransformerException; y, como retorno de éxito, retorna un ADT de tipo TransformedResult. El objeto Transformer tiene un atributo con nombre live el cual define el módulo de ZIO ZLayer asociado a la clase que implementa el servicio TransformedImpl. Para finalizar, se define un objeto para enlazar las funciones del objeto Transformer. El snippet del código es el siguiente:

  type Transformer = Has[Transformer.Service]
  object Transformer {
    trait Service {
      def doTransformer(data: ExtractDataResult): IO[TransformedException, TransformedResult]
    }

    case class TransformerImpl() extends Transformer.Service {
      override def doTransformer(data: ExtractDataResult): IO[TransformedException, TransformedResult] =
        data match {
          case dataIn: OkExtract => ZIO.succeed(OkTransformed(id = dataIn.id, name = dataIn.name, result = true))
          case _                 => ZIO.fail(BasicTransformedException())
        }
    }

    val live: ZLayer[Any, Nothing, Transformer] = ZLayer.succeed(TransformerImpl())
  }
[...]
import ModuleLayerExample4Module.Transformer
package object transformer {
  def transformer(data: ExtractDataResult) = ZIO.accessM[Transformer](_.get.doTransformer(data))
}

En la parte inferior del diagrama tenemos los elementos que definen el cargador Loader. Se define un objeto con nombre Loader el cual tiene una relación de composición por valor con un trait llamado Service el cual define la operación de carga con la función doLoader; esta función, retorna un elemento de la librería ZIO de tipo Task con un ADT de tipo LoaderResult. El tipo Task de ZIO es aquel tipo definido para tareas asíncronas. El objeto Loader tiene un atributo con nombre live el cual define el módulo de ZIO ZLayer asocoado a la clase que implementa el servicio LoaderImpl. Para finalizar, se define un objeto de paquete para enlazar las funciones del objeto Transformer. El snippet del código es el siguiente:

  type Loader = Has[Loader.Service]
  object Loader {
    trait Service {
      def doLoader(data: TransformedResult): Task[LoaderResult]
    }

    case class LoaderImpl() extends Loader.Service {
      override def doLoader(data: TransformedResult): Task[LoaderResult] =
        data match {
          case dataIn: OkTransformed =>
            ZIO.fromFuture(implicit ec => loaderData(dataIn)).mapError(msg => new ErrorLoaderException())
          case _ => ZIO.fail(BasicLoaderException())
        }
    }

    val live: ZLayer[Any, Nothing, Loader] = ZLayer.succeed(LoaderImpl())
  }
[...]
import ModuleLayerExample4Module.Loader
package object loader {
  def loader(data: TransformedResult) = ZIO.accessM[Loader](_.get.doLoader(data))
}

En la parte izquierda del diagrama, se define el módulo controlador ModuleLayerExample4 con el cual declaramos el programa con las definiciones de las operaciones del proceso ETL. El snippet del módulo es el siguiente:

  type Services = Extractor with Transformer with Loader with Logging

  // Log layer
  val envLog =
    Logging.console(
      logLevel = LogLevel.Info,
      format = LogFormat.ColoredLogFormat()
    ) >>> Logging.withRootLoggerName("ModuleLayerExample4")

  val appEnvironment = envLog >+> Extractor.live >+> Transformer.live >+> Loader.live

  def program(): ZIO[Services, Throwable, Boolean] = {
    (for {
      _               <- log.info("[START]")
      dataExtracted   <- extractData
      _               <- log.info(s"[extrated done] data = ${dataExtracted}")
      dataTransformed <- transformer(dataExtracted)
      _               <- log.info(s"[transformed done] data = ${dataTransformed}")
      dataLoaded      <- loader(dataTransformed).catchAllCause(cause => log.info(s"Exception Loader=${cause.prettyPrint}"))
      _               <- log.info(s"[loaded done] data = ${dataLoaded}")
      _               <- log.info(s"[END]")

    } yield { true }) orElse ZIO.succeed(false)

  }

  override def run(args: List[String]): URIO[ZEnv, ExitCode] = {
    (program()
      .catchAllCause(cause => putStrLn(s"Exception=${cause.prettyPrint}"))
      .exitCode)
      .provideCustomLayer(appEnvironment)

  }

Lo primero que se define es el tipo Services el cual contiene las funciones a utilizar; en nuestro caso, definimos un tipo con un conjunto de tipos: Extractor, Transforamer, Loader y Logging definidos previamente. El objetivo de este tipo es definir todas aquellas funciones que estarán disponibles en el programa a declarar, en nuestro caso, el programa que declara la funcionalidad del proceso ETL, así, podremos “inyectar” al programa las funciones que necesitemos.

A continuación, se define la referencia al log y al entorno de ejecución del programa, es decir, define aquellos elementos que contienen las implementaciones de las funciones a utilizar.

Para finalizar se define la función que contiene el programa con las operaciones de la ETL. La función retorna un tipo ZIO con la siguiente composición: como entorno de ejecución, tiene un tipo de tipo Services; como tipo de retorno de error define un tipo Throwable; y, como tipo de resultado de éxito, retorna un tipo Boolean.

Dado que el módulo ModuleLayerExample4 es un objeto de la clase zio.App se debe de definir e implementar la función run() la cual realiza la invocación del la función del programa ETL suministrando las capas de los módulos definidas en el elemento appEnvironment.

Al lector interesado puede acceder al código en el siguiente enlace.

La utilización de la librería ZIO permite tener programas modulares, declarativos y seguros. No tenemos que preocuparnos de realizar una inyección de dependencias sino que hay que definir conjunto de tipos con la funcionalidad necesarias la cual utilizaremos en los programas; y, sobre todo, aclarar el proceso de diseño y desarrollo ya que permite definir los componentes o módulos que intervienen en la solución y sus relaciones. Una vez que se tienen claros los módulos y las firmas de los métodos nos permite sin haber desarrollado cada función una estructura de la solución final.

ZIO III: testing

Continuamos con al serie de la librería ZIO. En la entrada que estamos tratando, ZIO III: testing, me centraré en la definición de test. Las entradas publicadas hasta la fechas son las siguientes:

Los ejemplos mostrados en las entradas anteriores, se han realizado utilizando aserciones de test de prueba o bien mediante código no definido en un test. Para definir test y aserciones claras y concisas, definiremos unos patrones y ejemplos en los siguientes apartados, lo cuáles son:

  • Ejemplo de plantillas.
  • Generación de propiedades en los test.
  • Ejemplo de aserciones.

1.- Ejemplo de plantillas

Las pruebas unitarias tienen que ser categorizadas por funcionalidad y, para conseguir categorias funciones de test, empleamos la función suite. La función suite permite definir pruebas agrupados por una funcionalidad a probar. El conjunto de todas las agrupaciones forman las pruebas de una entidad.

Un requerimiento para la definición de test es que cada clase de test debe de heredar de la clase DefaultRunnableSpec la cual proporciona todos los módulos de ZIO; como por ejemplo: Clock o Random. Un ejemplo de test es el descrito en la siguiente entrada:

import zio.test._
import zio.clock.nanoTime
import Assertion._

import zio.test.DefaultRunnableSpec

object TemplateZioTest extends DefaultRunnableSpec {

    val suite1 = suite("suite1")(
      testM("s1.t1") { assertM(nanoTime)(isGreaterThanEqualTo(0L)) },
      testM("s1.t2") { assertM(nanoTime)(isGreaterThanEqualTo(0L)) }
    )

    val suite2 = suite("suite2")(
      testM("s2.t1") { assertM(nanoTime)(isGreaterThanEqualTo(0L)) },
      testM("s2.t2") { assertM(nanoTime)(isGreaterThanEqualTo(0L)) },
      testM("s2.t3") { assertM(nanoTime)(isGreaterThanEqualTo(0L)) }
    )

    val suite3 = suite("suite3")(
      testM("s3.t1") { assertM(nanoTime)(isGreaterThanEqualTo(0L)) }
    )

    def spec = suite("All test")(suite1, suite2, suite3)

}

2.- Generación de propiedades en los test.

En cierto tipo de test requerimos de datos para ejecutar las pruebas. Los datos pueden ser generados de forma automática por generadores los cuales pueden generar datos primitivos, case class o bien objetos. La entidad para la generación de datos es la entidad Gen definida en zio.test.Gen.

Un requisito fundamental es la necesidad de utilizar el módulo Random con Sized en la definición de los generadores.
Las dependencias de los módulos de los ejemplos es el siguiente:

import zio.test.Assertion.{equalTo, isTrue}
import zio.test.{DefaultRunnableSpec, Gen, Sized, assert, check, suite, testM}
import zio.random.Random
import zio.test.magnolia._
  • Ejemplo de generación de tipos primitivos.

Para la generación de tipos primitivos invocaremos a la función anyXXX, siendo XXX un tipo primitivo, en la definición de test. Un ejemplo de uso de generadores primitivos es el que se define en el siguiente snippet.

testM("Gen Int") {
   check(Gen.anyInt, Gen.anyInt, Gen.anyInt) { (x, y, z) =>
     assert((x + y) + z)(equalTo(x + (y + z)))
   }
},
  • Ejemplo de generación de una case class.

Sea una case class que represente una entidad con nombre Point. Para poder definir una generador de la clase Point, utilizamos la entidad DeriveGen cuyo tipo sea la case class Point. La definición de la clase y el generador de la clase Point es la siguiente:

final case class Point(x: Double, y: Double) {
   def isValid(): Boolean = true
}
val genPoint: Gen[Random with Sized, Point] = DeriveGen[Point]

Para definir el test de la entidad Point con su generador utilizaremos la función check como se muestra en el siguiente ejemplo:

testM("Gen Point") {
  check(genPoint) { (point) =>
     assert(point.isValid())(equalTo(true))
   }
},
  • Ejemplo de generación de objetos.

De la misma manera que el caso anterior para definir un generador de unos objetos a partir de un trait, se realiza de la misma manera. En el siguiente ejemplo, se define el test en donde se utiliza un generador de objetos basados en la definición de un trait:

sealed trait Color {
  def isValid(): Boolean = true
}
case object Red   extends Color
case object Green extends Color
case object Blue  extends Color
val genColor: Gen[Random with Sized, Color] = DeriveGen[Color]

testM("Gen Color") {
   check(genColor) { (color: Color) =>
      assert(color.isValid())(isTrue)
   }
}

3.- Ejemplo de aserciones.

La capacidad de poder verificar todo tipo de dato en una prueba permite definir con más exactitud la ejecución de una prueba. En ZIO empleamos las funciones definidas en la entidad zio.test.Assertion; como pueden ser: equalTo, hasField, isRight,etc…

A continuación, muestro unos ejemplos de pruebas con diferentes tipos de aserciones:

  • Ejemplo de un String.

Supongamos que necesitamos verificar el resultado de un efecto cuyo resultado es un String y, del valor del resultado,
necesitamos verificar que contenga un determinado valor y finalice con otro. La aserción la realizamos empleando la función assert y las funciones containsString y endsWithString de la siguiente manera:

testM("Assertion examples: string") {
  for {
    word <- IO.succeed("The StringTest")
  } yield {
    assert(word)(
       Assertion.containsString("StringTest") &&
          Assertion.endsWithString("Test")
     )
   }
},
  • Ejemplo de un Either.

Supongamos que necesitamos verificar el resultado de un efecto cuyo resultado es un Either. El esquema del test es parecido al anterior pero empleando funciones específicas para el contenedor binario. El ejemplo del snippet es el siguiente:

testM("Assertion examples: either") {
  for {
     either <- IO.succeed(Right(Some(2)))
  } yield {
     assert(either)(isRight(isSome(equalTo(2))))
  }
},
  • Ejemplo de una case class.

Supongamos que necesitamos verificar el resultado de un efecto que retorna una entidad definida en una case class. El esquema del test es como los anteriores pero utilizando la función hasField para acceder a los atributos de la entidad. El ejemplo del snippet es el siguiente:

testM("Assertion examples: case class") {
   final case class Address(country: String, city: String)
   final case class User(name: String, age: Int, address: Address)

   for {
      test <- IO.succeed(User("Nat", 25, Address("France", "Paris")))
   } yield {
      assert(test)(
        hasField("age", (u: User) => u.age, isGreaterThanEqualTo(18)) &&
          hasField("country", (u: User) => u.address.country, not(equalTo("USA")))
      )
   }
},

En la siguiente entrada, ZIO IV: modularización, me centraré en la definición de módulos funcionales.

ZIO II: manejo de errores y recursos

En la entrada anterior, ZIO I: presentación, presenté la librería ZIO y ejemplos con la creación de efectos y operaciones básicas. En la presente entrada, ZIO II: manejo de errores y recursos, describiré cómo podemos manejar errores en la ejecución de efectos con ZIO y el manejo de recursos.

ZIO

La estructura de la entrada está compuesta de los siguientes apartados:

  1. Manejo de errores.
  2. Manejo de recursos.

1.- Manejo de errores

Dada la definición de un efecto en ZIO, sabemos cómo proporcionar el entorno y ejecutar dicho efecto; pero, tenemos que dar respuesta a la siguiente pregunta: ¿cómo podemos realizar el control de la ejecución si se produce un error en la ejecución del efecto? La respuesta es sencilla, el control del efecto se realiza capturando y controlando las excepciones que se puedan originar, así como, si se produce un error tener la posibilidad de poder volver a ejecutar el efecto.

  • Tratamiento de error con el contenedor binario Either.

La primera estrategia es empleando un contenedor binario Either mediante la función either en la cual podemos tener los siguientes valores: en Left, el valor de error; o bien en right, el resultado correcto. Este primer ejemplo es el más sencillo porque se asemeja al control de errores de una función.

El ejemplo más básico de la definición de un ejemplo es el siguiente:

val zeither: UIO[Either[String, Int]] = IO.fail("Boom!").either
val result: Either[String, Int]       = Runtime.default.unsafeRun(zeither)
assertResult(Left("Boom!"))(result)
  • Tratamiento de error en un efecto con el tipo explícito.

Supongamos que tenemos un efecto cuyo posible error lo conocemos; supongamos que el efecto, es la lectura de un fichero y, como conocemos, el error en el tratamiento de un fichero es la generación de una excepción de tipo IOException. La solución consiste en la definición de un efecto en el que definamos el tipo de error y su resultado; en concreto, la solución consiste en definir un efecto cuyo tipo de error es una excepción de tipo IOException y su resultado es un tipo List[String] definiendo un tipo UIO[IOException, List[String]].

En el siguiente ejemplo, se define una función que realiza la lectura de un fichero mediante un efecto de tipo UIO, su ejecución y verificación de tratamiento.

def readFile(nameFile: String): UIO[List[String]] = {
  IO.succeed(Source.fromFile(nameFile).getLines().toList)
}
val readFileResult: IO[IOException, List[String]] = readFile(getURIFileTest(nameFile).getPath)
val resultReadFileOK: List[String]                = Runtime.default.unsafeRun(readFileResult)
assert(resultReadFileOK.isEmpty === false)
assertResult(List("1 2 3", "4 5 6"))(resultReadFileOK)
  • Tratamiento de errores con la función catchAll.

Supongamos que realizamos la lectura de un fichero y queremos capturar todas las posibles excepciones que se puedan producir; para este escenario, utilizamos la función catchAll definida en ZIO. En el siguiente ejemplo, realizamos la lectura de las líneas de un fichero cuyo nombre es pasado por parámetro y, con la función catchAll, capturamos todas las excepciones. Si se produce una excepción entonces realizamos la lectura de un fichero cuyos datos son valores por defecto. El snippet de ejemplo es el siguiente:

 def readFileCatchAll(nameFile: String): Task[List[String]] = {
   ZIO(Source.fromFile(nameFile).getLines().toList).catchAll {
     case _ => {
       val uriFile = this.getClass.getClassLoader.getResource("default.data").toURI
       readFile(uriFile.getPath)
     }
   }
 }

 val readFileOK: Task[List[String]] = readFileCatchAll(getURIFileTest(nameFile).getPath)
 val resultReadFileOK: List[String] = Runtime.default.unsafeRun(readFileOK)
 assert(resultReadFileOK.isEmpty === false)
 assertResult(List("1 2 3", "4 5 6"))(resultReadFileOK)

 val readFileKO: Task[List[String]] = readFileCatchAll("errorFile.data")
 val resultReadFileKO: List[String] = Runtime.default.unsafeRun(readFileKO)
 assert(resultReadFileKO.isEmpty === false)
 assertResult(List("OK"))(resultReadFileKO)
  • Tratamiento de un error con la función catchSome.

Supongamos que queremos capturar un tipo determinado de excepción, en este supuesto utilizamos la función catchSome. En el siguiente ejemplo, se muestra el mismo ejemplo del apartado anterior pero realizando el tratamiento para la excepción FileNotFoundException. El snippet del ejemplo es el siguiente:

 def readFileOrDefault(nameFile: String): Task[List[String]] = {
   ZIO(Source.fromFile(nameFile).getLines().toList).catchSome {
     case _: FileNotFoundException => {
       val uriFile = this.getClass.getClassLoader.getResource("default.data").toURI
       readFile(uriFile.getPath)
     }
   }
 }

val readFileOK: Task[List[String]] = readFileOrDefault(getURIFileTest(nameFile).getPath)
val resultReadFileOK: List[String] = Runtime.default.unsafeRun(readFileOK)
assert(resultReadFileOK.isEmpty === false)
assertResult(List("1 2 3", "4 5 6"))(resultReadFileOK)

val readFileKO: Task[List[String]] = readFileOrDefault("errorFile.data")
val resultReadFileKO: List[String] = Runtime.default.unsafeRun(readFileKO)
assert(resultReadFileKO.isEmpty === false)
assertResult(List("OK"))(resultReadFileKO)
  • Ejecución de un efecto alternativo con la función orElse.

Supongamos que queremos ejecutar un efecto y, suponiendo que se produzca un error en el efecto, deseamos que se ejecute un efecto secundario; para este supuesto, utilizamos la función orElse. En el siguiente snippet de código se muestra el ejemplo con la función orElse.

def readFileFallback(nameFile: String): Task[List[String]] = {
   ZIO(Source.fromFile(nameFile).getLines().toList).orElse {
     val uriFile = this.getClass.getClassLoader.getResource("default.data").toURI
     readFile(uriFile.getPath)
    }
}

val readFileOK: Task[List[String]] = readFileFallback(getURIFileTest(nameFile).getPath)
val resultReadFileOK: List[String] = Runtime.default.unsafeRun(readFileOK)
assert(resultReadFileOK.isEmpty === false)
assertResult(List("1 2 3", "4 5 6"))(resultReadFileOK)

val readFileKO: Task[List[String]] = readFileFallback("errorFile.data")
val resultReadFileKO: List[String] = Runtime.default.unsafeRun(readFileKO)
assert(resultReadFileKO.isEmpty === false)
assertResult(List("OK"))(resultReadFileKO)
  • Tratamiento de un efecto de forma no pura.

Supongamos que queremos retornar el resultado y no realizar un tratamiento específico, es decir, si el efecto se ejecuta sin problemas retornamos el resultado; pero, si se produce un error retornamos un resultado del tipo esperado; para este supuesto, utilizamos la función fold. En el siguiente snippet de código se muestra el ejemplo con la función fold:

def readFileFold(nameFile: String): Task[List[String]] = {
  ZIO(Source.fromFile(nameFile).getLines().toList).fold(_ => List("OK"), data => data)
}

val readFileOK: Task[List[String]] = readFileFold(getURIFileTest(nameFile).getPath)
val resultReadFileOK: List[String] = Runtime.default.unsafeRun(readFileOK)
assert(resultReadFileOK.isEmpty === false)
assertResult(List("1 2 3", "4 5 6"))(resultReadFileOK)

val readFileKO: Task[List[String]] = readFileFold("errorFile.data")
val resultReadFileKO: List[String] = Runtime.default.unsafeRun(readFileKO)
assert(resultReadFileKO.isEmpty === false)
assertResult(List("OK"))(resultReadFileKO)
  • Tratamiento de un efecto de forma pura.

El caso contrario al ejemplo anterior es definir un efecto para el caso de éxito y caso de error mediante la función foldM. En el siguiente snippet de código se muestra el ejemplo con la función foldM.

def readFileFoldM(nameFile: String): Task[List[String]] = {
  ZIO(Source.fromFile(nameFile).getLines().toList)
    .foldM(_ => ZIO.succeed(List("OK")), data => ZIO.succeed(data))
}

val readFileOK: Task[List[String]] = readFileFoldM(getURIFileTest(nameFile).getPath)
val resultReadFileOK: List[String] = Runtime.default.unsafeRun(readFileOK)
assert(resultReadFileOK.isEmpty === false)
assertResult(List("1 2 3", "4 5 6"))(resultReadFileOK)

val readFileKO: Task[List[String]] = readFileFoldM("errorFile.data")
val resultReadFileKO: List[String] = Runtime.default.unsafeRun(readFileKO)
assert(resultReadFileKO.isEmpty === false)
assertResult(List("OK"))(resultReadFileKO)
  • Tratamiento con reintento de ejecución.

Supongamos que queremos reintentar ejecutar un efecto si se produce un error un número determinado de veces y,
si dado ese número de reintentos no tenemos éxito, capturar la excepción y retornar un efecto con un resultado por defecto; para este caso, utilizamos la función retry para definir un número de reintentos con un Schedule y la función catchAll. El snippet de código con el ejemplo es el siguiente:

import zio.clock.Clock
  [...]
  def readFileRetrying(nameFile: String): ZIO[Clock, Throwable, List[String]] = {
    ZIO(Source.fromFile(nameFile).getLines().toList)
      .retry(Schedule.recurs(5))
      .catchAll { case _ =>
        ZIO.succeed(List("OK"))
      }
}

val readFileOK: ZIO[Clock, Throwable, List[String]] = readFileRetrying(getURIFileTest(nameFile).getPath)
val resultReadFileOK: List[String]                  = Runtime.default.unsafeRun(readFileOK)
assert(resultReadFileOK.isEmpty === false)
assertResult(List("1 2 3", "4 5 6"))(resultReadFileOK)

val readFileKO: ZIO[Clock, Throwable, List[String]] = readFileRetrying("errorFile.data")
val resultReadFileKO: List[String]                  = Runtime.default.unsafeRun(readFileKO)
assert(resultReadFileKO.isEmpty === false)
assertResult(List("OK"))(resultReadFileKO)

Para el lector interesado en el código de los ejemplos, puede acceder al mismo a través del siguiente enlace.

2.- Manejo de recursos

Para el manejo de recursos es necesario definir un patrón estructural basado en la estructura try/finally. Supongamos que definimos un efecto y, una vez que finaliza su ejecución, queremos ejecutar un segundo efecto de finalización; para ello, utilizamos la función ensuring. Un ejemplo de patron try/finally con efectos en ZIO es el siguiente:

val finalizer2: UIO[Unit] = UIO.effectTotal(println("finally"))
val operation: UIO[Unit] = IO.succeed(println("Finalizing 2!")).ensuring(finalizer2)
val resultOperation      = Runtime.default.unsafeRun(operation)
assertResult(())(resultOperation)

Otra forma de aplicar el patrón try/finally es utilizando la función bracket en la cual se realiza una adquisición de un recurso, una tratamiento y un cierre de recurso. Un ejemplo de utilización de función bracket con un fichero es el siguiente:

def readFileBracket(nameFile: String): Task[List[String]] =
  UIO(Source.fromFile(nameFile)).bracket(bufferedSource => UIO(bufferedSource.close())) { file =>
    UIO(file.getLines().toList)
  }

val file: Task[List[String]] = readFileBracket(getURIFileTest(nameFile).getPath)
val resultFile               = Runtime.default.unsafeRun(file)
assertResult(List("1 2 3", "4 5 6"))(resultFile)

Para el lector interesado en el código de los ejemplos, puede acceder al mismo a través del siguiente enlace.

En el siguiente ejemplo, ZIO III: testing, describiré unos patrones para la realización de test con ZIO.

ZIO I: presentación

Inicio una serie de entradas de la librería ZIO. En la presente entrada, ZIO I: presentación, realizaré una presentación y realizaré unos ejemplos básicos introductorios.

ZIO es aquella librería en Scala para ejecutar tareas asíncronas y tareas de programación concurrente la cual es una librería funcional pura. La librería está inspirada en la mónada IO de Haskell.

El tipo de dato ZIO está compuesta por tres parámetros como sigue: ZIO[R, E, A]. Los tipos tienen la siguiente definición semántica:

  • R , Tipo de entorno.- El efecto requiere un tipo de entorno representado por R. Si el tipo está definido como Any, significa que no tiene requerimiento porque no necesitas un valor.
  • E , Tipo de fallo.- El efecto puede terminar en error con un tipo definido en E. Si puede terminar con error, se define con el tipo Throwable; si no puede terminar con error, se define con el tipo Nothing.
  • A, Tipo de éxito.- El efecto puede terminar con un tipo de éxito representado por el tipo A. Si el tipo es Unit, significa que el efecto no retorna información; si el tipo es Nothing, significa que el efecto está corriendo de forma indefinida

Unos ejemplos de definición de un tipo ZIO pueden ser los siguientes:

  • ZIO[Any, IOException, String].- Definición de un tipo que no tiene un requerimiento, retorna un valor de tipo String y, si se produce un error, retorna un elemento de tipo IOException.
  • ZIO[String, Throwable, Int].- Definición de un tipo con un requerimiento de tipo String, retorna un valor de tipo entero y, si se produce un error, retorna un elemento de tipo Throwable.

El requerimiento hay que visualizarlo como el valor de entrada al efecto para que sea procesado.

La librería ZIO define un conjunto de alias para poder trabajar de forma sencilla. Los alias definidos son las siguientes:

  • IO[E, A].- IO es el alias de ZIO[Any, E, A]. Define un efecto que no tiene requerimientos, el error puede ser de tipo E y el resultado es de tipo A.
  • UIO[A].- UIO es el alias de ZIO[Any, Nothing, A]. Define un efecto que no tiene requerimientos,
  • URIO[R, A].- URIO es el alias de ZIO[R, Nothing, A]. Define un efecto que tiene un requerimiento de tipo R, no puede tener un error y el resultado es de tipo A.
  • Task[A].- Task es el alias de ZIO[Any, Throwable, A]. Define un efecto que no tiene un requerimiento, el tipo de error es de tipo Throwable y el resultado es de tipo A.
  • RIO[R, A].- RIO es el alias de ZIO[R, Throwable, A]. Define un efecto que tiene un requerimiento de tipo R, el tipo de error es de tipo Throwable y el resultado de de tipo A.

La definición de las dependencias de la librería ZIO en un proyecto gestionado con sbt son las siguientes:

val zio = "1.0.3"
lazy val zio_core  = "dev.zio" %% "zio" % Versions.zio
lazy val zio_streams  = "dev.zio" %% "zio-streams" % Versions.zio
lazy val zio_test = "dev.zio" %% "zio-test"  % Versions.zio % "test"
lazy val zio_test_sbt = "dev.zio" %% "zio-test-sbt"  % Versions.zio % "test"
lazy val zio_test_magnolia = "dev.zio" %% "zio-test-magnolia" % Versions.zio % "test" 

La estructura de la entrada está compuesta de los siguientes apartados:

  1. Creación de efectos.
  2. Operaciones básicas.

1.- Creación de efectos

En el presente apartado, mostraré ejemplos básicos para la definición de efectos con ZIO. Son ejemplos muy simples pero son aclaratorios para dar los primeros pasos. La definición de efectos se muestra en los siguientes puntos:

  • Efecto succeed.- empleamos la función succeed para crear un efecto cuyo resultado es exitoso.
val int42 = for {
   intS1 <- ZIO.succeed(42)
} yield (intS1)
val resultInt42 = Runtime.default.unsafeRun(int42)
assert(42 === resultInt42)
  • Efecto fail.- empleamos la función fail para crear un efecto cuyo resultado no es satisfactorio.
val f1: zio.URIO[Any, Either[String, Nothing]] = ZIO.fail("Uh oh!").either
val resultFailf1: Either[String, Nothing]      = Runtime.default.unsafeRun(f1)
assertResult(resultFailf1)(Left("Uh oh!"))
  • Efecto effectTotal.- empleamos la función effectTotal cuando estamos seguro que el efecto no tiene un efecto de lado.
val effectTotal: Task[Long] = ZIO.effectTotal(System.currentTimeMillis())
val resultEffectTotal: Long = Runtime.default.unsafeRun(effectTotal)
assert(resultEffectTotal > 0)
  • Efecto fromOption.- empleamos la función fromOption para crear un efecto a partir de un tipo Option.
val zoption: IO[Option[Nothing], Int] = ZIO.fromOption(Some(2))
val resultZOption: Int                = Runtime.default.unsafeRun(zoption)
assert(2 === resultZOption)
  • Efecto fromEither.- empleamos la función fromEither para crear un efecto a partir de un tipo Either.
val zeither: IO[Either[Exception, String], String] = ZIO.fromEither(Right("Success"))
val resultZeither: String                                         = Runtime.default.unsafeRun(zeither)
assert("Success" === resultZeither)
  • Efecto fromTry.- empleamos la función fromTry para crear un efecto a partir de un tipo Try.
 val ztry: Task[Int] = ZIO.fromTry(Try(40 / 2))
 val resultZTry: Int = Runtime.default.unsafeRun(ztry)
 assert(20 === resultZTry)
  • Efecto fromFunction.- empleamos la función fromFuction para crear un efecto a partir de una función.
val zfun: URIO[Int, Int] = ZIO.fromFunction((i: Int) => i * i)
val resultZfun: Int      = Runtime.default.unsafeRun(zfun.provide(5))
assert(25 === resultZfun)
  • Efecto fromFuture.- empleamos la función fromFuture para crear un efecto a partir de un Future.
lazy val future = Future.successful("Hi!")
val zfuture: Task[String] = ZIO.fromFuture { implicit ec =>
   future.map(_ => "Goodbye!")
}
val resultZFuture: String = Runtime.default.unsafeRun(zfuture)
assert("Goodbye!" === resultZFuture)
  • Efecto desde un efecto de lado.- Definimos una función con un efecto de lado, en el ejemplo, escribir un texto en la consola.
def putStrLn(line: String): UIO[Unit] =
  ZIO.effectTotal(println(line))
val resultPut: Unit = Runtime.default.unsafeRun(putStrLn("Test"))
assert(resultPut === ())

Para el lector interesado, puede acceder al código de los ejemplos del apartado mediante el siguiente enlace.

2.- Operaciones básicas

Una vez visto cómo podemos crear efectos en ZIO, estamos en disposición de mostrar ejemplos de operaciones básicas. Las operaciones consisten en la declaración de un programa con un conjunto de operaciones; esas operaciones, pueden ser puras, o bien, pueden tener efectos de lado, por ejemplo: la lectura desde consola, o bien, escribir en la salida estándar. El primer ejemplo que voy a mostrar es la definición de una función que muestre un mensaje por pantalla y la lectura de consola. Para realizar el programa, definiremos dos funciones: getStrlLn, función que realiza la lectura por consola; putStrLn, función que escribe un mensaje en la consola. La definición de las funciones son las siguientes:

val getStrLn: Task[String] = ZIO.effect(StdIn.readLine())
def putStrLn(line: String): UIO[Unit] = ZIO.effectTotal(println(line))

Una vez definido las funciones básicas, definimos el programa que realiza la concatenación de las funciones anteriores mediante la función exampleChaining y, como segunda opción, definimos el mismo programa utilizando for comprehension. Los snippet de las funciones son las siguientes:

def exampleChaining(): Unit = {
      val operation1 = getStrLn.flatMap(input => putStrLn(s"-->${input}"))
      Runtime.default.unsafeRun(operation1)
}

def exampleForComprenhensions(): Unit = {
      val program = for {
        _    <- putStrLn("Nombre")
        name <- getStrLn
        _    <- putStrLn(s"Value=${name}")
      } yield ()
      Runtime.default.unsafeRun(program)
}

Otra forma de encadenar efectos es utilizando la función zip, zipRight, o bien, zipLeft. En el siguiente ejemplo, se muestan ejemplos parecidos a los anteriores con la función zipRight y su alias *>. Hay que destacar que la función zipRight realiza la concatenación de efectos y, además, ejecuta una función map para tratar el resultado del primer efecto. El snippet del código es el siguiente:

def exampleZipping(): Unit = {
      val zipRight1               = putStrLn("Name Right 1?").zipRight(getStrLn)
      val resultZipRight1: String = Runtime.default.unsafeRun(zipRight1)
      println(s"=>${resultZipRight1}")
      val zipRight2               = putStrLn("Name Right 2?") *> getStrLn
      val resultZipRight2: String = Runtime.default.unsafeRun(zipRight2)
      println(s"=>${resultZipRight2}")
}

Para el lector interesado, puede acceder al código de los ejemplos del apartado mediante el siguiente enlace.

En la siguiente entrada, ZIO II: manejo de errores y recursos, continuaremos describiendo la librería ZIO centrándonos en cómo se manejan errores y recursos mediante.

HTTP4S: Introducción

La primera solución para implementar servicios o microservicios en Scala es utilizar AKKA HTTP; pero, con las prestaciones de librerías como Cats, ha permitido la creación de librerías como HTTP4S. En la presente entrada, HTTP4s: Introducción, realizaré una breve descripción para la creación de servicios con la librería HTTP4S.

Definición de dependencias

La definición de dependencias y la gestión del ciclo de desarrollo del software se realizará con sbt. La versión de Scala a utilizar es la versión 2.13.4. Las librería utilizadas son las siguientes:

  • http4s_%.- librerías específicas de http4s.
  • munit_%.- librerías específicas para la realización de test.
  • circe_%.- librerías específicas para el tratamiento de componentes JSON.

El snippet del código con la definición de un módulo que utilice la librería HTTP4s es el siguiente:

val munit = "0.7.20"
val munit_cats_effect_version = "0.12.0"
val http4s = "0.21.14"
val circe = "0.13.0"
[…]
lazy val munit = "org.scalameta" %% "munit" % Versions.munit % Test
lazy val munit_cats_effect_2 = "org.typelevel" %% "munit-cats-effect-2" % Versions.munit_cats_effect_version % Test
lazy val http4s_blaze_server = "org.http4s" %% "http4s-blaze-server" % Versions.http4s
lazy val http4s_blaze_client = "org.http4s" %% "http4s-blaze-client" % Versions.http4s
lazy val http4s_dsl = "org.http4s" %% "http4s-dsl" % Versions.http4s
lazy val http4s_circe = "org.http4s" %% "http4s-circe" % Versions.http4s
lazy val circe_generic = "io.circe" %% "circe-generic" % Versions.circe
lazy val circe_literal = "io.circe" %% "circe-literal" % Versions.circe
[…]
lazy val http4s = (project in file("http4s"))
 .settings(
    name := "example-http4s",
    assemblySettings,
    scalacOptions ++= basicScalacOptions,
    testFrameworks += new TestFramework("munit.Framework"),
    libraryDependencies ++=
    http4sDependencies ++ Seq(
      scalaTest,
      munit,
      munit_cats_effect_2
    )
  )
  lazy val http4sDependencies = Seq(
     http4s_blaze_server,
     http4s_blaze_client,
     http4s_circe,
     http4s_dsl,
     circe_generic,
     circe_literal
   )

Definición de Servicios

No me centrará en definir qué es un micro-servicio o servicio ya que ha sido definido y descrito en otras entradas. Desde el punto de vista de la librería HTTP4s, un servicio es aquella definición de un método HTTP el cual, dado un path determinado, recibe una petición HTTP, realiza una funcionalidad determinada y, como resultado, retorna una respuesta HTTP.

HTTP4s está basada en la librería Cats y, al definir operaciones con efecto de lado, emplearemos como tipo parametrizado el componente IO.

El servicio lo definieremos con la función of del componente HttpRoutes, definiremos el tratamiento a realizar en función del método HTTP junto al path del recurso; para cada método, se realizará la creación de una respuesta con el componente Ok.

El servicio es definido y utilizado en un objeto de tipo aplicación de entrada salida IOApp el cual, con la definición de la función run, arranca la aplicación y levanta el servicio. Esta clase es propia de la librería Cats. La función run realiza la creación de un server con el objeto de tipo BlazeServerBuilder al cual se le configura con el servicio, el puerto y el host deseado.

En los siguiente apartados, se definen ejemplos de definición de servicios con HTTP4s.

Ejemplo de servicio básico

Ejemplo básico de tipo “Hello World” donde se define un servicio HTTP con método GET. El código de ejemplo es el siguiente:

import cats.effect._
import org.http4s._
import org.http4s.dsl.io._
import scala.concurrent.ExecutionContext.Implicits.global
import org.http4s.server.blaze._
import org.http4s.implicits._
object ServiceEjem1 extends IOApp {

  val helloWorldService = HttpRoutes
     .of[IO] { 
        case GET -> Root / "hello" / name => Ok(s"Hello, $name.")
     }.orNotFound

  def run(args: List[String]): IO[ExitCode] =
     BlazeServerBuilderIO
       .bindHttp(8080, "localhost")
       .withHttpApp(helloWorldService)
       .serve
       .compile
       .drain
       .as(ExitCode.Success)
}

Para probar el servicio anterior desde la línea de comando, se utiliza el siguiente comando curl:

curl http://localhost:8080/hello/Pete

Test

Para realizar el test del ejemplo anterior, usaremos el framework MUnit. La definición del test consiste en la declaración de una clase que herede de munit.FunSuite, en nuestro caso, la clase ServiceEjem1Test; ésta, define los test de prueba con la función test y, la verificación de resultado, se realiza con las funciones assert.

Dado que el servicio creado se implementa como una función Kleisli, no es necesario arrancar un server para realizar pruebas, con lo cual, el proceso de pruebas es un proceso de test de una función, simplificando dichas tareas.

La clase de test del servicio anterior es la siguiente:

import cats.effect._
import org.http4s._
import org.http4s.implicits._
class ServiceEjem1Test extends munit.FunSuite {

  test("Test ServiceEjem1 OK") {
     val service = ServiceEjem1.helloWorldService
     val requestTest = Request[IO](Method.GET, uri"/hello/test")
     val result = service.run(requestTest).unsafeRunSync()
     assertEquals(result.status, Status.Ok)
  }

  test("Test ServiceEjem1 KO") {
     val service = ServiceEjem1.helloWorldService
     val requestTest = Request[IO](Method.GET, uri"/hello")
     val result = service.run(requestTest).unsafeRunSync()
     assertEquals(result.status, Status.NotFound)
  }

}

La prueba consiste en la creación de una referencia al servicio, definido con el objeto service; definición de la petición HTTP, definido en el objeto requestTest; y, para su ejecución, emplearemos la función run() y unsafeRunSync(); el resultado, se recoge en el objeto result el cual es utilizado en las funciones assert.

Composición de servicios

Un servicio está implementado como una función Kleisli y, la composición de funciones Kleisli, se realiza combinado dichas funciones. Para ello, utilizamos la función <+> la cual está definida en la sintaxis de la librería cuyo paquete es cats.syntax.all._.

En el código ejemplo, se define un servicio básico tipo “Hola Mundo” en el objeto helloWorldService y se define un servicio tweeService. El servicio tweetService define dos métodos para dos endpoints diferentes. La composición se define en el objeto services con la función <+>.

Una vez definido la composición del servicio, se crea el enrutado de los servicios en el objeto httpApp; este objeto, será utilizada para levantar la aplicación en la función run.

El código de ejemplo es el siguiente:

object ServiceEjem2 extends IOApp {
   val helloWorldService = HttpRoutes.of[IO] { 
     case GET -> Root / "hello" / name => Ok(s"Hello, $name.")
   }
   case class Tweet(id: Int, message: String)
   […]

   def getTweet(tweetId: Int): IO[Tweet] = IO(Tweet(id = 1, message = "Tweet1"))

   def getPopularTweets(): IO[Seq[Tweet]] = IO(
      List(Tweet(id = 2, message = "Tweet2"), Tweet(id = 3, message = "Tweet3"))
   )

   val tweetService = HttpRoutes.of[IO] {
     case GET -> Root / "tweets" / "popular" =>
        getPopularTweets().flatMap(Ok()) 
     case GET -> Root / "tweets" / IntVar(tweetId) =>  
        getTweet(tweetId).flatMap(Ok())
   }
   val services = tweetService <+> helloWorldService

   val httpApp = Router("/" -> helloWorldService, "/api" -> services).orNotFound

   def run(args: List[String]): IO[ExitCode] =
      BlazeServerBuilder[IO](global)
        .bindHttp(7676, "localhost")
        .withHttpApp(httpApp)
        .serve
        .compile
        .drain
        .as(ExitCode.Success)
}

Test

La definición de los test se realiza con el mismo criterio del primer ejemplo. Para simplificar, me centraré los test del servicio compuesto y en la aplicación.

La estrategia de prueba sigue la misma secuencia, definición del servicio, definición de la petición de pruebas, ejecución y valoración de resultados.

El snippet de prueba es el siguiente:

[…]
test("Test ServiceEjem2.service (compose service) OK") {
   val service = ServiceEjem2.services
   val requestTestHello = Request[IO](Method.GET, uri"/hello/test")
   val resultHello = service.orNotFound(requestTestHello).unsafeRunSync()
   assertEquals(resultHello.status, Status.Ok)
   val requestTestTweet = Request[IO](Method.GET, uri"/tweets/popular")
   val resultTweet = service.orNotFound(requestTestTweet).unsafeRunSync()
   assertEquals(resultTweet.status, Status.Ok)
}
test("Test httpApp OK") {
   val httpApp = ServiceEjem2.httpApp
   val requestTestHello = Request[IO](Method.GET, uri"/hello/test")
   val resultHello = httpApp.run(requestTestHello).unsafeRunSync()
   assertEquals(resultHello.status, Status.Ok)
   val requestTestTweet = Request[IO](Method.GET, uri"/api/tweets/popular")
   val resultTweet = httpApp.run(requestTestTweet).unsafeRunSync()
   assertEquals(resultTweet.status, Status.Ok)
}
[…]

Definición de Middleware

En HTTP4S un middleware es un envoltorio de un servicio para poder manipular la petición enviada, o bien, la respuesta. La estrategia de definición de un middleware puede ser empleando una función, o bien, utilizando un objeto. En los siguientes apartados se muestran unos ejemplos prácticos.

Definición de un middleware mediante una función.

La forma básica para definir un middleware es empleando una función la cual recibe como parámetro un servicio y, como resultado, retorna una función kleisli representado en un HttpRoutes. El middleware ejecutará el servicio el cual, en función del resultado, modificará las cabeceras del objeto de respuesta. El resto de elementos sigue la misma estructura y función que los ejemplos de servicios.

El snippet del código es el siguiente:

object MiddlewareEjem1 extends IOApp {
   def myMiddle(service: HttpRoutes[IO], header: Header): HttpRoutes[IO] = Kleisli { (req: Request[IO]) =>
      service(req).map {
         case Status.Successful(resp) =>
             resp.putHeaders(header)
         case resp =>
             resp
      }
   }

   val service = HttpRoutes.of[IO] { 
     case GET -> Root / "hello" / name => Ok(s"Hello wrapper, $name.")
   }

   val wrappedService = myMiddle(service, Header("SomeKey", "SomeValue"))

   val apiService = HttpRoutes.of[IO] { 
     case GET -> Root / "rest1" => Ok("OK response API")
   }

   val httpRoute = Router("/" -> wrappedService, "/api" -> apiService).orNotFound

   def run(args: List[String]): IO[ExitCode] =
     BlazeServerBuilder[IO](global)
      .bindHttp(7676, "localhost")
      .withHttpApp(httpRoute)
      .serve
      .compile
      .drain
      .as(ExitCode.Success)
}

Test

Para definir las pruebas unitarias del middleware, igual que los servivios, se emplea el framework Munit; en nuestro caso, en el resultado se obtendrá las cabeceras asignadas por el middleware.

El snippet de las pruebas unitarias es el siguiente:

class MiddlewareEjem1Test extends munit.FunSuite {
   […]
   test("Test wrappedService MiddlewareEjem1 OK") {
     val service = MiddlewareEjem1.wrappedService
     val requestTest = Request[IO](Method.GET, uri"/hello/test")
     val result = service.orNotFound(requestTest).unsafeRunSync()
     assertEquals(result.status, Status.Ok)
     assertEquals(result.headers.get(CaseInsensitiveString("SomeKey")).get.value, "SomeValue")
   }
   […]
}

Definición de un middleware con un object.

Otra forma de definir el middleware es utilizando un objeto. El objeto implementará el método apply el cual tendrá la misma funcionalidad que la función del ejemplo anterior; en nuestro caso, se utiliza una función addHeader para modularizar más el código. El servicio que emplee este objeto, wrappedService, simplemente realiza la creación del objeto; posteriormente, se emplea en la creación del Router.

El snipper del código ejemplo es el siguiente:

object MiddlewareEjem2 extends IOApp {
   object MyMiddle {
     def addHeader(resp: Response[IO], header: Header): Response[IO] = resp match {
        case Status.Successful(resp) => resp.putHeaders(header)
        case resp => resp
     }

     def apply(service: HttpRoutes[IO], header: Header) =
        service.map(addHeader(_, header))
   }

   val service = HttpRoutes.of[IO] { 
      case GET -> Root / "middleware" / name =>
        Ok(s"Hello wrapper, $name.")
   }

   val wrappedService = MyMiddle(service, Header("SomeKey", "SomeValue"))

   val apiService = HttpRoutes.of[IO] { 
      case GET -> Root / "rest1" =>
        Ok("OK response API")
   }

   val httpRoute = Router("/" -> wrappedService, "/api" -> apiService).orNotFound
      def run(args: List[String]): IO[ExitCode] =
         BlazeServerBuilder[IO](global)
           .bindHttp(7676, "localhost")
           .withHttpApp(httpRoute)
           .serve
           .compile
           .drain
           .as(ExitCode.Success)
}

Test

La definicón del test del ejemplo anterior sigue la misma estructura que los ejemplos anteriores. El Snippet con el código de test es el siguiente:

[…]
test("Test wrappedService MiddlewareEjem1 OK") {
   val service = MiddlewareEjem2.wrappedService
   val requestTest = Request[IO](Method.GET, uri"/middleware/test")
   val result = service.orNotFound(requestTest).unsafeRunSync()
   assertEquals(result.status, Status.Ok)
   assertEquals(result.headers.get(CaseInsensitiveString("SomeKey")).get.value, "SomeValue")
}
[…]

Composición de un middleware y un servicio.

La composición de middleware sigue el mismo criterio que los servicios porque son funciones kleisli. El ejemplo de una composición de middleware es el siguiente:

object MiddlewareEjem3 extends IOApp {

  object MyMiddle {
    def addHeader(resp: Response[IO], header: Header): Response[IO] = resp match {
      case Status.Successful(resp) => resp.putHeaders(header)
      case resp => resp
    }

    def apply(service: HttpRoutes[IO], header: Header) =
      service.map(addHeader(_, header))
  }

  val service = HttpRoutes.of[IO] { case GET -> Root / "middleware" / name =>
      Ok(s"Hello wrapper, $name.")
  }

  val apiService = HttpRoutes.of[IO] { case GET -> Root / "rest1" =>
      Ok("OK response API")
  }

  val wrappedService = apiService <+> MyMiddle(service, Header("SomeKey", "SomeValue"))

  val httpRoute = Router("/api" -> wrappedService).orNotFound

  def run(args: List[String]): IO[ExitCode] =
     BlazeServerBuilder[IO](global)
      .bindHttp(7676, "localhost")
      .withHttpApp(httpRoute)
      .serve
      .compile
      .drain
      .as(ExitCode.Success)
}

La definición de los test de este ejemplo es análogo a los anteriores.

Para el lector interesado en el código ejemplo puede acceder a través del siguiente enlace.

En la siguiente entrada, HTTP4S: manejo de JSON, me centraré en cómo se manejan componentes JSON con HTTP4S.

MUnit IV: Filtros

Finalizamos la serie de MUnit con esta última entrada, MUnit IV: Filtros, en donde describiremos cómo filtrar aquellos test que queramos ejecutar y cuál no. Para el lector interesado en la serie de entradas puede acceder a través de los siguiente enlaces:

  1. MUnit I: declaración de test.
  2. MUnit II: aserciones.
  3. MUnit III: accesorios.

Los filtrados a los test los podemos definir de la siguiente forma:

  • Ejecutar solo un test de una clase.- Para ejecutar solo un test definido en una clase se debe de utilizar la función only en el texto de la definición de un test. Un ejemplo de uso es el siguiente:
class FilteringEjem1 extends munit.FunSuite {
  test("test-issue-455") {
    assert(1 == 1)
  }
  test("consoletest-issue-456".only) {
    assert(1 == 1)
  }
  test("test issue 457") {
    assert(1 == 1)
  }
}
  • Ignorar un test.- Si se desea ignorar la ejecución de un test en una clase se debe de utilizar la función ignore en el texto de la definición de un test. Un ejemplo de uso es el siguiente:
class FilteringEjem2 extends munit.FunSuite {
  test("test-issue-455") {
    assert(1 == 1)
  }
  test("consoletest-issue-456".ignore) {
    assert(1 == 1)
  }
  test("test issue 457") {
    assert(1 == 1)
  }
}
  • Ejecución de test en función de condiciones dinámicas.- Si se desea la ejecución de test en función de valores externos, como por ejemplo: la ejecución de un test si es en una máquina Linux o Mac, se emplea la función assume la cual, si no cumple una función, lanza una excepción. Un ejemplo de uso de esta función es la siguiente clase:
class FilteringEjem3 extends munit.FunSuite {
  import scala.util.Properties
  test("paths linux") {
    try {
      print(f"Properties.isLinux=${Properties.isLinux}")
      assume(Properties.isLinux, "this test runs only on Linux")
      assume(Properties.versionNumberString.startsWith("2.13"), "this test runs only on Scala 2.13")
      assert(1 == 1)
    } catch {
      case exception: Exception => fail("error: " + exception.getMessage)
    }
  }
  test("paths mac") {
    try {
      println(f"Properties.isMac=${Properties.isMac}")
      assume(Properties.isMac, "this test runs only on Mac")
      assume(Properties.versionNumberString.startsWith("2.13"), "this test runs only on Scala 2.13")
      assert(1 == 1)
    } catch {
      case exception: Exception => fail("error: " + exception.getMessage)
    }
  }
}

Los test del ejemplo anterior fallarán o no en función de si la ejecución se realiza en una máquina Linux o Mac.

  • Ignorar una clase de test por anotación.- Un camino rápido para ignorar la ejecución de una clase de test es la utilización de la anotación munit.IgnoreSuite. Un ejemplo de uso es el siguiente:
@munit.IgnoreSuite
class FilteringIgnoreClassEjem4 extends munit.FunSuite {
  test("Ignore test 1") {
    assert(1 == 1)
  }
  test("Ignore test 2") {
    assert(1 == 1)
  }
}

La utilización de MUnit es muy intuitiva para todos aquellos que hayan trabajado con JUnit y, para quien no, no considero un aprendizaje duro y costoso por la sencillez de la definición y uso. La posibilidad de definir pruebas de tareas asíncronas es un aspecto importante para considerar su uso en ciertos casos. Por el contrario, es posible que el uso de los accesorios (fixture) sea algo más laborioso al tener que definir de forma explícita el objeto en el test.

MUnit III: accesorios

En la presente entrada, MUnit III: accesorios, definiré qué es un accesorio (fixtures) en un test con MUnit y mostraré ejemplo de uso. Para el lector interesado, el resto de entradas de la serie son las siguientes:

+ MUnit I: declaración de test.
+ MUnit II: aserciones.

Los accesorios en las pruebas son los entornos de ejecución en donde se ejecutan los test; en estos entornos, permiten la adquisición de recursos para ejecutar la prueba y, una vez finalizada, liberar todos aquellos recursos utilizados. Podemos tener dos tipos de accesorios: funcionales, son aquellos en donde se adquiere un recurso determinado ; y, los reusables, son aquellos en donde se puede definir una funcionalidad antes y después del test.

Las clases de test en donde se definen accesorios son clases que heredan de la clase munit.FunSuite y, en función de si es un accesorio funcional o reusable, se define la referencia a  munitFixture.

Los ejemplos de accesorios son aquellos en los que se definen test en donde es necesario utilizar un recurso, ya sea un fichero o bien una base de datos con los cuáles operar.

Ejemplo de accesorio funcional

Supongamos que necesitamos crear un fichero temporal para un test, necesitamos crear un fichero antes del test, ejecutar el test y, para finalizar, liberar dicho fichero. Un ejemplo de test es el siguiente:

import java.nio.file.{Files, Path}
class FunctionalTestLocalFixturesFilesEjem1 extends munit.FunSuite {
  val files = FunFixture[Path](
    setup = { test =>
      Files.createTempFile("tmp", test.name)
    },
    teardown = { file =>
      Files.deleteIfExists(file)
      ()
    }
  )
  files.test("Functional Test Local Fixtures") { file =>
     assert(Files.isRegularFile(file), s"Files.isRegularFile($file)")
  }
  [...]
}

En el ejemplo anterior, se define un objeto FunFixture cuyo tipo parametrizado es un objeto Path del paquete java.nio.file; la función setup, es aquella función que se ejecuta antes de la ejecución del test; y, la función teardown, es aquella función que se ejecuta después del test; en nuestro caso, se realiza la creación de un fichero temporal y su liberación respectivamente. Una vez definido el accesorio, se invoca la función test del objeto FunFixture en el cual se define las aserciones oportunas.

Si deseamos realizar una composición de accesorios, podemos emplear la función map2 o map3 del objeto FunFixture. Un ejemplo de composición de dos accesorios como el definido anteriormente es el siguiente:

import java.nio.file.{Files, Path}
class FunctionalTestLocalFixturesFilesEjem1 extends munit.FunSuite {
  [...]
  val files2 = FunFixture.map2(files, files)
  files2.test("Multiple Functional Test Local Fixtures") {
    case (file1, file2) => {
      assertNotEquals(file1, file2)
      assert(Files.isRegularFile(file1), s"Files.isRegularFile($file1)")
      assert(Files.isRegularFile(file2), s"Files.isRegularFile($file2)")
    }
  }
}

Ejemplo de accesorio reusable

En JUnit puedes definir funciones con funcionalidad antes del test y después, representadas en las funciones before y after. Para conseguir estas funciones, necesitamos definir accesorios reusables las cuáles son más poderosas que los accesorios funcionales. En el siguiente ejemplo se muestra una accesorio reusable que trata con ficheros:

import java.nio.file.{Files, Path}
class ReusableTestLocalFixturesFilesEjem1 extends munit.FunSuite {
  val file = new Fixture[Path]("files") {
    var file: Path = null
    override def apply(): Path = file
    override def beforeEach(context: BeforeEach): Unit = {
      file = Files.createTempFile("files", context.test.name)
    }
    override def afterEach(context: AfterEach): Unit = {
      Files.deleteIfExists(file)
      ()
    }
  }
  override def munitFixtures: Seq[Fixture[_]] = List(file)
  test("exists") {
    assert(Files.exists(file()))
  }
}

En el ejemplo anterior, se definie un accesorio de la clase Fixture con un tipo parametrizado de tipos Path; esta clase, define las funciones beforeEach y afterEach con la referencia al recurso de tipo file con el que se trabaja. Además, se define la lista de Fixtures que pueden ser utilizados en cada test.

Si por el contrario, deseamos trabajar con una base de datos, el ejemplo de definición de la clase de test con un Fixture con el tratamiento de una base de datos es el siguiente:

import java.sql.{Connection, DriverManager}
class ReusableTestLocalFixturesDBEjem1 extends munit.FunSuite {
  val db = new Fixture[Connection]("database") {
    private var connection: Connection = null
    override def apply(): Connection = connection
    override def beforeEach(context: BeforeEach): Unit = {
      connection = DriverManager.getConnection("jdbc:h2:mem:test", "sa", "password")
    }
    override def afterEach(context: AfterEach): Unit = {
      connection.close()
      ()
    }
  }
  override def munitFixtures: Seq[Fixture[_]] = List(db)
  test("test1") {
    db()
    assert(1 == 1)
  }
  test("test2") {
    db()
    assert(1 == 1)
  }
}

En el ejemplo anterior, para cada test definido, se inicializa una base de datos de tipo m2 en memoria.

En la siguiente entrada, MUnit IV: filtrado, describiré como realizar filtros de test en ejecución.

MUnit II: aserciones

En la entrada anterior, Munit I: declaración de test, realizaré una descripción de cómo se definen test; en la presenta entrada, Munit II: aserciones, realizaré una descripción de cómo utilizar las aserciones en los test.

Las aserciones son aquellas comprobaciones lógicas que determinan si el resultado del test es correcto. Las aserciones se definen, entre otras, con las siguientes funciones : assert, assertNotEquals, assertEquals,… Las aserciones están compuestas por una comprobación lógica, o bien, por una comprobación lógica y un mensaje informativo. Unos ejemplos básicos de test son los siguientes:

class AssertEjem1 extends munit.FunSuite {
  test("Basic assert() 1") {
    val obtained = 42
    val expected = 43
    assert(obtained < expected)
  }
  test("Basic assert() 2") {
    val obtained = 42
    val expected = 43
    assert(obtained < expected, "obtained was smaller than expected")
  }
  [...]
}

MUnit ofrece la posibilidad de mostrar información sobre aquellos test cuyo resultado no es válido. Para mostrar información adicional, es necesario utilizar la función clue; para su mayor comprehensión, mostramos los siguientes ejemplos de test con sus respectivas salidas por consola:

  • Test sin función clue.
class AssertEjem1 extends munit.FunSuite {
  test("Basic assert() 1") {
    val obtained = 42
    val expected = 43
    assert(obtained == expected)
  }
}

La salida por consola es la que se muestra en la siguiente imagen:

  • Test con función clue.
class AssertEjem1 extends munit.FunSuite {
  test("Basic assert() clue - error") {
    val obtained = 42
    val expected = 43
    assert(clue(obtained) == clue(expected))
  }
}

La salida por consola es la que se muestra en la siguiente imagen:

Realizando la comparativa de la información que se muestra en los resultados de los test, al utilizar la función clue, MUnit muestra los datos que se emplean para poder realizar un análisis de los datos que se han tratado en el test y, así, poder realizar las correcciones oportunas en el momento de la definición del test.

La función clue no se usa exclusivamente con valores básicos, podemos utilizar con datos más estructurados como se muestra a continuación:

  • Clue con case class.

Supongamos que definimos un test que realiza la comparación entre dos objetos definidos en una case class, el test sería el siguiente:

test("Basic assertEquals() case class".flaky) {
  case class Library(name: String, awesome: Boolean, versions: Range = 0.to(1))
  val munitLibrary = Library("MUnit", true)
  val mdocLibrary = Library("MDoc", true)
  assertEquals(clue(munitLibrary), clue(mdocLibrary))
}

La salida por consola es la que se muestra en la siguiente imagen:

Como se observa en la imagen anterior, MUnit muestra la diferencia en los valores de los objetos que se utilizan en la aserción.

  • Clue con Map.

Supongamos que queremos definir una aserción de igualdad con dos elementos de tipo Map cuyos valores son diferentes. La definición del test es el siguiente:

test("Basic assertEquals Map".flaky) {
  assertEquals(
   clue(Map(1 -> List(1.to(3)))),
   clue(Map(1 -> List(1.to(4))))
  )
}

El resultado no es satisfactorio al no ser iguales los objetos Map y, el resultado del test, muestra las diferencias entre los dos objetos. La salida se muestra en la siguiente imagen:

  • Clue con String.

Supongamos que tenemos dos string y queremos verificar que no existen diferencias entre ellos; pero, los strings tienen una longitud grande. La definición del test es el siguiente:

test("Basic assertNoDiff") {
  val obtainedString = "val x = 41\nval y = 43\nval z = 43"
  val expectedString = "val x = 41\nval y = 42\nval z = 43"
  assertNoDiff(obtainedString, expectedString)
}

El resultado no es satisfactorio al existir diferencias. La salida se muestra en la siguiente imagen:

  • Interceptación de una excepción.

Para capturar una excepción en un test, se utiliza la función intercept. Un ejemplo de uso en un test se muestra en el siguiente código de ejemplo:

test("Basic intercept") {
  intercept[java.lang.IllegalArgumentException] {
    def throwException(): Unit = throw new IllegalArgumentException()
    throwException()
  }
}
  • Interceptación de un mensaje de una excepción.

Para capturar un mensaje de una excepción en un test, se utiliza la función interceptMessage. Un ejemplo de uso en un test se muestra en el siguiente código de ejemplo:

test("Basic interceptMessage") {
  interceptMessage[java.lang.IllegalArgumentException]("My Message Exception") {
    def throwException(): Unit = throw new IllegalArgumentException("My Message Exception")
    throwException()
  }
}

MUnit permite definir test para verificar que un snippet de código no tenga errores de compilación. Un ejemplo de uso de este tipo de test cuyo resultado es correcto es el siguiente código:

test("Basic compileError") {
  compileErrors("val x: String = 2")
}

La verificación del resultado de los test es muy intuitiva ya que el concepto de aserciones es utilizado por muchas soluciones; de la misma manera, la captura de excepciones o mensajes. Esta situación supone que la curva de aprendizaje de MUnit no sea grande.

En la siguiente entrada, MUnit III: accesorios, describiré cómo trabajar con los entornos de ejecución.

MUnit I: declaración de test

Inicio una serie de entradas relacionadas MUnit. MUnit es una librería de testing para Scala. En la presente entrada, MUnit 1: declaración de test, realizaré una introducción y una descripción de cómo se declaran test con esta librería.

MUnit tiene una parecido a otra librería de testing como es JUnit. JUnit es una librería del contexto del lenguaje de programación Java. La filosofía de MUnit es seguir la misma línea de JUnit pero en el contenxto del lengua Scala. Las características de MUnit son las siguientes:

  1. MUnit se implementa como un ejecutor de JUnit e intenta construir sobre JUnit siempre que sea posible.
  2. No tiene dependencias externas con otras librerías del mundo Scala.
  3. Es una librería multiplataforma que complica MUnit a JVM a través de JavaScript Scala.js.
  4. Informes de pruebas entendibles para analizar los problemas.

Definición de dependencias

La definición de dependencias de MUnit en un proyecto Scala en donde se utiliza sbt se realiza de la siguiente manera:

val MunitVersion = "0.7.20"
val MunitCatsEffectVersion = "0.12.0"
[...]
lazy val root = (project in file("."))
  .settings(
     scalacOptions += "-Yrangepos",
     libraryDependencies ++= Seq(
        "org.scalameta" %% "munit" % MunitVersion % Test,
        "org.typelevel" %% "munit-cats-effect-2" % MunitCatsEffectVersion % Test
     ),
  testFrameworks += new TestFramework("munit.Framework")
)

Ejemplo básico de test con MUnit

La definición de un test en MUnit y la forma de trabajar es parecida a JUnit. Los test se definen heredando de la clase munit.FunSuite, se declara un test con la sentencia test y, dentro de esta, se define la prueba funcional verificando el resultado con assertEquals. Un ejemplo básico de test es el descrito en el siguiente snippet:

class BasicEjem1 extends munit.FunSuite {
  test("Basic") {
    val obtained = 43
    val expected = 43
    assertEquals(obtained, expected)
  }
}

Declaración de test en MUnit

Declaración de test asíncronos.

MUnit tiene la capacidad de realizar test de tareas asíncronas. Esta tarea es posible gracias a los transformadores de MUnit los cuáles permiten controlar la ejecución de este tipo de tarea con un tiempo límite de espera de 30 segundos.

En el siguiente ejemplo, se muestra la definición de un test asíncrono cuyo tiempo de espera es el valor por defecto.

import scala.concurrent.Future
class BasicAsyncEjem1 extends munit.FunSuite {
  implicit val ec = scala.concurrent.ExecutionContext.global
  test("async") {
    Future {
      println("Hello World")
    }
  }
}

Si deseamos modificar el timeout, debemos de modificar el valor del atributo munitTimeout. Un ejemplo de modificación del campo munitTimeout es el siguiente:

import scala.concurrent.Future
import scala.concurrent.duration.Duration
class BasicAsyncEjem2 extends munit.FunSuite {
  implicit val ec = scala.concurrent.ExecutionContext.global
  override val munitTimeout = Duration(1, "s")
  test("slow-async") {
    Future {
      Thread.sleep(5000)
      println("Hello world, slow-async")
    }
  }
}

La salida por consola es la excepción de Timeout cuya traza es la siguiente:

java.util.concurrent.TimeoutException: Future timed out after [1 second]

MUnit tiene una tratamiento especial para manejar Future, pudiendo definir tareas asíncronas sin necesidad de ser ejecutas con un resultado de éxito del test. En el siguiente ejemplo, se muestra una tarea asíncrona definida en un case class que nunca se ejecuta y el resultado de ejecución es correcto.

class BasicAsyncEjem3 extends munit.FunSuite {
  implicit val ec = scala.concurrent.ExecutionContext.global
  case class LazyFuture[+T](run: () => Future[T])
  object LazyFuture {
    def apply[T](thunk: => T)(implicit ec: ExecutionContext): LazyFuture[T] =
      LazyFuture(() => Future(thunk))
  }
  test("buggy-task") {
    LazyFuture {
      Thread.sleep(10)
      println("Hello world BasicAsyncEjem3")
    }
  }
}

Para poder ejecutar la anterior tarea asíncrona, necesitamos definir un ejecutor que sea capaz de ejecutar la referencia a la función run. En el siguiente ejemplo, definimos dicho ejecutor identificado como munitValueTransform. El código del ejemplo es el siguiente:

import scala.concurrent.{ExecutionContext, Future}
class BasicAsyncEjem4 extends munit.FunSuite {
  case class LazyFuture[+T](run: () => Future[T])
  object LazyFuture {
    def apply[T](thunk: => T)(implicit ec: ExecutionContext): LazyFuture[T] =
      LazyFuture(() => Future(thunk))
  }
  override def munitValueTransforms = super.munitValueTransforms ++ List(
    new ValueTransform(
      "LazyFuture",
      { 
        case LazyFuture(run) => run()
      }
    )
  )
  implicit val ec = ExecutionContext.global
    test("tarea OK") {
      LazyFuture {
         Thread.sleep(5000)
         println("Hello world BasicAsyncEjem4")
      }
    }
}

La salida por consola del código anterior es la siguiente:

Hello world BasicAsyncEjem4

Definir test con una función auxiliar.

Podemos definir una función que defina un test cuyos parámetros pueden ser por valor o por nombre. Un código ejemplo de estos test es el siguiente:

class AuxiliarFunctionEjem1 extends munit.FunSuite {
   def check[T](name: String, original: List[T], expected: Option[T])(implicit loc: munit.Location): Unit = {
      test(name) {
         val obtained = original.headOption
         assertEquals(obtained, expected)
      }
   }
   check("basic", List(1, 2), Some(1))
   def checkByName(name: String, bytes: => Array[Byte]): Unit =
       test(name) {
          assertEquals(bytes.length > 0, true)
       }
   import java.nio.file.{Files, Paths}
   checkByName("file", Files.readAllBytes(Paths.get("build.sbt")))
}

Definir test que siempre falle.

En ocasiones necesitamos que un test falle. Para definir este comportamiento, empleamos la función fail. Un código ejemplo es el siguiente:

class AlwaysFailEjem1 extends munit.FunSuite {
  test("issue-456".fail) {
     assertEquals(1, 1)
  }
}

Modificar el comportamiento de ejecutor munitTest

Si necesitamos modificar el comportamiento de un test empleamos un tag. Un tag es una entidad de Munit la cual se representa con un case class. El comportamiento del test lo definiremos en una clase TestTransform del ejecutor munitTestTransforms, referenciando al tag identificador del comportamiento. En la identificación del test, se define la referencia al tag a ejecutar. Un código ejemplo para ejecutar un test cuatro veces es el siguiente:

case class Rerun(count: Int) extends munit.Tag("Rerun")
class CustomizeEvaluationTestEjem1 extends munit.FunSuite {
   override def munitTestTransforms = super.munitTestTransforms ++ List(
     new TestTransform(
       "Rerun",
       { test =>
           val rerunCount = test.tags.collectFirst { case Rerun(n) => n }.getOrElse(1)
           if (rerunCount == 1) test
           else {
             test.withBody(() => {
                Future.sequence(1.to(rerunCount).map(_ => test.body()).toList)
             })
           }
       }
     )
   )
   test("files".tag(Rerun(4))) {
       println(s"Hello world...")
   }
}

El resultado del anterior código es la escritura en consola del texto “Hello world…” cuatro veces.

Modificar el nombre de un test de forma dinámica.

Si necesitamos ejecutar test cuyo nombre dependa de circunstancias externas, es necesario emplear un TestTransform. Un código ejemplo que modifica el nombre de los test de forma dinámica con la versión de scala es el siguiente:

class CustomizeTestNameEjem1 extends munit.FunSuite {
  val scalaVersion = scala.util.Properties.versionNumberString
  override def munitTestTransforms: List[TestTransform] = super.munitTestTransforms ++ List(
     new TestTransform(
        "append Scala version",
        { test =>
            test.withName(test.name + "-" + scalaVersion)
        }
      )
  )
  test("test-Foo") {
     assert(scalaVersion.startsWith("2.13.4"))
     assertEquals(scalaVersion, "2.13.4")
  }
}

El resultado de la ejecución es el que se muestra en la siguiente imagen:

Saltar un test.

Si necesitamos saltar un test, emplearemos la función flaky para saltar la ejecución. Un código ejemplo es el siguiente:

class FlakyTestEjem1 extends munit.FunSuite {
  test("requests".flaky) {
    val obtained = 42
    val expected = 43
    assertEquals(obtained, expected)
  }
}

Para saltar la ejecución en los test, es necesario ejecutar sbt definiendo la variable MUNIT_FLASK_OK con valor a true. Si no se emplea la variable, los test se ejecutan normalmente. Un ejemplo de ejecución es el siguiente:

MUNIT_FLAKY_OK=true sbt test

Compartir configuración de test.

Si necesitamos definir clases de test con componentes comunes, se define una herencia de clases cuya clase base defina todo aquello que sea común. Si necesitamos modificar el nombre de los test de dos clases diferentes, definimos una clase base con el transformador del nombre de test y, sus clases hijas, heredan de dicha clase base. Un código ejemplo es el siguiente:

class BaseSuite extends munit.FunSuite {
   val scalaVersion = scala.util.Properties.versionNumberString
   override def munitTestTransforms: List[TestTransform] = super.munitTestTransforms ++ List(
      new TestTransform(
        "append Scala version",
        { test =>
          test.withName(test.name + "-" + scalaVersion)
        }
      )
   )
}
class MyFirstTestSuite extends BaseSuite {
   test("FirstTestSuite.test1") {
      println("Hello world ...FirstTestSuite.test1")
   }
   test("FirstTestSuite.test2") {
      println("Hello world FirstTestSuite.test2")
   }
}
class MySecondTestSuite extends BaseSuite {
   test("SecondTestSuite.test1") {
      println("Hello world ...SecondTestSuite.test1")
   }
   test("SecondTestSuite.test2") {
      println("Hello world SecondTestSuite.test2")
   }
}

La salida por consola es la que se muestra en la siguiente imagen:

Definición de una batería de pruebas.

Si necesitamos definir una batería de pruebas, definimos una clase de test que herede de munit.Suite, definimos el tipo de de valor de las pruebas y, para finalizar, definimos la lista de test con la creación de tantas clases Test como queremos. Un código de ejemplo es el siguiente:

import munit.Assertions.assertEquals
import munit.{Location, Tag}
class TestLibrarySuite2 extends munit.Suite {
   override type TestValue = Unit
   override def munitTests(): Seq[Test] = List(
     new Test(
       "example1",
       body = () => {
          val obtained = 43
          val expected = 43
          assertEquals(obtained, expected)
       },
       tags = Set.empty[Tag],
       location = implicitly[Location]
     ),
     new Test(
        "example2",
        body = () => {
           val obtained = "43"
           val expected = "43"
           assertEquals(obtained, expected)
        },
        tags = Set.empty[Tag],
        location = implicitly[Location]
     )
   )
}

En la siguiente entrada, MUnit II: aserciones, describiré en cómo definir aserciones en los test.

Composición de FreeMonad

En la entrada anterior, FreeMonad en Cats, realicé una descripción de cómo definir un DSL utilizando una FreeMonad pero, en ciertas situaciones, necesitamos utilizar un segundo DSL conjuntamente con el primero. En la entrada de hoy, Composición de FreeMonad, realizaré un ejemplo de una aplicación que utiliza conjuntamente dos DSL para la definición de un programa.

Presentación del problema

Continuando con las entidades de dominio de la entrada anterior, supongamos que necesitamos realizar la creación de un esquema de base de datos, realizar unas inserciones, eliminar y consultar; es decir, necesitamos un programa que realice unas operaciones básicas de tipo CRUD; pero además, necesitamos que las operaciones sean trazadas en un log en la salida estándar; pudiendo ser de dos tipos: mensajes informativos, tipo info; y, mensajes de depuración, tipo debug.
Para definir un programa que cumpla con estos requisitos necesitamos lo siguiente: definir un DSL para las operaciones en base de datos, definir un DSL para las operaciones de log y un intérprete que entienda el lenguaje de los DSL`s.

Definición de los ADT`s

Definiré dos ADT’s para los dos tipos de operaciones: DBOperations, para el ADT’s de las operaciones en base de datos; y, LogOperation. Antes de definir los ADT’s, definiremos el alias a utilizar. Definimos un alias con nombre Response con un tipo genérico, define un contenedor binario de tipo Either de un tipo Exception y un tipo genérico. La definición del alias es el siguiente:

type Response[A] = Either[Exception, A]

El ADT que define las operaciones de base de datos es el mismo que se utiliza en la entrada anterior, mediante la siguiente estructura de clases:

sealed trait DBOperation[A]
case class Configure(xa: Aux[IO, Unit]) extends DBOperation[Response[Unit]]
case class CreateSchema() extends DBOperation[Response[Boolean]]
case class Insert(author: Author) extends DBOperation[Response[Int]]
case class Select(key: Int) extends DBOperation[Response[Option[String]]]
case class Delete(key: Int) extends DBOperation[Response[Int]]

Las clases definidas definen las siguientes operaciones: clase Configure, define la operación de configuración de Transactor de la base de datos; CreateSchema, creación del esquema de base de datos: Insert, inserción de una entidad Author; Select, seleccionar un autor por clave; Delete, eliminación de un autor por clave.

El ADT que define las operaciones de escritura de log se define mediante la siguiente estructura de clases:

sealed trait LogOperation[A]
case class Info(msg: String) extends LogOperation[Response[Unit]]
case class Debug(msg: String) extends LogOperation[Response[Unit]]

Las clases definidas definen las siguientes operaciones: Info, define la escritura de un mensaje de tipo informativo; Debug, define la escritura de un mensaje de tipo depuración.

En los dos ADT’s, se define como respuesta de la operación el tipo Response.

Definición de los DSL’s

Una FreeMonad permite a un Functor tener la funcionalidad de una mónada; añadir esta funcionalidad, la proporciona el tipo Free[_]. Además, para poder trabajar con otros DSL, es necesario añadir elementos que permitan la unión de los DSL; para ello se utilizan las siguientes herramientas:

  • InjectK[DBOperation, F].- Type class que permite inyectar el tipo DBOperation en el tipo F del contexto de ejecución.
  • Free.inject[DBOperation, F].- Función que permite enlazar el tipo DBOperation al tipo F del contexto de ejecución.

La definición de los DSL`s DBOperations y LogOperations se realiza definiendo una clase y su companion object el cual define una referencia implícita a la instancia de la clase. El código de los DSL`s se definen en el siguiente snippet:

class DBOperations[F[_]](implicit I: InjectK[DBOperation, F]){
  def configure(xa: Aux[IO, Unit]): Free[F, Response[Unit]] = Free.inject[DBOperation, F](Configure(xa))
  def createSchema(): Free[F, Response[Boolean]] = Free.inject[DBOperation, F](CreateSchema())
  def insert(elem: Author): Free[F, Response[Int]] = Free.inject[DBOperation, F](Insert(elem))
  def delete(key: Int): Free[F, Response[Int]] = Free.inject[DBOperation, F](Delete(key))
  def select(key: Int): Free[F, Response[Option[String]]] = Free.inject[DBOperation, F](Select(key))
}
object DBOperations{
  implicit def dboperations[F[_]](implicit I: InjectK[DBOperation, F]) = new DBOperations[F]()
}
class LogOperations[F[_]](implicit I: InjectK[LogOperation, F]){
  def infoLog(msg: String): Free[F, Response[Unit]] = Free.inject[LogOperation, F](Info(msg))
  def debugLog(msg: String): Free[F, Response[Unit]] = Free.inject[LogOperation, F](Debug(msg))
}
object LogOperations{
  implicit def logopearations[F[_]](implicit I: InjectK[LogOperation, F]) = new LogOperations[F]()
}

Definición de los intérpretes

Los intérpretes son los functores de transformación. Realizan la interpretación del DSL, interpretando el lenguaje para el que está definido, ejecuta la funcionalidad requerida y retorna el valor transformado.

El intérprete del DSL DBOperations se define en el objeto DBOperationInterprete el cual es un functor de transformación de un tipo DBOperation a OperationResponse. El tipo OperationResponse es un alias del tipo identidad definido en Cats. El alias se define de la siguiente forma:

type OperationResponse[A] = Id[A]

DBOperationsInterprete define una referencia a un transactor de la librería Doobie con una configuración por defecto, esta configuración es un valor mutable ya que puede ser configurada de forma dinámica. Para todo elemento del ADT, se utiliza el repositorio de Author y se trata el resultado como un tipo OperationResponse[A]. El snippet del código con el intérprete es el siguiente:

object DBOperationsInterpreter extends (DBOperation ~> OperationResponse){
  implicit val cs = IO.contextShift(ExecutionContexts.synchronous)
  // TODO var -> val?
  private var xa = Transactor.fromDriverManager[IO](
    s"com.mysql.jdbc.Driver", s"jdbc:mysql://host:port/doobie", s"user", s"pwd",
    Blocker.liftExecutionContext(ExecutionContexts.synchronous) // just for testing
  )
  override def apply[A](fa: DBOperation[A]) = fa match {
    case Configure(xaTransactor) => {
      this.xa = xaTransactor
      val result: OperationResponse[Response[Unit]] = Right(Unit)
      result
    }
    case CreateSchema() => {
      val resultCreateSchema: Response[Boolean] = AuthorRepository.createSchemaIntoMySqlB(xa)
      val result: OperationResponse[ Response[Boolean]] = resultCreateSchema
      result
    }
    case Insert(author) =>{
      val resultTask: Response[Int] = AuthorRepository.insertAuthorIntoMySql(xa, author)
      val result: OperationResponse[Response[Int]] = resultTask
      result
    }
    case Delete(key) => {
      val resultTask: Response[Int] = AuthorRepository.deleteAuthorById(xa, key)
      val result: OperationResponse[Response[Int]] = resultTask
      result
    }
    case Select(key) => {
      val resultTask: Response[Option[String]] = AuthorRepository.selectAuthorById(xa, key)
      val result: OperationResponse[Response[Option[String]]] = resultTask
      result
    }
  }
}

Para el lector interesado en el código de ejemplo del repositorio Author puede acceder a través del siguiente enlace.

El intérprete del DSL`s de operaciones de Log se define en el objeto LogOperationsInterprete el cual define un functor transformador de un tipo LogOperation a un tipo OperationResponse. El intérprete define las operaciones para los mensajes de tipo info y debug escribiendo mensajes en la salida estándar. El snippet de código con el intérprete es el siguiente:

object LogOperationsInterpreter extends (LogOperation ~> OperationResponse){
  override def apply[A](fa: LogOperation[A]) = fa match {
    case Info(msg) =>
      println(s"[*** INFO] ${msg}")
      val result: OperationResponse[Response[Unit]] = Right(Unit)
      result
    case Debug(msg) =>
      println(s"[*** DEBUG] ${msg}")
      val result: OperationResponse[Response[Unit]] = Right(Unit)
      result
  }
}

Un aspecto importante a destacar es que en los dos funtores de transformación, es decir, los intérpretes, tienen el mismo tipo de salida definido en el alias OperationResponse[A].

Llegado a este punto, tenemos definidos los dos intérpretes de forma individual pero, nos falta la definición del intérprete que comprenda los dos lenguajes; para ello, tenemos que definir un tipo que englobe a los dos ADT de los DSL definidos y, posteriormente, define un functor que transforma del tipo anterior al resultado final.

El tipo DoobiePureComposingApp es un alias que define un tipo EitherK con los tipos DBOperation, LogOperation (ADT de los DSL definidos) y el tipo A. Este tipo comprende los tipos de las gramáticas de los DSL.

type DoobiePureComposingApp[A] = EitherK[DBOperation, LogOperation, A]

El tipo que define el resultado es el tipo identidad de los DSL definidos.

type OperationResponse[A] = Id[A]

Así, la definición del intérprete que engloba a los dos DSL se define de la siguiente forma:

val interpreter: DoobiePureComposingApp ~> OperationResponse = DBOperationsInterpreter or LogOperationsInterpreter

Definición del programa de uso de los DSL

Llegado a este punto, estamos en disposición de declarar un programa que realice operaciones en base de datos de la entidad Author y con capacidad de escribir en un log. Como comentamos al inicio de la entrada, el programa declara un conjunto de operaciones representativas con un objetivo pedagógico. El snippet del código es el siguiente:

implicit val cs = IO.contextShift(ExecutionContexts.synchronous)
final case class DatabaseConfig( host: String, port: String, user: String, password: Secret[String])
def loadEnvironmentVariables(): DatabaseConfig = {
  val host: ConfigValue[String] = env("DDBB_HOST").or(prop("ddbb.host")).as[String]
  val port: ConfigValue[String] = env("DDBB_PORT").or(prop("ddbb.port")).as[String]
  val user: ConfigValue[String] = env("DDBB_USER").or(prop("ddbb.user")).as[String]
  val password: ConfigValue[Secret[String]] = env("DDBB_PWD").secret
  val configureEnv: ConfigValue[DatabaseConfig] = (host, port, user, password).parMapN(DatabaseConfig)
  configureEnv.load[IO].unsafeRunSync()
}
val dataConfigure: DatabaseConfig = loadEnvironmentVariables()
private val xa = Transactor.fromDriverManager[IO](
  "com.mysql.jdbc.Driver",
  s"jdbc:mysql://${dataConfigure.host}:${dataConfigure.port}/doobie",
  s"${dataConfigure.user}",
  s"${dataConfigure.password.value}",
  Blocker.liftExecutionContext(ExecutionContexts.synchronous) // just for testing
)
def programBusiness(xa: Aux[IO, Unit])(implicit DB: DBOperations[DoobiePureComposingApp],
L: LogOperations[DoobiePureComposingApp]): Free[DoobiePureComposingApp, Response[Option[String]]] = {
  import DB._
  import L._
  for {
    _ <- debugLog("Configuring database...")
    _ <- configure(xa)
    _ <- debugLog("Creating database...")
    result <- createSchema()
    numInsert1 <- insert(Author(0, "AuthorTest1"))
    numInsert2 <- insert(Author(0, "AuthorTest2"))
    numDelete1 <- delete(key = 1)
    nameAuthor <- select(key = 2)
    _ <- infoLog("Created Database.")
  } yield {
    nameAuthor
  }
}
val result = programBusiness(xa).foldMap(interpreter)
println(s"Result=${result}")

El código presentado, realiza la carga de la configuración de base de datos desde variables de entorno utilizando la librería Ciris; esta funcionalidad, queda definida en la función loadEnvironmentVariables la cual retorna una clase DatabaseConfig con la configuración; se define el Transactor de la librería Doobie con la configuración la cual es utilizada posteriormente en la declaración del programa; y, por último, se declara el programa en la función programBusiness el cual define como implícitos las referencias a las instancias de los DSL con el tipo DoobiePureComposingApp y, como retorno, un tipo Free con el tipo DoobiePureComposingApp y el tipo de retorno del programa Response[Option[String]].

La salida por consola es la siguiente:

[*** DEBUG] Configuring database…
[*** DEBUG] Creating database…
[*** INFO] Created Database.
Result=Right(Some(AuthorTest2))

Para el lector interesado en el código puede acceder a través del siguiente enlace y, para la entrada en donde explico el uso de la librería Ciris, puede acceder mediante el siguiente enlace