vendredi 14 avril 2017

Approval Tests Intro

ApprovalTests is a great tool for testing a lot of data with very little effort. It's unbeatable for protecting refactorings. This week I made a short presentation on this topic, so I thought I'd record a video, besides the slides, to show the mechanism behind it.

I've written on how to use Approval tests on several occasions, Golden Master and test dataGolden Master and legacy and published another video showing how to cover a lot of code with a small amount of test code.

Please tell me if you liked it or if you didn't. @johan_alps

mercredi 11 janvier 2017

Flexible karma and protractor configuration without duplication

Whether you need to split a test suite or introduce variation into how it is run, but you depend on
configuration files (karma, protractor) to run them. Here's a sample project to show how to do that without duplicating a single piece of that configuration. Below you'll find a walk-through

Why split a test suite?

Often I split test suites in a project. One common use case is to have one unit test suite (stable, ultra-fast) and another one for focused integration, they are still low-level tests and basically asserts both that I integrate well with external web services, message-queues, etc (inherently unstable, quite fast).

It’s a bad idea to mix both in one test suite for many reasons, one of which is that they fail for different reasons. The focused integration tests rarely fail because of bugs my team introduced.

But now we have duplication!

Anyway now that we have to test suites we need two karma.conf.js files, most of which will be duplicated.
Look at the following example, a very short snippet from a typical karma conf. Only the second entry of *files* will differ between test suites
It' a good thing that this is not only static conifiguration, but real code. If we have code then we have to power to eliminate duplication.

    files: [
    // lots of other properties 

A solution

It is dead-simple:
extract what differs to karma-unit.conf.js, and karma-integration.conf.js.
These are the entry-points and they just extract a function to build the specifics into the overwhelmingly common part.
That’s what we’ll find in buildKarmaConf.js
Here from karma-integration.conf.js

    let testFiles = 'integration-test/**/*.spec.js'

    let karmaConfObject = buildKarmaConf(testFiles)

In buildKarmaConf we have something like

function buildKarmaConf (testFiles) {
    var sourceFiles = ['src']
    var allSourcesAndSomeTestFiles = sourceFiles.concat(testFiles)

    return {
        files: allSourcesAndSomeTestFiles,
        // lots of other properties 

Another solution would be to use a environment variable and an if-statement instead of two *.conf.js files, but as in most of our code we have better alternatives (requiring less cyclomatic complexity), like what we're doing here - composing objects.

What if my situation is more complicated?

Compose further using the full power of a programming language (OO, FP). It is unlikely that the limited framework is going to solve the problem very efficiently.

What about protractor?

The exact same thing works


Karma and Protractor both use plain javascript to describe the test suite. That means we can use the the full power of JS to eliminate duplication just like in any other part of the application.

mercredi 8 juin 2016

Polymorphic directives in AngularJs

This is a short write up on how to perform ReplaceConditionalWithPolymorphism for directives in angular

Recently I had to add some functionality to a menu-bar that handles navigation between different screens. It is implemented as a directive. The problem was the same directive was instantiated by several controllers, and from some controllers it needs an instance of something, lets call it Book, and from one other controller it needs an instance something else that we’ll call Page.

I’m going to use the syntax of javascript classes to explain the problem, as it is rather clear and not specific to a framework. At the end we’ll look at the angular version.

class MenuBar {
     constructor(book, page) {
          // either of book or page are undefined

     goToView(viewItem) {
    if (onBookView()) {   // i.e. page == undefined
    } else // on page view


It is awkward and subject to error to allow either book or page to be null/undefined as it is difficult for another developer to know what is a valid way of instantiating it. Can both be undefined? If I define page, to I have to provide book? As far as testing goes, we have little confidence that it is instantiated with the right arguments in every view, so we're kind of forced to test all functionality in every view to be sure we don’t get a runtime failure. A combinatorial problem.

In addition much of the cyclomatic complexity of this class is unnecessary. Basically one set of branches are used when we have a book and a completely different one when we have a page. This is a clear cut for polymorphism :

class MenuBarForBook {
     constructor(book) {...}
     goToView(viewItem) {


class  MenuBarForPage {
     constructor(page) {...}

     goToView(viewItem) {

With this design it is unlikely that a constructor won't be called with the right arguments. The combinatorial problem is solved and we've lowered the testing burden.

So how can we do this in angular. Easy; create two different directives that expose the same functions and use the same template.

angular.module('menuBar', [])
    .directive('menuBarBook', [
    function () {
        return {
            scope: {
                book‘=‘    // constructor argument
            linkfunction ($scope) {
                $scope.goToView function () {    // function goToView()
    .directive('menuBarPage', [
    function () {
        return {
            scope: {
            linkfunction($scope) {
                $scope.goToView function () {


Polymorphism is a powerful tool both for making the code more usable to other developers by making it more explicit how to use a piece of code. Also, removing if-statements not only makes the code simpler but also makes the tests simpler. I just discovered this could be done with directives without too much overhead. It is worth naming directive inheritance here. However to my understanding it solves a different problem, namely sharing code.

jeudi 2 juin 2016

It's not a configuration issue. It’s a design issue

Consider this piece of code

url applicationConfig.publicationUrl relativeResourcePath
it contains a source of error, namely data.relativeResourcePath is of the form files/document.pdf and publicationUrl is 
of the form http://someserver/. So when someone changes the the applicationConfig to say http://otherServer:81 the download is not going to work anymore as we dropped the trailing slash. So url would be http://otherServer:81files/document.pdf which obviously won’t work

Ok so this is a configuration issue. What a pity, can’t do much about that. Even if we do TDD, testing configuration effectively isn’t easy. 

But wait! This code suffers from a Code Smell called Primitive Obsession. A better design would be the following:

url applicationConfig.publicationUrlFor(relativeResourcePath)
Poka Yoke

Now it’s easy to add the extra slash in case it is missing within the publicationUrlFor method and this type of configuration issue is gone forever throughout the application. Besides publicationUrlFor() is testable.

This is a simple example to highlight the idea that we can design away many of the bugs that we live with in our projects. By designing away sources of errors we make our code more usable, it can only be used in the right way. In Lean this is called Poka-Yoke. Every situation needs a different design to eliminate the possibility of misuse, but the general idea is the same - Design away sources of bugs.

For inspiration have a look at this other example of how to design away bugs due to temporal coupling: section Eliminate Exceptions in this post.

dimanche 13 mars 2016

Usable code and TDD

There’s a strong link between TDD and the usability of a code base, they go hand in hand.

By usability I mean how easy it is to steadily add features to it (you can read more on the concept by A. Bolboaca). The relationship between TDD and usability is that whenever it is difficult to use TDD in some piece of software there’s a reason for it - its usability level is very low. It follows that if developers work with a low usability tool (the code base), then development is not fast.

Let me explain why inability to use TDD on some codebases also makes it not usable for any other type of development. To understand that we need to look at what we need for writing a test before the code. Besides training in TDD, we need to know:
  • How to put the system (or class) in a relevant state => SETUP
  • Where the new behaviour will reside  => ACT (which class/function to call)
  • Which state or side effects to expect as a result of an action => ASSERT

Now this is difficult if interactions are complex because it is difficult to learn and memorise what to expect and assert for. Basically we’ve scored badly at two of the five usability criteria. Say we’re in a situation where we know not so much of the necessary outputs, we don’t know what to assert for, then our major concern is not to use TDD (to raise the chance that we’re implementing what we think we are) but to find out which outputs we weren’t aware of in the first place. This is often done by switching to the trial-and-error approach: change something, run the application, change something, run ….  But remember, the reason we switched from TDD to trial-and-error  is because it is difficult to cognitively master the application

Is the trial-and-error approach slow? Not always, but it goes with quite some manual testing and chances are we’ll still leave a few bugs in there to be discovered and fixed later and that is far from free. In addition we’ll avoid refactoring to not break more than necessary thus leaving more than necessary complexity in there and to further slow down the next feature.

I claim that IF it is difficult to do TDD on an application THEN it is in a state where even good developers have a hard time mastering the complex interactions and everyone will work slowly all while making the problem worse! The good news is that I’ve seen this problem being pretty much solved in various applications. It also means that if you do TDD or at least write good tests you’re likely to create an application with a high degree of usability, simply because you’ll have to remove accidental complexity.

Stay tuned an example will follow

lundi 22 février 2016

Inheritance dead end

Please use more object composition!

TLDR; There are problems with inheritance. Often composition is a better alternative. Below is an example where inheritance is employed for code reuse, but it ends up forcing duplication! The post continues with showing the more flexible alternative, object/function composition, and exposes several of its advantages.

Too often I come across codebases where there are big inheritance hierarchies. But it doesn't even have to be huge, I get suspicious when I see more than one level of inheritance or more than one overridden method in a subclass. Reluctance to refactor or lack of knowledge of alternatives drives those hierarchies to grow and become inflexible and difficult to grasp.

As an example take a restaurant that served only a single menu to start with. Then as business grew it added two variations of its menu MeatLoversMenu and GourmetsMenu. Its single public method serveMenu() serves an apetizer, then the main course, then dessert and finally coffee. For variation in which mainCourse() and which dessert() is served it uses TemplateMethod overriding the default implementations. 


Now, a few months later, it would like to offer a NoGlutenMenu as there is a lot of business in this niche. 
In theory it could serve the main course from the MeatLoversMenu and the dessert from GourmetsMenu as they don't contain any gluten. It's a simple need, but impossible to satisfy without duplicating some code given the current architecture (without multiple inheritance), where there's no way of inheriting the code of both MeatLoversMenu and GourmetsMenu.


In this case we'd be much better off using the StrategyPattern or the CommandPattern for serving the main course and the dessert.

Lets refactor the code so that Menu is a concrete class that calls an object of Type MainCourse to serve the main course and Dessert to serve the dessert. It does NOT know which one it is serving, it doesn't care. When the chef composes a noGlutenMenu he simply creates a new Menu instance using an instance of FiletMignon and CremeCaramel as shown in the bottom right corner of the diagram.


We have gained less coupling:
  • No more duplication of the logic of serving filet mignon and creme caramel
  • The chef is really happy as he can add new MainCourses and Desserts and compose menus as he like!
  • It is a lot easier to test classes like FiletMignon than MeatLoversMenu as there is less setup code involved, and less duplication between tests.
  • We even have the flexibility of opening up the restaurant in the afternoon serving only desserts. I.e. Reusing the small objects outside the context of a Menu.

Consider composition every time you override. If you can't visualize what the composition alternative would look like, then practice it. Your code is going to be much better off if you master this technique!

There are some general guidelines on when Composition over inheritance applies. Additionally Steven Lowe has some interesting insights. My personal experience tells me that I was a poor judge before I was experienced in composition and in particular knew how to refactor away an inheritance hierarchy.

Here’s a simple example of the refactoring

Note: object composition has lost a lot of boiler-plate code with the introduction of lambda-expressions in most languages. Nowadays we don't have to create interfaces for Dessert and MainCourse and no classes for the concrete implementations (unless we chose to for explicitness). An example of a modern strategy/command pattern in java

vendredi 23 octobre 2015

Tests uncover Design Smells

TLDR; Tests, even written after the code, help tremendously in pointing to production code that could

use an improved design. If writing a tests hurts, then it is often the designers fault, not the tests.

Tests, wether written before/during (TDD) or after pushes us to choose a design that will make both tests and code relatively painless. That easiness is of course bounded by the design options we already know of. Many times in life my tests have hurt, without me knowing what to do about it. But then weeks or months later I discover a new way of designing my code that would have made it better. My default assumption whenever I can’t find a way to make my tests painless, is that I have something to learn about software design. I believe this is a state of mind that is very useful if you want to have better code on your project.

Here’s a stripped down typical example of a piece of untested code. I came across this recently and I’ll show how the tests point me to a weakness in the design, and one way to deal with it. First let's have a look at the tests to know what the code does.

$ mocha test/LangBuilder.spec.js 

   ✓ is the language found in the pdf file
   ✓ can be explicitly overridden
   ✓ is french by default
   ✓ is a collection of pages in the pdf file
      every face
   ✓ has the width and height of the first page
   ✓ has a unique id

But its not the whole story, sure it returns a lang, but it also submits another piece of data to a message queue. Admittedly that is a violation of the Single Responsibility Principle, but I’m going to concentrate on a more subtle design smell. So here are the interesting parts of the code, in particularly we'll be interested in the _sendOffSplitJob function.

BTWYou can find a link to the full piece of code at the bottom of this post under "References"

So what could the tests for the sendOff part look like? It’d be something of an ugly stub/mock-hell that is one of the main reasons many people shy away from unit testing. Just for the record I show one of the test, but please don’t spend energy on understanding it. It's just proof of uglyness in case you didn't trust me.

Why is this test difficult to write? Well we deal with a third party library that wasn’t designed for easy mocking and certainly not designed to optimise one specific use case of our application (that’s not saying the library is ill-designed), so from the standpoint of LangBuilder we can simplify the design of the message queue library.

Imagine we had a function: submitJob(splitJobData) that took care of the queue naming retries and eventual send-off. A side-note on this example; javascript has first-class functions so I’m using function-composition by passing a function to the constructor of LangBuilder instead of passing an object as in object-composition. Here's that function

And the refactored LangBuilder

Then we could simply assert that LangBuilder calls it with the correct arguments, like so: 

In the process LangBuilder became easier to use, it doesn't have to bother with configuration related to the library. 

Looking at the submitJob function it became easier to use too, we didn’t just move the complexity of the queue management to a different class, we simplified it's desing with respect to our needs. In it’s original design it was mixing non changing parameters like the queue name and the number of attempts with the changing parameter splitJobData. Now we can pass those parameters at boot time creating a function that takes only the constantly changing parameter. And that simple function can be passed to any function or object that needs it.

Then we can test the submitJob function in integration with a redis server. I always put this kind of test in a different suite for practical reasons, more on that in a follow-up post. The basic idea of such a test is isolate the smallest sensible amount of code into a first-class object or function. Then test that unit extensively with the real thing.

Writing that test was a pain. Acknowledging it as a possible design smell allowed us to improve design as LangBuilder now respects a bit more the Single Responsibility Principle. Both the tests of LangBuilder and jobQueue are easy to write. jobQueue is now a first-class function that is easy to reuse elsewhere in the application.

Listening to tests allows us to spot where the tests and the production code could use an improved design. Of course tests help us spot problems and protect us during refactoring, but they don't find good alternative design. That's up to us developers to find and chose.