DEV Community: Arminas Katilius

Why TDD is Not Working For You

Arminas Katilius — Mon, 18 Mar 2019 13:42:47 +0000

Test Driven Development seems such a simple technique, yet it causes a wide range of reactions towards it. From people thinking it’s making you more professional, to people thinking it’s dead.

Overall I think too strong push from TDD enthusiasts does more harm than good. It's great when you are excited about good coding practice, but when you start forcing others, it can have the opposite reaction. There is even a psychological term for it - Reactance theory:

Reactances can occur when someone is heavily pressured to accept a certain view or attitude. Reactance can cause the person to adopt or strengthen a view or attitude that is contrary to what was intended, and also increases resistance to persuasion.

I think this somewhat affects that developers are more likely to express and share an opinion on why TDD is not working for them.
TDD is a specific technique and it is naive to think that it can be applied for everyone. And nobody should feel bad or unprofessional for not using TDD. However maybe TDD is the right technique for you, but multiple coincidences lead you to the conclusion that it's too hard and impractical. Here I will share a few ideas that might help you rethink your TDD experience. Some of them are ideas about how to apply the rules alternatively and some of them how to improve test experience, even if you are not using TDD.

You follow rules too strictly

This comes from all tutorials and books, where the rules are laid out strictly. First law of TDD states:

You are not allowed to write any production code unless it is to make a failing unit test pass.

From such strong wording, it might seem that following the rules strictly is a must. While all 3 laws describe TDD process accurately and some developers do follow them strictly, it should be treated as material for initial learning.

Learn the rules, THEN break them

For TDD it means that once you grasp how it works, you can apply it whenever you feel it works. Initially, strict process teaches you how to write testable code. But later you might find it more comfortable to build structure first and start writing TDD tests for logic then.

You are only using it for unit tests

It's a common misconception, that TDD == unit tests. Actually, even the name is "Test Driven Development", not "Unit Test Driven Development". Unit tests are mostly used in TDD examples and tutorials, and usually, TDD works really great with pure unit testable functions. But in reality, the technique works with any kind of tests.

For example, I have written a lot of SQL queries using TDD. Sometimes I am not sure what SQL I need to write, but I just need to create a test that inserts few database rows and expects some result. And then I can try out different SQL queries until it works. And same with API tests. You might need to fix bug where JSON output is a wrong format. Instead of testing manually with Postman, you can write an API test case and then start fixing the code.

Your testing infrastructure is too slow

The great benefit of TDD is that it actually can make you faster. Here is how.

Writing a new functionality, or fixing existing one process could be oversimplified into two steps:

Create/Update code
Check if it works as intended

TDD lets you optimize the speed of the "Check if it works as intended". You need not to wait for an app to be rebuilt, you need not open a browser, create test data and see if the code works as you expected. With TDD you see the result instantaneously.

However, if tests execution is slow, that just breaks the flow. Some say tests should run in 10 seconds or less.
And I can partly agree because TDD felt best for me when a test suite was fast. However, I would not agree that it's bad to run part of a test suite in order to be faster if you have a big test suite. But before using that technique, there are other ways to improve speed.

First, it’s essential to find out why tests are slow. Integration tests might slow down if there is redundant data initialization, or if the database is being rebuilt each time. Each case is unique. And it is the same with unit tests, it varies depending on the stack or tools you are using. Find out their limitations and best practices and see if you can improve the speed in any way.

And if there is no other way to improve speed (for example IT tests are naturally slower than unit). You can apply this technique, which allows running tests fast. Run a different amount of tests in a specific frequency:

Execute a single test most often, when you do small code changes
After a certain time, or if you think you have made a large change, run all tests for a particular function/method
After a certain time, run multiple related tests (might be all tests for the same class/module)
Finally, run all test suit

This is not an exact science and you should find what works best. But try not to think too much about which tests you should need to run.

Your testing infrastructure is inconvenient

It closely relates to the previous statement about speed. To be efficient at TDD, you have to use comfortable tools (same applies to be efficient at writing tests without TDD as well).

As an example I can mention two qualities of testing infrastructure, that I think are really important:

How easy is to execute all tests vs single test? Best case is that you can execute needed tests with a single button click or keyboard shortcut. Going to console and typing regex to match test you want to run is just tedious.
How clear are assertion errors? You should not need to decipher why the test failed. Failure message like "Expected true to be false", when you were expecting certain item in an array is no good.

