DEV Community: Leonardo Colman Lopes

Expand your digital picture frame use cases with Pi3D integrated USB media stick support using UDiskie

Leonardo Colman Lopes — Mon, 10 Mar 2025 21:03:28 +0000

I built and customized three instances of The Digital Picture Frame. It’s so simple yet such a great system setup that I fell in love.

Today I want to share a method to use USB Media Sticks to view our photos. This method uses Udiskie, while the traditional method (explained by Wolfgang Männel in Expand your digital picture frame use cases with Pi3D integrated USB media stick support) uses python scripts to achieve a very similar goal.

I recommend reading both articles and picking the method you feel more comfortable in. Both methods are mostly feature compatible in the end -- having an auto-mounted USB device.

What This Setup Does

Use Udiskie to manage USB auto-loading/reloading
Modify Picture Frame's configuration to read photos from the automount directory
Prepare the system to have Udiskie running when the system boots

Installing Udiskie

udiskie is a udisks2 front-end that allows to manage removable media such as CDs or flash drives from userspace.

Let's install udiskie by running one simple command:

sudo apt install udiskie udisks2

And although we won't use it, udiskie has a cool UI!

Setup Udiskie Auto-Start

To setup udiskie to work without password prompt and on boot we must first install PolicyKit:

sudo apt-get install policykit-1

And then let's create a policy configuration with required permissions. Let's create the file with sudo nano /etc/polkit-1/rules.d/99-udisks2.rules and the following content:

polkit.addRule(function(action, subject) {
    if (action.id.indexOf("org.freedesktop.udisks2.filesystem-mount") === 0 &&
        subject.isInGroup("plugdev")) {
        return polkit.Result.YES;
    }
});

Finally, let's create a udiskie.service file to ensure udiskie is working all the time. Let's use sudo nano /etc/systemd/system/udiskie.service:

[Unit]
Description=Auto-mount USB drives with udiskie
After=graphical.target network-online.target

[Service]
User=pi
ExecStart=/usr/bin/udiskie --automount
Restart=on-failure

[Install]
WantedBy=default.target

Then let's restart all services that are used:

sudo systemctl enable polkit
sudo systemctl enable udisks2
sudo systemctl enable udiskie

sudo systemctl restart polkit
sudo systemctl restart udisks2
sudo systemctl restart udiskie

And we're done with udiskie!

Modifying PicFrame Configuration

Configuration change to PicFrame is simple. We're going to change the photo directory to /media, the location where drives are mounted (e.g. /media/pi/E342-JS2J)

nano picframe_data/config/configuration.yaml

And inside model, let's change this line:

pic_dir: "/media" # default="/home/pi/Pictures", root folder for images

And we are done with PicFrame Configuration! With this we should be done! Reboot the system and insert a flash drive or two to see if pictures from all drives are coming to PicFrame.

Converting an old TV Box into an epic Picture Frame

Leonardo Colman Lopes — Fri, 07 Mar 2025 16:18:15 +0000

I built and customized 3 instances of The Digital Picture Frame. It's so simple yet such a great system setup that I fell in love.

People have built such awesome setups for this small utility, and passion drove me to my calling: It's my time to hack a device and turn it into a Picture Frame.

My chosen target? An old TV Box:

It has everything needed:

A Hackable Android TV that I can turn into Linux
A way to boot a custom system (i.e. an SD card)
A way to mount different media for photo display (i.e. Flash Drives)

Let's dive in this journey and perhaps you will have a TV Box-Frame too!

⚠️ A Word of Warning First:
Not all TV Boxes will work. Some (if not most) are not able to host a custom system. Be wary when following this as a guide as your setup might vary.

Installing Armbian

Armbian is a "Minimal custom Debian or Ubuntu based Linux perfect for server and IOT". We're going to pick it as most TV Boxes are ARM-based, and Armbian is perfect for the job.

We are going to follow the guide CSC Armbian for RK322x TV box boards.

For this tutorial we're going to use a RK3229 as our pilot chip. It's available in many TV Boxes and is not hard to setup

Discovering the Chipset

If you're not sure that your TV Box chip is supported, download and install through the TV Box the app Z-CPU or the FLOSS App CPU Info.

In the app we're looking for information on the chipset. Chipsets of the format RK322X are supported.

Unbricking Instructions

Technically, rockchip devices cannot be bricked. In some cases a screw-up might require repairing of the original system, and the unbricking instructions from CSC Armbian for RK322x TV box boards can help.

Installing Using SD Card

We're going to use an SDXC Card (Or most commonly an SD Card + Adapter). This card will hold our entire operating system*, and will be plugged in the machine 24/7. I recommend anything 8GB or bigger, but realistically 3GB is the entire system + files.

* You could instead install the system directly to the machine. I couldn't get that to work reliably and preferred the permanent SD approach.

Preparing the TV Box with Multitool

The Multitool is a small but powerful tool to make changes to our RK322X.

Multitool - A small but powerful image for RK322x TV Box maintenance

Let's flash the Multitool image onto the SD Card first. You can use any tool for it, but I like Balena Etcher.

Our goal with Multitool is straightforward:

Flash Multitool to the SD Card
Put the card in the TV Box and power on. After a few seconds Multitool should appear on the display
RECOMMENDED Make a backup of the current firmware with Backup Flash
Select Install Jump Start for Armbian

And we're done with Multitool! Power the device down and retrieve the SD card. Store your backup and get ready to flash it again!

Choosing an Image

