DEV Community: Jean-Paul Delimat

Continuous Integration without unit tests

Jean-Paul Delimat — Thu, 06 Feb 2020 06:54:20 +0000

Do you think continuous integration is not for you because you have no automated tests? Or no unit tests at all? Not true. Tests are important. But there are many more aspects to continuous integration than just testing.

1. Building the codebase

It is the most critical issue continuous integration should solve though. The main branch of your codebase should always build/compile. It seems silly to even mention it.

Take a team of 12. Say 1 faulty commit gets into the main branch. Everybody pulls. Here starts the process of finding what's wrong and coordinating who should or will fix it. The confusion puts your whole team out of focus for around 30 minutes. Plus the frustration it brings.

Let's say this happen once a week (everybody makes mistakes eventually). 30 minutes x 12 people is 8 lost hours per week.

If you are OK with that you might as well:

set up a CI process preventing faulty builds to get into the main branch
give away a day off to one developer every week

Same outcome, happier team :)

The effort to setup a CI process that ensures your codebase compiles is less than half a day work. It's worth the effort.

2. Static code analysis

This comes for free in almost every language and is a one liner to run against a predefined set of rules:

Javascript: eslint, tslint
Java: sonarlint
Python: pylint
Go: golint

Setting up the static code analysis (or linting) takes 1 hour or so. For what benefits?

You have well formatted and "by the book" code in your main branch. That's a clear quality increase for your code base.

If that is the least of your problems because your team is always rushing to meet deadlines, think of it this way. Your code review process will be faster. Anything that is in the area of code structure, best practices etc. is already checked by your CI process. No need to review or discuss it. Your developers can focus on the business content of code reviews.

Great bonus: developers learn the code conventions automatically. The static analysis tool provides the violated rule and a why it is wrong to do so.

A hurdle with conventions is developers are dogmatic about tabs VS space kind of things. At the end of the day good conventions are ones followed by all. Pick a set of standard conventions and roll with it.

3. Culture change

Continuous Integration is not a technical problem. It's a team process. You want to work in small increments and integrate code to the main branch often. See How to get started with CI for a larger discussion on what the culture goal actually is.

After the team masters the first critical elements, another shift should happen. People will realize that working in smaller increments is more efficient. Automated checks of basic mistakes will boost confidence to merge code faster.

As a result branches life span will decrease. Code review will be faster. Every body will work with nearly latest code. It will prevent drifts and merge conflicts due to people working apart. See Why you should not use feature branches for a full list of benefits.

At the end of the day CI works with our human pride and ego.

Everybody would be happy for a tool to catch their mistake before it reaches the world.

How do you get started?

Here is a very simple and actionable process to get started. It works regardless of your git provider: GitHub, Bitbucket, Gitlab, Azure DevOps, ... and all the others.

1. Enable a Pull Request (PR) process

Lock your main branch from direct pushes. Everything should come through PRs. Here are links on how to do this for Github, Bitbucket, GitLab, Azure DevOps.

2. Pick a CI platform

Every git provider allows to define build pipelines for your PRs. The builds will run when the PR is created and for each new push to the branch the PR carries. A pre condition to complete your PR (= merge your branch) will be a succesfull build.

The big CI players are CircleCI, Codeship, Travis CI.

I of course recommend Fire CI since its the platform I've built. I don't claim it is better than the rest for each and every use cases.

Pick one and get started.

3. Define a 2 liner build

The most basic build we want to achieve is build + static code analysis. Getting there is 2 or 3 commands in a shell.

All CI platforms go for "configuration as code". You define your build in a *.yml file at the root of your repository and the platform picks it up.

With Fire CI for example you would need to add a .fire.yml file at the root of your repo that would look like this:

pipeline: 
  dockerfile: Dockerfile

Then you add a file named "Dockerfile" to build your app. Here are a few examples of simple Dockerfiles.

Any yarn/npm based tech like React/Angular/Vue/Node:

FROM python:3
WORKDIR /app 
COPY . .
RUN yarn
RUN yarn lint
RUN yarn build

Python:

FROM python:3
WORKDIR /app 
COPY . .
RUN pip install all_your_dependencies
RUN pylint all_your_python_files.py

Go:

FROM golang:latest
WORKDIR /app
COPY . .
RUN go build -o main .

I could go on with many more. These examples are simplisitc and could be improved with a few more commands. But you get the point: it's easy.

Optional: Enable code reviews

Now that every code contribution comes through a PR, code reviews are easy to do. Every git provider has an awesome UI to present the differences and allow you to comment on code.

If you are new to the process do not define a mandatory set of reviewers as it will slow your team down. Do start a best effort process to review each others code. And build on that.

What then?

As with everything, think big but start small. Having a CI process in place opens a world of opportunities.

Testing

Once you have the basic process in place, it becomes a breeze to add your first automated test. And then some others. Low yet continuous effort can bring you an awesome test coverage before you know it.

I recommend you remain lean and not invest effort to "let's write some tests". Check what breaks often or requires a high effort to test manually. Automate that.

Always keep productivity in mind. Having a ton of tests just because is worth nothing.

Other perks

There are many tools out there that you can integrate to your CI process. They are not key but the effort VS benefits could be worthwile.

A few examples below. Links are for the GitHub marketplace but other git providers integrate as easily.

Automatic update of dependencies: Depfu suggests you dependencies updates automatically. This way you remain up to date doing small increments. Always better than a once a year "let's bump everything" strategy
Open source security: Snyk warns you about security threats in open source libraries
Images optimisation: ImgBot detects large images in your repository. And submits a PR with size optimized version. Relevant for frontend projects, but still nice.

There are many more out there. Browse the marketplace for things that could solve a problem for you.

Careful though! Resist the urge to use everything that comes to mind. Pick the ones that really provide a productivity boost. Free metrics or tools that are not looked at are harmful as people are not sure what to do with them.

Conclusion

You do not need fancy tests suites to get started with Continuous Integration.

Literally 2 hours of effort can get you rolling. And enable a virtuous circle for your team productivity.

The bigger your team and your projects, the greater the benefits. In 2020 there is no good reason to not have a CI process.

Feel free to contact me if you need help setting up a CI process for your team. I'll be happy to help if I can.

Thanks for reading and good luck!

Originally published on The Fire CI Blog.
(the awesome cover photo is from Will Porada on Unsplash)

The Top Five Developer Skills That'll Make You a Hero (Hint: Involves LEGOs)

Jean-Paul Delimat — Tue, 28 Jan 2020 07:27:32 +0000

Programming is like building Lego bricks. Any developer can pick a brand new Lego set and build it following the instructions. This is very easy. Think of it as coding school assignments or entry level tutorials.

A real software project is different. It is like building a very large castle set. Except it was already built in the past. Then someone torn it to pieces with a savage kick. The bigger parts remained kind of together. Smaller parts were completely crushed. Some elements went out the window.

You get a box containing what's left, but also thousands of pieces from other sets. And the instructions are gone of course. You can only rely on one picture to know what the castle looks like.

Now that's interesting! Let's see how to work effectively in this environment.

1. Accept the unknowns

The first step of any development task is to understand what you need to do. It sounds obvious. And yet, the bigger the task, the more unknown variables you get. This is the moment to set clear expectations.

If you have no clue how to get started, there is no point thinking and conceptualizing too long. Start and get your head around the key elements you need. Then think again. If anyone asks you for estimates or a deadline upfront, be open and honest. Some parts of the system you don't know or may not understand. And that's OK.

Think of platforms like Facebook, Netflix or Oracle. Or any larger enterprise software out there. Very few people can grasp the full scope. The ones who do have either built it or spent years working with it. So first of all, give yourself a break for not knowing everything. And more importantly, accept that you won't know everything.

Experienced and productive developers are not better coders. They are better at evaluating what they need to do. And at picking the right strategies to cope with the unknowns.

Lego analogy: Think of the castle set we want to rebuild. Say someone gives you a picture of the castle and the box, and asks you "how much time do you need to build the castle?". There is no good answer to that except "I don't know yet. Let me start and let's see where I am at after a day or two".

The ultimate "I fear the unknowns" approach to this task would be to lay out all the elements from the box on the floor. Try to separate them into the sets they belong to based on color and shape. Then look at the picture and make a mental map on how to assemble the bricks.

This approach is wrong for 2 reasons. First, if the castle is too big you'll probably never get there. Second and most important: you can't assess progress. You could be on the right track or not at all. You have no feedback loop.

Another approach would be to start building the castle. As you go you will learn if it is easy to find the pieces you need or not. You will know if the picture shows all the details or if the construction is more complex than it looks.

Based on these information you'll be able to make a more educated guess on the time and effort it will take to do the job. And if it's worth doing at all. If you need it built for tomorrow morning, maybe going to the store and buying the same castle again is a better solution? That's might not be your decision to make, but solutions to a problem does not always come through more code.

2. Accept compromise

Developers often praise and value "great attention to details". Every job offer out there has this in one form or the other. That's all good. But don't confuse attention to details with stubbornness to have everything perfect.

When starting a big task you have to define 2 versions of it. The first version is the bare minimum you need to verify that things will work the way you think they will.

That's what I call "working horizontally". Each piece of your bigger task is a vertical. You don't have to go deep to get the first results. Focus on the main use case or scenario first. And take it from there.

The things you can leave behind in the first version:

error handling
edge cases
clean code
configuration

Don't think of all that and just write the code you need as it flows from your fingers. You should get to a high functional coverage quickly. Sure, it will take a lot of time to move from this first, simplistic version to the final one. So what is the point?

That's a safer way to progress. You want to verify your assumptions. As smart and capable as you may be, designing and conceptualizing can only take you that far. Get your hands dirty. It will give you more knowledge and insight than any "thinking it through".