The list can go on, but the main goal is to minimize thinking about routine actions. This instead allows thinking more about the actual problem that you need to solve. If testing infrastructure gets in the way and makes you think too much about how to start writing or write test, it will be really hard to be efficient at TDD. This way tests will become annoying chore no matter if you write them after or before.

You apply TDD for simple cases only

Writing tests for simple logic, especially if mocking is involved, can feel a bit awkward. You need to write setup code, initialize mock objects, add assertions for method calls, etc. And finally, the actual code is just "if" statement and few function calls. And this can feel a bit underwhelming.

I am not saying you should not use TDD for simple cases. While learning it certainly helps. But applying for simple cases only might not reveal it's full potential. When I started using TDD, it seemed that I can only apply it to a new code, and only to certain functions. But I have started to use it when fixing new bugs or adding new functionality to existing code and it really helped me to understand how to apply it in different cases.

TDD feels best when you have complex logic to implement. You do not even know how to implement it, but it allows you to chip away requirements and finally get fully working solution. And also it adds a lot of confidence to refactor while you do it.

You are testing too much implementation details

Good tests are clear and easy to understand. And with TDD it should be simple to think of what test to write upfront. However, if you are trying to cover internal behavior too much, it might be too hard to write test upfront.

For example that happens a lot when a lot of stubbing and mocking involved. These kind of tests are hard to write because they involve assertions like "this method should be called 3 times with these arguments", etc.

Another example I can remember is writing React tests using Enzyme. I sometimes ended up with tests that were checking internal state, checking how component renders children components and etc. And when I have started using React Testing Library it become much easier to use TDD. You do not have access to internal details and it forces you to think about components testing differently. You do not care what child components are being rendered and what props are passed to them. Instead, you can write tests that expect certain text being rendered, and such tests are definitely easier to write upfront.

Writing Javascript Codemods and Understanding AST Easily

Arminas Katilius — Tue, 05 Mar 2019 20:36:12 +0000

Originally posted in my personal blog

One of the big advantages when using statically typed language is ease of refactoring. Different IDE tools can easily rename class or method across hundreds of files with hundreds of usages. And given the nature of Javascript, some of the refactorings are hard, or even impossible.

Despite that, different tools, that modify or inspect Javascript code still emerge. And in some cases, they are even better than ones in statically typed languages ecosystem. Prettier, Eslint, React Codemods to name a few.

They all have one in common - they all analyze or modify parsed Abstract Syntax Tree of the code. Basically, AST let you traverse source code using a tree structure. AST is a general programming languages term and not specific to Javascript. I will not go into the theory about AST here, but I will show a concrete example of how to use it.

Notable tools and libraries

AST Explorer - one of the most useful tools while learning. You paste JS code and see AST representation in different AST specs.
jscodeshift - a tool by Facebook, that helps writing code modification scripts.
AST Types - type specification on which jscodeshift is based.
react-codemod - collection of scripts, written for jscodeshift that convert React code in different ways. There are some good examples to look into.
js-codemod - Similar collection of scripts, that are not React specific. Also, help to learn by example.

Setting up codemod project for TDD workflow

Codemod is textbook sample where TDD works. You have an input file, you run the script and you get output. Thus I would really recommend using TDD for codemod projects. Not only it makes codemods more stable, but having projects with test workflow setup, will help you learn. Because you can experiment just by running the same test over and over again.

Here is how to create codemod project from scratch:

Create empty npm project (npm init sample-codemod)
Install codeshift npm i -S jscodeshift
Install jest npm i -S jest
Copy over test utils from jscodeshift library src/testUtils.js
Modify testTest.js, by replacing require('./core') with require('jscodeshift')
Create initial folder structure:

+-- src
|   +-- __testfixtures__  - put sample files for transformation, use suffixes .input.js and .output.js
|   +-- __tests__ -simplicity-in-technology.markdown

After that, you can create a test file and start adding tests. Test utils from jscodeshift allow you to create 2 type tests:

Inline, where input and output is defined as string defineInlineTest(transformFn, options, input, output)
Using files, where you define path to input and output files defineTest(__dirname, transformName, options, testFilePrefix)

I have created a repo with this sample in Github.

Steps to create codemod

Essentially codemods could be oversimplified to just 2 steps:

Find the tree node
Replace with new one or modify

Since there are many ways to write the same logic in JS. You will need to think of all ways developer could write the thing you want to replace. For example, even finding imported value is not that trivial. You can use require instead of import, you can rename named import, you can do same import statement multiple times and etc.

At start I would suggest to think only about the simplest case and not think about edge cases. That's why I think TDD is essential, you can gradually add more complex cases, while not breaking initial functionality.