CSC Armbian for RK322x TV box boards explains how to make a build, but we are going to grab a pre-built binary from armbian/community.

Let's take the image Rk322x-box_bookworm_current_6.12.15_minimal.img.xz

As we've done earlier, let's flash it to our SD card using Balena Etcher.
After flashing, insert the SD with the new Armbian image on the device and power it on.

Welcome to Armbian

If everything worked correctly, you should now have a shell inside Armbian asking you for information.
The most important point here is that we'll create a normal user account with the username pi. This will be important to follow The Digital Picture Frame without too many changes on the scripts.

To finish configuring Armbian, let's run two commands:

sudo rk322x-config and select your board characteristics to enable leds, wifi chips, etc.
armbian-config to configure timezone, locales and other personal options

At this point you can also connect your device to your network and connect to it through ssh.

Install The Digital PictureFrame

From this point on we are done with the system and can start playing with PictureFrame itself. We are going to follow the guide for Raspberries as close as we can until we get it working.

Let's first install necessary dependencies:

sudo apt update
sudo apt install build-essential pkg-config python3-dev python3-pip python3.11-venv libjpeg-dev libtiff-dev libfreetype6-dev zlib1g-dev liblcms2-dev libwebp-dev tcl-dev tk-dev libharfbuzz-dev libfribidi-dev libxcb1-dev libpng-dev cmake ninja-build git libgles2-mesa libegl1-mesa libgl1-mesa-dri libglapi-mesa libsdl2-2.0-0 libsdl2-dev

And compile + install HEIF, as the ones from Armbian aren't updated enough:

cd ~
git clone https://github.com/strukturag/libheif.git
cd libheif

mkdir build && cd build
cmake ..
make -j$(nproc)
sudo make install

Then let's prepare a Python VEnv to install picframe into:

cd ~
mkdir venv_picframe

python3 -m venv /home/pi/venv_picframe

source venv_picframe/bin/activate

And finally, let's install PicFrame!

pip install picframe

To know it worked, we should see after a long (maybe 30+ minutes) some positive messages:

Successfully installed IPTCInfo3-2.1.4 Pillow-11.1.0 PyYAML-6.0.2 defusedxml-0.7.1 ninepatch-0.2.0 numpy-2.2.3 paho-mqtt-2.1.0 pi-heif-0.21.0 pi3d-2.53 picframe-2024.11.1 pysdl2-0.9.17

Configuring PicFrame

On Configuring PicFrame we have clear instructions on how to configure picframe. Let's do that now!

You will be asked three questions for the basic configuration settings. Just hit Enter to keep the default for now. You can always change these settings later.

mkdir {Pictures,DeletedPictures}

picframe -i /home/pi/

You don’t need to make changes in the configuration file at this point. But you probably want to customize it later. In that case, open it with

nano ~/picframe_data/config/configuration.yaml

Starting Picframe

Let's create a script to start our Picframe:

nano start_picframe.sh

#!/bin/bash
source /home/pi/venv_picframe/bin/activate # activate phyton virtual env
picframe &  #start picframe

while true; do sleep 10; done # Keep the script running

Save and close and make the file executable with

chmod +x ./start_picframe.sh

And now, finally, let's run our PicFrame

./start_picframe.sh

And if everything went through correctly, we'll get a beautiful mug on the screen:

Auto Starting Picframe

This part will work a bit different from Autostarting PictureFrame, so pay close attention!

Let's start by creating the file picframe.service with sudo nano /etc/systemd/system/picframe.service and pasting the following content inside:

[Unit]
Description=PictureFrame Startup
After=multi-user.target

[Service]
Type=simple
ExecStart=/bin/bash /home/pi/start_picframe.sh
Restart=on-failure  # Only restart if it fails
RestartSec=10       # Wait 10 seconds before restarting
User=pi
WorkingDirectory=/home/pi
Environment=DISPLAY=:0
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

Then reload systemd and enable the brand new service:

sudo systemctl daemon-reload
sudo systemctl enable picframe.service
sudo systemctl start picframe.service

We can check the service status by running

systemctl status picframe.service

Enable Autologin on tty1

The pi user doesn't have auto-login enabled, and we must have it if we don't want to stare at a login screen. Let's change that by creating an override for getty@tty1:

sudo mkdir -p /etc/systemd/system/getty@tty1.service.d
sudo nano /etc/systemd/system/getty@tty1.service.d/override.conf

And paste this inside to enable auto-login:

[Service]
ExecStart=
ExecStart=-/sbin/agetty --autologin pi --noclear %I $TERM

PictureFrame should now start on boot!

Automated Screenshot Taking in Android using Kotest and Ktor

Leonardo Colman Lopes — Sun, 26 Jan 2025 12:43:19 +0000

1. Introduction

Automated screenshot testing is essential in Android development for ensuring UI consistency across updates and devices. Manually verifying UI changes is time-consuming and error-prone, making automation a vital practice.

In this guide, we’ll show how to use Kotest for capturing screenshots and Ktor for uploading them to a local server. This setup streamlines UI validation, improves efficiency, and centralizes screenshot storage for better collaboration and quality assurance.

This article contains a simpler implementation of what's currently in production on Petals App

2. Setup

To get started with automated screenshot testing using Kotest and Ktor, we’ll need to prepare our project by configuring the necessary tools and libraries.

Update our project’s build.gradle.kts file to include the required libraries for testing and screenshot uploads. Below are the key dependencies:

dependencies {
    // Kotest for writing tests
    androidTestImplementation("br.com.colman:kotest-runner-android:${version}")

    // Fuel library for uploading screenshots
    androidTestImplementation("com.github.kittinunf.fuel:fuel:${version}")
}

Here:

Kotest provides the framework for writing and running tests.
Kotest-Android provides specific bindings for running Android tests.
Fuel simplifies HTTP requests for uploading screenshots during tests.

3. Preparing a Local Server to Receive Screenshots

A critical component of automated screenshot testing is a server to store the captured images for validation or archival purposes. We’ll use Ktor, a lightweight Kotlin-based framework, to set up a local server capable of handling screenshot uploads.

Create a Kotlin script file named refresh_screenshots.main.kts. This script will configure and launch a local server using Ktor.

3.1. Disabling Animations

Animations in the Android emulator can affect screenshot consistency. The script disables them using ADB commands:

fun disableAnimations() {
    listOf(
        "adb shell settings put global window_animation_scale 0",
        "adb shell settings put global transition_animation_scale 0",
        "adb shell settings put global animator_duration_scale 0"
    ).forEach { command ->
        try {
            val process = Runtime.getRuntime().exec(command)
            process.waitFor()
        } catch (e: Exception) {
            println("Error while trying to disable animations via ADB: ${e.localizedMessage}")
        }
    }
    println("Animations in the emulator have been disabled")
}

3.2. Starting the Ktor Server

The server listens on port 8081 and handles file uploads. Uploaded screenshots are stored in language-specific directories based on parameters (lang and country) in the request:

fun startServer(): NettyApplicationEngine {
    return embeddedServer(Netty, port = 8081) {
        install(ContentNegotiation) {
            json()
        }
        routing {
            post("/upload") {
                val multipart = call.receiveMultipart()
                val lang = call.parameters["lang"] ?: "unknown"
                val country = call.parameters["country"] ?: "unknown"

                multipart.forEachPart { part ->
                    if (part is PartData.FileItem) {
                        val countryHyphen = if (country.isNotBlank()) "-$country" else ""
                        val dir = File("../fastlane/metadata/android/${lang}${countryHyphen}/images/phoneScreenshots")
                        if (!dir.exists()) {
                            dir.mkdirs()
                        }
                        val file = File(dir, part.originalFileName ?: "screenshot.png")
                        part.streamProvider().use { input -> file.outputStream().buffered().use { input.copyTo(it) } }
                    }
                    part.dispose()
                }
                call.respondText("File uploaded successfully", status = HttpStatusCode.OK)
            }
        }
    }.start(wait = false)
}

3.3. Running Tests and Handling the Server

The script runs Android tests using Gradle and stops the server once the tests are completed:

val server = startServer()

disableAnimations()

// Run Android tests
val process = ProcessBuilder(
    "../gradlew",
    "connectedFdroidDebugAndroidTest",
    "-Pandroid.testInstrumentationRunnerArguments.class=br.com.colman.petals.ScreenshotTakerTest"
).inheritIO().start()
val exitCode = process.waitFor()

server.stop(1000, 10000)

3.4. Full Script

Let's take a look at the final result by merging all the scripts and adding relevant imports:

#!/usr/bin/env kotlin

@file:DependsOn("org.jetbrains.kotlinx:kotlinx-coroutines-core-jvm:1.10.1")
@file:DependsOn("io.ktor:ktor-server-core-jvm:2.3.13")
@file:DependsOn("io.ktor:ktor-server-netty-jvm:2.3.13")
@file:DependsOn("io.ktor:ktor-server-content-negotiation-jvm:2.3.13")
@file:DependsOn("io.ktor:ktor-serialization-kotlinx-json-jvm:2.3.13")
@file:DependsOn("io.ktor:ktor-server-host-common-jvm:2.3.13")

import io.ktor.http.*
import io.ktor.http.content.*
import io.ktor.serialization.kotlinx.json.*
import io.ktor.server.application.*
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.plugins.contentnegotiation.*
import io.ktor.server.request.*
import io.ktor.server.response.*
import io.ktor.server.routing.*
import java.io.File

// Function to disable animations via ADB
fun disableAnimations() {
  listOf(
    "adb shell settings put global window_animation_scale 0",
    "adb shell settings put global transition_animation_scale 0",
    "adb shell settings put global animator_duration_scale 0"
  ).forEach { command ->
    try {
      val process = Runtime.getRuntime().exec(command)
      process.waitFor()
    } catch (e: Exception) {
      println("Error while trying to disable animations via ADB: ${e.localizedMessage}")
    }
  }
  println("Animations in the emulator have been disabled")
}

fun startServer(): NettyApplicationEngine {
  return embeddedServer(Netty, port = 8081) {
    install(ContentNegotiation) {
      json()
    }
    routing {
      post("/upload") {
        val multipart = call.receiveMultipart()
        val lang = call.parameters["lang"] ?: "unknown"
        val country = call.parameters["country"] ?: "unknown"

        multipart.forEachPart { part ->
          if (part is PartData.FileItem) {
            val countryHyphen = if (country.isNotBlank()) "-$country" else ""
            val dir = File("../fastlane/metadata/android/${lang}${countryHyphen}/images/phoneScreenshots")
            if (!dir.exists()) {
              dir.mkdirs()
            }
            val file = File(dir, part.originalFileName ?: "screenshot.png")
            part.streamProvider().use { input -> file.outputStream().buffered().use { input.copyTo(it) } }
          }
          part.dispose()
        }
        call.respondText("File uploaded successfully", status = HttpStatusCode.OK)
      }
    }
  }.start(wait = false)
}