This is the same principle that applies to MVPs for new products or features in business. The approach also has the advantage that you can show your first version and get feedback. Or ask questions. It's easier to brainstorm on existing code than on a drawing or concept.

Lego analogy: You are building the tower of the castle. On the picture the high tower walls is made of interlaced grey and white bricks. There is a princess locked in the tower and a dragon on the roof.

You find the princess and the dragon but it would take you ages to find the grey and white bricks you need. The right approach is to build the wall using any bricks, and place the princess and the dragon. You can leave a TODO like "Improve the bricks of the wall".

The idea is that you have identified a problem: it's going to be difficult to build the perfect wall. Let's accept that and move on to discover all the other obstacles we don't know about yet. Accepting the compromise prevents you from getting stuck.

Even if you never get to the TODO, you can tell your customer: "Here is the full castle. We know we have to improve the tower wall, but it's built". This is much better than "We are heavily delayed because it took us ages to find the right bricks for the tower. But look, the tower is perfect and exactly as on the picture you sent us. Now we'll get to the rest of the castle".

Important: don't confuse compromise and sloppiness.

The key elements of the tower are the princess and the dragon. Don't put a farmer in the tower and a cat on the roof and think that's an OK compromise. It won't work :)

3. Start with the outside world

There are many things you can control. And things you can't. I've learnt it the hard way on one of my first assignments as a developer ten years ago. The task was to integrate an external API and process the data. I had one week. It was a very reasonable timeline, even for an inexperienced guy like me.

Here is what I've done (and you shouldn't).

It's Monday morning. I've read the API documentation for 10 minutes. It seems very easy. I create a test data set and moving on to write the code to process it. I will test with the real API once I'm done.

Wednesday morning and I'm almost done. I think my code is clean and well designed and everything (it wasn't). Now I just need to integrate the API and I'll probably finish ahead of time. I can't help to think that "I am awesome".

I quickly get to the API part. I'm trying to reach it with my code. Except I can't. Something is wrong. I waste the whole day double checking everything. Using different API clients. No progress. The day flashes and it is Wednesday evening now.

I am stuck, and I feel quite the opposite of awesome.

I get to work on Thursday and ask a colleague for help. He tells me that access to the API may be IP restricted and that I have to contact the company to white-list our IPs. Good, I have a way forward.

I send an email to the company owning the API. It's like 8AM. I foolishly expect a quick answer and resolution within minutes. I sweat all morning and at noon I finally pick up the phone and call the support number. I explain my problem and try to highlight the best I can how big an "emergency" it is (it wasn't).

The guy on the other side of the line explains me that the white-listing time is usually 1 or 2 days. Now I am depressed. 1 or 2 days? How is this possible? My task is the most important in the world (only to me of course) and they tell me "1 or 2 days"?

All the sudden I am not ahead anymore. I am late. I failed. I go to my boss and tell him I fucked up. I should have checked the API Monday morning. I would then have requested access the same day and I would have written my code in the meantime. He just smiles back as a "Yes you should have".

I finally get access on Friday and have to stay very late to finish the job. I adapt my code to the many surprises the API data bring. Good bye well designed and clean code. I will justified it later saying "There was no time for that" (there was).

In my naiveness of the time, I felt the access thing and wrong documentation were very bad luck. Now I can tell it is business as usual.

The lesson is to start with what you can't control. Confirm every assumption you have about the environment. Use manual and low costs ways to try things out as early as possible.

Lego analogy: Imagine you are building the castle and things are running smooth. You now have mixed the box about 100 times looking for pieces. You can't help thinking "I never came across that huge orange dragon sitting on the tower on the picture".

You ignore that information to focus on the good progress you have. That's human. Moving forward is more exciting than dealing with problems. At the end you'll have to acknowledge that the dragon is missing. And tell your customer very late that the bigger piece of the set will not be present. That's not good.

The thing to do instead is to follow up on that hint: "Where is the dragon?". Spend the time needed to be 100% sure it's not there. Raise the issue right away. Tell your customer "Hey, there is no dragon in the box. I can't make up a dragon out of the other bricks. What do we do?".

People are surprisingly OK with problems when they know early enough. Discovering problems early opens more possible solutions. "Shall we continue knowing there is no dragon?". "Can we buy the dragon alone?". "I can see a dinosaur in the box. Can we use it instead?".

4. Draw a clear line

When you start working on a new feature for an existing system, start by defining how it interfaces with the existing code. Of course you should try and follow SOLID principles etc. but the key part is simpler than that. Just try to make the touching surface as low as possible.

The simple process of clearly defining the cut will improve your solution. It will force you force you to tackle the key questions: How will the users or system use my code? What inputs will I get? What outputs should I produce? It helps you keep your eyes on the ball. This is even more true if you don't know much about the system you are working with yet. It is a good opportunity to explore the unknowns before diving into what you know already.

It also makes it easy to turn the feature on or off. You can use a boolean flag or a more advance feature toggle mechanism.

Lego analogy: Say you need to build an extension of the castle. Requirements are rather high level so there is plenty of room for creativity. You can't touch the existing castle though.

You could go and build a great extension only to find out there is no space to attach it to the castle anywhere. That's unfortunate. You'll have to quickly alter your extension to make it fit somehow.

The right approach would be to think of the touching surface first. Where will the extension be on the castle. What bricks can I attach it to? What form do they have? Put together the few bricks of the extension attaching it to the castle. Verify they plug for a solid connection. From there you can freestyle any extension you want.

5. Don't be too DRY

DRY stands for Don't Repeat Yourself. That is probably the easiest rule to follow. As soon as you see duplicated lines of code, you make an abstraction. It can be a base class, a helper method, whatever.

What happens then? The next person comes and the common code needs to change to cover more cases. She or he adds parameters and if statements to cope with the emerging complexities. Soon, the 5 initial and simple lines become 30 lines and it's difficult to figure out what is happening.

Poor readability is not a good trade for code repetitions.

It would have been better to keep the duplicated lines. You could then change each instance at will.

The next time you reach for "abstraction over repetition", ask yourself: how many times did you see someone go back from an abstraction? Like removing a base class and putting the common code back to the inheriting classes. I bet the answer is never.

The reason is abstractions and design patterns in general are cool and sophisticated. And if one exists then "there must be a good reason". So once you introduce the abstraction, there is a good chance it will stay there forever.

Does this mean you should never use abstractions? No. User abstractions when they fit requirements. Things like:

"We want to log every call to this method with inputs outputs"
"We want to log every HTTP requests with data a, b, c"
"Every time a user is created we need to do this and that

These are good candidates for abstraction and there are many more examples, but notice how the requirements are more technical than business related (logging, security, analytics, etc.). It is rare that abstraction friendly requirements are part of your business domain.

Why? Because the business domain is close to the real world. And that we can't control. Assumptions made at the beginning of a project often fall short pretty soon. Don't over engineer code just to avoid repetition.

Lego analogy: None. There is no DRY concept in Lego bricks.

Takeaways

Working smart is not about better code. It is about figuring out what needs to be done, and safely progressing toward the goal.

Large and challenging development tasks will carry unknowns. Embrace it. Learn to work with it.

You will be more productive if you keep things simple and align expectations for the outcome with your team, boss, customer, ideally everybody.

Thanks for reading!

Originally published on The Fire CI Blog.

The real difference between CI and CD

Jean-Paul Delimat — Sun, 01 Dec 2019 21:24:07 +0000

There is plenty of content out there describing what Continuous Integration, Continuous Delivery and Continuous Deployment are. But what are these processes for in the first place?

It is crucial to understand the problems CI and CD solve to use them properly. It will allow your team to improve your process. And avoid putting effort chasing fancy metrics that do not bring any value to your process.

Continuous Integration is a team problem

If you work in a team you are several developers working on the same repository. There is a main branch in the repository carrying the latest version of the code. Developers work on different things on different branches. Once someone is done with his change, he’ll push or merge it to the main branch. Eventually the whole team will pull this change.

The scenario we want to avoid is that a faulty commit makes it to the main branch. Faulty means the code does not compile or the app won't start or is unusable.
Why? Not because the app is broken or because all tests must always be green. That is not a problem, you can very well never deploy that version and wait for a fix.

The problem is that your entire team is stuck. All the developers who pulled the faulty commit will spend 5 minutes wondering why it doesn't work. Several will probably try to find the faulty commit. Some will try to fix the issue by themselves in parallel of the faulty code author.

This is a waste of time for your team. The worst part is that repeated incidents fuel a mistrust of the main branch and encourage developers to work apart.

Continuous Integration is all about preventing the main branch of being broken so your team is not stuck. That's it. It is not about having all your tests green all the time and the main branch deployable to production at every commit.

The process of Continuous Integration is independent of any tool. You could verify manually that the merge of your branch and the main branch works locally. And then only actually push the merge to the repository. Now that would be very inefficient. That's why Continuous Integration is implemented using automated checks.

The checks shall ensure the bare minimum:

The app should build and start
Most critical features should be functional at all times (user signup/login journey and key business features)
Common layers of the application that all the developers rely on, should be stable. This means unit tests on those parts.

In practice it means you need to pull any unit test framework that work for you and secure the common layers of the application. Sometimes it is not that much code and can be done fairly quickly. Also you need to add a "smoke test" verifying that the code compiles and that the application starts. This is especially important in technologies with crazy dependency injections like Java Spring or .NET core. In large projects it is so easy to miswire your dependencies that verifying that the app actually always at least starts is a must.

If you have hundreds or thousands of tests you don't need to run them all for each merge. It will take a lot of time and most tests probably verify "non team blocker" features.

We'll see in the next sections how the process of Continuous Delivery will make good use of these many tests.