Sample codemod

Let's write simple codemod using this workflow. First let's define a simple test case, as we are trying to work with TDD.

We want to convert this:

export default (a, b) => a + b;

into:

export default function (a, b) {
  return a + b;
}

If we are using file approach for jscodeshift. It would be defined this way:

describe('arrow-to-function', () => {
    defineTest(__dirname, 'arrow-to-function', null, 'defaultExportedArrow');
});

Once we have this sample, we can launch AST Explorer and inspect how to input code is parsed as AST (make sure you use esprima spec):

From explorer it's clear that we need to find the node of type ArrowFunctionExpression. And based on the highlight, we care about arrow function body and params fields.
After analyzing what to find, we also need to find out what we need to build, here AST explorer helps as well. Just paste output code to it:

From the structure, it's clear, that regular functions are a bit more complex. We need to add a block statement and return statement.

Let's start with finding arrow functions. To create codeshift transformation you need to create file and export single function. That function will receive three arguments: fileInfo, API, options. Currently, we mostly care about api.jscodeshift (usually, it is defined as j) and fileInfo. Finding all arrow functions is simple:

module.exports = function transform(file, api) {
  const j = api.jscodeshift;

  j(file.source).find(j.ArrowFunctionExpression);
};

This will return the collection instance, which we can iterate and replace nodes. Let's replace all arrow functions with regular functions:

module.exports = function transform(file, api) {
  const j = api.jscodeshift;

  return j(file.source)
    .find(j.ArrowFunctionExpression)
    .replaceWith(p => {
      const nodeValue = p.value; // get value from NodePath

      // whole node will be replaced with newly built node:
      return j.functionDeclaration(
        j.identifier(""),
        nodeValue.params,
        j.blockStatement([j.returnStatement(nodeValue.body)])
      );
    })
    .toSource();
};

Each item is an instance of NodePath, which allows you get parent node, therefore in order to access actual node you need to use p.value field.
If you access jscodeshift field starting with uppercase, it will return type (j.ArrowFunctionExpression). It is used to filter and check nodes.
If you access jscodeshift field starting with lowercase, it will return build instance. Which allows creating code blocks. Check AST Types repo to see what fields are supported using each builder. For example, if you would open core.ts file and look for FunctionExpression, it has following definition: build("id", "params", "body"). Which means that you need to pass id, params, and body.

And that's pretty much it. If you follow these steps, it's not that hard to write more complex codemod. Just constantly check AST Explorer and gradually you will become more familiar with the structure.

Further improvements

The current implementation is extremely naive and should not be run on actual code base. Yet, if you would like to work further on this example to learn, here are some suggestions:

Handle arrow functions with block statement {}
Do not convert arrow functions that call this. Arrow functions handle this differently and current codemod would break working code.
Convert arrow function declaration into named functions, for example const sum = (a, b) => a + b could be converted to named function function sum(){...}

Running on codebase

I have mentioned previously that this code should not be run on the real codebase, however, if you would build fully working codemod, here is how to run it:

npx jscodeshift -t script-path.js pathToFiles

Dealing with complexity

Extract custom predicates. For example, if you are dealing a lot with JSX, you might create predicates like hasJsxAttribute, isNativeElement, etc.
Extract builder functions. If you keep creating import statements, create a function that would return the node with the import statement.

Using Typescript

It takes a bit of guessing when using jscodeshift API if you are not familiar with it. Typescript can simplify this process, it works with AST Types mentioned at the start of the post. With Typescript it's a bit easier, to guess what parameters to use in a builder, or how to access certain values. However since parsing is really dynamic in nature, time saved by getting type info is sometimes lost dealing with Typescript type system and defining types manually.

Jscodeshift recipes

Here I will share some code snippets, that might help you do some tasks while writing your own codemod. They are not 100% error prone, but at least they show some different modifications you can do.

Create function call statement

// will generate this:
const result = sum(2, 2);

j.variableDeclaration('const',
    [j.variableDeclarator(
      j.identifier('t'),
      j.callExpression(j.identifier('result'), [j.literal(2), j.literal(2)])
    )]
  );

Find imports in file

function findImportsByPath(j, root, importPath) {
    const result = {
        defaultImportUsed: false,
        namedImports: []
    };
    root.find(j.ImportDeclaration, (node) => node.source.value === importPath)
        .forEach(nodePath => {
            nodePath.value.specifiers.forEach(specifier => {
                if (j.ImportDefaultSpecifier.check(specifier)) {
                    result.defaultImportUsed = true;
                } else {
                    // specifier interface has both local and imported fields
                    // they are the same unless you rename your import: import {test as b}
                    result.namedImports.push(specifier.imported.name)
                }
            })
        });
    return result;
}