// Start the server
val server = startServer()

// Disable animations
disableAnimations()

// Run Android tests
val process = ProcessBuilder(
  "../gradlew",
  "connectedFdroidDebugAndroidTest",
  "-Pandroid.testInstrumentationRunnerArguments.class=br.com.colman.petals.ScreenshotTakerTest"
).inheritIO().start()
val exitCode = process.waitFor()

// Stop the server
server.stop(1000, 10000)

4. Writing a Screenshot Test in Kotest

This section demonstrates how to create comprehensive screenshot tests using Kotest in an Android project. The provided code integrates Jetpack Compose testing with screenshot capture and upload functionality, supporting multiple locales and organized storage on a local server.

4.1. Key Features of the Screenshot Tests

1. Multi-Locale Testing
The tests iterate over a list of language (lang) and country (country) codes, ensuring the UI is tested across different locales.

2. Screenshot Capture
Screenshots are taken directly from the UI during tests using Jetpack Compose's testing utilities.

3. Automated Uploads
Screenshots are uploaded to a local server via HTTP, organized into directories by language and country.

4.2. Multi-Locale Screenshot Tests

Below is the main test class, which runs multiple tests and captures screenshots at different points:

class ScreenshotTakerTest : FunSpec({

    val locales = listOf(
        "de" to "DE",
        "en" to "US",
        "es" to "ES",
        "fr" to "FR",
        "it" to "IT",
        "pt" to "BR",
        "ru" to "RU",
        "tr" to "TR",
        "uk" to ""
    )

    test("Screenshot for Main Page") {
        runAndroidComposeUiTest<MainActivity> {
            locales.forEach { (lang, country) ->
                activity?.setLocale(Locale(lang, country))
                waitForIdle()

                // Interact with UI
                onNodeWithTag("UsageMainColumn").performTouchInput { swipeUp() }
                waitForIdle()

                // Capture and upload screenshot
                takeScreenshot("main_page.png", lang, country)
            }
        }
    }
})

4.3. Helper Functions

The implementation relies on utility functions for common operations.

Setting the App Locale Updates the app’s locale dynamically during tests:

private fun MainActivity.setLocale(locale: Locale) {
    val resources = baseContext.resources
    Locale.setDefault(locale)
    val config = resources.configuration
    config.setLocale(locale)
    resources.updateConfiguration(config, resources.displayMetrics)
    runOnUiThread { recreate() }
}

Capturing a Screenshot Uses Jetpack Compose's captureToImage() to capture the current UI state:

private fun AndroidComposeUiTest<*>.takeScreenshot(file: String, lang: String, country: String) {
    sleep(3000) // Wait for animations to settle
    val bitmap = onRoot().captureToImage().asAndroidBitmap()
    uploadScreenshot(bitmap, file, lang, country)
}

Uploading the Screenshot Sends the captured screenshot to the local server:

private fun uploadScreenshot(bitmap: Bitmap, fileName: String, lang: String, country: String) {
    val tempFile = File.createTempFile(fileName, null).apply {
        outputStream().use { bitmap.compress(Bitmap.CompressFormat.PNG, 100, it) }
    }
    Fuel.upload("http://10.0.2.2:8081/upload?lang=$lang&country=$country")
        .add(FileDataPart(tempFile, name = "file", filename = fileName))
        .response()
}

Note: 10.0.2.2 is the ip address of the computer running the emulator. It's an special address

5. Conclusion

Automating screenshot testing in Android using Kotest and Ktor streamlines the UI validation process and ensures consistency across multiple locales. By combining Jetpack Compose testing utilities with an efficient local server, developers can easily capture, organize, and analyze screenshots during automated tests.

This approach offers several benefits:

Improved Efficiency: Automates tedious manual testing tasks.
Comprehensive Coverage: Validates UI behavior across different languages, countries, and configurations.
Centralized Storage: Screenshots are uploaded to a server and organized systematically for future analysis.

By adopting this solution, teams can reduce testing overhead, improve collaboration, and ensure a polished, reliable user interface. This setup can further be extended with CI/CD pipelines, enabling seamless integration into modern development workflows.

Start implementing automated screenshot testing today to enhance your app’s quality and streamline your development process.

Validar CPF facilmente em Kotlin

Leonardo Colman Lopes — Wed, 26 Aug 2020 23:14:09 +0000

NL;NL

Desenvolvi a biblioteca SimpleCPFValidator para facilitar validações de CPF em Kotlin.

Olá, Kotliners!

Todo novo cadastro de usuário em todo aplicativo segue sempre o mesmo padrão. Pedimos nome, data de nascimento e CPF de nossos queridos usuários quase que rotineiramente.

Quem já brincou de validar CPF sabe que é uma chatice contar todos os números, fazer valer com o digito verificador e zás e zás...

A validação

As regras de validação em si são bem simples, e estão facilmente disponibilizadas pela web, além das normas oficiais da receita.

CPFs com números repetidos (111.111.111-11, 222.222.222-22, ... 999.999.999-99) não são válidos
O CPF 000.000.001-91 é válido apenas para representar pessoas sem CPF
O cálculo maluco de digito verificador

Esta última regra é mais chata de entender. Este artigo do Só Matemática explica bem como funciona, mas se tiver interesse, leia:

O número do CPF é escrito na forma ABCDEFGHI/JK

O J e o K são o 1̣° e 2° dígitos verificadores