It's not about tools

Tools and automated checks are all fine. But if your developers only merge giant branches they work on for weeks, they won't help you. The team will spend a good amount of time merging the branches and fixing the code incompatibilities that will arise eventually. It is as much a waste of time as being blocked by a faulty commit.

Continuous Integration is not about tools. It is about working in small chunks and integrating your new code to the main branch and pulling frequently.

Frequently means at least daily. Split the task you are working on into smaller tasks. Merge your code very often and pull very often. This way nobody works apart for more than a day or two and problems do not have time to become snowballs.

A large task does not need to be all in one branch. It should never be. Techniques to merge work in progress to the main branch are called "branching by abstraction" and "feature toggles". See the blog post How to get started with Continuous Integration for more details.

Key points for a good CI build

It's very simple. Keep it short. 3-7 minutes should be max. It's not about CPU and resources. It is about developers' productivity.
The first rule of productivity is focus. Do one thing, finish it, then move to the next thing.

Context switching is costly. Studies show it takes ~23 minutes to deeply refocus on something when you get disturbed. Imagine you push your branch to merge it.
You start another task. You spend 15-20 minutes getting into it. The minute after you are in the zone you receive a "build failed" notification from your 20 minutes long CI build for the previous task. You get back to fix it. You push it again. You easily lost more than 20 minutes moving back and forth.

Multiply 20 minutes once or twice a day by the number of developers in your team ... That's a lot of precious time wasted.

Now imagine the feedback came within 3 minutes. And you knew it would. You probably wouldn't have started the new task at all. You would have proof read your code one more time or reviewed a PR while waiting. The failed notification would come. You would fix it. And then move on to the next task. That is the kind of focus your process should enable.

Keeping your CI build short makes it a trade off. Tests that run longer or provide little value in the context of CI should be moved to the CD step. And yes, failures there also need to be fixed. But since they are not preventing anybody from doing their thing, you can take the fixes as a "next task" when you finish what you are doing. Just turn off the notifications while working and check every now and then. Keep the context switching to its minimum.

Continuous Delivery and Deployment are engineering problems

Let’s settle on the definitions to get that out of the way.

Continuous Delivery is about being able to deploy any version of your code at all times. In practice it means the last or pre last version of your code. You don’t deploy automatically, usually because you don’t have to or are limited by your project lifecycle. But as soon as someone feels like it, deploy can be done in minimum time. That someone can be the test/QA team that wants to test things out on a staging or preproduction environment. Or it can actually be time to roll out the code to production.

The idea of Continuous Delivery is to prepare artefacts as close as possible from what you want to run in your environment. These can be jar or war files if you are working with Java, executables if you are working with .NET. These can also be folders of transpiled JS code or even Docker containers, whatever makes deploy shorter (i.e. you have pre built in advance as much as you can).

By preparing artefacts I don't mean turning code into artefacts. This is usually a few scripts and minutes of execution. Preparing means:

Run all the tests you can to ensure that once deployed the code will actually work. Run unit tests, integration tests, end to end tests and even performance tests if you can automate that.

This way you can filter which versions of your main branch are actually production ready and which are not. The ideal test suite:

Ensures that the application key functionalities work. Ideally all functionalities
Ensures that no performance deal breaker has been introduced so when your new version hits your many users it has a chance to last
Dry run any database updates your code needs to avoid surprises

It does not need to be very fast. 30 minutes or 1 hour is acceptable.

Continuous Deployment is the next step. You deploy the most up to date and production ready version of your code to some environment. Ideally production if you trust your CD test suite enough.

Note that depending on the context this is not always possible or worth the effort. Continuous Delivery is often enough to be productive. Especially if you are working in a close network and have limited environments you can deploy to. It can also be that the release cycle of your software prevents unplanned deploys.

Continuous Delivery and Continuous Deployment (let’s call them CD from now on) are not team problems. They are about finding the right balance between execution time, maintenance efforts and relevance of your tests suite to be able to say "This version works as it should". And it is a balance. If your tests last 30 hours that is a problem. See this epic post about how the Oracle database test suite looks like. If you spend so much time keeping your tests up to date with latest code that it impedes the team progress, that is not good either. And if your test suite ensures pretty much nothing ... it is basically useless.

In an ideal world we want 1 set of deployable artefacts per commit to the main branch. You can see we have a vertical scalability problem: the faster we move from code to artefacts, the more ready we are to deploy the newest version of the code.

What’s the big difference?

Continuous Integration is an horizontal scalability problem. You want developers to merge their code often so the checks must be fast. Ideally within minutes to avoid developers switching context all the time with highly async feedback from the CI builds.

The more developers you have, the more computing power you need to run simple checks (build and test) on all the active branches.

A good CI build:

Ensures no code that breaks basic stuff and prevents other team members to work is introduced to the main branch

Is fast enough to provide feedback to developers within minutes to prevent context switching between tasks

Continuous Delivery and Deployment are vertical scalability problems. You have one rather complex operation to perform.

A good CD build:

Ensures that as many features as possible are working properly

The faster the better, but it is not a matter of speed. A 30-60 minutes build is OK

A common misconception is to see CD as a horizontal scalability problem like CI: the faster you can move from code to artefacts, the more commits you can actually process, and the closer to the ideal scenario you can be. But we don't need that. Producing artefacts for every commit and as fast as possible is usually overkill. You can very well approach CD on a best effort basis: have a single CD build that will just pick the latest commit to verify once a given build is finished.

Make no mistake about CD. It is really hard. Getting to sufficient test confidence to say your software is ready to be deployed automatically usually works on low surface applications like APIs or simple UIs. It is very difficult to achieve on a complex UI or a large monolith system.

Conclusion

Tools and principles used to execute CI and CD are often very similar. The goals are very different though.

Continuous Integration is a trade off between speed of feedback loop to developers and relevance of the checks your perform (build and test). No code that would impede the team progress should make it to the main branch.

Continuous Delivery of Deployment is about running as thorough checks as you can to catch issues on your code. Completeness of the checks is the most important factor. It is usually measured in terms code coverage or functional coverage of your tests. Catching errors early on prevents broken code to get deployed to any environment and saves the precious time of your test team.

Craft your CI and CD builds to achieve these goals and keep your team productive. No workflow is perfect. Problems will happen every now and then. Use them as lessons learned to strengthen your workflow every time they do.

Published on 27 Nov 2019 by Jean-Paul Delimat on the Fire CI Blog

API end to end testing with Docker

Jean-Paul Delimat — Tue, 12 Nov 2019 15:24:34 +0000

Testing is a pain in general. Some don't see the point. Some see it but think of it as an extra step slowing them down. Sometimes tests are there but very long to run or unstable. In this article you'll see how
you can engineer tests for yourself with Docker.

We want fast, meaningful and reliable tests written and maintained with minimal effort. It means tests that are useful to you as a developer on a day-to-day basis. They should boost your productivity and improve the quality of your software. Having tests because everybody says "you should have tests" is no good if it slows you down.

Let's see how to achieve this with not that much effort.

The example we are going to test

In this article we are going to test an API built with Node/express and use chai/mocha for testing. I've chosen a JS'y stack because the code is super short and easy to read. The principles applied are valid for any tech stack. Keep reading even if Javascript makes you sick.

The example will cover a simple set of CRUD endpoints for users. It's more than enough to grasp the concept and apply to the more complex business logic of your API.

We are going to use a pretty standard environment for the API:

A Postgres database
A Redis cluster
Our API will use other external APIs to do its job

Your API might need a different environment. The principles applied in this article will remain the same. You'll use different Docker base images to run whatever component you might need.

Why Docker? And in fact Docker Compose

This section is a lot of arguments in favour or using Docker for testing. You can skip it if you want to get to the technical part right away.

The painful alternatives

To test your API in a close to production environment you have two choices. You can mock the environment at code level or run the tests on a real server with the database etc. installed.
Mocking everything at code level clutters the code and configuration of our API. It is also often not very representative of how the API will behave in production. Running the thing in a real server is infrastructure heavy. It is a lot of setup and maintenance, and it does not scale. Having a shared database, you can run only 1 test at a time to ensure test runs do not interfere with each other.

Docker Compose allows us to get the best of both worlds. It creates "containerized" versions of all the external parts we use. It is mocking but on the outside of our code. Our API thinks it is in a real physical environment. Docker compose will also create an isolated network for all the containers for a given test run. This allows you to run several of them in parallel on your local computer or a CI host.

Overkill?

You might wonder if it isn't overkill to go end to end tests at all with Docker compose. What about just running unit tests instead?

For the last 10 years, large monolith applications are being split into smaller services (trending towards the buzzy "micro services"). A given API component relies on more external parts (infrastructure or other APIs). As services get smaller, integration with the infrastructure becomes a bigger part of the job. You should keep a small gap between your production and your development environments. Otherwise problems will arise when going for production deploy. By definition these problems appear at the worst possible moment. They will lead to rushed fixes, drops in quality, and frustration for the team. Nobody wants that.

You might wonder if end to end tests with Docker compose run longer than traditional unit tests. Not really. You'll see in the example below that we can easily keep the tests under 1 minute. At great benefits: the tests reflect the application behaviour in the real world. This is more valuable than knowing if your class somewhere in the middle of the app works OK or not. Also, if you don't have any tests right now, starting from end to end gives you great benefits for little effort. You'll know all stacks of the application work together for the most common scenarios. That's already something! From there you can always refine a strategy to unit tests critical parts of your application.

Our first test

Let’s start with the easiest part. Our API and the Postgres database. And let’s run a simple CRUD test. Once we have that framework in place, we can add more features both to our component and to the test.

Here is our minimal API with a GET/POST to create and list users:

const express = require('express');
const bodyParser = require('body-parser');
const cors = require('cors');

