Three article series about how to manage technical debt in a simple and fun way.

Why teams struggle with technical debt. Technical debt definition adapted to modern times. Introduction to a simple framework to classify and see technical debt impact in a team.

Keep reading!

We will evolve the simple framework by using industry standard definitions, like the sofware architecture illities and explaining by example, grouping them on predefined categories.

Part 2 (coming soon!)

Standardize metrics, language and communication to allow company wide alignment and high level planning. Examples of how this framework can be used across different teams.

Part 3 (coming soon!)

Introduction

Recently, I met with a team to share ideas about how they (engineering and product owners alike) could raise awareness of the importance of their tech-debt, but also how to take ownership of it. For some reason, this team had heavy churn, and the engineers could not find a way to remove or tackle their pain points during their sprints.

With other team members, we had already identified some items in various repositories and services, but we had not been able to onboard everyone on the importance of them. For example, there were some code smells, some services had tons of legacy code (with few tests or no documentation) and other stuff that usually is considered technical debt.

The most senior or historic engineers on the team did not consider lack of documentation or tests as technical debt (after all they were the technical experts and owners of the repositories), but the product owners were seeing some slowness onboarding new engineers on the team. On the other hand, the product owners had not noticed some technical deficiencies (or if they were they thought there was almost no impact) as technical debt, but the engineers were not happy with some old tools, libraries and patterns used.

Although when reading the above examples it might be clear a relationship exists between the pairs, it needed external feedback to make the whole team aware of it. It was not a problem of communication between engineers and product owners, it was just that they were not able to align themselves nor see the impacts of each other’s worries or the relation with parts of their code.

So we gathered together again, this time hands-on to try to find the best approach to the problems they were facing:

• How to identify if something was really tech-debt or just a false positive
• How to measure the impact of each tech-debt item
• How to reach consensus within the team (including product owner) that a given piece of software needed some love :heart_eyes: :hearts: ^{:hearts: :hearts:}

Basically we were going to observe, measure impact and raise awareness.

The first iteration

We tried to start small, with specific examples and use cases, in order to then iterate over them trying to find generalizations.

So we started with a very basic question:

What things do we have that we believe are tech-debt right now? (aka what are our current pain points?)

We identified some of them (and left some for the next iterations):

We intentionally left some stuff aside as at this point we already began to discuss that some pain points were consequence of others; for example, slow onboarding was a direct consequence of not having good enough documentation.

We decided to follow that line of thought (consequences and impacts) later on, instead focusing at that moment on extracting common information from our items by grouping or classifying them.

In order to classify something, you need a criterion. Our criteria were not clear then but became clearer when we saw the impacts, much later on. At this stage we just tried to group it, and we saw some “architectural deficiencies”, some “things related to production” and finally other stuff related to “how fast and happy the team was” while working on certain repositories.

We used the initials A, O and S to tag our items:

We had reached a stage where we could simply add some tags to given tech-debt items that gave some inspiration to categorize them, but most importantly, we were able to extract the impact. Effectively, how we were categorizing an item told us about its impact.

Retrospective

This very first iteration was so powerful! We were really happy, as this gave us great insights but also offered opportunities to establish some technical debt goals within the team. We could focus on specific themes (using the impact) according to the upcoming user stories and thus was a great way to align everyone, from product to engineering, into dealing with technical debt.

We did a small retrospective, and we all agreed that while it was powerful to raise awareness, we could benefit even more if we dug deeper on the framework we were creating.

Some examples

Let’s say there are new features involving integrating with third parties that will consume our fancy new API, that was just built in a hurry for a PoC, in the next quarter. We had identified some tech debt related to speed on that part of the codebase, like not enough tests, documentation, or some code that needs refactor because it was just a PoC. We know that this will impact the time to market, so we can anticipate and just focus as a technical goal for the sprints to “improve the time to market for new API features” while working on the user stories. Focusing only on that goal (for example omitting any big architectural refactor) we could tackle our codebase at the same time we were delivering new value.

Maybe our Company is expecting a peak in our # of requests because of some sales goals (go sales, :moneybag: go!), and we need to focus on improving our operations stuff, like monitoring, scaling or making the jobs resilient and parallelizable. This way, we could introduce technical parts to the user stories (for example, the big architectural refactor that we omitted before) that were aligned with the company goals or certain user stories.

Technical Debt

What is Technical Debt

How do we know that something is technical debt? Because we are afraid to work on it. Or because it hinders product development by not being able to achieve the speed we want. Or maybe because it breaks too much. Or it is not aligned with the company strategies…

Sounds familiar? Basically it is what the second image above illustrates: Team Speed Stuff, Operations Stuff and Architecture Stuff. In other words:

• Techdebt doesn’t allow product owners to deliver features at the speed they want: It slows development teams
• Techdebt are also pieces of software that we cannot maintain any longer (obsolete technology, tools or lack of experts): it is not aligned with company strategies
• Techdebt is also present when some products break too often or even don’t work as expected: products already running in the company that have a high operational cost

Basically, it is a slow poison, draining resources from the company or increasing the cost to deliver new value.

What is the formal definition?

From Wikipedia:

The formal definition states that technical debt reflects the implied cost of additional rework caused by choosing an easy (limited) solution now instead of using a better approach that would take longer. Technical debt can be compared to monetary debt. If technical debt is not repaid, it can accumulate ‘interest’, making it harder to implement changes later on. Unaddressed technical debt increases software entropy. Technical debt is not necessarily a bad thing, and sometimes (e.g., as a proof-of-concept) technical debt is required to move projects forward.

From: Martin Fowler:

Software systems are prone to the build up of cruft - deficiencies in internal quality that make it harder than it would ideally be to modify and extend the system further. Technical Debt is a metaphor, coined by Ward Cunningham, that frames how to think about dealing with this cruft, thinking of it like a financial debt. The extra effort that it takes to add new features is the interest paid on the debt.

At this point we could use one of the wide known definitions of tech debt, but we decided to go with our own.

Why would we change it?

Simply, because software engineering has evolved a lot since the first of those definitions were introduced back in 1992 by Ward Cunningham.

Now we use infrastructure as a code, microservices architecture, CI/CD, agile philosophy, and evolved technology stacks, some of which were born just a couple of years ago and give a competitive advantage over old ones.

We have seen stacks rise and fall since then, and using those dead stacks was not considered technical debt at the time, they were state of the art. We consider that anything in engineering that induces a cost for the company to grow, deliver or build new features is technical debt, be it new developments or things already in production. From architecture to code but also, culture and training.

The above definitions define technical debt when the software is created, not when the environment changes.

This was our amendment to the classic technical debt definitions:

We do not consider technical debt only stuff made consciously, but also things made some time ago which needs reconsideration based on current software engineering standards, tools and technology, but also on updated company strategy and needs.

This updated definition helped us to revisit our projects periodically to make sure they are aligned with company strategy but also helps us to deprecate things we are going to evolve when their stacks become obsolete.

How technical debt is born

Technical debt is not only born in the code. This is one of the biggest mistakes that startups make when thinking about it. This also happens in established companies. According to our definition above it can be born in different ways.

Let’s explore some examples:

• A stakeholder meeting establishing a plan for the company to duplicate clients or traffic will spawn a bunch of technical debt items to optimize performance, allow scalability or other evolutions that are needed to achieve that goal. Especially if scalability was not important for some services previously, and thus their architecture was not focused on that.
• Our company is not yet ready to use fully automated CI/CD pipelines, and we have some manual QA testing, and some teams keep detecting in their retrospectives that there is a problem there, needing additional environments or just evolving the pipelines and training the team to help them automate those tests.
• A new technology spawning in our market that gives an advantage to competitors and forces the company to switch to it, evolving architectures or tools, or just because there is a lack of engineers working in our previous technology stack.
• A merge is happening with another company, and we need to improve our ability to integrate with them, by improving our documentation, APIs and standardization.
• A library we were using in the past suddenly gets a new major version and drops support and compatibility with the previous one. While dead (maintenance mode) projects could keep using the library, keeping it on live/active projects could trigger a problem in the near future.
• A quick bug fix that did not pass a proper code review gets forgotten in the codebase. Also, this bug fix has unforeseen consequences
• …

I stumbled recently upon this blog entry Intentional Qualities from Roman Elizarov and would like to highlight a couple of paragraphs there:

See, the fact is that you cannot accidentally write a software that has a specific quality. You cannot accidentally write fast code. Your code cannot be secure by an accident. Accidentally easy to learn? Never heard of it.

[…]

Qualities are often lost by an accident, but are never accidentally acquired. It is similar to the second law of thermodynamics. In order to maintain quality you have to be very conscious, intentional about it. You have to constantly fight against losing it.

I love that statement! You can start writing code that follows a target (secure, fast, easy to learn or maintain) but several iterations later, it only needs one small commit not focused on that -ility, and the code is not longer secure, fast or maintainable.

As a recap, these are five examples of technical debt appears:

• At any time (dev, test, prod), detecting something that was not detected before (third party library bug, side effect…)
• During development, as a conscious decision or consensus in order to achieve a given goal faster (PoC or other)
• During development, by mistake (i.e. losing one or more of our software qualities)
• Because new needs / company goals turns something into not-ideal / not good enough / not aligned
• Because new tools / technology / patterns emerge that solves problems in a different and more efficient way

We never consider our bugs technical debt items (unless they become a feature), but we might consider third party bugs, problems or missing features and other external things that we might need to invest time into as technical debt if left unattended.

The second iteration

As a recap of our exercise above after the not-so-brief retrospective, we had already identified some tags (A, O, S) and the impact of some technical debt items. We had a starting point, and the feeling of being in the right path.

We started to look for existing standards about the tags we were using on our tech-debt items, but we were also aiming to keep this simple enough to make it broadly used in the company.

I already mentioned early the Software Architecture -ilities (check some videos about them from Neal Ford or Mark Richards), so we started straight with their recommendations. Something was going to be tech-debt and not just false positives if it was lacking any of the important -ilities for the company or team on a given point in time (important -ilities change overtime as company goals and tools evolve).

There are some frameworks and acronyms that try to classify software according to their -ilities, like ACID for transactions, RAS for operations, FURPS for requirements… We were inspired by them, and we decided to group the list of -ilities that were important for the company into one or more of the categories we already had identified.

In the next entry of this series, we will introduce an evolved version of this framework by further defining and grouping those illities, while in the last entry of this series we will dive deeper by using it to help not only the teams but also the company to make better decisions, to react to changes and to reach its goals.

This post could not have been possible without some awesome coworkers

Great news delivered on the heels of bad news makes both bits worse. The bad news feels like it’s being buried, the good news feels like it’s being injected to change the mood. Be honest with each by giving them adequate space.

Why did this statement trigger something in my head?

I am Spanish. Mediterranean, but I’ve worked in Netherlands, France, Bulgaria, San Francisco… I’ve caught glimpses of other cultures. One of the soft skills I was able to improve while working in the US was giving and receiving feedback.