Para obter J multiplicamos A, B, C, D, E, F, G, H e I 
pelas constantes correspondentes:
| A   | B  | C  | D  | E  | F  | G  | H  | I  |
| 10x | 9x | 8x | 7x | 6x | 5x | 4x | 3x | 2x |
O resultado de 10A + 9B + ... + 2I é então dividido por 11, e
o valor que RESTAR da divisão será utilizado. Se o resto for
0 ou 1, J = 0. Caso contrário, J = 11 - resto

Para obter K. seguimos a mesma regra, porém com J no final 
da tabela, e começaremos a conta a partir de 11:
| A   | B   | C  | D  | E  | F  | G  | H  | I  | J  |
| 11x | 10x | 9x | 8x | 7x | 6x | 5x | 4x | 3x | 2x |
O resultado de 11A + ... + 2J é então dividido 
por 11, e a regra do resto será a mesma que o J.

É fácil, não?

As regras são simples, não são? Fáceis de entender do ponto de vista matemático e do ponto de vista de código. Então Por que é sempre tão chato implementar isso? Ou copiamos códigos de outros projetos, ou escrevemos um espaguete para seguir essas regras. Testar é complicado, e no final fica uma gororoba.

Essa gororoba precisa de manutenção, no entanto, e estará amarrada no nosso projeto pra sempre. Não queremos isso!

A maneira fácil

Em Kotlin temos a tendência de evitar boilerplates, e não carregar nosso código de tanta coisa.

Com isso em mente, desenvolvi a biblioteca open source SimpleCPFValidator. Ela colocará em seu projeto alguns utilitários para validação de CPF.

Busquei as regras originais para validação, e desenvolvi funções de extensão em cima disso:

val userCpf = userCpf.text
if(userCpf.isCpf()) {
    // Is CPF!
}

E simples assim, seu código conhece as regras de validação de CPF!

Por padrão, os caracteres . e - são retirados da String (permitindo o formato 123.456.789-11, por exemplo), mas isso pode ser modificado através do parâmetro charactersToIgnore:

"123.456.789/11".isCpf(charactersToIgnore = listOf('.', '/'))

Para utilizar essa lib em seu projeto,coloque em seu build.gradle:

implementation("br.com.colman.simplecpfvalidator:simple-cpf-validator:{version}")

Writing reusable tests with Kotest's Test Factory

Leonardo Colman Lopes — Thu, 16 Apr 2020 20:02:59 +0000

TL;DR - How to use Kotest 4.0.0 new Test Factory feature to include reusable blocks of test in your test suite

Hello, Kotliners!

In this article we'll see how to use a feature from the Kotest Framework to create reusable tests in your test suite, for cases in which you test multiple classes exactly the same way.

Declaring a Test Factory function

