I don’t think you still need to be convinced of the need of TestContainers when you write Unit Tests. There are plenty of good articles that explain why it should be done, for instance when testing against a DB, or a message broker. In short, in hexagonal architecture, providing your adapters with the real world implementation. My favorite article, that truly made me understand it, was from Philip Hauer’s blog.

Nothing beats real wire connection: your in memory stubs implementations will always be flawed by design. Moreover, if you’re using Postgres for instance, you can even run all your database migration scripts before running your tests, ensuring they are working as expected as part of the tests.

I recently changed tech stack from Kotlin+Springboot to a new full Golang stack in my new awesome team at Ubisoft. I had to re-learn things that were obvious to me such as dependency injection, new packages layout and so on.

But one thing was really missing from my previous experience: TestContainers. I used to use it to locally substitute production document or relational databases, AMQP message brokers. I could not live without it. The test confidence that those bring is unmatched. (I’m a big fan of DDD/TDD concepts, so asserting your application/service layer work as intended against an actual implementations of repositories is priceless)

I was astonished when I discovered github/testcontainers-go and its nice documentation page. Here are the advice I can give you to make them work in your Golang Unit Tests environment.

If you would like to see the code first, all following code snipets are available at my personal Github.

Let’s say you want to test a service that manipulates a repository holding video games, at random 😉, Ubisoft games:

The first thing you usually do is implement your tests against an in memory implementation of this repository. I’ll leave the implementation details to the Github repository.

Being a DDD oriented person, you could write your tests that way, following an arrange/act/assert (AAA) pattern:

The tests pass, that’s nice, but you just tested against an in memory implementation… Antón would not be proud of you.

Now, where does that allGames come from? It would be nice if we could substitute any implementation to the interface.

I like to use a Golang test routines integration called TestMain (official doc). By convention, it helps defining setup and teardown behaviour during all tests execution from the current package. It has to be declared within a _test.go file, obviously.

A small example would be:

Now that you get the concept, let’s write the logic. Here we first describe what a docker image is, and the repository interface I want to satisfy. Then I reuse the testcontainers.Container struct to add a URI to it, that will hold the exposed container endpoint, with its dynamic port.

Then we can concentrate on how we will prepare and run the container using the library:

It is pretty straightforward, and reuses the Java library terms that I was used to. You first describe the ContainerRequest that you provide to the GenericContainer . Then, on l.12 the container will already be running with a local random available port mapped on your local interface.

To get this dynamically picked port you just call the MappedPort function.

Last, we return the full scheme mongodb://host:port that will now be ready to satisfy your testing needs.

I use this prepareContainer function in a setup function to create a container struct that we previously described:

All remains is to integrate it. I chose the following strategy:

If I get an error running the container — that most likely will be caused by an environment without an up and running docker daemon — or if for some reason the database is not reachable, I fall back to an in-memory (mem) implementation of the repository. It’s up to you to decide what to do here.

The nice thing here is that the tests we previously wrote in the AAA pattern will not have to be rewritten, they should run the same against any implementation of the repository, should it be the mongo one or the mem one.

You could also enforce that any dev on your team runs docker to locally test your services and I won’t even be mad at you 😇.

To get to the point, here is the final implementation of the TestMain function:

Then, when we run the tests, we get the following output:

2022/05/02 17:15:22 Starting container id: 9d9d56e5bcf1 image: docker.io/testcontainers/ryuk:0.3.3
2022/05/02 17:15:22 Waiting for container id 9d9d56e5bcf1 image: docker.io/testcontainers/ryuk:0.3.3
2022/05/02 17:15:22 Container is ready id: 9d9d56e5bcf1 image: docker.io/testcontainers/ryuk:0.3.3
2022/05/02 17:15:22 Starting container id: 4a1e5d93a03f image: mongo:5.0.8
2022/05/02 17:15:23 Waiting for container id 4a1e5d93a03f image: mongo:5.0.8
2022/05/02 17:15:24 Container is ready id: 4a1e5d93a03f image: mongo:5.0.8
2022/05/02 17:15:24 TestContainers: container mongo:5.0.8 is now running at mongodb://localhost:54970
=== RUN   Test_Add
--- PASS: Test_Add (0.02s)
=== RUN   Test_Replace
--- PASS: Test_Replace (0.01s)
=== RUN   Test_By
--- PASS: Test_By (0.00s)
=== RUN   Test_All
--- PASS: Test_All (0.00s)
PASS