As part of a team-building exercise to build trust, we made confessions to coworkers. One of the techniques shared by the trainer was the sandwich. I’ve learned that it is a classic in American culture, and once aware of it I was able to identify the sandwich :hamburger: early on during conversations:

Hey Juan! Can I say something personal to you? I’ve always appreciated you and your family! You need to lose some weight because your health is important, and it’s a wonderful daughter you need to take care of!

That happened (not literally but almost!) during lunch with an American friend that visited a year ago (I’m improving my health, I promise :muscle: ). I saw the pattern immediately and let my friend know that I caught him in the sandwich (we always laugh at our cultural differences) and he confirmed that it is in his DNA.

What’s funny about it is, as Basecamp code says, everything is wrong with that technique. The first slice of bread seems artificial, and the wonderful daughter seems to be there just to change the mood, burying the important thing, that is to lose weight or get healthier.

Feedback Canvas

When giving feedback, you should be constructive, specific and always assume good intent. That goes in both directions: when you receive feedback, assume that the person who is giving you the feedback is going beyond his comfort zone and is pro-actively trying to help you to grow further.

When you give feedback to someone else, please keep in mind that you don’t know the full picture: assume that your colleague was acting and performing to the best of his skills and knowledge and with good intent.

All feedback must be specific. That is, you should name specific examples.

Sometimes feedback is just one way conversation, and the receiving part will just receive and think about it. Other times it spawns a two-way conversation, creating actionable take-aways. In this latter case, it is ok to recommend steps that your colleague can act upon. Otherwise, let them come himself with actions and be ready to give him your opinion on them if applicable.

This is my canvas for feedback conversations, and it is the one I use in my 1:1s when nobody provides a different framework.

After the intro, I have some questions to help drive the conversation:

• What are some things that you see me doing well and should continue doing?
• Is there anything I am not doing yet that you would want to see me start doing?
• Is there anything I am doing that you would want to see me stop doing?

The goal of the first question is to see if my efforts are aligned with what people perceive, while the second one is to see what might be in my blind spot but is obvious to others.

Usually, the most difficult question is the last one, but it’s not sandwiched between the other ones. It’s left at the end on purpose; it is what pushes people outside their comfort zone.

In my experience, people still use sandwiches to avoid bringing negative stuff into a conversation, and that is ok. I am often told that I go too fast or that I intimidate people because I come across as self-confident, which makes them feel insecure or worried about their own skills or capabilities (impostor syndrome).

What is funny is that those things don’t appear on the third question, but instead during the first or second one. I have found it very challenging to learn how to ask the right questions when I want to understand how I can be a better person or coworker.

Of course the first two questions are important. Yet in the end, those negative points that we are often afraid of drawing attention to are the points that can spawn the spark of a change.

There’s a big list of learning experiences I had while I was modding games:

• I learned map-reduce by using Vgaplanets Mess host util, whose developer and website is still online (wow!);
• memory hacking with “Game Wizard 32” (for DOS), as well as memory optimization with some hacking;
• macroing on Dark Age of Camelot;
• some 3d design stuff (reflections, sprites, animations…) by creating maps in counter-strike 0.5;
• UI modding on Everquest 2, which I continued on Vanguard: Saga of Heroes, where my Tarod’s Shortcut Panel was well-known in the community;
• I did the same with Lord of the Rings Online;
• customized my HOTAS for Elite: Dangerous;
• learned Unity modding Motor Sport Manager;
• … and many more.

Now it was time for Elder Scrolls Online.

Elder Scrolls Online (ESO) uses Lua as scripting language for UI interaction. UI components are described in XML, but it’s the scripting part that I was interested on. I always like cmd-line so I wanted to write a script that reacted to some basic slash commands.

Writing the Addon

This was going to be really fun as I had never written any Lua code before.

Let’s write our user story:

I, as a <gamer> want to <know who is online on each of my guilds when I log in> to the game so that <I can interact with them> without opening additional tools, menus or windows.

As a reference site I used ESOUI Wiki to get me started. Contrary to the recommendations I was not connecting to the TEST game server (mainly because I was short on disk space) so kids don’t try this at home.

I created my addon folder, my addon metadata file and registered my addon with the game UI engine.

TarodGuildInfo = {}
TarodGuildInfo.name = "Tarod's Guild Info"
TarodGuildInfo.id = "TarodGuildInfo"

function TarodGuildInfo:Initialize()
end

function TarodGuildInfo.OnAddOnLoaded(event, addontName) 
    if addontName == TarodGuildInfo.id then
        TarodGuildInfo:Initialize()
    end
end

EVENT_MANAGER:RegisterForEvent(TarodGuildInfo.id, EVENT_ADD_ON_LOADED, TarodGuildInfo.OnAddOnLoaded)

I opened the game and enabled my addon… and the game didn’t crash which was good.

In order to reload my addon without closing the game I could have some commands, but I wanted to be transparent with the engine, so each time I changed my code I just did a /redloadui on the game to see the effect.

Using the API to read data from the game

The game API for developers can be found at the developer forums or via ESO UI Wiki. For me, the best resource was ESOUI’s GitHub repo. I opened API Doc and started my investigation.

I started to search for “guild” but there were too many results. I went for “getguild”, and I got some interesting hits, like * GetGuildInfo(integer guildId) and the surrounding functions (isPlayerInGuild, GetNumGuilds(), GetGuildId(*luaindex* _guildIndex_), etc.).

The API is organized so that one can ask about the number of guilds the current player (our <gamer> persona in the user story) belongs to, and then ask the game about what’s the internal guild id for a given guild index for the player.

Although this can leave some inconsistencies if between one call and the next one (some temporal coupling), specially if the player joins or leaves a guild between calls, this was not a problem for me as I want to do this only at game start.

Sending data back to the UI

I started to wonder how to write messages on the game chat (as result of my api calls), and I noticed there’s a special d(*str message) function to send messages to the System message channel.

I did not want my mod to do anything special like using chat channels or other fancy stuff at the moment so It was fine for me. However, system messages are sent only to the first tab unless using pChat or other chat mods.

After some hacking I got a first version working, listing the online members for my guilds, as well as the guild name:

function TarodGuildInfo:GuildInfo() 
    local guildCount = GetNumGuilds()
    for idx = 1, guildCount do
        local guildId = GetGuildId(idx)
        d(GetGuildName(guildId))
        local _, onlineMemberCount, _, _ = GetGuildInfo(guildId)
    
        d("There are " .. onlineMemberCount .. " members online")
        local guildMemberCount = GetNumGuildMembers(guildId)
            
        for idx=1, guildMemberCount do
            local _, _, _ , _,logoff = GetGuildMemberInfo(guildId, idx)
            local _, charName, _, _, _, _, _, _, _ = GetGuildMemberCharacterInfo(guildId, idx)
            
            if logoff == 0 then
                d(charName)
            end
        end
    end 
end

The code was ugly, but I was working. I found very challenging not being able to unit test my code (mainly because this was my very first lua interaction) but at this time just manual testing was ok for me.

Formatting messages

First thing I wanted was to use the full return values from the functions above (instead of _) to display more detailed information, like player name, zone, level or champion points, etc. I wanted to add colors and proper formatting, so I decided to start with the number of people online in a guild and using conditional formatting.

Most languages support conditional formatting, and in this case this was achieved not with the default lua stdlib but by using Zenimax Online (the developer of ESO) string format function. There is an article about it so I’ll jump right to the first formatting. I took the chance to do some refactor to have easier to follow functions.

function TarodGuildInfo:Initialize()
    TarodGuildInfo.currentPlayer = GetUnitName("player")
    d(zo_strformat("Welcome Back |cB27BFF<<1>>|r!", TarodGuildInfo.currentPlayer))
    TarodGuildInfo:GuildInfo()
end

function TarodGuildInfo:GuildInfo() 
    local guildCount = GetNumGuilds()
    for idx = 1, guildCount do
        TarodGuildInfo:PrintGuildInfo(idx)
    end 
end

function TarodGuildInfo:PrintGuildInfo(idx)
    local guildId = GetGuildId(idx)
    d(zo_strformat("|cFFFFFF<<1>>|r: |cFFB5F4<<2>>|r", GetGuildName(guildId), GetGuildMotD(guildId)))
    local _, onlineMemberCount, _, _ = GetGuildInfo(guildId)
    local additionalMembers = onlineMemberCount - 1

    d(zo_strformat(" |cC3F0C2<<1[You are the only one online :(/There is only another member online:/There are $d members online:]>>|r", additionalMembers))

    TarodGuildInfo:PrintGuildMembers(guildId)
end

function TarodGuildInfo:PrintGuildMembers(guildId)
-- nothing to see here.
end

Here there are some things to highlight:

• TarodGuildInfo.currentPlayer = GetUnitName("player") is creating a global variable on my addon namespace.
• zo_strformat("Welcome Back |cB27BFF<<1>>|r!", TarodGuildInfo.currentPlayer) displays some text and then the current character’s name in purple color (or that’s what I think since I am colorblind :smiley:)
• "|cFFFFFF<<1>>|r: |cFFB5F4<<2>>|r", name, motd was displaying the guild name in white and the Message of the Day in some shade of grey, on the same line
• |cC3F0C2<<1[ a/b/There are $d members online:]>>|r, additionalMembers: Displays a when additionalMembers is zero, b when it’s 1 and There are <additionalMembers> members online when it’s greater than 1

Some bugs on the API…

When using this from /reloadui everything was working fine, but at first login my own character was not online yet so the -1 there was not making much sense.

This was really weird because the documentation said that the addons are invoked after character goes online, and not before. As usual, undocumented stuff happens…

After some trial and error trying to use global variables and locks, I decided that it was easier to have a function to just iterate over the members and then perform the filtering myself:

TarodGuildInfo = {}

-- ...

function TarodGuildInfo:CountOtherGuildMembers(guildId)
    local guildMemberCount = GetNumGuildMembers(guildId)
    local onlineCount = 0
    for idx=1, guildMemberCount do
        local _,_,_,_,logoff = GetGuildMemberInfo(guildId, idx)
        local _, charName, _, _, _, _, _, _, _ = GetGuildMemberCharacterInfo(guildId, idx)
        -- Why GetUnitName returns formatted string while charName has the localization suffixes??
        if logoff == 0 and zo_strformat("<<1>>", charName) ~= TarodGuildInfo.currentPlayer then
            onlineCount = onlineCount + 1
        end
    end
    return onlineCount
end

-- ...

One weird thing happened was with the GetUnitName and charName returned by the GetGuildMemberCharacterInfo. One of them gave the current character, but the other one had the strformat suffixes for the gender, and it was not possible compare directly.

Almost done

I could now glue all together and have almost the final version of the script:

TarodGuildInfo = {}

TarodGuildInfo.name = "Tarod's Guild Info"
TarodGuildInfo.id = "TarodGuildInfo"
TarodGuildInfo.currentPlayer = nil
TarodGuildInfo.maxOnline = 15