const config = require('./config');

const db = require('knex')({
  client: 'pg',
  connection: {
    host : config.db.host,
    user : config.db.user,
    password : config.db.password,
  },
});

const app = express();

app.use(bodyParser.urlencoded({ extended: false }));
app.use(bodyParser.json());
app.use(cors());

app.route('/api/users').post(async (req, res, next) => {
  try {
    const { email, firstname } = req.body;
    // ... validate inputs here ...
    const userData = { email, firstname };

    const result = await db('users').returning('id').insert(userData);
    const id = result[0];
    res.status(201).send({ id, ...userData });
  } catch (err) {
    console.log(`Error: Unable to create user: ${err.message}. ${err.stack}`);
    return next(err);
  }
});

app.route('/api/users').get((req, res, next) => {
  db('users')
  .select('id', 'email', 'firstname')
  .then(users => res.status(200).send(users))
  .catch(err => {
      console.log(`Unable to fetch users: ${err.message}. ${err.stack}`);
      return next(err);
  });
});

try {
  console.log("Starting web server...");

  const port = process.env.PORT || 8000;
  app.listen(port, () => console.log(`Server started on: ${port}`));
} catch(error) {
  console.error(error.stack);
}

Here are our tests written with chai. The tests create a new user and fetch it back.
You can see that the tests are not coupled in any way with the code of our API.
The SERVER_URL variable specifies the endpoint to test. It can be a local or a remote environment.

const chai = require("chai");
const chaiHttp = require("chai-http");
const should = chai.should();

const SERVER_URL = process.env.APP_URL || "http://localhost:8000";

chai.use(chaiHttp);

const TEST_USER = {
  email: "john@doe.com",
  firstname: "John"
};

let createdUserId;

describe("Users", () => {
  it("should create a new user", done => {
    chai
      .request(SERVER_URL)
      .post("/api/users")
      .send(TEST_USER)
      .end((err, res) => {
        if (err) done(err)
        res.should.have.status(201);
        res.should.be.json;
        res.body.should.be.a("object");
        res.body.should.have.property("id");
        done();
      });
  });

  it("should get the created user", done => {
    chai
      .request(SERVER_URL)
      .get("/api/users")
      .end((err, res) => {
        if (err) done(err)
        res.should.have.status(200);
        res.body.should.be.a("array");

        const user = res.body.pop();
        user.id.should.equal(createdUserId);
        user.email.should.equal(TEST_USER.email);
        user.firstname.should.equal(TEST_USER.firstname);
        done();
      });
  });
});

Good. Now to test our API let's define a Docker compose environment. A file called docker-compose.yml will describe the containers Docker needs to run.

version: '3.1'

services:
  db:
    image: postgres
    environment:
      POSTGRES_USER: john
      POSTGRES_PASSWORD: mysecretpassword
    expose:
      - 5432

  myapp:
    build: .
    image: myapp
    command: yarn start
    environment:
      APP_DB_HOST: db
      APP_DB_USER: john
      APP_DB_PASSWORD: mysecretpassword
    expose:
      - 8000
    depends_on:
      - db

  myapp-tests:
    image: myapp
    command: dockerize
        -wait tcp://db:5432 -wait tcp://myapp:8000 -timeout 10s
        bash -c "node db/init.js && yarn test"
    environment:
      APP_URL: http://myapp:8000
      APP_DB_HOST: db
      APP_DB_USER: john
      APP_DB_PASSWORD: mysecretpassword
    depends_on:
      - db
      - myapp

So what do we have here. There are 3 containers:

db spins up a fresh instance of PostgreSQL. We use the public Postgres image from Docker Hub. We set the database username and password. We tell Docker to expose the port 5432 the database will listen to so other containers can connect
myapp is the container that will run our API. The build command tells Docker to actually build the container image from our source. The rest is like the db container: environment variables and ports
myapp-tests is the container that will execute our tests. It will use the same image that myapp because the code will already be there so there is not need to build it again. The command node db/init.js && yarn test ran on the container will initialize the database (create tables etc.) and run the tests. We use dockerize to wait for all the required servers to be up and running. The depends_on options will ensure that containers start in a certain order. It does not ensure that the database inside the db container is actually ready to accept connections. Nor that our API server is already up.

The definition of the environment is like 20 lines of very easy to understand code. The only brainy part is the environment definition. User names, passwords and URLs must be consistent so containers can actually work together.

One thing to notice is that Docker compose will set the host of the containers it creates to the name of the container. So the database won't be available under localhost:5432 but db:5432. The same way our API will served under myapp:8000. There is no localhost of any kind here. This means that your API must support environment variables when it comes to environment definition. No hardcoded stuff. But that has nothing to do with Docker or this article. A configurable application is point 3 of the 12 factor app manifesto, so you should be doing it already.

The very last thing we need to tell Docker is how to actually build the container myapp. We use a Dockerfile like below. The content is specific to your tech stack but the idea is to bundle your API into a runnable server.

The example below for our Node API installs Dockerize, installs the API depencencies and copies the code of the API inside the container (the server is written in raw JS so no need to compile it).

FROM node AS base

# Dockerize is needed to sync containers startup
ENV DOCKERIZE_VERSION v0.6.0
RUN wget https://github.com/jwilder/dockerize/releases/download/$DOCKERIZE_VERSION/dockerize-alpine-linux-amd64-$DOCKERIZE_VERSION.tar.gz \
    && tar -C /usr/local/bin -xzvf dockerize-alpine-linux-amd64-$DOCKERIZE_VERSION.tar.gz \
    && rm dockerize-alpine-linux-amd64-$DOCKERIZE_VERSION.tar.gz

RUN mkdir -p ~/app

WORKDIR ~/app

COPY package.json .
COPY yarn.lock .

FROM base AS dependencies

RUN yarn

FROM dependencies AS runtime

COPY . .

Typically from the line WORKDIR ~/app and below you would run commands that would build your application.

And here is the command we use to run the tests:

docker-compose up --build --abort-on-container-exit

This command will tell Docker compose to spin up the components defined in our docker-compose.yml file. The --build flag will trigger the build of the myapp container by executing the content of the Dockerfile above. The --abort-on-container-exit will tell Docker compose to shutdown the environment as soon as one container exits. That works well since the only component meant to exit is the test container myapp-tests after the tests are executed. Cherry on the cake, the docker-compose command will exit with the same exit code as the container that triggered the exit. It means that we can check if the tests succeeded or not from the command line. This is very useful for automated builds in a CI environment.

Isn't that the perfect test setup?

The full example is here on GitHub.
You can clone the repository and run the docker compose command:

docker-compose up --build --abort-on-container-exit

Of course you need Docker installed. Docker has the troublesome tendency of forcing you to sign up for an account just to download the thing. But you actually don't have to. Go to the release notes (link for Windows and link for Mac) and download not the latest version but the one right before. This is a direct download link.

The very first run of the tests will be longer than usual. It is because Docker will have to download the base images for your containers and cache a few things. Next runs will be much faster.

Logs from the run will look as below. You can see that Docker is cool enough to put logs from all the components on the same timeline. This is very handy when looking for errors.