🎉 Congratulations Gringo 🎉, you’ve successfully used TestContainers to run your Go unit tests against an actual instance of a database!

It opens a lot more, anything that can be containerised could be used. In my current project, we use it to spin up a Postgres and an AWS DynamoDB at the same time for a full test suite.

If you want to access, compile or run the code used in this article, feel free to go and clone it from my personal Github.

Adiós!

Koson: A Kotlin DSL To Write And Serialize JSON

The Scene

When you write code for distributed apps, especially in the all mighty microservices era, there is one word that keeps showing up during technical conceptions: format.

“What human readable format will our services use to exchange messages?”

“What scheme will we be using to provide the standard output with logs?”

Very often nowadays, the answer lies within four letters: JSON (JavaScript Object Notation). Although there are other human readable alternatives (yaml is less verbose, but indentation sensitive; XML is more verbose etc.) more and more people tend to suggest (and use) JSON.

Our technical stack, as far as the JVM is concerned, is now completely implemented with Kotlin+SpringBoot services. These services produce their logs according to a specific format, that is described using JSON. They also use JSON to serialize and deserialize outgoing and incoming messages. These messages are then also validated using JSON schemas.

Long story short, JSON has become key to how we communicate, manage logs, provide and consume APIs to/from different teams.

The Problem

We all tend to like things simple. However when you are not in a JavaScript first class citizen technical stack, it can be tedious to always have to write classes just for the sole purpose of serializing and deserializing JSON. You very often have to rely on a serialization library like Jackson. To add insult to injury, sometimes when writting unit tests, you just want to provide a method, an endpoint, a BDD test with a simple JSON object.

What are your choices if you want to avoid relying on a library or a framework?

You could always use Kotlin's multiline Strings to format your objects, especially since there is a pretty good integration in IntelliJ IDE. You could even inject language reference (Alt+Enter → Inject language or reference → JSON) and would benefit from some coloration/completion while creating your object.

But ultimately, every developer has to remember there is such a functionality in their IDE to benefit from these tools. However, if you want to play a bit more with formatting and still keep the code maintainance easy for future developers, this is not ideal. You can then decide to switch to a trimMargin() version.

But then JSON language injection would be lost because of the introduced | chars.

These solutions may suit you perfectly. But keeping up with upcoming code change while keeping indentation the way you want can be tricky.

The Idea

It all started from a rather simple observation: Kotlin internal DSLs allow its users to design APIs that fit well with the language, obviously.

But other interesting aspects arise. Since Kotlin allows for a very good interop with Java, it is also possible to wrap existing libraries into a nicer looking Kotlin hierarchical syntax, or even use the language as core descriptor for a build tool, such as Gradle 's Kotlin DSL.

The advantages are numerous: you’ll get code completion & formatting for free while benefiting from the compiler’s type checks.

Without digging too deep into Kotlin 's design, DSLs heavily rely on these 5 language specificities :

• extension functions
• infix notation
• higher order functions
• lambdas with receiver
• the trailing lambda rule

Koson was created using these functionalities only. No other third party libraries are used, resulting in a very lightweight Kotlin library.

Koson

lectra-tech/koson

Koson was open sourced under the MIT licence in 2018. Some functionalities have been added over the years, but mainly, this is how you use it:

obj and arr are the main entry points of the library, allowing to start describing your JSON content.

Here is another example:

// 1 Will output a single line formatted JSON String:

{"key":3.4,"anotherKey":["test","test2",1,2.433,true],"nullValue":null,"emptyObject":{},"emptyArray":[],"custom":"2020-07-15T10:59:19.042965+02:00[Europe/Paris]"}

// 2 Will output a 2 whitespaces indented JSON String:

Now the good thing is you will benefit from syntax highlighting, code completion, formatting and even type safety.

For instance the library prevents errors at compile time:

Koson also allows the user to feed an Iterable as a source for an array, external JSON source embedding and custom types definition if you are not happy with the way Koson serializes all “primitive” types.

How does it work?

Long story short, everything you use is defined in a single Koson.kt file.

The obj is a function with a lambda with receiver parameter that operates over a Koson type. The Koson class is used to produce an ObjectType, that can add a finite instance type list to the object.

The arr is in fact a singleton (object in Kotlin) that uses the operator overload to permit the use of the [] as a function. It returns an ArrayType when invoked.

To sum it up, here is a diagram to show the full type hierarchy.

If you are curious and want to check out the implementation details, or why not contribute to improve this library, feel free to check the official github repository here : https://github.com/lectra-tech/koson

If you want to learn more about how Kotlin DSL can be written, you can watch this video (FR only) by Benoit introducing Kotlin DSLs.

There also is a video of a talk I gave (FR only) explaining how a private company can contribute to OSS and why they should, even if they think they don’t have material to do so. It also shortly explains how Koson’s publication process works.

Performance

Now that’s nice, but how does it behave? Is it faster than using your favorite serialization library?

To try answering that question, we’ve built 4 different benchmarks using the JMH OpenJDK tool. If you want to have a look or run the benchmarks on your machine, you’ll find all the details on our github page and in the following embedded project.

To sum it up, here are the results in operations/second (throughput mode), higher = better.

Conclusion

If your only need is having to create JSON String representations from scratch in Kotlin, Koson is made for you. Feel free to ⭐ the project if you enjoy it, use it, and why not suggest improvements using issues !

Kotlinly yours ;)

At my company (Lectra), an increasing number of backend Cloud applications use Kotlin. The need of using a strongly typed language came from a simple fact : it drastically reduces bugs, since everything your compiler/IDE does for you is something you don’t have to think about. Then you can simply focus on the domain code, and more importantly what your application is supposed to do. Kotlin was designed with this idea as ground rule.

Kotlin bundles a very powerful syntax : sealed classes. We will only focus on one aspect of it in this article.

A sealed class can be considered as a type with a finite set of subtypes. It is simply defined this way :

This class is by default abstract, and cannot be instantiated.

Now we can define sub-classes. However you don’t have to think about these sub-classes as inheritance (event if it is generated this way in the bytecode) but more like a type catalog, a type enum, or a kind of distinct union types (as in TypeScript)

Note the () constructor for each of these types. Now we have a concrete class to represent a booking, two singleton instances to improve the expressiveness of the different choices. You could also choose to use a data class if needed.

Now, here is the interesting part. In Kotlin, the compiler/IDE is aware of this sealed class hierarchy exhaustiveness. What this means is, when you will provide a service for your consumers, it reveals all its power :

Now for the fun part. For every consumer of your service, the sealed class BookingOutcome becomes the contract. Meaning every caller will benefit from the compiler checks whether they exhaustively planned (or not) to handle all your possible outcomes !

For instance :

Now IntelliJ and Kotlin compiler will come to the rescue ! When combined with the when keyword, it is a very strong way to enforce the way an API is used. (‘when’ is Kotlin’s version of Java’s ‘switch’ , with a pattern matching-like syntax)

It even does the beginning of the work for the consumer :

More importantly, it will not compile if the branches are not complete, or without a willingly declared else -> branch !

Since it is a “pattern matching”-like friendly language, it will even auto smartcast on the right side.

We’ve only seen one aspect of sealed classes in this article, but it should really become a reflex when you think about enumerations that carry any kind of useful information for your services/APIs or any kind of type expressiveness you want to achieve.

Kotlinly yours ;)