function TarodGuildInfo:Initialize()
    TarodGuildInfo.currentPlayer = GetUnitName("player")
    d(zo_strformat("Welcome Back |cB27BFF<<1>>|r!", TarodGuildInfo.currentPlayer))
    TarodGuildInfo:GuildInfo()
end

function TarodGuildInfo:GuildInfo() 
    local guildCount = GetNumGuilds()
    for idx = 1, guildCount do
        TarodGuildInfo:PrintGuildInfo(idx)
    end 
end

function TarodGuildInfo:PrintGuildInfo(idx)
    local guildId = GetGuildId(idx)
    d(zo_strformat("|cFFFFFF<<1>>|r: |cFFB5F4<<2>>|r", GetGuildName(guildId), GetGuildMotD(guildId)))
    local onlineMemberCount = TarodGuildInfo:CountOtherGuildMembers(guildId)
    local additionalMembers = onlineMemberCount

    d(zo_strformat(" |cC3F0C2<<1[You are the only one online :(/There is only another member online:/There are $d members online:]>>|r", additionalMembers))
    if (onlineMemberCount < TarodGuildInfo.maxOnline ) then 
        TarodGuildInfo:PrintGuildMembers(guildId)
    end
end

function TarodGuildInfo:CountOtherGuildMembers(guildId)
    local guildMemberCount = GetNumGuildMembers(guildId)
    local onlineCount = 0
    for idx=1, guildMemberCount do
        local _,_,_,_,logoff = GetGuildMemberInfo(guildId, idx)
        local _, charName, _, _, _, _, _, _, _ = GetGuildMemberCharacterInfo(guildId, idx)
        if logoff == 0 and zo_strformat("<<1>>", charName) ~= TarodGuildInfo.currentPlayer then
            onlineCount = onlineCount + 1
        end
    end
    return onlineCount
end

function TarodGuildInfo:PrintGuildMembers(guildId)
    local guildMemberCount = GetNumGuildMembers(guildId)
        
    for idx=1, guildMemberCount do
        local _, _, _ , _,logoff = GetGuildMemberInfo(guildId, idx)
        local _, charName, _, _, _, _, _, _, _ = GetGuildMemberCharacterInfo(guildId, idx)
        
        if logoff == 0 then
            d(charName)
        end
    end
end

function TarodGuildInfo.OnAddOnLoaded(event, addontName) 
    if addontName == TarodGuildInfo.id then
        TarodGuildInfo:Initialize()
    end
end

EVENT_MANAGER:RegisterForEvent(TarodGuildInfo.id, EVENT_ADD_ON_LOADED, TarodGuildInfo.OnAddOnLoaded)

I added a global variable to not display online guild members if there were too many of them online, but the rest is just almost gluing together the previous pieces.

Adding clickable links to the client

Now it was time to improve how to add detailed info to each logged character info. Here, the main challenge was making valid links in order to be able to interact with the players/characters by right clicking on them. As usual, there is an article about it on the wiki:

function TarodGuildInfo:PrintGuildMembers(guildId)
    local guildMemberCount = GetNumGuildMembers(guildId)
    
    for idx=1, guildMemberCount do
        local pname,note,rank,status,logoff = GetGuildMemberInfo(guildId, idx)
        local hasChar, charName, zoneName, classType, alliance, level, cp, zoneId, consoleId = GetGuildMemberCharacterInfo(guildId, idx)
        
        -- Why GetUnitName returns formatted string while charName has the localization suffixes??
        if logoff == 0 and zo_strformat("<<1>>", charName) ~= TarodGuildInfo.currentPlayer then
            local gender = GetGenderFromNameDescriptor(charName)
            local className = GetClassName(gender, classType)
            if cp > 810 then cp = 810 end
            local text = zo_strformat("   |cB27BFF|H1:character:<<1>>|h<<1>>|h|r/|c6EABCA<<2>>|r |cC3F0C2<<3>> <<4>> <<5[/%dcp/%dcp]>> in <<6>>|r", pname, charName, className, level, cp, zoneName)
            d(text)
        end
    end
end

Interesting stuff about the special string format:

• ` `: I found no way to insert tabs, so I switched to spaces instead. After all, who argues about tabs vs spaces? (spoiler, he was wrong)
• cB27BFF|H1:character:<<1>>|h<<1>>|h|r/|c6EABCA<<2>>|r: Color playerName with a link to interact, followed by current character name
• <<5[/%dcp/%dcp]>> displays the champion points only if they are present (conditional formatting as above: empty string for zero, same string for 1 and greater than 1)

Extra: /slash_commands

Finally, I wanted to register some SLASH_COMMANDS with the game UIEngine:

SLASH_COMMANDS["/guildinfo"] = function (extra)
    local guilds = GetNumGuilds()
    local index = tonumber(extra)
    if index == nill or guilds == 0 then 
        TarodGuildInfo:GuildInfo()
    elseif index >= 1 and index <= guilds then 
        TarodGuildInfo:PrintGuildInfo(index)
    else
        d(zo_strformat("Please use |cC3F0C2/guildinfo|r |cB27BFF#num_guild|r where |cB27BFF#num_guild|r is a valid guild number between 1 and <<1>>", guilds))
        d("You can also use plain |cC3F0C2/guildinfo|r to get the default welcome message.")
    end
end

Although the /guildinfo command is really out of the scope of the initial user story, I found it useful, specially after adding the right click feature of the player names on the previous step. I could just write /guildinfo # on the chat and interact with my guild mates without opening the guild window.

The Result

The full sourcecode for the addon can be found in my Git Hub repository.

Happy modding!

I’ve seen some companies writing their own k8s ctl application, in order to offer a basic cmd-line interface that either lists contexts/services or has shortcut. Sometimes the shortcuts are needed, but most of the times those could have been solved with a plugin, like using k8s plugins and binding them into bash / zsh autocomplete.

First, we have kube config files generated per team and since as architect I work across several teams, I was looking to the right way to include different config files on k8s in a very standard way. The standard way would be a single .kube/config file, but I went to adding each file to my $KUBECONFIG env variable:

export KUBECONFIG=$KUBECONFIG:${HOME}/.cube/some-config-file:${HOME}./some-other-config-file

Then I setup Krew as per k8s recommendation:

Installing kubectl plugins You can use Krew to discover and install kubectl plugins from a community-curated plugin index.

So installing krew was pretty straight forward (just have to add to $PATH the installation path), and I was ready to use the plugins I was most interested in. As we are having more than 200 namespaces (services) in several contexts (environments) it was a natural follow up to install kubectx and kubens.

kubectl krew install ctx
kubectl krew install ns

Are we done? Not yet. We lack autocomplete in the plugins.

Both come with autocomplete on the standalone version (that is kubectx and kubens) but I prefer to stick to kubectl or as I have aliased with bash-it, kc.

There is a request on k8s to add autocomplete support to plugins here but since the support needs to be optional and universal there’s still no agreement on how to implement it.

So let’s dive a little into how to add that support ourselves.

bash/zsh differences: The basic procedure applies both zsh and bash but I am going to use bash as an example.

Getting kubernetes completion on the shell

As a starting point, kubectl already includes code completion for bash and zsh. We will be using that as a reference for our code.

We just generate k8s completion for our shell and save in a file on our dotfiles or equivalent (some shells require tools like bash-completion; I am using bash-it as I said before)

kubectl completion bash > ~/.bash-it/custom/completion/custom.completion.bash

or if you are using oh-my-zsh

kubectl completion zsh > ~/.oh-my-zsh/custom.completion.kube.config

This is the basic step but we have not configured anything yet.

Then we need to include the generated file in our profile. If using bash-it it’ll be included automagically with the above naming convention. If you’re following the example on zsh above just add the following line to your .zshrc customizations:

source ~/.oh-my-zsh/custom.completion.kube.config

What we want at this point is:

• Add completion to kubectl to include ctx and ns commands
• After ctx complete the command with the different kube contexts
• After ns complete the command with the different kube namespaces (of the current context)

The fastest and easier way to do it is just edit our newly generated file above. With your favorite editor, find the function _kubectl_root_command() and add our new commands at the bottom of the command list:

_kubectl_root_command()
{
    last_command="kubectl"
    command_aliases=()
    
    commands=()
    commands+=("annotate")

    ...

    commands+=("wait")
    # add plugin commands to completion:
    commands+=("ctx")
    commands+=("ns")
    
    ...

}

If we run now kubectl with autocomplete, we get the right completions:

And they also behave as we expect when we’ve partial words:

Great! We can cross the first item in our todo-list; now for the second one.

We observe that the file generated by k8s contains a bunch of helper functions (those that start with __) and some command functions (that start with _) There’s also a convention on the variables they use (like last_command or the commands list we hacked above). What we are going to do is to add our own handler to the kubectl ctx and ns commands and then we will instruct the autocomplete code to do it’s magic. To the magic part we will be using a function that k8s already had there but can help us to start hacking: __kubectl_custom_func()

Define your own handler

This is straight forward. Our command is kubectl ctx so we define a function called _kubectl_ctx (the magic parsing on the script and autocomplete will do the rest). Inside our function, we clear any variable that might have been set but could break some k8s commands:

I decided to add my functions at the bottom ot k8s’ generated file

_kubectl_ctx()
{
    last_command="kubectl_ctx"

    command_aliases=()

    commands=()

    flags=()
    two_word_flags=()
    local_nonpersistent_flags=()
    flags_with_completion=()
    flags_completion=()

    must_have_one_flag=()
    must_have_one_noun=()
    noun_aliases=()
}

Those lists and flags can handle the behavior of this command but we’re relying now on the custom function mentioned above.

Once we have added this, we can glue our new command to the function above. Since we want to autocomplete with the contexts and the switch there already has a case for completing commands with contexts, we are almost done. We just add our new command to the right case:

__kubectl_custom_func() {
    case ${last_command} in

        ...

        kubectl_config_use-context | kubectl_config_rename-context | kubectl_ctx)
            __kubectl_config_get_contexts
            return
            ;;

        ...

        *)
            ;;
    esac
}

To add the namespace completion, we just add one additional case to the switch above, right before the default:

__kubectl_custom_func() {
    case ${last_command} in

        ...

        kubectl_ns)
            __kubectl_get_resource_namespace
            return
            ;;
        *)
            ;;
    esac
}

Don’t forget to add the function to handle the ns command!:

_kubectl_ns()
{
    last_command="kubectl_ns"

    command_aliases=()

    commands=()

    flags=()
    two_word_flags=()
    local_nonpersistent_flags=()
    flags_with_completion=()
    flags_completion=()

    must_have_one_flag=()
    must_have_one_noun=()
    noun_aliases=()
}

This was really easy because we already had the __kubectl_get_resource_namespace (and get contexts) functions there, but we could have written our own implementation.

If you want to dive deep into this subject, the generated k8s autocompletion script is full of examples. The first iteration can be, for example, support some kubectl flags, like the rest of the commands; for example, copying the available list of flags from one of them (or the root command).

Cheers!