Rename JSX attribute

function transform(file, api) {
    const j = api.jscodeshift;

    return j(file.source)
        .find(j.JSXAttribute, n => n.name.name === 'class')
        .forEach(nodePath => {
            nodePath.node.name = 'className'
        }).toSource();
}

Improving Code Quality using Pull Requests

Arminas Katilius — Sat, 19 Jan 2019 17:54:23 +0000

Originally posted in company blog

Pull requests are a bit like writing automated tests. First, the usefulness of them is hard to measure, since each project is different. At the same time using both become industry standard. Yet, there is still a lot of skeptics. They think that tests/pull requests slow developers from delivering functionality faster. Finally, both lose meaning, if they are used just for the sake of using.

Another interesting thing is how tests and pull requests, besides their main purpose, improve other areas. For example, tests and especially TDD can help improve code quality and design. In this post, I will try to provide good practices for pull requests. And I will also try to mention how they can improve other areas.

Before starting, one could ask why do pull requests at all. I will not go deep into it, each team can decide why pull requests are important, or why they are not. Yet, these are the things where pull requests are useful:

Giving confidence for the author, that the code is good enough for merging
Sharing knowledge and understanding
Making ourselves less lazy
Noticing bugs

How to prepare Pull Request better

Keep it small

That is one of the most common problems with PRs, and it can affect overall experience while using pull requests. It's hard to understand changes and notice problems when there are a lot of files. Depending on team members, that usually results in two situations:

reviewers just skim through files and approve without reading
review drags on because it causes multiple discussions and the author must fix a lot of files
There are different techniques to reduce the size of PR. What you can do depends on the type of project and release cycles. You could first introduce a partially working solution, and then with following pull requests expand it. For example, if you need to implement a data table with filtering and sorting, you could start with just a table, then add sorting with other pull requests and finally filtering. Or if you have a single repository for the project, you could introduce API changes first, and UI later.

If you do not want to merge partially working functionality into a common branch, there are other techniques. You could introduce pull requests into the feature branch. With this technique, you need to create branches from your main feature branch and create pull requests back to it. It does add overhead and playing around with branches, but it might work for you.

There are other ways how to split a large problem into smaller ones, and it depends on how each person tackles it. But by trying to split it into smaller chunks you can at the same time improve your problem-solving skills. This, in turn, helps in task estimation and other areas, because even before coding, you can split a task into easy to digest parts better.

All things considered, think if large pull requests are not a symptom of too big tasks/stories. All these techniques are rarely needed if tasks are small enough.

Refactor with separate Pull Request

This tightly relates to the previous tip about small pull requests, but I wanted to mention it because it is a good technique for development even without using pull requests. The general rule states: “First refactor to make it easy to add new functionality, and only then add new functionality “. It's a great technique because instead of over-engineering, you allow new functionality guide design of the system.

If you follow this rule, you can create simpler pull requests for your team to review. This adds a lot of benefits. It automatically splits huge pull request into few smaller ones. At the same time, if refactoring affects a lot of files, you introduce them sooner, rather than later. I have not always followed this rule, and it often caused painful merge conflicts, because other team members were editing the same files.

The only downside of this approach might be if you introduce refactoring tightly to new feature you are implementing and for some reason, the feature is no longer added to the codebase, and you are left with code refactored and prepared for functionality that is not needed.

Use git commit messages wisely

Another general programming tip that translates well to pull requests is good to commit messages. It documents code and all the changes in a pull request. Think of it this way: instead of creating description where you list changes you have made, commit messages will document that. And in pull request description you can write other relevant information. And as a side effect, I really liked the description, I heard from colleague: “Writing meaningful commit messages, makes you structure tasks better and divide your work into meaningful parts.”

Comment code yourself

If you have doubts about the implementation of a feature, better discuss them before start coding and not do that in a pull request. But sometimes it might be less important things you are not sure of. For example - naming method or class. You can mention that in the pull request and somebody might suggest another name that you like better.

Another way you might help reviewers is by commenting important places of the code or even explaining why you have done the things you have done. You can use it to guide reviewers to the changes you have made.

Introduce new ideas with PRs

As I've mentioned earlier, it is better to discuss things before starting to code. But sometimes you might end up in the situation, where it's just hard to imagine if the suggested solution would work without seeing the actual code. In this case, you can create proof of concept solution and create a pull request for it. It doesn't have to be merged, but PR review page is a good place to discuss that solution.