Creating tuto-api-e2e-testing_db_1    ... done
Creating tuto-api-e2e-testing_redis_1 ... done
Creating tuto-api-e2e-testing_myapp_1 ... done
Creating tuto-api-e2e-testing_myapp-tests_1 ... done
Attaching to tuto-api-e2e-testing_redis_1, tuto-api-e2e-testing_db_1, tuto-api-e2e-testing_myapp_1, tuto-api-e2e-testing_myapp-tests_1
db_1           | The files belonging to this database system will be owned by user "postgres".
redis_1        | 1:M 09 Nov 2019 21:57:22.161 * Running mode=standalone, port=6379.
myapp_1        | yarn run v1.19.0
redis_1        | 1:M 09 Nov 2019 21:57:22.162 # WARNING: The TCP backlog setting of 511 cannot be enforced because /proc/sys/net/core/somaxconn is set to the lower value of 128.
redis_1        | 1:M 09 Nov 2019 21:57:22.162 # Server initialized
db_1           | This user must also own the server process.
db_1           | 
db_1           | The database cluster will be initialized with locale "en_US.utf8".
db_1           | The default database encoding has accordingly been set to "UTF8".
db_1           | The default text search configuration will be set to "english".
db_1           | 
db_1           | Data page checksums are disabled.
db_1           | 
db_1           | fixing permissions on existing directory /var/lib/postgresql/data ... ok
db_1           | creating subdirectories ... ok
db_1           | selecting dynamic shared memory implementation ... posix
myapp-tests_1  | 2019/11/09 21:57:25 Waiting for: tcp://db:5432
myapp-tests_1  | 2019/11/09 21:57:25 Waiting for: tcp://redis:6379
myapp-tests_1  | 2019/11/09 21:57:25 Waiting for: tcp://myapp:8000
myapp_1        | $ node server.js
redis_1        | 1:M 09 Nov 2019 21:57:22.163 # WARNING you have Transparent Huge Pages (THP) support enabled in your kernel. This will create latency and memory usage issues with Redis. To fix this issue run the command 'echo never > /sys/kernel/mm/transparent_hugepage/enabled' as root, and add it to your /etc/rc.local in order to retain the setting after a reboot. Redis must be restarted after THP is disabled.
db_1           | selecting default max_connections ... 100
myapp_1        | Starting web server...
myapp-tests_1  | 2019/11/09 21:57:25 Connected to tcp://myapp:8000
myapp-tests_1  | 2019/11/09 21:57:25 Connected to tcp://db:5432
redis_1        | 1:M 09 Nov 2019 21:57:22.164 * Ready to accept connections
myapp-tests_1  | 2019/11/09 21:57:25 Connected to tcp://redis:6379
myapp_1        | Server started on: 8000
db_1           | selecting default shared_buffers ... 128MB
db_1           | selecting default time zone ... Etc/UTC
db_1           | creating configuration files ... ok
db_1           | running bootstrap script ... ok
db_1           | performing post-bootstrap initialization ... ok
db_1           | syncing data to disk ... ok
db_1           | 
db_1           | 
db_1           | Success. You can now start the database server using:
db_1           | 
db_1           |     pg_ctl -D /var/lib/postgresql/data -l logfile start
db_1           | 
db_1           | initdb: warning: enabling "trust" authentication for local connections
db_1           | You can change this by editing pg_hba.conf or using the option -A, or
db_1           | --auth-local and --auth-host, the next time you run initdb.
db_1           | waiting for server to start....2019-11-09 21:57:24.328 UTC [41] LOG:  starting PostgreSQL 12.0 (Debian 12.0-2.pgdg100+1) on x86_64-pc-linux-gnu, compiled by gcc (Debian 8.3.0-6) 8.3.0, 64-bit
db_1           | 2019-11-09 21:57:24.346 UTC [41] LOG:  listening on Unix socket "/var/run/postgresql/.s.PGSQL.5432"
db_1           | 2019-11-09 21:57:24.373 UTC [42] LOG:  database system was shut down at 2019-11-09 21:57:23 UTC
db_1           | 2019-11-09 21:57:24.383 UTC [41] LOG:  database system is ready to accept connections
db_1           |  done
db_1           | server started
db_1           | CREATE DATABASE
db_1           | 
db_1           | 
db_1           | /usr/local/bin/docker-entrypoint.sh: ignoring /docker-entrypoint-initdb.d/*
db_1           | 
db_1           | waiting for server to shut down....2019-11-09 21:57:24.907 UTC [41] LOG:  received fast shutdown request
db_1           | 2019-11-09 21:57:24.909 UTC [41] LOG:  aborting any active transactions
db_1           | 2019-11-09 21:57:24.914 UTC [41] LOG:  background worker "logical replication launcher" (PID 48) exited with exit code 1
db_1           | 2019-11-09 21:57:24.914 UTC [43] LOG:  shutting down
db_1           | 2019-11-09 21:57:24.930 UTC [41] LOG:  database system is shut down
db_1           |  done
db_1           | server stopped
db_1           | 
db_1           | PostgreSQL init process complete; ready for start up.
db_1           | 
db_1           | 2019-11-09 21:57:25.038 UTC [1] LOG:  starting PostgreSQL 12.0 (Debian 12.0-2.pgdg100+1) on x86_64-pc-linux-gnu, compiled by gcc (Debian 8.3.0-6) 8.3.0, 64-bit
db_1           | 2019-11-09 21:57:25.039 UTC [1] LOG:  listening on IPv4 address "0.0.0.0", port 5432
db_1           | 2019-11-09 21:57:25.039 UTC [1] LOG:  listening on IPv6 address "::", port 5432
db_1           | 2019-11-09 21:57:25.052 UTC [1] LOG:  listening on Unix socket "/var/run/postgresql/.s.PGSQL.5432"
db_1           | 2019-11-09 21:57:25.071 UTC [59] LOG:  database system was shut down at 2019-11-09 21:57:24 UTC
db_1           | 2019-11-09 21:57:25.077 UTC [1] LOG:  database system is ready to accept connections
myapp-tests_1  | Creating tables ...
myapp-tests_1  | Creating table 'users'
myapp-tests_1  | Tables created succesfully
myapp-tests_1  | yarn run v1.19.0
myapp-tests_1  | $ mocha --timeout 10000 --bail
myapp-tests_1  | 
myapp-tests_1  | 
myapp-tests_1  |   Users
myapp-tests_1  | Mock server started on port: 8002
myapp-tests_1  |     ✓ should create a new user (151ms)
myapp-tests_1  |     ✓ should get the created user
myapp-tests_1  |     ✓ should not create user if mail is spammy
myapp-tests_1  |     ✓ should not create user if spammy mail API is down
myapp-tests_1  | 
myapp-tests_1  | 
myapp-tests_1  |   4 passing (234ms)
myapp-tests_1  | 
myapp-tests_1  | Done in 0.88s.
myapp-tests_1  | 2019/11/09 21:57:26 Command finished successfully.
tuto-api-e2e-testing_myapp-tests_1 exited with code 0

We can see that db is the container that initializes the longest. Makes sense. Once its done the tests start.
The total runtime on my laptop is 16 seconds. Compared to the 880ms used to actually execute the tests it is a lot. In practice tests that run under 1 minute are gold as it is almost immediate feedback. The 15'ish seconds overhead are a buy in time that will be constant as you add more tests. You could add hundreds of tests and still keep execution time under 1 minute.

Voila! We have our test framework up and running. In a real world project the next steps would be to enhance functional coverage of your API with more tests. Let's consider CRUD operations covered. It's time to add more elements to our test environment.

Adding a Redis cluster

Let's add another element to our API environment to understand what it takes. Spoiler alert: it's not much.

Let us imagine that our API keeps user sessions in a Redis cluster. If you wonder why we would do that, imagine 100 instances of your API in production. Users hit one or another server based on round robin load balancing. Every request needs to be authenticated. It requires user profile data to check for privileges and other application specific business logic. One way to go is to make a round trip to the database to fetch the data every time you need it, but that is not very efficient. Using an in memory database cluster makes the data available across all servers for the cost of a local variable read.

This is how you enhance your Docker compose test environment with an additional service.
Let’s add a Redis cluster from the official Docker image (I've only kept the new parts of the file):

services:
  db:
    ...

  redis:
    image: "redis:alpine"
    expose:
      - 6379

  myapp:
    environment:
      APP_REDIS_HOST: redis
      APP_REDIS_PORT: 6379
    ...
  myapp-tests:
    command: dockerize ... -wait tcp://redis:6379 ...
    environment:
      APP_REDIS_HOST: redis
      APP_REDIS_PORT: 6379
      ...
    ...

You can see it's not much. We added a new container called redis. It uses the official minimal redis image called redis:alpine. We added Redis host and port configuration to our API container. And we've made tests wait for it as well as the other containers before executing the tests.

Let’s modify our application to actually use the Redis cluster:

const redis = require('redis').createClient({
  host: config.redis.host,
  port: config.redis.port,
})

...

app.route('/api/users').post(async (req, res, next) => {
  try {
    const { email, firstname } = req.body;
    // ... validate inputs here ...
    const userData = { email, firstname };
    const result = await db('users').returning('id').insert(userData);
    const id = result[0];

    // Once the user is created store the data in the Redis cluster
    await redis.set(id, JSON.stringify(userData));

    res.status(201).send({ id, ...userData });
  } catch (err) {
    console.log(`Error: Unable to create user: ${err.message}. ${err.stack}`);
    return next(err);
  }
});

Let's now change our tests to check that the Redis cluster is populated with the right data. That's why the myapp-tests container also gets the Redis host and port configuration in docker-compose.yml.

it("should create a new user", done => {
  chai
    .request(SERVER_URL)
    .post("/api/users")
    .send(TEST_USER)
    .end((err, res) => {
      if (err) throw err;
      res.should.have.status(201);
      res.should.be.json;
      res.body.should.be.a("object");
      res.body.should.have.property("id");
      res.body.should.have.property("email");
      res.body.should.have.property("firstname");
      res.body.id.should.not.be.null;
      res.body.email.should.equal(TEST_USER.email);
      res.body.firstname.should.equal(TEST_USER.firstname);
      createdUserId = res.body.id;

      redis.get(createdUserId, (err, cacheData) => {
        if (err) throw err;
        cacheData = JSON.parse(cacheData);
        cacheData.should.have.property("email");
        cacheData.should.have.property("firstname");
        cacheData.email.should.equal(TEST_USER.email);
        cacheData.firstname.should.equal(TEST_USER.firstname);
        done();
      });
    });
});

See how easy this was. You can build a complex environment for your tests like you assemble Lego bricks.

We can see another benefit of this kind of containerized full environment testing. The tests can actually look into the environments components. Our tests can not only check that our API returns the proper response codes and data. We can check that data in the Redis cluster have the proper values. We could also check the database content.

Adding API mocks

A common element for API components is to call other API components.

Let's say our API needs to check for spammy user emails when creating a user. The check is done using a third party service:

const validateUserEmail = async (email) => {
  const res = await fetch(`${config.app.externalUrl}/validate?email=${email}`);
  if(res.status !== 200) return false;
  const json = await res.json();
  return json.result === 'valid';
}

app.route('/api/users').post(async (req, res, next) => {
  try {
    const { email, firstname } = req.body;
    // ... validate inputs here ...
    const userData = { email, firstname };

    // We don't just create any user. Spammy emails should be rejected
    const isValidUser = await validateUserEmail(email);
    if(!isValidUser) {
      return res.sendStatus(403);
    }

    const result = await db('users').returning('id').insert(userData);
    const id = result[0];
    await redis.set(id, JSON.stringify(userData));
    res.status(201).send({ id, ...userData });
  } catch (err) {
    console.log(`Error: Unable to create user: ${err.message}. ${err.stack}`);
    return next(err);
  }
});

Now we have a problem for testing anything. We can't create any users if the API to detect spammy emails is not available . Modifying our API to bypass this step in test mode is a dangerous cluttering of the code.

Even if we could use the real third party service, we don't want to do that. As a general rule our tests should not depend on external infrastructure. First of all, because you will probably run your tests a lot as part of your CI process. It’s not that cool to consume another production API for this purpose. Second of all the API might be temporarily down, failing your tests for the wrong reasons.

The right solution is to mock the external APIs in our tests.

No need for any fancy framework. We'll build a generic mock in vanilla JS in ~20 lines of code. This will give us the opportunity to control what the API will return to our component. It allows to test error scenarios.

Now let’s enhance our tests.

const express = require("express");

...

const MOCK_SERVER_PORT = process.env.MOCK_SERVER_PORT || 8002;

// Some object to encapsulate attributes of our mock server
// The mock stores all requests it receives in the `requests` property.
const mock = {
  app: express(),
  server: null,
  requests: [],
  status: 404,
  responseBody: {}
};

// Define which response code and content the mock will be sending
const setupMock = (status, body) => {
  mock.status = status;
  mock.responseBody = body;
};

// Start the mock server
const initMock = async () => {
  mock.app.use(bodyParser.urlencoded({ extended: false }));
  mock.app.use(bodyParser.json());
  mock.app.use(cors());
  mock.app.get("*", (req, res) => {
    mock.requests.push(req);
    res.status(mock.status).send(mock.responseBody);
  });

  mock.server = await mock.app.listen(MOCK_SERVER_PORT);
  console.log(`Mock server started on port: ${MOCK_SERVER_PORT}`);
};

// Destroy the mock server
const teardownMock = () => {
  if (mock.server) {
    mock.server.close();
    delete mock.server;
  }
};

describe("Users", () => {
  // Our mock is started before any test starts ...
  before(async () => await initMock());

  // ... killed after all the tests are executed ...
  after(() => {
    redis.quit();
    teardownMock();
  });

  // ... and we reset the recorded requests between each test
  beforeEach(() => (mock.requests = []));

  it("should create a new user", done => {
    // The mock will tell us the email is valid in this test
    setupMock(200, { result: "valid" });

    chai
      .request(SERVER_URL)
      .post("/api/users")
      .send(TEST_USER)
      .end((err, res) => {
        // ... check response and redis as before
        createdUserId = res.body.id;

        // Verify that the API called the mocked service with the right parameters
        mock.requests.length.should.equal(1);
        mock.requests[0].path.should.equal("/api/validate");
        mock.requests[0].query.should.have.property("email");
        mock.requests[0].query.email.should.equal(TEST_USER.email);
        done();
      });
  });
});

The tests now checks that the external API has been hit with the proper data during the call to our API.

We can also add other tests checking how our API behaves based on the external API response codes:

describe("Users", () => {
  it("should not create user if mail is spammy", done => {
    // The mock will tell us the email is NOT valid in this test ...
    setupMock(200, { result: "invalid" });

    chai
      .request(SERVER_URL)
      .post("/api/users")
      .send(TEST_USER)
      .end((err, res) => {
        // ... so the API should fail to create the user
        // We could test that the DB and Redis are empty here
        res.should.have.status(403);
        done();
      });
  });

  it("should not create user if spammy mail API is down", done => {
    // The mock will tell us the email checking service
    //  is down for this test ...
    setupMock(500, {});

    chai
      .request(SERVER_URL)
      .post("/api/users")
      .send(TEST_USER)
      .end((err, res) => {
        // ... in that case also a user should not be created
        res.should.have.status(403);
        done();
      });
  });
});

How you handle errors from third party APIs in your application is of course up to you. But you get the point.

To run these tests we need to tell the container myapp what is the base URL of the third party service:

  myapp:
    environment:
      APP_EXTERNAL_URL: http://myapp-tests:8002/api
    ...

  myapp-tests:
    environment:
      MOCK_SERVER_PORT: 8002
    ...

Conclusion and a few other thoughts

Hopefully this article gave you a taste of what Docker compose can do for you when it comes to API testing. The full example is here on GitHub.

Using Docker compose makes tests run fast in an environment close to production. It requires no adaptations to your component code. The only requirement is to support environment variables driven configuration.

The component logic in this example is very simple but the principles apply to any API. Your tests will just be longer or more complex. They also apply to any tech stack that can be put inside a container (that's all of them). And once you are there you are one step away from deploying your containers to production if need be.

If you have no tests right now this is how I recommend you should start. End to end testing with Docker compose. It is so simple you could have a first test running in a few hours. Feel free to reach out to me if you have questions or need advice. I'd be happy to help.

I hope you enjoyed this article and will start testing your APIs with Docker Compose. Once you have the tests ready you can run them out of the box on our continuous integration platform Fire CI.

One last idea to succeed with automated testing.

When it comes to maintaining large test suites, the most important feature is that tests are easy to read and understand. This is key to motivate your team to keep the tests up to date. Complex tests frameworks are unlikely to be properly used in the long run. Regardless of the stack for your API, you might want to consider using chai/mocha to write tests for it. It might seem unusual to have different stacks for runtime code and test code, but if it gets the job done ... As you can see from the examples in this article, testing a REST API with chai/mocha is as simple as it gets. The learning curve is close to zero. So if you have no tests at all and have a REST API to test written in Java, Python, RoR, .NET or whatever other stack, you might consider giving chai/mocha a try.

If you wonder how to get start with continuous integration at all, I have written a broader guide about it. Here it is: How to get started with Continuous Integration.

Originally published on the Fire CI Blog on 06 Nov 2019.

Essential skills every developer should master (besides coding)

Jean-Paul Delimat — Wed, 24 Apr 2019 06:59:50 +0000

Whether you are learning to code, looking for a new job, or just want to improve your skills as a developer, you need to master the essential tools of team collaboration. These are as important as knowing how to code.

It is teamwork that makes or breaks software projects.

Your code will work eventually. If you want it to work “on time” and be of good quality, you and your team need to be organized.

Everyone needs to know what they have to do and when
People’s work should not overlap or clash
Common rules need to be followed through by everyone

You can achieve this using the right processes and tools. You want your team to focus on coding 90% of the time (the remaining 10% are for coffee breaks and Windows Updates).

Here are four essential things you need to master.

1. Git and Pull Requests

Configuration management is the foundation of team collaboration in software. Many tools exist for it, but luckily one has become the absolute and ultimate reference: Git.

Documentation on the key aspects is well described in the Git Book.

There are plenty of turnkey services to get started: GitHub is probably the most popular, but also BitBucket or GitLab.

A great graphical tool to work with is SourceTree. I recommend you master the command line before reaching for UI tools, though.

Below are the questions you should know how to answer:

How do I merge or rebase my branch, and what is the difference?
How do I resolve conflicts? For example, mine versus theirs versus manual merge
What is a feature branch?
What is a pull request?
What are the different collaboration workflows in Git?

That’s it, and this is pretty straightforward. After reading the theory and with some practice, you will become a Git master in a jiffy.

2. The Agile board

The first thing a team needs to do when starting a project or a larger task is to split the job. Over the last 10 years, the “Agile” methodology replaced the traditional waterfall planning. The Agile manifesto is here.

Practically speaking it says “let’s not plan too much ahead, because inputs and assumptions we have today about the project will change”. This is almost always true, and nowadays there is hardly any team under the sun that is not (sometimes self-proclaimed) “Agile”.

Here are the practical things you need to know:

The most popular Agile way of working is Scrum. Divide your project into “sprints” of two weeks and put “tasks” in the content of the sprint. All the rest is for the future and is called the “backlog”. This is useful to track progress, adjust planning going forward, and improve team velocity over time.
Another Agile approach is Kanban. The idea is to limit the number of tasks that are “in progress”. This way, you are sure to close one item fully before moving to the next. There are no sprints or time frames like in Scrum. You just go through tasks one after the other until you’re done. In Agile, a software project will be split into tens or hundreds of tasks. You need a tool to manage them. The reference tool is JIRA.

Other tools exist of course, but you will probably have to work with JIRA at some point. So if you are new to these all the tools, just go for JIRA. There is a free 7 day trial. It is more than enough to get an overview of how things work. Again, this is fairly straightforward, and very well-documented.

3. Testing and Continuous Integration

Git and agile tools allow teams to go fast. With speed inevitably come errors and bugs. Consider a team of five developers working on rather independent pieces of code. Each of them will make a pull request to the repository. Two problems can arise:

Once the code of the “first developer” gets to the Git repository, the code of the others is no longer valid or working because some things have changed. This is not a mistake from “the first developer”, it is just life and it will happen.
Once all the developers pushed their code to the Git repository, chances that everything work as expected out of the box are rather low. Again, this is not a reflection of poor teamwork. It will just happen.

Therefore, you need to test your software. Even after each developer has pushed their code? It would be great, but a waste of time.

When other developers push their code, we’ll need to repeat this task. Should you test once everyone has pushed their code? Also great, but you’ll find bugs late in the process, which can delay the whole project. So how can you solve this?

Automated tests and Continuous Integration are there to the rescue.

Automated testing is a topic one could write many books about. Each language and framework has its own set of tools. Listing them all would not make sense here. Just keep in mind that testing is time consuming and not always planned for.

Regardless, you should know how to write unit tests for your code and be proactive about writing them. If you don’t have time to actually do it, you should at least be aware that it’s wrong.

Continuous Integration is a process in which every push to your repository triggers a build and runs your tests automatically. A red flag is raised as soon as a faulty commit goes in. Pull requests should also be tested automatically before merging to avoid bugs that impact the whole team.

Continuous Delivery is the extension of Continuous Integration. If the tests pass properly, the tested version is pushed to the production environment automatically.

As an example: at Quora, they track the time between a push to the repository and deployment of that code to production servers. The last benchmark I read about was 15 minutes … for around 100 developers. This is the most powerful setup a team could hope for.

Popular continuous integration servers are Jenkins, Travis, CircleCI, and a few more. We at Fire CI promote a serverless approach to Continuous Integration to put developers productivity at its best. You do not need to know how to set the server up and everything, but you should know such tools exist, and a red alert should trigger in your head if your team do not use any.

4. Patience and understanding

As a developer your main frustration will not come from the code. You might spend a few hours searching Google and Stack Overflow for answers
but this is a driving activity. The real pain will come from the outside:

Unclear or misunderstood requirements
People unhappy with the end result of your work because they didn't knew what they wanted in the first place and they expected you to figure it out
Tools that become slow or stop working for some reasons
Interruptions now and then because people think that sitting at your desk means they can disturb you any time

The keyword here is "patience". Try to understand the people around you. They don't know everything. Remember that you don't either. Do make them understand though that your time is valuable and that they should respect it.

The last but not the least when it comes to customers and requirements: do not accept low level or clumsy detailed requirements if you didn't get a brief on the big picture. You need to understand the business you are building software for. At the end of the day your code is here to improve an existing process or enable new ones.

The better your understand the business side of things, the better developer you'll be.

Conclusion

The core of a developer’s job is coding. Once you move from solo/hobbyist to member of a performing team, proper use of the key collaboration tools is as important as writing clean code. Hopefully this article gave you an overview of what these tools are and how to dig further to be the best at what you do!

Originally published at Fire CI Blog on April 5th, 2019.

Why you should not use (long-lived) feature branches

Jean-Paul Delimat — Fri, 19 Apr 2019 10:30:50 +0000

Isn't the git history in the picture above nice to work with? There are probably many problems in that repository, but one of them is most definitely the use of feature branches. Let's see how such a bad thing became such a common practice.

When git came to replace SVN it brought a ridiculously easy way to create branches.

The idea behing git is to ease your pain as a developer working on many features at a time. Not to push branches around and tie them to the whole development process of your team.

When JIRA and others came along , companies like Atlassian started to heavily promote the "git workflow" and feature branches. The "Create branch" button appeared in your JIRA tasks and boom, feature branches were born! Atlassian tells you all about it in this interesting article. I like Atlassian's products very much. Keep in mind though that their core business is tasks management for development teams. The more tangled it gets with branches and code, the better.

Ten years later, feature branching is a standard in most teams, when in fact it doesn't bring any benefits to your bottom line: release quality software to production. Not only feature branches provide zero benefit, they actually slow you down!

For the sake of clarity: this article assumes a feature branch will carry the whole feature you are developing and is a so called 'long-lived' feature branch that will last 1 week or more. It's not a "no branches at all" mantra.

"The feature is ready. I just need to merge it!"

I've heard this way too many times. This falls in the same category as statements like "It compiles so it works".

In practice the merging leads to the "unpredictable release syndrome". It can be quick or evince a major incompatibility, which needs fixing in a rush. You are either lucky or … your timeline shifts and code quality drops.

The real problem with feature branches is the reason they are so popular: they pump a developer's pride and make you feel good about your work.

Your feature branch is your own perfect garden and you can keep it clean and shiny. But it is separated from the other gardens of your team. The more you work apart, the harder it is to reconcile.

I am a big fan of the management book "The goal". It shows how over time people tend to use metrics that highlight local optimums of a process because it is more comfortable. They just lose focus on their global bottom line. The book is about a production plant, but the analogy stands. Your feature branch is a local optimum with high quality code. It may also be so far off the main branch that it is of no use for the upcoming release.

Trunk based development to the rescue

As the name suggests, in trunk based development the whole team pushes continuously to the main branch or use very short lived (1 or 2 days max) branches.

Here is a detailed description of the idea. I have no affiliation with the linked website. It is just a great overview of the concept.

When you push your work to the main branch often, the amount of code to merge is way smaller and it becomes trivial. There is a far greater benefit though: you and your team can spot problems before they become painful. It might be that your refactoring clashes with another feature. Or you are drifting off from the project conventions or architecture patterns. This is the real value of the process. As I preach in any place I find myself in:

It is teamwork that makes or breaks software projects.

Working days on code that will never get to the release on time is the biggest failure there is for a team.

Another upside of pushing or merging often to the main branch is that your changes will run live in some environment. It is always good to deploy and battle test your code, even in progress, in some real deploy.

"WIP" in the main branch?

If you read so far you are probably thinking "This is crazy, how can I push my half done work to the main branch when it will probably get deployed to production very soon!?!".

Here are the common objections one might have and a tentative solution.

How can I expose unfinished work?

Use feature toggles. They can be environment variables or whatever suits you best to turn on and off your work in progress. Make it defensive of course so your half finished code does not get active in production by mistake.

Your whole team will love this: you can activate code on any environment at any time to see how it looks or performs. Testers can prepare testing early on. Product owners can comment on your work along the way. It is all live and easy to access for everyone! If your work is like just started this provide little value. But evil lies in the details. It usually takes half the time to get to 90% completion and another half to finish the remaining 10%. Sharing your work in this state of 90% completion is always a good idea ;)

Another thing that comes for free: you can turn the feature off in production if a problem arise after deployment. After a few days or weeks, once the feature runs smoothly, just remove the toggle from the code.

What if I break the main branch for everyone?

It is 2019. If you don't have a continuous integration setup that builds and runs tests automatically … then set it up yesterday. If you break anything you'll be notified before it becomes a problem for the whole team. In pure Trunk Based Development the feedback will come after the merge and has to be fixed right away. If you are using short lived branches the merge should be blocked by your CI tool. A short lived branch is something that should last 1 or 2 days max and carry a consistent piece of code that contribute to the feature you are building.

There must be a code review before we merge anything in!

That's a valid point. Code reviews do not need feature branches though. If the code review culture is strong in your team then it can very well be done on the commit to the main branch. The reviewer would stop by the author of the commit and discuss what needs to be fixed. The fix would come in another commit. Even better, have the code review together before pushing the commit in the first place.

If it is not acceptable to your team to have post merge code reviews (because let's face it it is less handy as tools do not really support that), use short lived branches and apply your code review process there.

I want to see the code that is related to a task

If you have a given branch per feature then it is easy to track code back to your agile board. You can navigate from a task to the branch that implements it.

It sounds cool, while in reality this is useless! How many people can you have on an agile team? Up to 5? Up to 10? How hard is it to ask the guy running a task or story what commits you need to look at to deep dive into the implementation?

After some time, once tasks are completed for a long time, linking tasks to code does not make sense anymore. Developers rely on git blame to know the who, on code content to know the how, and hopefully on comments to know the why.

The cherry on the cake: opt-in on new features

It became common to see major UI features or updates released using an "opt in" approach. Github, Bitbucket, Gmail, … to name a few.

The concept is that major changes are introduced using a banner "Hey we have this new feature / improved dashboard / whatever. Click here to try it out". You can opt in, and usually opt out as easily if you don't like the change. This is a very good adoption testing strategy as it involves the end users in the decision process. If people opt in and stay there it means you are improving the experience. If they opt in and out … you know you've changed things for worse.

If you are using feature toggles from the start, exposing these on a per user basis at run time becomes very easy.

Conclusion

If you never thought of trunk based development as an alternative to the feature branch mantra, I hope this article gave you some perspective and will to try it out.

The best thing is that to get there you'll need to setup or improve every other aspect of your process (CI, automated tests, code reviews). This is a good path to take. We obviously recommend Fire CI as a continuous integration tool.

Remember that your bottom line is to put quality software in front of your users. The closer your code is from the production environment at all times, the better.

Now, although the article is very much "trunk based development" oriented, note that it might not be a valid approach for your team.
If your team is highly distributed, in different time zones, has a lot of junior developers who need to learn the project conventions and architecture, using longer lived feature branches might work better.

The main idea in this article is:

The faster you integrate the different pieces together and check that things are working, the safer you are to have a working product at the end.

A good common ground is to use short lived branches that last 1 or 2 days max and merge them to the main branch. This way you can human control what gets in and still integrate code fast.

Originally published at Fire CI Blog on March 30, 2019.

How to get started with Continuous Integration

Jean-Paul Delimat — Mon, 15 Apr 2019 09:03:55 +0000

Everything you need to know to get started with continuous integration. Branching strategies, tests automation, tools and best practices.

The goal: Deliver working code quickly and safely

The goal of Continuous Integration is to deliver code to the main branch of your repository:

Quickly: from pushing new code to the repository to merging it to the main branch when it works should be done within minutes
Safely: how do we know the new code works? Continuous Integration is about setting up the right checks to merge code automatically in full confidence

Continuous Integration is a bit about tools and a lot about mindset and culture in the team. You want your development process to facilitate fast integration of new code while keeping a working main branch at all times. This working main branch will enable Continuous Delivery or Continuous Deployment in the future. But these are for another post. Let's focus on Continuous Integration first.

There are 2 pillars to achieve Continuous Integration.

Work in small chunks

Imagine a team of 5 working on a SaaS product. Each of them develops a separate new feature. The workload on each feature is about 1 or 2 weeks. There are 2 ways to go here.

The team could go with feature branches. Each developer will work on its part on a "feature branch". The branches will be merged to the main branch once everyone is happy with their work
The team could go with branches (still) but integrate their work to the main branch on every push . Even if things are still work in progress! The work in progress would remain invisible to any end user or tester of the main branch

Which approach do you think will work best?

The first approach will ultimately lead to the "unpredictable release syndrome". Long lived feature branches create a false sense of safety and comfort for each developer individually. As the branches drift apart for a long period of time, there is no way to measure how hard it will be to merge it all. At best some minor code conflicts will arise, at worst fundamental design assumptions will be challenged and things will have to be reworked ... the hard way.

Rework will be done under time pressure, leading to a drop in quality and accumulation of technical debt. This is a vicious circle.

See the post about Why you should not use feature branches for the dirty details.

The second approach is what we need to enable continuous integration. Each developer does work on its own branch. Difference is:

Changes are merged to the main branch on every push, and each developer syncs its branch with latest main branch version a few times a day.

This way the team can fix conflicts and align design assumptions faster and easier. 5 small problems discovered early on are way better that 1 big problem discovered just before release day. Check out the "Feature Toggles" section below to see how you should integrate "work in progress" to the main branch.

Safety comes with automated checks

Ancient software development process was based on a build cycle followed by a test cycle. And this would probably still fit the "feature branches" approach described above. If we integrate and merge code tens of times a day, manual testing does not make sense. It would take too long. We need automated checks to verify that the code works properly. We need a CI tool that will take each developers' push and run build and tests automatically.

The tests type and content should be:

fast enough to provide feedback to the developer within minutes
thorough enough to merge the code to the main branch in full confidence

Unfortunately there is no one size fit all tests type and content. The right balance is specific to your project. Do not run large and time consuming test suites during your CI phase. Such tests provide better safety but they come at the cost of a delayed feedback to the developers. This leads to context switching which is a pure waste of time.

Optimize developers time and reduce context switching

Long CI checks, and by long I mean over 3 minutes, introduce a compound waste of time for each developer in your team.
Let's compare a "good" and a "bad" worklow. The "good" workflow:

You commit and push your code
The CI build and tests run for 1 to 3 minutes
During the 1 to 3 minutes you review the task at hand, bump the status in some management tool, or review your code once again
Within 3 minutes you get a succesfull status: you can move on to the next part of your task. If you get a failed build: you can fix the issue right away

The "bad" workflow:

You commit and push your code
The CI build and tests run for 15 minutes
What do you do during these 15 minutes?
- You could grab a cup of coffee with the team. Fair enough, but how many of these can you have per day?
- You would probably get your head on the next task in your pipeline
15 minutes later you get a failed build notification. You need to switch back to the previous task, try to fix the issue ... and go for another 15 minutes loop ...
At that point you are wondering: should I get back to this next task again or just wait the 15 minutes and achieve peace of mind that I am actually really done with my current task ...

The bad workflow is not only a waste of time. It is also frustrating for developers. And productive developers are happy developers.

You need to align your tools and workflows to keep your developers happy.

Tools

Branching

Continuous Integration is about integrating code from different developers branches to a common branch in your configuration management system. Chances are you are using git. In git the default main branch in a repository is called "master". Some teams create a branch called "develop" as the main branch for continuous integration. They use "master" to track deliveries and deployments (develop being merged to master).

You probably already have a main branch your team pushes or merges code to. Stick with it.

Each developer should work on their own branch. One can use multiple branches if working on many different topics at once. Although this would be a sign of "unfocused" work at best.
As soon as a consistent part of your code is ready, push your repository. The CI will checks will kick in and merge your code to the main branch if they are successful. If the checks fail, you are still on your own branch and can fix whatever needs to be and push again.

The important word in the process above is consistent part of your code. How do you know it is consistent? Simple.

If you can easily come up with a good commit message, it's consistent.

On the other hand if your commit message needs 3 bullets and many adjectives and adverbs, it's probably not good. Split your work in multiple, consistent commits. And then push the code.
Consistent commits help code reviews and make the repository history easier to follow.

Don't just push whatever because it's the end of the day!

Pull requests

What is a pull request? A pull request is a concept in which you ask the team to merge your branch to the main branch. The acceptance of your request should go through a status provided by your CI tool and potentially a code review. Ultimately the manual acceptance of a human being in charge of merging the pull requests.

Pull requests were born in open source projects. Maintainers needed a structured way to evaluate contributions before merging them in. Pull requests are not part of Git. They are supported by any Git provider though (GitHub, BitBucket, GitLab, ...).

Note that pull requests are not mandatory for Continuous Integration. Their main benefit is to support a code review process, which cannot be automated by design.

If you are using pull requests, the same principles or "work in small chunks" and "optimize developers time" apply:

keep each pull request small and with one clear purpose (it will make code review way easier)
keep your CI checks fast

Automated checks

The heart of your Continuous Process are automated checks. They ensure that the main branch code is working properly after your code is merged. If they fail, your code does not get merged. As a minimum the code should compile or transpile or whatever is your tech stack doing to make it ready for runtime.

On top of compilation you should run automated tests to ensure the software works properly. The better the test coverage, the better confidence you can have in the new code being merged to the main branch. Careful though! Better coverage means more tests and longer execution time. You need to find the right tradeoff.

Where do you start when you have no tests at all or need to cut down on some long running tests? Focus on what is critical for your project or product.

If you are building a SaaS application, you should check that users can sign up or login, and perform the most basic operations your SaaS provides. Unless you are developing a Salesforce competitor, you should be able to run your tests within minutes if not seconds. If you are building a heavy data processing backend: use limited data sets to exercise the different building blocks. Keep long running runs on large data sets out of Continuous Integration. Long running tests can be triggered after code is merged.

Pro Tips

Feature toggles

The key concept of Continuous Integration is to put your code in the main branch as soon as possible. Even work in progress. Even features that do not fully work or that you don't want exposed to testers or end users. The way to achieve that is to use feature toggles. Have your new feature under an enabled/disabled toggle. The toggle can be a compile time boolean flag, an environment variable or a runtime thing. The right approach depends on what you want to achieve.

The first major benefits of feature toggles is that you can take them up to production and enable/disable the new feature upon need. You could restart a server with a changed environment variable, or toggle on/off a new UI dashboard layout. This way you have full flexibility to roll out the feature. Or disable it if causes unexpected issues in production. Or allow end users to opt in or out of the feature (in case of the UI toggles).

The second major benefit of feature toggles is that they force you to think of the boundary between what you are doing and the existing code. This is a good exercise and this is what you should start with anyway every time you make an addition to an existing system. The feature toggle step makes this step of the process more visible.

The only drawback on feature toggles is that you need to clean them up periodically from the environment and from the code. Once a feature is battle tested and adopted by users, it should be the default. The code for the toggle and the old version of things (if any) should be cleaned up. Don't fall into the trap of a "configuration as toggles" system. The pitfall is that you will never be able to maintain and test all combination of the toggles and have a fragile architecture in the end.

Keep CI build time under 3 minutes

Remember the "good" and the "bad" workflow in the first part of the article. We want to avoid context switching for developers. Pick your phone and set a 3 minutes timer on. See how long it is when you are just waiting for something! 3 minutes should be an absolute maximum for you to focus and move safely and efficiently from one task to the other.

A build under 3 minutes might seem crazy to some teams, but it is definitely achievable. It has more to do with how you organize your work than the tools you use. Ways to optimize your build are:

Use more build capacity: if you don't have enough concurrent builds on your CI tool and builds get queued, developers lose time
Leverage caching: most tech stacks require to install and configure dependencies when running a fresh build. Your CI tool should be able to cache these steps when dependencies do not change to optimize build time
Review your tests: check that your tests are optimized for time. Remove timeouts and "safely long" waiting steps. If you have heavy tests suites to run, consider moving them on a separate build that is run after the merge to the main branch. They would not be part of the Continuous Integration safeguard anymore, but heavy tests should not be anyway
Split your code base: do you have to have everything in one repository? do you have to build and run tests on everything even when some small part changes? There might be wins here.
Run tests conditionally: run your tests only if some directories have changed. If your codebase is well organized, this can be a huge win

The great thing about forcing a short time limit on your CI checks is that it requires you to fundamentally improve your whole development process.

As Jim Rohn said:

"Become a millionaire not for the million dollars, but for what it will make of you to achieve it"

The virtual merge: your code alone does not really matters

Most Continuous Integration tools run the CI build on your branch to say if it can be merged or not. But that is not what is of interest here. If you know what you're doing there is a pretty good chance that the code you have just pushed is working already! What your CI tool is supposed to verify is that your branch merged with the main branch works properly.

Your CI tool should perform a local merge of your branch to the main branch and run the build and tests against that. Your branch can then be automatically merged if the main branch does not change in the meantime. If it does change, the CI checks should be run again until your code can be safely merged. If your CI tools does not support this kind of workflow, change your tool.

The evil task manager

There is a misbelief that it is cool to be able to trace the code related to a task in your Agile board or bug tracker like JIRA or similar. While it is a nice concept on paper, the impact on the development process is for sure not worth the effort. The task manager provides a "features and bugs" view of the world. The code is structured and layered in a very different way. Trying to reconciling an item in the task manager and a set of commits is pointless. If you want to know why a piece of code has been written, you should be able to get the information from the code context and comments.

Final Thoughts

Tools are only tools. Setting up the tools is probably a 1 hour thing. If you use them wrong though, you won't get the expected results.

Keep in mind the goals we set for ourselves for Continuous Integration:

Deliver working code quickly and safely
Optimize developers time and reduce context switching

The real deal is about shifting your mindset to "continuously deliver value" to your project or product.

Think of your software development process as a hardware production facility. Developers code represent the moving parts. The main branch is the assembled product.

The faster you integrate the different pieces together and check that things are working, the safer you are to have a working product at the end.

A few practical examples:

You are working on a new feature and have to change a low level component others will most likely use. Make a dedicated commit for that common component part and have it merge already. Then continue working on the rest of your feature. Other developers will be able to base their work on your change right away.
You are working on a large feature that will require a lot of time and code? Use a feature toggle. Don't work in isolation. Ever!
You are waiting for a code review but no one is available to do it. If your code is passing the CI checks then just merge it and make the code review happen afterwards. If it sounds like breaking the process, remember that "done is better than perfect". If it is working, it provides more value in the main branch than parked on the side for days.

Thanks for reading!

Article originally published at fire.ci on April 9, 2019.