Gradle 5+ has been out for a while now and with that we finally got the ability to write our Gradle scripts in Kotlin. Almost every example out there about JUnit and Gradle is still using the old dependencies or Groovy Gradle syntax, so let’s try to migrate a Groovy build using JUnit Platform to Kotlin DSL, specifically, based on examples about how to extend Gradle’s test output to add summaries at the end of the build.

What we will achieve

We are starting from a plain Groovy Gradle script that configures a test task to log our JUnit test status (like examples here or here )

In addition, we will enable spotless and checkstyle in our Kotlin project as well as configuring IntelliJ IDEA Gradle plugin to download javadoc and sources of our dependencies.

Starting point

So let’s see how an old Groovy build.gradle is like when we want to use JUnit 5:

test {
    testLogging {
        exceptionFormat = 'full'
        events 'FAILED', 'SKIPPED', 'PASSED'
        showStandardStreams = true
        afterSuite { desc, result ->
            if (!desc.parent) {
                println "\nTest result: ${result.resultType}"
                println "Test summary: ${result.testCount} tests, " +
                        "${result.successfulTestCount} succeeded, " +
                        "${result.failedTestCount} failed, " +
                        "${result.skippedTestCount} skipped"
            }
        }        
    }

    useJUnitPlatform {}
}

cleanTest {}

configure(cleanTest) { group = 'verification' }

This is the very basic example we are going to find in stackoverflow or other forums.

We have a closure to display some test statistics, like the number of passed, failed and skipped tests. We also instruct Gradle to use Junit Platform (Junit5) with the useJUnitPlatform {} instruction and we also add the cleanTest task to the verification group (any clean<Task> in Gradle will delete the results by <Task>).

This last bit adds the task to our IDE Gradle tasklist in the desired group.

Migrating to Gradle Kotlin DSL

As with every software engineering project, our task to migrate can be broken in smaller chunks and we are going to start with the MVP, which is being able to build and test our project. Since we are testing, we will add also our test framework dependencies: mockk and assertj:

repositories {
    mavenCentral()
}

plugins {
    kotlin("jvm") version "1.3.40"
}


dependencies {
    implementation(kotlin("stdlib-jdk8"))

    testImplementation("io.mockk:mockk:1.9.3")
    testImplementation("org.assertj:assertj-core:3.11.1")
    testImplementation("org.junit.jupiter:junit-jupiter-api:5.4.2")
    testImplementation("org.junit.jupiter:junit-jupiter-params:5.4.2")

    testRuntimeOnly("org.junit.jupiter:junit-jupiter-engine:5.4.2")
}

test {
    useJunitPlatform()
}