How to Review Pull Request Better:

Do not approve PRs blindly

One of the worst practices to do if you are doing pull requests. If multiple developers approve requests without reading them, it means that you aren't actually doing code reviews and pull requests, you are just creating an illusion.

At the beginning I have mentioned, that one of the qualities of a pull request process is created confidence that your code is good enough to merge. You get this confidence because you know that other developers reviewed requirements against code, and checked readability. Reasonably sized pull request was approved 5 seconds after creation, you have a problem.

If you are busy at the time, better leave pull request for others to review and come back to it later. I would rather wait longer for my pull request to be approved, but at least then I would know that somebody looked into it.

Be polite, ask first

Sometimes you do not know why the certain code was written the way it was, and you might tell someone to fix a certain problem. Sometimes it is polite to first ask the question and then suggest improvement. For example: Why have you iterated list four times instead of one?

When you really are familiarized with code, go ahead and suggest improvement. But don't forget to be polite as well. There is a difference how you can communicate the same information:

Split this method into three smaller ones vs.
It would increase readability if you would split this method into 3 smaller ones.
A thing to remember is that people reading your comments do not see your facial expression. And you might have best intentions with your suggestion, but once it becomes text, it might seem mean or rude. And I had many situations where I wanted to just be concise and clear, but the person receiving the suggestion was not happy about that.

Use code snippets

When I started doing code reviews, I often wrote things like “This could be simplified”, “You could use lodash here”, etc. But then the author was not sure what I mean or did not know how to implement the suggestion. Gradually, I replaced generic messages with code snippets. It does take more time, but at the same time, it's much easier to compare the current code with suggested improvements and see if it's even worth doing. Also, the snippet might not be 100% accurate, the main goal is to convey information to the author more clearly.

The thing to remember is that this suggestion is not a hard rule. If you feel that some part of the code is hard to read, you can express that in different ways. Sometimes just stating concern about complexity might be enough. It might help the author notice a problem and improve the code on his own.

Review the code even if you are new

Often new team members are not sure who's pull requests they can review or even when they can review PRs at all. Each team can have a different agreement when a person can “approve“ pull requests, but you should start reading and even commenting pull requests right away. You might even add questions for the author about general ways of coding in the project and learn best practices.

How to Improve Overall Pull Request Process

Make use of static analysis tools

One of the things reviewers tend to notice is code style. It might be multiple empty lines, unused variables, and functions etc. Pull requests help to align different styles of code across developers. It does not mean that one style is better than another but having a consistent style across codebase is better compared to random style for each file. However, using pull request for that has multiple problems. One is that developers are just humans, and they will not always notice these problems.

Another is that comments about code style can take quite a lot of pull request review. They are for sure easy to fix, but when there-there are ten comments about style and one about readability, then the most important can get lost easily.

All things considered, I am not saying that it’s not worth to mention style problems in PR, but if you notice certain problems too often, consider using linting tool to notice those before pull request. If a robot can do things for you and even better, why do it yourself? Moreover, it’s easier when the robot notices problems - you cannot take offense.

Have a checklist for things to require before approving

Each developer decides if a pull request is ready to be merged, or not. But if the reviewer is stubborn, he could avoid approving pull request, even though there are no major problems with it. When you start noticing, that kind of behavior, discuss and agree on common values for the code. Then using values as a basis, decide on things required for the pull request to be approved. For example, if tests are important, make a rule that bug fix requires a new test or existing test fix. Having list of required things before approve really helps for new team members and reduces the number of discussions when PR is not being approved.

Stop large threads of discussions sooner than later

Programmers love their code. Imagine you have worked all day on the particular algorithm and somebody just starts to dissect it and tells to do things differently. Even worse, the reviewer might not be particularly polite about that. He might be wrong, or he might be right, but the point is that this could cause long discussion thread, where you exchange arguments why one or another way is better. Even if the conversation is polite, you should stop it before it gets too long and has a live discussion about that. Sometimes it’s enough to just go to other developer desk and chat, and sometimes you might need to schedule a meeting.

Gamify process

When you find trouble making developers commit to reviewing pull requests, instead of adding rules immediately, try adding some fun to the process. If you have a TV in office box that shows stats, add a new section which shows some information about pull requests. For example, you could show requests, that are pending for quite some time and are not reviewed. Additionally, you could have stats like “Reviewer that added most comments this month” or other fun statistics, that would encourage people to commit to reviewing. There are many other creative ways to improve the process and encourage the developer to participate.