It's very easy to create a reusable test. You must first pick your favourite style among Kotest's test styles. You can pick any of them, but my personal favourite (and the one I'll use here) is FunSpec.

Declaring a test using FunSpec is as simple as:

class MySpec : FunSpec({
    test("Foo should not be equal to bar") {
        "foo" shouldNotBe "bar"
    }
})

Declaring the same test, but this time as a test factory is very similar:

// Top level val
val myReusableTest = funSpec {
    test("Foo should not be equal to bar") {
        "foo" shouldNotBe "bar"
    }
}

However, there are some cases in which having the same test will produce a different result if called multiple times. For cases which our tests depend on some parameters, we might rather want to use use this as a function:

fun myReusableTest(myParameter: String) = funSpec {
    test("$myParameter should not be equal to bar") {
        myParameter shouldNotBe "bar"
    }
}

Both cases can be included in any Spec by using the include function:

class MyTest : FunSpec({
    test("My usual test") {
        // ...
    }

    include(myReusableTest("A"))
    include(myReusableTest("B"))

    test("Another usual test") {
        // ...
    }
})

And as expected, the tests from the test factory are applied!

A small example

Now that we understand the basic concept, let's play a little bit with a more realistic example: Calculators! ~~really realistic, everyone implements calculators~~

Let's suppose we have 3 types of calculators:

A Sum Calculator
A Subtraction Calculator
A Complete Calculator, that can do both operations.

interface SumOp {
    fun sum(a: Int, b: Int): Int
}

object SumCalculator : SumOp {
    override fun sum(a: Int, b: Int) = a + b
}

interface SubtractionOp {
    fun subtract(a: Int, b: Int): Int
}

object SubtractionCalculator : SubtractionOp {
    override fun subtract(a: Int, b: Int) = a - b
}

To test these implementations, we would create a Spec for each:

class SumCalculatorTest : FunSpec({
    test("Sum 2 and 2 should be 4") {
        SumCalculator.sum(2, 2) shouldBe 4
    }
})

class SubtractionCalculatorTest : FunSpec({
    test("4 minus 2 should be 2") {
        SubtractionCalculatorTest.subtract(4, 2) shouldBe 2
    }
})

When implementing our CompleteCalculator, we should test these behaviours as well.

object CompleteCalculator : SumOp, SubtractionOp {

    override fun sum(a: Int, b: Int) = a + b

    override fun subtract(a: Int, b: Int) = a - b
}

class CompleteCalculatorTest : FunSpec({
    test("Sum 2 and 2 should be 4") {
        CompleteCalculator.sum(2, 2) shouldBe 4
    }

    test("4 minus 2 should be 2") {
        CompleteCalculator.subtract(4, 2) shouldBe 2
    }
})

We have ended up writing the same test that we already wrote for sum calc and sub calc. This is duplication that we'd like to try and avoid.

Now let's exercise what we learned previously. Writing tests through composition:

fun sumTests(calc: SumOp) = funSpec {
    test("Sum 2 and 2 should be 4") {
        calc.sum(2, 2) shouldBe 4
    }
}

fun subtractionTests(calc: SubtractionOp) = funSpec {
    test("4 minus 2 should be 2") {
        calc.subtract(4, 2) shouldBe 2
    }
}

class SumCalculatorTest : FunSpec({
    include(sumTests(SumCalculator))
})

class SubtractionCalculatorTest : FunSpec({
    include(subtractionTests(SubtractionCalculator))
})

class CompleteCalculatorTest : FunSpec({
    include(sumTests(CompleteCalculator))
    include(subtractionTests(CompleteCalculator))
})

And voilà! We successfully reused a test for more than one scenario!

What could this be useful for?

In the real world we won't be implementing calculators as often as we want to. So, why would I use this kind of factory and composition?

We created these Test Factories for any kind of repeatable test pattern. For example:

If you need to test that every Repository<MyEntity> creates a database entity with a new ID
If your cache and your actual database return data in the same format
If sending a POST request to some endpoint always returns the payload in a specific format
If all instances of a sealed class have their class' name on the toString function

And much more scenarios that you might be exploring with!

Handling fixed-length files using a Kotlin DSL

Leonardo Colman Lopes — Wed, 13 Nov 2019 12:34:36 +0000

TL;DR - Fixed Length files can be troublesome to handle, and even more troublesome when there are multiple kinds of records on the lines. To solve this, we'll use Guiabolso's fixed length file handler, a library designed just for this purpose.

Hello Kotliners!

In this article we will see a little bit on how to handle fixed-length files by using this library, by Guiabolso (with some contributions made by myself). There are many solutions for this kind of problem on the JVM, but all of them are focused on Java.

These libraries are old and not optimized for Kotlin, and become very cumbersome/verbose to use. We created a Kotlin-DSL to handle these cases in a beautiful and concise way.

Remembering: What is a Fixed-Length file?

If you ever worked with a fixed length file, you know that most of the times it's a big pain in the ass.

Photo by Tim Gouw from Pexels

A fixed length or fixed width file is a file containing data separated by fields. These fields have a specific length and is sometimes prefixed/suffixed with a character to denote emptiness, such as 0003 for an int 3 of fixed length 4.

An example of a fixed length file is the following:

Kotlin    1201.63
Java      0219.52
Python    0129.62
Javascript0308.43

It represents data from PYPL, and the data is organized as:

Field	From index	To Index	Padding
Language Name	0	10	RightPadding(' ')
Ranking	10	12	LeftPadding('0')
Share %	12	17	LeftPadding('0')

This kind of file is broadly used by legacy systems (I'm looking at you, banking system), and integrating with them is troublesome and not fun.

Parsing fixed-length files

These files are hard to understand and boring to deal with. The solution to parsing them usually involves a lot of string manipulation and manual buffer control (or bringing the entire file to memory if it's viable).

When dealing with Kotlin code, this verbosity is annoying. We want simplicity and conciseness.

For this, the company I work for, Guiabolso, developed a small library for fixed-length file handling in Kotlin.

GuiaBolso / fixed-length-file-handler

Handlers for Fixed Length files in a beautiful Kotlin DSL

This library provides a beautiful ~~(I wrote it, so I can say it's beautiful, right?)~~ Kotlin DSL to parse this kind of file. Using our previous example as example:

data class PYPLRecord(langName: String, ranking: Int, share: Double)

val pyplSequence = fixedLengthFileParser<PYPLRecord>(fileStream) {
    PYPLRecord(
        field(0, 10, Padding.PaddingRight(' '),
        field(10, 12, Padding.PaddingLeft('0'),
        field(12, 17, Padding.PaddingLeft('0')
    )
}

This will allow us to map our file to a lazy Sequence, which will process the file as a stream instead of bringing it to memory. The library already supports many of the usual Java/Kotlin types, without having to cast and translate them.

"Advanced" fixed-length files

For some reason yet to be defined reason, some of these legacy systems use the same file for more than one record type

Photo by Juan Pablo Serrano Arenas from Pexels

In these cases, our example above will be used for more things, such as Developer Name and Preferred Language

1Kotlin    1201.63
1Java      0219.52
1Python    0129.62
1Javascript0308.43
2Leonardo Colman LopesKotlin
2Jane Doe             Javascript

The type of the record is marked at some position in the line, and your system must find a way to parse it any way.

This leads to a bigger String manipulation spaghetti and a more unsustainable code.

The library also provides a way to parse this kind of file:

data class PYPLRecord(langName: String, ranking: Int, share: Double)
data class DevRecord(devName: String, preferredLang: String)

fixedLengthFileParser<Any>(fileInputStream) {
    withRecord({ line -> line[0] == '1' }) {
        PYPLRecord(
            field(1, 11, Padding.PaddingRight(' '),
            field(11, 13, Padding.PaddingLeft('0'),
            field(13, 18, Padding.PaddingLeft('0')
        )
    }

    withRecord( { line -> line[0] == '2' }) {
        DevRecord(
            field(1, 22, Padding.PaddingRight(' '),
            field(22, 32, Padding.PaddingRight(' ')
        )
    }
}

We believe that parsing fixed-length files will be easier with this library, and we hope to help anyone that needs this kind of feature. Take a look!

GuiaBolso / fixed-length-file-handler

Handlers for Fixed Length files in a beautiful Kotlin DSL

Fixed Length File Handler

Introduction

When processing data from some systems (mainly legacy ones), it's usual to have Fixed Length Files, which are files that contain lines which content is split using a specific length for each field of a record.

This kind of files are sometimes tricky to handle as many times there is a spaghetti of string manipulations and padding, and character counting and... Well, many things to take care of.

This library comes to the rescue of programmers dealing with fixed length files. It enables you to simply define how your records are structured and it will handle these records for you in a nice Kotlin DSL for further processing.

Using with Gradle

Import it into your dependencies:

dependencies {
    implementation("br.com.guiabolso:FixedLengthFileHandler:{version}")
}

Basic Usage

The basic usage assumes that you're reading a file with a single type of record.

Given a Fixed-Length File:

…

View on GitHub

Testing Koin applications with Kotest

Leonardo Colman Lopes — Mon, 22 Jul 2019 15:09:16 +0000

TL;DR - Using the KoinListener from Kotest to write tests that depend on Koin modules in a Kotest Spec

Hello, Kotliners!

In this article we will see how to test applications that use the Koin DI Framework in a Spec from the Kotest Framework. We'll take the JUnit example from Koin's documentation and enhance it with Kotest.

3 simple steps

Add Kotest's Koin extensions to your build.gradle
Transform your JUnit test into a Kotest Spec (or create one from scratch)
Add the KoinListener to your class

Add Koin extension to your build.gradle

On your build.gradle file we'll add the Koin Extension dependency as a testImplementation. I'm assuming you already have Kotest configured. If you don't, take a look at the docs on how to do it.

I like to keep the Koin Extension definition close to my Kotest definition

build.gradle

dependencies {
    // ... Your dependencies ... 

    // Kotest
    testImplementation("io.kotest:kotest-runner-junit5:{version}")
    testImplementation("io.kotest:kotest-extensions-koin:{version}")

}

Transform a JUnit test to a Kotest Spec

For this example, we are going to use the JUnit example from the Koin docs:

class MyTest : KoinTest {

    // Lazy inject property
    val componentA : ComponentA by inject()

    // use it in your tests :)
    @Test
    fun `make a test with Koin`() {
        startKoin { modules(appModule) }

        // use componentA here!
    }
}

Converting the test

There are a lot of styles that can be used in Kotest, let's try with FunSpec

class MyTest : FunSpec(), KoinTest {


    // Lazy inject property
    val componentA : ComponentA by inject()

    init {
        test("Make a test with Koin") {
            startKoin { modules(appModule) }

            // use componentA here!
        }
    }

}

This will already work!

This example works in the same way as the JUnit code. If we add more tests to the class, we'll have to clear Koin's context. In JUnit we create a @After method. Let's see how to do this in Kotest

Add KoinListener to the class

To fix this, we can either override the afterTest function, that works similarly to @After or we can use the KoinListener to do that automatically for us! Let's try with that approach:

class MyTest : FunSpec(), KoinTest {

    override fun listeners() = listOf(KoinListener(appModule))

    // Lazy inject property
    val componentA : ComponentA by inject()

    init {
        test("Make a test with Koin") {

            // use componentA here!
        }
    }

}

With KoinListener we will have Kotest handle both Koin's start (see that we removed that line in our test!) and Koin's stop.

And that's it!

With this simple setup, you'll be able to test your Koin Application with Kotest, and use all the available features from both of them!

If you still have any doubt, check out the full documentation on KoinListener

Testing System Properties and System Environment with Kotest

Leonardo Colman Lopes — Sun, 21 Jul 2019 21:16:50 +0000

TL;DR: Test code that uses System.getenv() or System.getProperty() with easy-to-use functions with Kotest

Hello Kotliners!

In this article we'll discuss a little bit two features of Kotest:

System Environment extensions
System Property extensions

They're very similar on their implementation and use, and are very easy to use!

The problem

In the JVM world, some (many) times our code depends on what the system provides us, usually through Environment Variables or Properties passed to the JVM.

However, neither is very easy to test when we want to use it.

The System.getenv() map is immutable. We can't set it up using plain Java
Messing with System.setProperty() manually forces us to do all the setup and tear-down, and becomes very verbose and cumbersome


Photo by Victoria Heath on Unsplash

The solution

Kotest provides some extensions and listeners to handle these scenarios. The complete documentation can be found here

System Environment Extensions

If the piece of code under test is small enough and used only once, we can use the withSystemEnvironment. It has overloads, but we'll use the key and value one. There's an overload expecting a Pair<K,V> and one expecting a Map<K,V>

class EnvironmentTest : FunSpec() {
    init {
        test("Changing environment") {
            withSystemEnvironment("fooKey", "barValue") {
                System.getenv("fooKey") shouldBe "barValue"
            }
        }
    }
}

System Properties Extensions

In the same fashion as above, we have the function withSystemProperties, that works very similarly:

class PropertyTest : FunSpec() {
    init {
        test("Changing System Properties") {
            withSystemProperties(mapOf("fooKey" to "barValue", "booKey" to "batValue")) {
                System.getProperty("fooKey") shouldBe "barValue"
                System.getProperty("booKey") shouldBe "batValue"
            }
        }
    }
}

Cleanup

After the execution, the previous values will be set to what they were before. What is already in the map will remain untouched during the execution.

Test Listeners

Perhaps your code require the specific properties in every test. You can configure the SystemPropertyTestListener and the SystemEnvironmentTestListener for that:

class SystemEnvironmentTestListenerTest : FunSpec() {

    override fun listeners() = listOf(
            SystemEnvironmentTestListener("fooKeyEnv", "barValueEnv"),
            SystemPropertyTestListener("fooKeyProp", "barValueProp")
        )

    init {
        test("System Property") {
            System.getProperty("fooKeyProp") shouldBe "barValueProp"
        }
        test("System Environment") {
            System.getenv("fooKeyEnv") shouldBe "barValueEnv"
        }
    }
}

The original values will reset after the test execution.

Project Listener

You can also set these globally by using the SystemEnvironmentProjectListener and the SystemPropertyProjectListener. More information on Project Configuration can be found in Kotest's Docs

class ProjectConfig : AbstractProjectConfig() {
    override fun listeners(): List<TestListener> = listOf(SystemEnvironmentProjectListener("foo", "bar"))
}

Override Mode

All the above extensions accept a parameter of the enum OverrideMode.

SetOrOverride - If the key we want to set is already in the properties/environment, we want to override it for the test
SetOrIgnore - If the key is already present, we'll not override it and the test will continue
SetOrError (default) - If the key is already present, interrupt the test with an Exception

These are very useful if you need to use, for example, a property in the global listener, but want to override it in a specific test.

withSystemProperty("foo", "bar", OverrideMode.SetOrOverride) {
    // foo is overrided here
}

Extensions in action

I've published 2 small and simple libs that exercise these listeners and extensions:

SimpleProperties - That reads values both from Environment and Properties. Test Class. It's even possible to see both extensions used at once
SimpleFeatureThrottler - A similar approach can be seen in this test class

Testing a Spring Boot application with Kotest

Leonardo Colman Lopes — Thu, 11 Jul 2019 03:49:44 +0000

TL;DR - How to use the SpringListener from Kotest to test Spring Boot applications, including some samples

Hello Kotliners!

In this article we'll see how to test Spring Boot apps using the Kotest Framework. We'll see some examples on how we test things using JUnit, and how to easily move to Kotest and enjoy it's features.

3 simple steps

Add Kotest's Spring Extension to your build.gradle
Transform your JUnit test into Kotest format (or create a new test from scratch)
Add the SpringListener to your class

Add Kotest Spring Extension

On your build.gradle file we'll add the Spring Extension dependency as a testImplementation. I'm assuming you already have Kotest configured. If you don't, take a look at the docs on how to do it.

I like to keep the Spring Extension definition close to my Kotest definition

build.gradle

dependencies {
    // ... Your dependencies ... 

    // Kotest
    testImplementation("io.kotest:kotest-runner-junit5:{version}")
    testImplementation("ioio.kotest.extensions:kotest-extensions-spring:{version}")

}

Transform a JUnit test to a Kotest Spec

For this part we'll assume that we already have a component in our application:

@Component
class SimpleComponent {
    fun foo() = "Bar"
}

Yes yes, it's very simple and very dummy... But stay with me, we will go step by step!

We usually write a JUnit + Spring integrated test for this, validating that this bean works correctly.

There.are.many.guides that show us how to do it. Let's take this basic approach:

@RunWith(SpringRunner::class)
@SpringBootTest
class SimpleComponentTest  {

    @Autowired
    private lateinit var simpleComponent: SimpleComponent

    @Test
    fun fooShouldReturnBar(){
        Assert.assertEquals("Bar", simpleComponent.foo())
    }
}

Transform that test in a Kotest Spec

There are a lot of styles that can be used in Kotest, let's try with FunSpec.

Let's convert it exactly as is:

@RunWith(SpringRunner::class)
@SpringBootTest
class SimpleComponentTest : FunSpec() {

    @Autowired
    private lateinit var simpleComponent: SimpleComponent

    init {
        test("foo should return Bar") {
            simpleComponent.foo() shouldBe "Bar"
        }
    }
}

Aaaand our test crashes.

kotlin.UninitializedPropertyAccessException: lateinit property simpleComponent has not been initialized

It's ok, it's ok! We need to tell Kotest that this is a Spring Test!

Add the SpringListener to the class

To fix the above error, we need to add the SpringListener to our class' listeners:

@SpringBootTest
class SimpleComponentTest : FunSpec() {

    override fun listeners(): List<TestListener> {
        return listOf(SpringListener)
    }

    @Autowired
    private lateinit var simpleComponent: SimpleComponent

    init {
        test("foo should return Bar") {
            simpleComponent.foo() shouldBe "Bar"
        }
    }
}

Notice that we also removed the @RunWith(SpringRunner::class), as we are not running with JUnit anymore.

And voilà, it works!

Of course this is a very modest example. What about all the other configurations? Profiles, context configuration, TestConfiguration?

Don't worry! they'll work the same way as we're used to in JUnit. Annotating the constructor and such.

For example, messing with profiles:

@SpringBootTest(classes = [Components::class])
@ActiveProfiles("test-profile")
class ActiveProfileSpringTest : FunSpec() {

    override fun listeners() = listOf(SpringListener)

    @Value("\${test-foo}")
    lateinit var testFoo: String

    init {
        test("Should load active profile properties correctly") {
            testFoo shouldBe "bar"
        }
    }

}

test from Kotest test suite

And this is all we have for today! Go ahead and test your Spring Apps with Kotest! More information on this extension can be found at the docs

Doubts? Suggestions? Leave us a comment!