But when we reimport the project… k-boom!

  Line 21: test {
  
^ Expression 'test' cannot be invoked as a function. The function 'invoke()' is not found
...

Why is this not working? Well, accessors for tasks are not published outside the tasks container (or accessor) on Gradle’s Kotlin DSL.

In order to solve this, we can use tasks and then filter by using one of the available methods:

Selecting a hardcoded taskname inside tasks block

tasks {
    "test"(Test::class) {
        useJUnitPlatform()
    }
}

Notice how the class of the tasks is specified by Test::class, thus allowing us to invoke useJUnitPlatform() method of the Gradle Test class. However we do not like hardcoded strings… like "test". Fortunately, we can simply modify the behavior of a list of tasks easily:

Filtering through the existing tasks

tasks.withType<Test> {

    useJUnitPlatform()
}

Much more readable! It will also apply to any Test task defined on our build.

By task accessor inside the task block (requires)

tasks {
    test {
        useJUnitPlatform()
    }
}

Even better! we do not need to know the type of the class since this is a type-safe accessor and comes with full IDE integration like code completion and inspections.

There are many other ways to access the builtin (or plugin added) tasks. Just check Gradle documentation

Logging JUnit output

Since the accessors are now type-safe, and we are working with Test tasks, we believe can invoke some of our previous functionality almost by copying and pasting from our original implementation.

Unfortunately, the following snippet breaks our build:

tasks {

    test {
        useJUnitPlatform()
    
        testLogging {
            exceptionFormat = 'full'
            events 'FAILED', 'SKIPPED', 'PASSED'
            showStandardStreams = true
            afterSuite { desc, result ->
                if (!desc.parent) {
                    println "\nTest result: ${result.resultType}"
                    println "Test summary: ${result.testCount} tests, " +
                    "${result.successfulTestCount} succeeded, " +
                            "${result.failedTestCount} failed, " +
                            "${result.skippedTestCount} skipped"
                }
            }
        }
    }
}

Unexpected tokens (use ';' to separate expressions on the same line). This refers to the events list we are filtering.

Since we are not using Groovy anymore, we need to convert them from hardcoded strings to the proper objects, and also use the right assignment with =

The same applies to the exceptionFormat so let’s also fix that. Don’t forget to import the new classes!

import org.gradle.api.tasks.testing.logging.TestExceptionFormat
import org.gradle.api.tasks.testing.logging.TestLogEvent

repositories {
    mavenCentral()
}

plugins {
    kotlin("jvm") version "1.3.40"
}

/*...*/

tasks {

    test {
    
        useJUnitPlatform()
    
        testLogging {
            exceptionFormat = TestExceptionFormat.FULL
            events = mutableSetOf(TestLogEvent.FAILED, TestLogEvent.PASSED, TestLogEvent.SKIPPED)
            showStandardStreams = true
            afterSuite { desc, result ->
                if (!desc.parent) {
                    println "\nTest result: ${result.resultType}"
                    println "Test summary: ${result.testCount} tests, " +
                    "${result.successfulTestCount} succeeded, " +
                            "${result.failedTestCount} failed, " +
                            "${result.skippedTestCount} skipped"
                }
            }
        }
    }
}

Ok, we fixed the imports but we are still facing the most difficult part so far.

Kotlin does not have Closure and our after suite block returns a pair of Nothing:

Type mismatch: inferred type is (Nothing, Nothing) -> TypeVariable(_L) but Closure<(raw) Any!>! was expected

At this point we might consider importing Groovy’s Closure but our objective was using Kotlin DSL and removing the Groovy dependency so there must be an alternative.

Digging on the internet cough, cough, over here we see that we can just add a TestListener and override the afterSuite method (which in fact is what the closure was doing):

/*...*/

tasks {

    test {
    
        useJUnitPlatform()
        
        addTestListener(object : TestListener {
            override fun beforeSuite(suite: TestDescriptor) {}
            override fun beforeTest(testDescriptor: TestDescriptor) {}
            override fun afterTest(testDescriptor: TestDescriptor, result: TestResult) {}
    
            override fun afterSuite(suite: TestDescriptor, result: TestResult) {
                if (suite.parent == null) { // root suite
                    logger.info("----")
                    logger.info("Test result: ${result.resultType}")
                    logger.info("Test summary: ${result.testCount} tests, " +
                        "${result.successfulTestCount} succeeded, " +
                        "${result.failedTestCount} failed, " +
                        "${result.skippedTestCount} skipped")
    
                }
            }
        })
    }
}

It is a pity that we don’t have an adapter with default empty implementations and we need to implement empty methods but this also opens the doors to some evolution in our build setup.

First we introduced the logger object, that the Kotlin DSL for Gradle exposes so we can log events. We have debug, info and all the familiar LOG_LEVELS but there is also an interesting log level called LIFECYCLE.

Since we (arguably) think that test results do not belong to info level but lifecycle instead, we will redefine the level we are logging test events.

We need to remember to properly configure the new lifecycle level we are using:

/*...*/

tasks {

    test {
    
        useJUnitPlatform()
    
        testLogging {
            lifecycle {
                events = mutableSetOf(TestLogEvent.FAILED, TestLogEvent.PASSED, TestLogEvent.SKIPPED)
                exceptionFormat = TestExceptionFormat.FULL
                showExceptions = true
                showCauses = true
                showStackTraces = true
                showStandardStreams = true
            }
            info.events = lifecycle.events
            info.exceptionFormat = lifecycle.exceptionFormat
        }
    
        // See https://github.com/gradle/kotlin-dsl/issues/836
        addTestListener(object : TestListener {
            override fun beforeSuite(suite: TestDescriptor) {}
            override fun beforeTest(testDescriptor: TestDescriptor) {}
            override fun afterTest(testDescriptor: TestDescriptor, result: TestResult) {}
    
            override fun afterSuite(suite: TestDescriptor, result: TestResult) {
                if (suite.parent == null) { // root suite
                    logger.lifecycle("----")
                    logger.lifecycle("Test result: ${result.resultType}")
                    logger.lifecycle("Test summary: ${result.testCount} tests, " +
                        "${result.successfulTestCount} succeeded, " +
                        "${result.failedTestCount} failed, " +
                        "${result.skippedTestCount} skipped")
                }
            }
        })
    }
}

Second, we can add some new logging details by overriding other functions. Let’s do a more detailed summary of failed and skipped tests:

/*...*/

tasks {

    test {
        
        /*...*/
                
        val failedTests = mutableListOf<TestDescriptor>()
        val skippedTests = mutableListOf<TestDescriptor>()
    
        // See https://github.com/gradle/kotlin-dsl/issues/836
        addTestListener(object : TestListener {
            override fun beforeSuite(suite: TestDescriptor) {}
            override fun beforeTest(testDescriptor: TestDescriptor) {}
            override fun afterTest(testDescriptor: TestDescriptor, result: TestResult) {
                when(result.resultType) {
                    TestResult.ResultType.FAILURE -> failedTests.add(testDescriptor)
                    TestResult.ResultType.SKIPPED -> skippedTests.add(testDescriptor)
                }
            }
    
            override fun afterSuite(suite: TestDescriptor, result: TestResult) {
                if (suite.parent == null) { // root suite
                    logger.lifecycle("----")
                    logger.lifecycle("Test result: ${result.resultType}")
                    logger.lifecycle("Test summary: ${result.testCount} tests, " +
                        "${result.successfulTestCount} succeeded, " +
                        "${result.failedTestCount} failed, " +
                        "${result.skippedTestCount} skipped")
                    if (failedTests.isNotEmpty()) {
                        logger.lifecycle("\tFailed Tests:")
                        failedTests.forEach {
                            parent?.let { parent ->
                                logger.lifecycle("\t\t${parent.name} - ${it.name}")
                            } ?: logger.lifecycle("\t\t${it.name}")
                        }
                    }
    
                    if (skippedTests.isNotEmpty()) {
                        logger.lifecycle("\tSkipped Tests:")
                        skippedTests.forEach {
                            parent?.let { parent ->
                                logger.lifecycle("\t\t${parent.name} - ${it.name}")
                            } ?: logger.lifecycle("\t\t${it.name}")
                        }
                    }
                }
            }
        })
    }
}

First we declare to mutableLists, one for failed and the other one for skipped tests. Then we check what kind of TestResult we are getting and add the TestDescriptor to the right list. One good thing from Kotlin scripting is that we can omit the else -> in the enum branching.

However, being able to use Kotlin, we can improve somehow the script with all the fancy Kotlin features.

For example, we can use extension functions to make the code more readable.

Also, since we are going to add some linter capabilities, we might want to adhere to best practices and use proper when branching and include the ELSE fallback.

How does our example build.gradle.kts look after all the optimizations?

1. We added some checkstyle, spotless and linter configurations as well as IntelliJ IDEA plugin.
2. We setup some configuration options for the plugins above.
3. We refactored how we log to use a functional approach and Kotlin features.
4. Since we love testing with ParameterizedTests, we added that bit for JUnit too.
5. Finally, we used the same approach than on the Test task customization to customize the Kotlin compile options.
6. As a bonus, we are passing spotless / checkstyle to all the Gradle.kts files in the KotlinGradle task in the spotless configuration.

The end result is:

import org.gradle.api.tasks.testing.logging.TestExceptionFormat
import org.gradle.api.tasks.testing.logging.TestLogEvent

repositories {
    mavenCentral()
}

plugins {
    kotlin("jvm") version "1.3.40"
    id("com.diffplug.gradle.spotless") version "3.23.1"
    id("org.jmailen.kotlinter") version "1.26.0"
    checkstyle
    idea
}

idea {
    module {
        isDownloadJavadoc = true
        isDownloadSources = true
    }
}

tasks.checkstyleMain { group = "verification" }
tasks.checkstyleTest { group = "verification" }

spotless {
    kotlin {
        ktlint()
    }
    kotlinGradle {
        target(fileTree(projectDir).apply {
            include("*.gradle.kts")
        } + fileTree("src").apply {
            include("**/*.gradle.kts")
        })
        ktlint()
    }
}

dependencies {
    implementation(kotlin("stdlib-jdk8"))

    testImplementation("io.mockk:mockk:1.9.3")
    testImplementation("org.assertj:assertj-core:3.11.1")
    testImplementation("org.junit.jupiter:junit-jupiter-api:5.4.2")
    testImplementation("org.junit.jupiter:junit-jupiter-params:5.4.2")

    testRuntimeOnly("org.junit.jupiter:junit-jupiter-engine:5.4.2")
}

tasks.compileKotlin {
    kotlinOptions {
        jvmTarget = "1.8"
        javaParameters = true
    }
}

tasks.test {
    useJUnitPlatform()

    testLogging {
        lifecycle {
            events = mutableSetOf(TestLogEvent.FAILED, TestLogEvent.PASSED, TestLogEvent.SKIPPED)
            exceptionFormat = TestExceptionFormat.FULL
            showExceptions = true
            showCauses = true
            showStackTraces = true
            showStandardStreams = true
        }
        info.events = lifecycle.events
        info.exceptionFormat = lifecycle.exceptionFormat
    }

    val failedTests = mutableListOf<TestDescriptor>()
    val skippedTests = mutableListOf<TestDescriptor>()

    // See https://github.com/gradle/kotlin-dsl/issues/836
    addTestListener(object : TestListener {
        override fun beforeSuite(suite: TestDescriptor) {}
        override fun beforeTest(testDescriptor: TestDescriptor) {}
        override fun afterTest(testDescriptor: TestDescriptor, result: TestResult) {
            when (result.resultType) {
                TestResult.ResultType.FAILURE -> failedTests.add(testDescriptor)
                TestResult.ResultType.SKIPPED -> skippedTests.add(testDescriptor)
                else -> Unit
            }
        }

        override fun afterSuite(suite: TestDescriptor, result: TestResult) {
            if (suite.parent == null) { // root suite
                logger.lifecycle("----")
                logger.lifecycle("Test result: ${result.resultType}")
                logger.lifecycle(
                        "Test summary: ${result.testCount} tests, " +
                        "${result.successfulTestCount} succeeded, " +
                        "${result.failedTestCount} failed, " +
                        "${result.skippedTestCount} skipped")
                failedTests.takeIf { it.isNotEmpty() }?.prefixedSummary("\tFailed Tests")
                skippedTests.takeIf { it.isNotEmpty() }?.prefixedSummary("\tSkipped Tests:")
            }
        }

        private infix fun List<TestDescriptor>.prefixedSummary(subject: String) {
                logger.lifecycle(subject)
                forEach { test -> logger.lifecycle("\t\t${test.displayName()}") }
        }

        private fun TestDescriptor.displayName() = parent?.let { "${it.name} - $name" } ?: "$name"
    })
}

// cleanTest task doesn't have an accessor on tasks (when this blog post was written)
tasks.named("cleanTest") { group = "verification" }

Gradle test sample output

Running ./gradlew clean build on a sample project, we can see that our Gradle project is working, hopefully we won’t get any checkstyle or spotless violations and all test will be green.

What is the output if some tests are disabled or failing?

See this little cropped example:

...

> Task :test

Error!
org.opentest4j.AssertionFailedError: Error!
	at org.junit.jupiter.api.AssertionUtils.fail(AssertionUtils.java:43)
	at org.junit.jupiter.api.Assertions.fail(Assertions.java:129)
	at org.junit.jupiter.api.AssertionsKt.fail(Assertions.kt:24)
	at org.junit.jupiter.api.AssertionsKt.fail$default(Assertions.kt:23)
	at org.lastminute.blog.examples.gradlekts.UnitTest.always failing test()(UnitTest.kt:24)
    ...
    

org.lastminute.blog.examples.gradlekts.UnitTest > always failing test() FAILED
    org.opentest4j.AssertionFailedError: Error!
        at org.junit.jupiter.api.AssertionUtils.fail(AssertionUtils.java:43)
        at org.junit.jupiter.api.Assertions.fail(Assertions.java:129)
        at org.junit.jupiter.api.AssertionsKt.fail(Assertions.kt:24)
        at org.junit.jupiter.api.AssertionsKt.fail$default(Assertions.kt:23)
        at org.lastminute.blog.examples.gradlekts.UnitTest.always failing test()(UnitTest.kt:24)
org.lastminute.blog.examples.gradlekts.UnitTest > disabled test() SKIPPED
org.lastminute.blog.examples.gradlekts.UnitTest > always passing test() PASSED
----
Test result: FAILURE
Test summary: 3 tests, 1 succeeded, 1 failed, 1 skipped
	Failed Tests
		org.lastminute.blog.examples.gradlekts.UnitTest - always failing test()
	Skipped Tests:
		org.lastminute.blog.examples.gradlekts.UnitTest - disabled test()
1 test completed, 1 failed, 1 skipped
> Task :test FAILED
FAILURE: Build failed with an exception.
* What went wrong:
Execution failed for task ':test'.
...

Conclusion

Gradle’s Kotlin DSL comes with a change of mindset when writing your build script. Kotlin is a type safe language which means that we need to be more strict now on our scripts, specially when migrating Groovy ones.

It is really great to be able to use Kotlin in our build scripts, since we can easily extend or implement new Tasks with few lines of code. Some engineers fear build scripts, specially if they are not comfortable with the language used, and having the opportunity to use the very same language you use everyday on your build scripts lowers the entry barrier for them.

Even JUnit 5 has a nice console launcher for building reports (on CI or manually), we engineers like to see a summary of what went wrong and we were missing that option with the new JUnit Engine on Gradle. Fortunately, with this entry we have improved our initial scripts and been able not only to summarize how the Test task was but also display which tests failed (or were skipped)

Originally published in Technology Blog

I have switched jobs recently, and I found myself doing some interviews. I have never been nervous nor feared interview processes as I tend to approach them with a learning attitude, both as interviewer and interviewee. However, I found some code assignments too demanding for some candidates.

I have seen a lot of bloggers on the last three months posting (or complaining) about code assignments in the interview process so, why am I also blogging about this? Because I will be talking from my recent experience about what I enjoyed, disliked and loved and what I am looking for when I’m being interviewed.

Companies need filters, because we might get thousands of applications per posting, and with some tools like Greenhouse, Freshworks or Lever, we can automate part of the process, where any candidate is sent directly to one of those screenings. But what is the appropriate screening process for candidates?

Basic algorithms or programming assignments on Hackerrank or similar platforms are a good filter for entry level positions but only adds some time delays on more senior candidates. Good candidates that are actively looking will take less than one month to find a new job and companies want to move faster than their competitors on this high-demanding environment, so any delay on the process can make a company to lose an opportunity.

When you reach some level of seniority, it is not selling yourself anymore. You are also buying.

When I was younger I faced all my interviews trying to sell myself, to rise above the rest of the candidates. I wanted to get a job and learn, so I almost did my research outside of the interview process. I was the one applying to jobs, so I was the one who felt scrutinized.

As I have acquired more skills and experience, I have also noticed new habits when I look for new opportunities. I rarely browse for openings but either contact some trusted recruiters, use my contacts network or directly, write HR managers on the companies I might be interested in. But, during the interviews, I am the one scrutinizing them.

The interview process

I did that with Thoughtworks and lastminute.com last month, as well as replied to some recruiters that were contacting me.

I discarded a lot of interviews when the process felt copy — pasted. Those recruiters that took time to talk with me and see if we were aligned got me in the process, while those with automated pipelines sending me standard emails got discarded almost immediately. Not to talk about those taking two or more weeks to reply to an email…

Seniors, leaders, or managers will rarely be applying to positions but positions will be offered to them, so having them to go through a long process without feedback or previous information is almost instant no from them.

Also, there is a relation between experience and age, and that often implies that senior candidates potentially have families. This, tied with sometimes very high demanding responsibilities, make difficult for the applicants to find time to do the coding challenge. Who can spend a weekend coding for an interview after fifty hours working without seeing the family?

We, candidates are not just selling ourselves but also buying companies.

We don’t get a job, we join a company, follow a leader or work with a team.

But I need to know if you can code!

Exactly! But not only that! You need to know if I can solve problems within your team. If I can understand your code, improve it, fix things. And doing an assignment at home, does often not prove that.

I have had candidates leaving a process because the assignment was going to take much time, or they were not allowed to use the language they felt more comfortable with, or candidates failing a code screen because they did not know the estimated amount of time or number of questions in advance and could not plan according. This even happened to me on a process, doing the assignment with low bandwidth(took 15 minutes to upload a 45 minutes typing session) when after finishing the upload a new question appeared on the wild, no prior notice… leaving my time-box completely blown.

Let’s walk through types of screens / interviews and a basic list cons and pros for companies and candidates based on resources/time dedicated to the interview, how prone to keep the interest of the candidate the process is and how easy is to validate software engineering skills or other soft skills.

The technical filter

The technical filter feels like a quiz, not an interview. In this kind of filter, interviewer asks several questions to the candidate, no matter how comfortable he or she is feeling. This is a company-buying-workforce type of interview. The candidate is not usually engaged in a conversation, and it requires a senior engineer with people soft skills to do it right (to make it more like a conversation or a two-way interview). Most companies have this filter earlier on the process and more than often it is the very first conversation between the company and the new possible hire.

PROS

• It helps a lot to filter out unaligned candidates (technically).

CONS

• It requires a senior engineer to perform the interview.
• Candidate might feel like in an exam. Senior candidates need to buy the company and this process does not give them much information about it.

The coding screen

Here, the candidate is given a time constrained series of problems in a tool or service like Hackerrank. Usually, algorithms, data-structures or database knowledge is tested but can grow as complex as the company needs.

PROS

• For the company, it helps out to filter junior level engineers.
• Fast to give feedback to candidates.
• No need of own engineers to get involved in the process at this stage as recruiters themselves can direct the candidates to the exercises.

CONS

• Senior candidates might find the problems too easy and loose interest in the job or reject to invest time without some calls first.
• The candidate might have a bad day, connection issues or just choose a bad solution with no reaction time to adapt. This might lead to loosing qualified candidates too early on the process.

The home assignment

Similar to the code assignment above, the home assignment just takes longer, needs some research or specific knowledge and engages the candidates with more complete solutions.

I have seen this kind of filter too often lately. I have been asked to spend a significant amount of time working on a problem, posting the code to a repository and then engaging with part of the company’s engineering team in an offline conversation via merge requests.

PROS

• Gathers a lot of information about how the candidate approaches a given problem (research, architecture, reading existing code if a template project is given to him or her…).
• Involves the candidate with the team, that is, helping him or her to understand how his or her future coworkers deal with his or her code.

CONS

• The candidate might not feel comfortable enough with the toolset (i.e. asked to work on a given framework, library or language).
• It might need a significant amount of time from the candidate (I have seen assignments that took a couple of full time days).

Whiteboard / master class

I was once this kind of interviewer (sorry!). There is a simple problem with a simple solution that can spawn a conversation about performance and several advanced topics. Usually this problem falls in the comfort zone of the interviewer who can drive the conversation wherever she / he wants.

PROS

• Gets to know the candidate.
• It is arguably easy to drive the candidate through different concepts / skill sets.

CONS

• Requires a lot of practice from the interviewer and a senior engineer to perform the interview.
• Can get the interviewee nervous if the interviewer misunderstands the skill set of the candidate and goes through difficult questions too early.
• Fairly subjective and not easy to standardize.

Code interviews re-imagined

Why we do refactor our code but not our habits or other processes as frequently as our code? Code interviews have been like above for decades now. Sure we have new tools and reports, but the interviews itself keep being the same format.

This is how some processes have evolved in the last years:

The WIP assignment

Similar to the assignment above, but way simpler and with one premise in mind: once finished, if the code passes to the next interview / stage, it will be refactored based on new constraints in a pair-programming session (see below)

This what I did at lastminute.com, a simple assignment that took around one hour to complete, using my language and tools of preference.

PROS

• Leverages the home assignment to be shorter and easy, establishing a base for the next interview.
• Done properly leaves space to the candidate to make the choice on language and tools of his or her preference.
• Can also drop candidates if the code is not good enough.

CONS

• Still requires some effort from the candidate.
• Needs to be reviewed by some engineers (hopefully won’t take as much time as the full assignment).
• The company needs people with some experience in the language and framework the candidate might have chosen.

The pair-programming session

At Thoughtworks, you get a pair-programming session. There is a task you need to tackle with your buddy and during the session your buddy swaps with a new buddy. You can choose the language of your preference, and you can use some external tools if needed.

This is also how the second part of the WIP assignment above works on other companies (i.e. lastminute.com) and to be honest, felt amazing to evolve your own code as part of the pairing session.

Other companies use a similar approach, for example, tackling a long-standing non important bug in real code together with the candidate and trying to solve as part of the onsite interview day.

PROS

• Engages the candidate within the team. It is a pair-programming session, so the buddy is responsible also to help the candidate to solve the problems they face.
• Identifies not only coding skills but also other skill like analytical mindset, communication skills and / or working under pressure.
• Feedback is given by two or more interviewers, not just one (on the same interview).
• Senior enough candidates who architect the solution themselves feel owner of the proposed solution while junior candidates can follow their buddy’s guidelines.

CONS

• The company need to book two engineers to interview each candidate.

Conclusion

If I had to summarize this post in a TLDR it would be something like

Senior engineers do not need an interview filter. Their CV or LinkedIn profile is the filter and some reading and checking from recruiters or other engineers is mandatory prior to invite them to the onsite interview.

I strongly agree with that statement (after all is mine), specially after a month of being interviewed almost every week. I enjoyed those processes that involved me, gave me feedback and were two-way communication lanes. They required from me the same amount of effort they were putting in the process.

They never asked me for some time which did not involved a two-way communication and even when I had a WIP assignment, it was properly communicated and short (took less than one hour). The interviews did not feel like exams, but conversations, and we were exchanging ideas, opinions and knowledge. This is the right way to do the code interview, working together to solve a problem.

As a close friend once said to me:

Be aware: seniority is different from leadership. Companies that are looking for senior engineers might be looking also for leaders, but that is not always the case. Make sure both you and the company you are being interviewed at are aligned.

Seniority <> Leadership.

If you want more than a senior position, but the company has already people leading teams, you might not find space to grow and feel happy.

And being happy at work makes the difference between stressed and ownership.

Originally published in Medium

- “Hey, over here, we’ve found a bug in Kotlin!”

Curious as I am always, I headed over their desk, and I was asked:

- “What do you think this statement will out?”

It’s a trap! I thought. I took a few moments and said something like “at first sight, without any coffee yet… false, but I suspect that’s wrong because “you found a bug in Kotlin”, so, what does this output?”.

That snippet, as you can see here, simply outputs true.

I looked again, and I got it. The Elvis **?:** operator in Kotlin, is not a ternary! That fooled me completely!

The Elvis operator just takes whatever is on his left and replaces with whatever lies on his right if the left side is null. That means that our expression in the first example becomes simply println(null != false) which obviously, is true.

Why? Not because “operand precedence”; the Elvis operator refers to it’s nearest variable. It is not precedence! It is by design. Think it like println(null != (null ?: false)) which translates exactly as the above result. Heck, we could even be super-null-safe and write println(null ?: false != null ?: false) or any other variation. It’s the design of the operator.

What’s the proper usage then, to avoid this weird confusion? Simply, use Elvis either on simple return (either from functions or from blocks) and for variable assignation:

One funny thing about the example above is that we cannot assign null to notNullableGuy because the compiler complains:

// notNullableGuy = null // we can't do this because   
// Null can not be a value of a non-null type Boolean

This is a common mistake for java/javascript engineers who start to play with Kotlin. So follow these simple rules:

These are some outputs from the snipped above:

assignment false  
fromBlock false  
computed null  
safe-output is false  
null  
null  
false  
true  
true  
false

assignment false  
fromBlock false  
computed null  
safe-output is false  
null  
false  
true  
true  
true  
false

To read more about the Elvis operator and Kotlin null-safety features, just deep read Kotlin language reference about null-safety.

Originally published in Medium

update 2020: Although the vast majority of stuff listed here still works on 2020, there is now WinGet that I’ve not personally worked with yet.

update 2019: If anyone is still reading this on 2019, after May 2019 Windows 10 Update, some PowerShell customizations (colours) won’t work anymore (reason is that they deprecated some PSReadLine.options values). I´ve switched to concfg to customize my shells.

Background

In one of my previous stories I told you about how I failed to adapt using a Mac laptop. For me, +20 years of typing on a standard keyboard, with its key placement was too much muscle memory. Other coworkers could adapt, but I was an avid gamer and using my home computer at the same time I was using a Mac for work turned into a no-way. Also, I almost don’t use my mouse when working in Windows or Linux since I’ve become one with the keyboard.

I wanted to be able to keep gaming on my laptop while avoiding purchasing additional disk space to dual boot it, I just thought, why not, we are living in the future, and I started my Ultimate Windows Workstation™

Being a fan of RHEL and since there isn’t yet a linux subsystem for windows based on RHEL (CentOS, Fedora…) I opted for a standalone environment, which means not installing cygwin nor the linux subsystems.

Package Managers

First I had to decide between the two major automated tools to deploy software on windows. Being impressed by Homebrew and after using my beloved yum in RHEL during several years, it had to be a cmd line tool. There are to major tools right now on Windows, each one with its own pros and cons: Chocolatey and Scoop

Scoop

Scoop installs in the user space; that is no messing with your program files or program data folders; and does not register almost anything within your environment. It will add a path (usually in your ~home/scoop/shims much like a usr/local works.

One needs to think about scoop tools like portable ones. The tools will be added to your ~home/scoop folder, and it can even maintain versions. A special symlink (yes, windows supports those since long ago with mklink tool) will maintain the current version while keeping the rest downloaded. You can switch versions painlessly and install tools without any elevated prompt.

However, if you want to make the tools get on well together, you might run into some issues. For example, ssh expects your .ssh in your home but since it is running kinda chrooted withing scoop, the .ssh folder needs to be sitting on the ~home/scoop/ssh/?version? folder. That means that it won’t look the default location and tools that interact with it (like the agent, and so) won’t play well with it. Then you end manually adding environment variables, paths and other obscure things and then you realize that maybe, you’re not using the right tool. You can add global installs and other kind of stuff but at that point it doesn’t start to feel right. It just should be like yum or brew and not having to play with the setup files like make.

Chocolatey

Chocolatey defines itself as “The package manager for Windows”, and after having used it for several months, sure it is.

Even Microsoft itself has played with Chocolatey by implementing OneGet!. Most Chocolatey packages get converted or packed into a nupkg which plays nice on Windows.

Chocolatey uses nupkg and some PowerShell own extensions to bypass some UI wizards on most of the existing installer technologies, by thus bringing true unattended installs. You can use Chocolatey from the command line much like scoop to install any packages you find, and you can make it interact with the already installed ones if you want.

One of the things I liked from Chocolatey is the ability to maintain my software updated. Just running choco upgrade all will upgrade my software, and I can even import the software I installed by myself.

On the other hand, I did not like the checksums checks on all packages. If a given package (cough drivefilestream cough) uses the same URL for downloading the installer, when the installer checksum changes, Chocolatey will complain, and you’ll need to add the flag to skip checksums. If you do that, Chocolatey might report an installed version older than the really installed one. Minor issue, isn’t it?

In contrast to scoop, Chocolatey is able to install both portable and standard packages, if one is able to build a portable one. By default, uses %PROGRAMDATA%folder (C:\ProgramData), which is protected from all users write so, if any tool you use (like I explain below under the gradle section) needs to write to that folder you might run into issues with that tool. Before the latest versions Chocolatey installed on your root drive under the c:\Chocolatey folder but this has been discouraged. In fact, if it detects that it is running there, and you’re updating it, it will switch to the %PROGRAMFILES% and %PROGRAMDATA% folders.

I enjoyed it so much, so I ended purchasing a personal PRO license for myself. I did this on the hopes that they add synchronization with manually installed software to the PRO users and not only the business ones soon. So far I have only automatic synchronization. This is one way sync (uninstalling from windows Chocolatey packages), but I want two-way (Chocolatey detecting manually installed packages also)

Chocolatey || Scoop ?

The answer is also a question: why not both? For example, I found the sudo app from Scoop to be better that Chocolatey one, so I used that one from scoop. Also, I maintain myself the tools that I want to keep updated myself or that have an auto-update feature. I can install them with a Chocolatey script and either pin choco pin … them or just install them manually.

One script to rule them all

With all the improvements that Microsoft has made over the years to PowerShell I thought it was possible to pack a script to set up my environment.

I started with the basics, installing scoop and Chocolatey and documenting everything on a document, so I could potentially create The One Script.

Execution Policy

In order to make things work for this script, since it is going to run several unsigned scripts (at least during the setup), one might need to enable them on PowerShell: set-executionpolicy unrestricted -s cu -f. Don’t hesitate to restore it to the previous state if needed (write it down from get-executionpolicy -s cu). On The One Script I will probably add a first and last line to alter and restore it.

ssh

One of the must-have tools if you already don’t have it is ssh. The new 2018 April patch brought ssh client to our windows desktops and servers, so we don’t need complicated setups to get it running.

To check if it is enabled on your workstation, on a privileged shell just run

Get-WindowsCapability -Online | where Name -like 'OpenSSH.Client*'

and if it is not installed, just install it with

Add-WindowsCapability -Online -Name OpenSSH.Client~~~~0.0.1.0

You’ll have to use the exact name from the first command (or automate it with some magic):

$ssh_client_capabilitry = `Get-WindowsCapability -Online | where Name -like 'OpenSSH.Client*'`
if ($ssh_client_capability) {  
    `Add-WindowsCapability -Online -Name $ssh_client_capability.Name`
}

Once ssh is installed, we need to generate our keys, start the agent and add the keys to agent’s list of managed keys so any tool can use them as needed. As a bonus I’ll add the key as identity file for github:

# Make sure ssh agent is enabled and on autostart  
Start-Service -Name ssh-agent  
Set-Service -Name ssh-agent -StartupType Automatic

# create ssh keys  
ssh-keygen -t rsa -b 4096 -C "[your_email@yourdomain.com](mailto:your_email@yourdomain.com)"  
ssh-add $env:USERPROFILE/.ssh/id_rsa

# edit .ssh/config for github  
Add-Content $env:USERPROFILE/.ssh/config "Host github.com"  
Add-Content $env:USERPROFILE/.ssh/config "    Hostname github.com"  
Add-Content $env:USERPROFILE/.ssh/config "    User git"  
Add-Content $env:USERPROFILE/.ssh/config "    IdentityFile ~\.ssh\id_rsa"  
Add-Content $env:USERPROFILE/.ssh/config "    # only use IdentityFile specified above, skip default ones"  
Add-Content $env:USERPROFILE/.ssh/config "    IdentitiesOnly yes"

Basic Tools

I’ll also install some tools using Chocolatey

choco install jdk8  
choco install greenshot  
choco install git.install  
choco install SkyFonts  
choco install 7zip #or choco install 7zip.install   
choco install gpg4win

cmd-line customizations

Next things to do is customize the cmd-line. Why? Again, why not? If you want to feel h4x0r or just love your own color scheme or fonts, it can also be automated.

I’ve been using Inconsolata for a while, but I’m switching to Source Code PRO.I also love Roboto. All of them are available through Chocolatey. By this time you’ll still bd running choco in a privileged prompt so maybe it is time to install sudo as well. As I said, I prefer scoop’s sudo to Chocolatey’s one. Remember to remove sudo if you are running privileged:

scoop install sudo  
sudo choco install Inconsolata  
sudo choco install RobotoFonts  
sudo choco install SourceCodePRO

You can make the fonts available to PowerShell console as well as to standard cmd, by editing the registry within PowerShell:

cd HKLM:  
cd '.\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Console'  
Set-ItemProperty -Path TrueTypeFont -Name Inconsolata -Value 'Inconsolata'

Just right click on the console bar and on the properties context you can change the font to use.

Further customization for your shell / console

We all know your shell is your $HOME. Most of us want a customized shell. I remember having long long time ago some cron tasks that changed my motd every day, and one funny server giving a bohf-excuse after every command typed. Now I am older, some say wiser, and I certainly can say a little more serious. That means no more bofh-excuses but still feeling at $HOME at my prompt.

I have tried several console replacements or wrappers for the standard shell and I must admit I have uninstalled all of them. However, I have solarized my shells and added a bunch of custom extensions or alias to my shell.

If you use git, knowing where you are in a repo is important and there are some extensions for PowerShell out there. I won’t go into deep details about how to and where customize your profile, but one must know that there are several profiles in a machine. I set up mine to include several modules and other options:

• Set-PSReadlineOption -BellStyle None to remove the abusive bell on the shell (seriously Microsoft, did you learn anything from Clippy?)
• Chocolatey extensions that allow for command line completion
• poshgit from dahlbyk
• DockerCompletion or posh-docker if you are using older versions
• Regarding docker, I added my own module with some fancy stuff like a local permanent redis and a db docker containers, as well as some aliases to manage, clean and manipulate images and containers.
• For the solarized theme, I used this one.

AWS

Probably you will use AWS or equivalent. You can set up your environment variables from shell, but I don’t think this is a good idea. If I ever was a h4x0r everything I write would always send the environment variables of whenever it was being ran to one of my compromised servers, including those secrets as keys and such. Any program can read the environment variables so be careful where do you set or store them.

setx AWS_ACCESS_KEY_ID xxx  
setx AWS_SECRET_ACCESS_KEY xxx  
setx AWS_REGION us-west-1

IntelliJ IDEA

One can install IDEA from Chocolatey (which is nice). With IntelliJ I experienced some minor issues:

• When using gradle, IntelliJ uses GRADLE_HOME environment variable instead of ~\.gradle folder. This means that on a default install of Chocolatey’s gradle it will attempt to download gradle wrapper binaries to a privileged location. Usually, you won’t be running gradle scripts as a privileged user so any build will fail. Though there are several options to work around this (install gradle on another location, grant all users write permission to the wrapper folder of gradle install dir…), I found the most obscure and bizarre one to be the best one. If you remove the GRADLE_HOME environment variable, every gradle invocation will just use your local .gradle folder, and you won’t have any issue. Even if I strongly discourage deleting from windows registry via scripts, you can delete the variable using REG delete "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /F /V GRADLE_HOME or browsing HKLM as above in PowerShell. My recommendation here is to manually delete the environment variable from the computer properties, as the old-fashioned way.
• Having a ~ on my .ssh/config file caused a NPE in IntelliJ IDEA on some setups (not to me), so you might need to replace with your full path. I suspect this has to do with native vs built-in ssh implementation. I opted for native.

• I am getting a NPE also if I import projects not using the JAVA_HOME for the Gradle JVM option in the import dialog. This does not happen on new projects, just imported ones. It is just a minor issue that will probably be fixed.
• Modifying gradlew files remove the executable bit for the linux users, so if you run gradle wrapper -=-gradle-version … --distribution-type all will probably overwrite the permissions for that file. I’m pretty sure there will be a way to avoid that, but I won’t mess with it yet.

git

I am using the default git installation from Chocolatey and works pretty good. One thing I tuned was gpg for my commits, and some flavors to my .gitconfig files:

.gitignore

# windows folder config  
desktop.ini

.gitconfig

Note: For some reason, using ~ on gitconfig file was not working on Windows, as neither was using $environment_variables. This does not apply to the special formatting of includeIf conditional config blocks.

# some options added by gpg below or git config above  
[alias]  
    # the acronym stands for "subtree add"  
    sba = "!f() { git subtree add --prefix $1 git@github.com:my_copmany_id/${1%/}.git master --squash; }; f"  
    # the acronym stands for "subtree update"  
    sbu = "!f() { git subtree pull --prefix $1 git@github.com:my_copmany_id/${1%/}.git master --squash; }; f"
[commit]  
    gpgsign = true  
[core]  
    excludesfile = C:\\Users\\juan\\.gitignore  
    autocrlf = true
[url "git@github.com:"]
	insteadOf = https://github.com/
[includeIf "gitdir:~/workspace/personal/"]
    path = C:\\Users\\juan\\workspace\\personal\\.gitconfig

git and gpg

For gpg there is the gpg4win package on Chocolatey and to configure the keys it is not really complicated except for some key formats. The following steps were working for me:

• gpg --full-generate-key
• gpg --list-secret-keys — keyid-format LONG
• gpg --armor — export <your key id from list above>
• Paste on Github
• run git config --global user.signingkey <your key id from list above>

I’m sure an avid reader can automate those steps with a single script (specially the --armor-export part). Since you need to open it to paste on Github I’ve left this steps out of The One Script.

VPN

Setting up a VPN in linux or windows, if it is not using a vendor client can be painful, specially since developers don’t often have a networking background. Though that is not my case since I was some years ago certified IBM sysadmin on RHEL and I had been doing some networking setups.

Often companies have a site-to-site VPN and a per user vpn for roadrunners. If that the case, there can be either a VPN client from a specific vendor (like OpenVPN, Cisco, Fortigate) or a standard setup like ipsec, l2tp or similar. I’m not going to write about specific vendor stuff (or OpenVPN) but just add some details about the ipsec standard.

ipsec / l2tp

In order to make an ipsec/l2tp VPN running on windows there are some tricks to keep in mind:

• every change to the networking stack configuration needs a reboot. If you add, edit or remove a registry setting, you will probably need to reboot your computer.
• You can set up your standard VPN as a Windows connection with a script:

#general settings     
$VpnName = connection_name  
$gateway = endpoint_ip  
$psk = your_secret_here
Add-VpnConnection -Name $VpnName -ServerAddress $gateway -TunnelType L2tp -AuthenticationMethod Chap -EncryptionLevel Optional -L2tpPsk $psk -Force -AllUserConnection -UseWinLogonCredential $false -SplitTunneling

• If you are behind a NAT (and you’ll probable be) you will need to edit a special value on the registry:

Set-ItemProperty HKLM:\SYSTEM\CurrentControlSet\Services\PolicyAgent -Name AssumeUDPEncapsulationContextOnSendRule -Value 2 -Type DWord

• As a topping, if you want to route only your internal traffic through the VPN (i.e. to route an A network you’ll add 10.0.0.0/8 as private_subnet/mask):

  add-VpnConnectionRoute -ConnectionName "connection_name" -DestinationPrefix "private_subnet/mask" -PassThru
  

• If for any reason your VPN is stuck on verifying or other step, make sure you have rebooted after the registry tweak above. If not, I have found that sometimes, specially after an update, the checkbox LCP Extensionson the VPN Properties -> Options Tab -> PPP settings is disabled. Just re enabling it will make the VPN work again. You can access this setting on the adapter settings for your VPN connection in the old network and sharing center by just opening Control Panel.
• Though not mandatory, I always like to disable the default GW on both IPV4 and IPV6 on the VPN properties. I do this manually but there are some commands to manipulate this from the registry or PowerShell. I do this because I want only the VPN traffic to be routed through it (unless I’m at a hotel where there is some kin of deep packet inspection or protocol filters that forbids videoconferencing, streaming or gaming.

Other customizations

I like having a workspace folder where I work. I place it outside the annoying Documents and Settings by default but since some tools open by default that folder I make a joint there. Also, since I’m lazy I make the same joint on the root of my drive, so I don’t have the need to write long path names:

mkdir $env:USERPROFILE/workspace
sudo New-Item -Path $env:USERPROFILE/Documents/workspace -ItemType SymbolicLink -Value $env:USERPROFILE/workspace
sudo New-Item -Path c:/workspace -ItemType SymbolicLink -Value $env:USERPROFILE/workspace

I also added a bunch of docker aliases but actually I keep using the long commands since I forget the name of my own aliases. However, the aliases serve as a repository of useful commands, and the only thing I need to do is to type or edit my aliases file from the command line like vim $PROFILE or similar and I have them there, waiting for me to use them.

Most of these additional customizations focus on my actual technology stack, like having a db docker image from our docker registry, or empty dockerized redis, or aliases and shortcuts (like opening Notepad++ from the command line), or some other context switching commands.

Most of the shortcuts have been added to my profile via the aforementioned different profiles in a machine. Pick your favourite and add there your shortcuts or aliases.

Originally published in Medium

Update 2019: Like this entry? Try Using Gradle Kotlin DSL with junit 5

Introduction

At Returnly we are using JUnit Jupiter to test our back-end services. We also use mockk and assertj which are great libraries that help a lot to build readable code.

This article will try to cover the basics of using parameterized tests, especially by trying to keep test data separated from the test classes.

We have started to move into parameterized tests by creating various set of data objects. Sometimes just CSV sources are fine, and our product managers love them (since they can define datasets without knowing how to code), but we, engineers, tend to prefer working with DSL or Domain Objects.

A @ParameterizedTest is a test which takes some kind of values as arguments and tests them. We found them useful to test edge error cases and unhappy paths, for example:

Gradle Setup

With the new gradle 4.6+ native JUnit Platform integration, it is straightforward to run the tests within gradle:

I like to add the cleanTest task there, so I can run it within my IDE and force to re-run the tests. This task just deletes test output.

Other people prefer to make the tests never UP-TO-DATE with test.outputs.upToDateWhen {false} or gradle test --rerun-tasks.

I prefer the built in cleantTest task.

On a console or standard output, the now deprecated plugin for JUnit displayed the test results in a tree, but with gradle’s native implementation we get only a BUILD SUCCESSFUL in {$time}s.

To see the summary we have added the afterSuite TestListener to the test closure as an example above.

The output has a nice summary:

Testing started at 16:56 ...  
16:56:17: Executing task 'test'...
> Task :compileKotlin NO-SOURCE  
> Task :compileJava NO-SOURCE  
> Task :processResources NO-SOURCE  
> Task :classes UP-TO-DATE  
> Task :compileTestKotlin UP-TO-DATE  
> Task :compileTestJava NO-SOURCE  
> Task :processTestResources NO-SOURCE  
> Task :testClasses UP-TO-DATE  
> Task :test  
org.tarodbofh.medium.junit5.parametrized.ValueSourceTest > amount must be positive(int)[1] PASSED  
org.tarodbofh.medium.junit5.parametrized.ValueSourceTest > amount must be positive(int)[2] PASSED  
Test result: SUCCESS  
Test summary: 2 tests, 2 succeeded, 0 failed, 0 skipped

Following this approach, one could build the same tree listener by having a look to JUnit’s implementation here.

The dependencies to add to test are (from maven central):

dependencies {  
    testCompile "org.assertj:assertj-core:3.11.1"  
    testCompile "org.junit.jupiter:junit-jupiter-api:5.2.0"  
    testCompile "org.junit.jupiter:junit-jupiter-params:5.2.0"  
    testRuntime "org.junit.jupiter:junit-jupiter-engine:5.2.0"  
}

Passing arguments to parameterized tests in kotlin

Following these hints, We have been using a @Nested inner class to implement the error cases or unhappy paths. Sometimes, ValueSource seems ugly, and it is not possible to add some flavor to it:

Values passed to an annotation need to be a constant value, which forbids us to use ranges or other constructs there, for example:

Throws a compile-time error like this:

Error:(16, 25) Kotlin: An annotation argument must be a compile-time constant

To solve that, we can use the @MethodSource annotation, but that forces us to:

• Have a method without arguments
• Use @TestInstance(TestInstance.Lifecycle.PER_CLASS) annotation and having the method part of the test class or producing a static method (source)

This leads to some strange code or other weird constructs, specially because we want to avoid using static methods in Kotlin with the JVMStatic annotation, like:

fun get1To10() = (1..10).toList().toIntArray()

As we mentioned earlier, we are using some DSL or pre-configured domain objects with know values (i.e. val valid_amounts = (1..10) ). Some people would have thought to bypass the compile-time constant error above by having something like:

const val VALID_AMOUNTS = valid_amounts.toList().toIntArray() //compile error

Unfortunately, in Kotlin, only primitives and Strings can be constant values, so often this is not an option.

Even though we always try to keep our tests simple, if we add the domain objects to the test class it can make it grow, and we don’t think that mixing test data with the test methods is a good idea.

We are using Kotlin Extensions to define our test domain objects and thus keeping our test data from our test implementation as clean as possible.

This means that we have a separate file with the test data (much like the old CSV files that product uses) but in an engineerly way.

One thing we can do, though is to use the ArgumentsSource annotation and have a Factory class which implements ArgumentsProvider and its arguments method.

Although it sounds overkill, it is easy to implement thanks to reified inline functions and delegation:

Then, our test method becomes:

The complete source now has two files, and it is easy to extend or maintain. We got a nice functionality to reuse our ArgumentsProvider if we move it to one of our standard libraries.

TLDR>

This is how the code looks after all the changes:

This is easy to extend, and we can replace the ArgumentsSource with CSVSource files once the product team have completed their test data.

Originally published in Medium

I was working in a new service; I had been pushing commits as crazy, with their appropriate tests, and I was using kotlin, spring, jooq and mockito. Then, I had run into an issue that felt could be improved.

I had read about mockk from a coworker, so I gave it a try. I started to implement a new functionality that had nothing to do with another one and implemented the tests. The only relation they had was a table that the new functionality was reading from the database (not writing to, I promise!).

Guess what happened after that? Some other tests started to fail. Seriously, why fixing something opens several other bugs? How could be possible that a completely different test suite that had nothing to do with those services started to fail? The symptoms were really strange. I was looking at the logs,and I could see jooq retrieving a row and suddenly failing to map an object because the id field was null. As I said, that could not be possible since my DB access was readonly this time and tests were not doing anything related with db yet.

This was a really weird case, since running those tests alone worked but when invoked as part of the suite, failed. Moreover, altering the order of the tests make them work or fail, as it some dark magic was controlling the code.

Since JUnit 5 does not have yet a way to specify the order of the tests much like JUnit 4 had, this was hard to test and identify. Digging deeper I found that on the native call on java.lang.reflect.Executable, it’s private native Parameter[] getParameters0(); was returning a different set of parameters after mockk had been invoked.

Our jooq’s ParameterAwareRecordMapper indeed uses constructor.getParameters to map from a record to a POJO and voila, after that call, jooq was unable to found any parameter from the record, and thus populating a POJO with all fields initialized to null.

What jooq was doing was reading the parameter names from the constructor of the POJO and looking for fields with those names on the record. Since the POJO was generated by jooq itself based on the DB fields everything should work fine from here. It was not. This messed up my pipeline, my code and got me through the rabbit hole for at least a couple of hours.

I managed to isolate the problem in the least lines of code possible and so far I have not found any work around nor way to reset what is happening after using mockk(). I suspect that the library uses reflection to inject its own constructor but forgets to keep the parameters name. Here is the minimal test to reproduce it (remember that JUnit 5 can’t warrant test order so run them independently if needed):

There are two tests, and a data class with two parameters in the constructor, name and age. The first test shows that the class has only one constructor, but it is not the same after calling to mockk(); the second one shows that the parameter names are not present anymore.

One expects that just mocking an object does not mess with the loaded class by the JVM, but I got this:

    15:25:12.631 [main] DEBUG io.mockk.impl.instantiation.AbstractMockFactory - Creating mockk for DataClass name=#2, moreInterfaces=[]  
    15:25:12.637 [main] DEBUG io.mockk.impl.stub.CommonClearer - Clearing [] mocks
    java.lang.AssertionError: Assertion failed
    at org.tarodbofh.medium.mockk.MockkMessingNativeJVM.testConstructorEqualityAfterClearMocks(MockkMessingNativeJVM.kt:26)

This means that after calling mockk() the constructor of the class had been altered!

Of course, the second test failed:

    15:25:11.563 [main] DEBUG io.mockk.impl.instantiation.AbstractMockFactory - Creating mockk for DataClass name=#1, moreInterfaces=[]  
    15:25:12.555 [main] DEBUG io.mockk.impl.stub.CommonClearer - Clearing [] mocks
    java.lang.AssertionError: [Extracted: name]   
    Expecting:  
      <["arg0", "arg1"]>  
    to contain exactly in any order:  
      <["name", "age"]>  
    elements not found:  
      <["name", "age"]>  
    and elements not expected:  
      <["arg0", "arg1"]>
    at org.tarodbofh.medium.mockk.MockkMessingNativeJVM.testConstructorGetParametersMocked(MockkMessingNativeJVM.kt:44)

The parameter names had changed, and that is why the other tests started to fail after I mocked an object on a Unit est. Don’t forget to compile with java parameters targeting Java 8 (see https://bugs.openjdk.java.net/browse/JDK-8046108).

To do that, just add this to your .gradle script: [compileKotlin, compileTestKotlin]*.kotlinOptions*.javaParameters = true and you’ll be using the parameters. Else, the first test will fail on the first assertion and not on the second one.

If you need help to set up gradle to test this, you can have a look at my .gradle file here.

I learned this the hard way but in the end I opted to not mock any object I was requiring, but using constant value objects.

For example, if I am testing underage people I will have a val UNDERAGE_PERSON = DataClass("underage, 1) on an TestExtensions.kt file instead of using a mocked object, at least for POJOs, DTOs and other stateful constructs. For stateless and business logic methods, I am hesitant until I inspect mockk code to see what is it doing to mess with the JVM.

After a brief chat on gitter with mockk maintainer he asked to submit a bug report, so I hope this gets fixed on a future release.

Some days later, I experienced the same bug with mockito, but only when @Mock annotations where used instead of using mock(...) methods. I was unable to reproduce it on a constant behavior as apparently this happened randomly.

This bug indeed seems related to this two bugs on mockito that were already resolved.

Update: The mockk issue fas fixed on mockk 1.8.7 release, less than 10 days after I submitted the bug.

That is grade A job from the maintainers. Kudos!

Originally published in Medium