DEV Community: Artem Sapegin

Thoughts on using AI for software development

Artem Sapegin — Mon, 25 Aug 2025 08:43:27 +0000

In this article, I share my somewhat random and disorganized thoughts and experiences on using AI for software development.

Subscribe to my newsletter if you enjoyed this article.

Recently, I stumbled upon the AI-first developer approach – when you start most of your tasks by asking AI to do it, and then decide whether it was a good idea or not. Similar to a dog that eats everything and then decides whether it was edible or not (I used to have one of those dogs – a remarkable creature!).

It seems that people either worship AI as a tool that can do everything (and will probably replace us all by lunch next Wednesday), or reject it completely. I think such a black-and-white approach is counterproductive and dangerous in the long term. I think the truth is somewhere in-between.

For me, it’s often faster and easier to use old-school methods, such as search and replace, than to explain to AI what I want—and I still need to review and fix each change it makes. Since AI often misses things, you end up using search anyway.

On the other hand, AI is good at writing small generic code snippets (the kind you might copypaste from Stack Overflow), generating throwaway code (prototypes, proofs of concepts, or even complete apps for fun or personal tools), creating tests and types, fixing linting errors, generating fake test data, brainstorming ideas, rubberducking, writing letters and emails, proofreading, working with Git, searching code, and even fixing bugs from a screenshot report.

Tip: AI can even make screenshots on its own or debug pages in a browser, using the Playwright MCP.

AI is great for bootstrapping or trying something new – when you’ve never done it before and have no idea how it works. Instead of googling and weeding through articles for hours, it’s often more efficient to ask AI to build it, and then have it explain or adjust things.

It can also be more efficient to ask AI a semi-generic question, then write your own code – rather than letting it go berserk in your codebase. It’s similar to googling solutions and copypasting code snippets from Stack Overflow.

I don’t really like the rhythm of working with an AI agent (such as Cursor or GitHub Copilot). It often feels slow and gets in my way, especially when making large-scale changes. It’s hard for me to stay focused on a task if I have to wait longer than a few seconds. My brain also works better with code than with text instructions.

The overall overhead of using AI for writing code is very high for me: prompting, waiting for results, reviewing generated code, asking for adjustments, and so on, and so forth… A highly customized environment with shortcuts is often more efficient for everyday tasks.

It’s also annoying that AI is incredibly verbose: it overexplains, overcomments, and overdocuments everything, often adding unnecessary low-level details or even “examples” of implementation code in the docs. I really wish I could make agents less extroverted and talkative, and more efficient. AI also has the annoying habit of making changes I didn’t ask for, such as random changes to formatting and comments.

Explaining how to do something in words, reviewing whether it was done correctly, then explaining to AI how to fix it, and reviewing again often takes more time – and far more mental effort – than doing it yourself. Besides, most coding tasks still require understanding, and often the best way to gain that understanding is by doing the task yourself. If I have to read, understand, and fix some code, I might as well write it myself. This is especially true for business logic, though less so for generic low-level code.

Sometimes, it’s almost impossible to make AI do what you want. I’ve lost count of how many times I’ve told AI, “DONT EVEN DUCKING THINK OF DOING THIS,” only for it to do exactly that – “you’re right, I apologize” – and do it again…

Even on good days, I have a very limited number of spoons. Writing code is relatively cheap for me. Talking to people burns more spoons. Arguing with them burns even more. Adjusting prompts to please a machine that doesn’t want to cooperate probably burns as much. If I want to accomplish anything in a day, I have to choose wisely how I spend my spoons.

Copypasting existing code, either from the same project or from one of my other projects, is often much faster than asking AI to write it. The quality is usually higher as well, and it requires less fixing.

Idea: I suppose, you could copypaste code from another project or point AI to a GitHub repository and ask it to adapt the code.

It’s frustrating to use AI to run code, execute tests, or handle basic project tasks. It’s cumbersome and much less efficient than using IDE shortcuts and tools such as npm scripts (either running them directly from terminal or using IDE). It could have been a good tool to discover the right commands in a particular project, but AI isn’t reliable for that – it changes its mind all the time: one day it runs a dev server using an existing npm script, the next day it tries to run it manually; and generally it ignores commands in the docs.

Overall, I treat AI code assistant as a junior developer on amphetamines: it can write lots of code very fast but often ignore direct instructions, is overconfident, erratic, and stubborn. It knows plenty of random facts but often can’t connect them and lacks common sense.

I’m starting to use AI agents as assistants rather than autonomous coders. I now ask the agent to outline a solution before writing any code. This makes it easier to spot issues in logic, which would be more time-consuming to catch while reviewing the code. This approach is often called spec-driven development.

Tip: I’m experimenting with a simplified spec-driven approach inspired by Kiro, where I use two custom agent modes: one to design the feature and give me an implementation outline for approval, and the other to write the code for it.

Another area I’ve started exploring is AI-powered code reviews in the editor, before opening a pull request. It can be a good first check to avoid wasting colleagues’ time on obvious issues, such as a stray debug console.log() left in the code.

It’s often faster to use AI chat for one-off operations, such as converting JSON to YAML, or formatting JSON, than to google an online service.

It’s true that AI sometimes lets us ship code very quickly. However, understanding and debugging skills are becoming even more important than before, especially for projects with a large amount of AI-written code and little or no supervision by senior engineers. AI is great at analyzing thousands of lines of code at superhuman speed, but sometimes it’s not smart enough to pinpoint the issue. Someone still has to make sense of and fix all the AI slop.

Often, AI cannot identify the root cause of an issue and falls into a loop of “Now I can see the issue!” and making random changes until it gets tired. It may even replace correct tests to generic ones that don’t really test anything but still pass with broken code.

Story time: Once, I thought I had a bug, and AI was happy to “fix” it by throwing a spaghetti net of duplicate code on top of the existing code, instead of telling me that the code was correct.

For small changes, such as writing a helper function, remembering tricky syntax, or adding types, I like inline chat in GitHub Copilot. It limits edits to the exact spot under the cursor, so you don’t have to explain where you want the changes. I immediately disable AI autocomplete, as I find it incredibly distracting.

AI can unblock you when you’re stuck or too tired to figure out how to start a new task. It can also help you brainstorm ideas or rubberduck a problem with you.

Naming is another thing AI shines at, especially for us, non-native English speakers. Usually, variable and function names are clear enough and don’t need adjustments. I often get stuck trying to come up with a short, clear name when writing code myself.

However, AI is horrible at writing commit messages: they’re too long and generic with things like “Refactor X to make it better” or a long list of low-level code changes that don’t explain why the changes were made.

Overall, AI can speed up my work in many cases, though often making it less fun. I feel like I’m spending less time doing what I actually like: writing code and solving problems, and more time on what I try to avoid: interacting with someone, worse when this someone is a machine. Especially if that machine is a mechanical parrot with an infinite power bank.

I hope the hype will calm down a bit and that AI providers will start talking to each other to minimize the configuration mess they’ve created. Each tool expects its own onboarding docs, and if you switch between several tools on the same project (or your colleagues use different tools), you end up with a bunch of similar files, such as .cursor/rules/something.md or .github/instructions/something.instructions.md.

Writing good prompts is an important skill, but it requires a lot of upfront planning – something I was never good at. My approach to most things in life (programming, photography, climbing, and so on) is somewhere between reactive and YOLO.

The shift from coders to project managers (or, in many cases, prompt masters) is real. We can already outsource the boring details of typing code to AI. But then the question is: how do we get good enough at writing code to be able to review it without actually writing much? Or even without seeing much of it – because when you vibe code, you forget the code even exists.

AI may change the way we treat dependencies: it often seems more efficient to ask AI to write your own version of some generic function than to search for a decent dependency on npm and having to update it forever. However, I still think we should stick to established, well-tested libraries for tricky code that requires specialized knowledge, involves obscure edge cases, or is platform-specific.

Today AI is very good at writing low-level, generic code, especially at answering Stack-Overflow-like questions, because it has been trained on millions of web pages and source code files written by humans. What will happen in 5-10 years, when the majority of the internet is written by AI itself?

What I want an AI assistant to be is like Poe in Altered Carbon. A tool that can actually solve problems on its own and can anticipate my needs. And, very importantly, doesn’t say “you’re absolutely right” when I’m absolutely not. Ideally, one that read my book and knows how I like to write code.

Tip: I’ve been experimenting with the latter a bit via Cursor User Rules, but it doesn’t seem to make a lot of difference.

Subscribe to my newsletter if you enjoyed this article.

Washing your code: don’t make me think

Artem Sapegin — Sun, 01 Dec 2024 11:58:06 +0000

You’re reading an excerpt from my book on clean code, “Washing your code.” Available as PDF, EPUB, and as a paperback and Kindle edition. Get your copy now.

Clever code is something we may see in job interview questions or language quizzes, when they expect us to know how a language feature, which we probably have never seen before, works. My answer to all these questions is: “it won’t pass code review”.

Some folks confuse brevity with clarity. Short code (brevity) isn’t always the clearest code (clarity), often it’s the opposite. Striving to make your code shorter is a noble goal, but it should never come at the expense of readability.

There are many ways to express the same idea in code, and some are easier to understand than others. We should always aim to reduce the cognitive load of the next developer who reads our code. Every time we stumble on something that isn’t immediately obvious, we waste our brain’s resources.

Info: I “stole” the name of this chapter from Steve Krug’s book on web usability with the same name.

Dark patterns of JavaScript

Let’s look at some examples. Try to cover the answers and guess what these code snippets do. Then, count how many you guessed correctly.

Example 1:

const percent = 5;
const percentString = percent.toString().concat('%');

This code only adds the % sign to a number and should be rewritten as:

const percent = 5;
const percentString = `${percent}%`;
// → '5%'

Example 2:

const url = 'index.html?id=5';
if (~url.indexOf('id')) {
  // Something fishy here…
}

The ~ symbol is called the bitwise NOT operator. Its useful effect here is that it returns a falsy value only when indexOf() returns -1. This code should be rewritten as:

const url = 'index.html?id=5';
if (url.includes('id')) {
  // Something fishy here…
}

Example 3:

const value = ~~3.14;

Another obscure use of the bitwise NOT operator is to discard the fractional portion of a number. Use Math.trunc() instead:

const value = Math.trunc(3.14);
// → 3

Example 4:

if (dogs.length + cats.length > 0) {
  // Something fishy here…
}

This one is understandable after a moment: it checks if either of the two arrays has any elements. However, it’s better to make it clearer:

if (dogs.length > 0 || cats.length > 0) {
  // Something fishy here…
}

Example 5:

const header = 'filename="pizza.rar"';
const filename = header.split('filename=')[1].slice(1, -1);

This one took me a while to understand. Imagine we have a portion of a URL, such as filename="pizza". First, we split the string by = and take the second part, "pizza". Then, we slice the first and the last characters to get pizza.

I’d likely use a regular expression here:

const header = 'filename="pizza.rar"';
const filename = header.match(/filename="(.*?)"/)[1];
// → 'pizza'

Or, even better, the URLSearchParams API:

const header = 'filename="pizza.rar"';
const filename = new URLSearchParams(header)
  .get('filename')
  .replaceAll(/^"|"$/g, '');
// → 'pizza'

These quotes are weird, though. Normally we don’t need quotes around URL parameters, so talking to the backend developer could be a good idea.

Example 6:

const condition = true;
const object = {
  ...(condition && { value: 42 })
};

In the code above, we add a property to an object when the condition is true, otherwise we do nothing. The intention is more obvious when we explicitly define objects to destructure rather than relying on destructuring of falsy values:

const condition = true;
const object = {
  ...(condition ? { value: 42 } : {})
};
// → { value: 42 }

I usually prefer when objects don’t change shape, so I’d move the condition inside the value field:

const condition = true;
const object = {
  value: condition ? 42 : undefined
};
// → { value: 42 }

Example 7:

const array = [...Array(10).keys()];

This wonderful one-liner creates an array filled with numbers from 0 to 9. Array(10) creates an array with 10 empty elements, then the keys() method returns the keys (numbers from 0 to 9) as an iterator, which we then convert into a plain array using the spread syntax. Exploding head emoji…

We can rewrite it using a for loop:

const array = [];
for (let i = 0; i < 10; i++) {
  array.push(i);
}
// → [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

As much as I like to avoid loops in my code, the loop version is more readable for me.

Somewhere in the middle would be using the Array.from() method:

const array = Array.from({ length: 10 }).map((_, i) => i);
// → [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

The Array.from({length: 10}) creates an array with 10 undefined elements, then using the map() method, we fill the array with numbers from 0 to 9.

We can write it shorter by using Array.from()’s map callback:

const array = Array.from({ length: 10 }, (_, i) => i);
// → [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

Explicit map() is slightly more readable, and we don’t need to remember what the second argument of Array.from() does. Additionally, Array.from({length: 10}) is slightly more readable than Array(10). Though only slightly.

So, what’s your score? I think mine would be around 3/7.

Gray areas

Some patterns tread the line between cleverness and readability.

For example, using Boolean to filter out falsy array elements (null and 0 in this example):

const words = ['Not', null, 'enough', 0, 'cheese'].filter(Boolean);
// → ['Not', 'enough', 'cheese']

I find this pattern acceptable; though it requires learning, it’s better than the alternative:

const words = ['Not', null, 'enough', 0, 'cheese'].filter(
  item => !!item
);
// → ['Not', 'enough', 'cheese']

However, keep in mind that both variations filter out falsy values, so if zeros or empty strings are important, we need to explicitly filter for undefined or null:

const words = ['Not', null, 'enough', 0, 'cheese'].filter(
  item => item != null
);
// → ['Not', 'enough', 0, 'cheese']

Make differences in code obvious

When I see two lines of tricky code that appear identical, I assume they differ in some way, but I don’t see the difference yet. Otherwise, a programmer would likely create a variable or a function for the repeated code instead of copypasting it.

For example, we have a code that generates test IDs for two different tools we use on a project, Enzyme and Codeception:

const props = {
  'data-enzyme-id': columnName
    ? `${type}-${toTitleCase(columnName)}-${rowIndex}`
    : null,
  'data-codeception-id': columnName
    ? `${type}-${toTitleCase(columnName)}-${rowIndex}`
    : null
};
// → {
//     'data-enzyme-id': 'type-Col-2',
//     'data-codeception-id': 'type-Col-2'
// }

It’s difficult to immediately spot any differences between these two lines of code. Remember those pairs of pictures where you had to find ten differences? That’s what this code does to the reader.

While I’m generally skeptical about extreme code DRYing, this is a good case for it.

Info: We talk more about the Don’t repeat yourself principle in the Divide and conquer, or merge and relax chapter.

const testId = columnName
  ? `${type}-${toTitleCase(columnName)}-${rowIndex}`
  : null;
const props = {
  'data-enzyme-id': testId,
  'data-codeception-id': testId
};
// → {
//     'data-enzyme-id': 'type-Col-2',
//     'data-codeception-id': 'type-Col-2'
// }

Now, there’s no doubt that the code for both test IDs is exactly the same.

Let’s look at a trickier example. Suppose we use different naming conventions for each testing tool:

const props = {
  'data-enzyme-id': columnName
    ? `${type}-${toTitleCase(columnName)}-${rowIndex}`
    : null,
  'data-codeception-id': columnName
    ? `${type}_${toTitleCase(columnName)}_${rowIndex}`
    : null
};
// → {
//     'data-enzyme-id': 'type-Col-2',
//     'data-codeception-id': 'type_Col_2'
// }

The difference between these two lines of code is hard to notice, and we can never be sure that the name separator (- or _) is the only difference here.

In a project with such a requirement, this pattern will likely appear in many places. One way to improve it is to create functions that generate test IDs for each tool:

const joinEnzymeId = (...parts) => parts.join('-');
const joinCodeceptionId = (...parts) => parts.join('_');
const props = {
  'data-enzyme-id': columnName
    ? joinEnzymeId(type, toTitleCase(columnName), rowIndex)
    : null,
  'data-codeception-id': columnName
    ? joinCodeceptionId(type, toTitleCase(columnName), rowIndex)
    : null
};

This is already much better, but it’s not perfect yet — the repeated code is still too large. Let’s fix this too:

const joinEnzymeId = (...parts) => parts.join('-');
const joinCodeceptionId = (...parts) => parts.join('_');
const getTestIdProps = (...parts) => ({
  'data-enzyme-id': joinEnzymeId(...parts),
  'data-codeception-id': joinCodeceptionId(...parts)
});
const props = columnName
  ? getTestIdProps(type, toTitleCase(columnName), rowIndex)
  : {};

This is an extreme case of using small functions, and I generally try to avoid splitting code this much. However, in this case, it works well, especially if there are already many places in the project where we can use the new getTestIdProps() function.

Sometimes, code that looks nearly identical has subtle differences:

function handleSomething(documentId) {
  if (documentId) {
    dispatch(changeIsWordDocumentExportSuccessful(true));
    return;
  }
  dispatch(changeIsWordDocumentExportSuccessful(false));
}

The only difference here is the parameter we pass to the function with a very long name. We can move the condition inside the function call:

function handleSomething(documentId) {
  dispatch(
    changeIsWordDocumentExportSuccessful(documentId !== undefined)
  );
}

This eliminates the similar code, making the entire snippet shorter and easier to understand.

Whenever we encounter a condition that makes code slightly different, we should ask ourselves: is this condition truly necessary? If the answer is “yes”, we should ask ourselves again. Often, there’s no real need for a particular condition. For example, why do we even need to add test IDs for different tools separately? Can’t we configure one of the tools to use test IDs of the other? If we dig deep enough, we might find that no one knows the answer, or that the original reason is no longer relevant.

Consider this example:

function getAssetDirs(config) {
  return config.assetsDir
    ? Array.isArray(config.assetsDir)
      ? config.assetsDir.map(dir => ({ from: dir }))
      : [{ from: config.assetsDir }]
    : [];
}

This code handles two edge cases: when assetsDir doesn’t exist, and when assetsDir isn’t an array. Also, the object generation code is duplicated. (And let’s not talk about nested ternaries…) We can get rid of the duplication and at least one condition:

function getAssetDirs(config) {
  const assetDirectories = config.assetsDir
    ? _.castArray(config.assetsDir)
    : [];
  return assetDirectories.map(from => ({
    from
  }));
}

I don’t like that Lodash’s castArray() method wraps undefined in an array, which isn’t what I’d expect, but still, the result is simpler.

Avoid shortcuts

CSS has shorthand properties, and developers often overuse them. The idea is that a single property can define multiple properties at the same time. Here’s a good example:

.block {
  margin: 1rem;
}

Which is the same as:

.block {
  margin-top: 1rem;
  margin-right: 1rem;
  margin-bottom: 1rem;
  margin-left: 1rem;
}

One line of code instead of four, and it’s still clear what’s happening: we set the same margin on all four sides of an element.

Now, look at this example:

.block-1 {
  margin: 1rem 2rem 3rem 4rem;
}
.block-3 {
  margin: 1rem 2rem 3rem;
}
.block-2 {
  margin: 1rem 2rem;
}

To understand what they do, we need to know that:

when the margin property has four values, the order is top, right, bottom, left;
when it has three values, the order is top, left/right, bottom;
and when it has two values, the order is top/bottom, left/right.

This creates an unnecessary cognitive load, and makes code harder to read, edit, and review. I avoid such shorthands.

Another issue with shorthand properties is that they can set values for properties we didn’t intend to change. Consider this example:

.block {
  font: italic bold 2rem Helvetica;
}

This declaration sets the Helvetica font family, the font size of 2rem, and makes the text italic and bold. What we don’t see here is that it also changes the line height to the default value of normal.

My rule of thumb is to use shorthand properties only when setting a single value; otherwise, I prefer longhand properties.

Here are some good examples:

.block {
  /* Set margin on all four sides */
  margin: 1rem;

  /* Set top/bottom and left/right margins */
  margin-block: 1rem;
  margin-inline: 2rem;

  /* Set border radius to all four corners */
  border-radius: 0.5rem;

  /* Set border-width, border-style and border-color
   * This is a bit of an outlier but it’s very common and
   * it’s hard to misinterpret it because all values have
   * different types */
  border: 1px solid #c0ffee;

  /* Set top, right, bottom, and left position */
  inset: 0;
}

And here are some examples to avoid:

.block {
  /* Set top/bottom and left/right margin */
  margin: 1rem 2rem;

  /* Set border radius to top-left/bottom-right,
   * and top-right/bottom-left corners */
  border-radius: 1em 2em;
  /* Set border radius to top-left, top-right/bottom-left,
   * and bottom-right corners */
  border-radius: 1em 2em 3em;
  /* Set border radius to top-left, top-right, bottom-right,
   * and bottom-left corners */
  border-radius: 1em 2em 3em 4em;

  /* Set background-color, background-image, background-repeat,
   * and background-position */
  background: #bada55 url(images/tacocat.gif) no-repeat left top;

  /* Set top, right, bottom, and left */
  inset: 0 20px 0 20px;
}

While shorthand properties indeed make the code shorter, they often make it significantly harder to read, so use them with caution.

Write parallel code

Eliminating conditions isn’t always possible. However, there are ways to make differences in code branches easier to spot. One of my favorite approaches is what I call parallel coding.

Consider this example:

function RecipeName({ name, subrecipe }) {
  if (subrecipe) {
    return <Link href={`/recipes/${subrecipe.slug}`}>{name}</Link>;
  }
  return name;
}

It might be a personal pet peeve, but I dislike when the return statements are on different levels, making them harder to compare. Let’s add an else statement to fix this:

function RecipeName({ name, subrecipe }) {
  if (subrecipe) {
    return <Link href={`/recipes/${subrecipe.slug}`}>{name}</Link>;
  } else {
    return name;
  }
}

Now, both return values are at the same indentation level, making them easier to compare. This pattern works when none of the condition branches are handling errors, in which case an early return would be a better approach.

Info: We talk about early returns in the Avoid conditions chapter.

Here’s another example:

<Button
  onPress={Platform.OS !== 'web' ? onOpenViewConfirmation : undefined}
  link={Platform.OS === 'web' ? previewLink : undefined}
  target="_empty"
>
  Continue
</Button>

In this example, we have a button that behaves like a link in the browser and shows a confirmation modal in an app. The reversed condition for the onPress prop makes this logic hard to see.

Let’s make both conditions positive:

<Button
  onPress={Platform.OS === 'web' ? undefined : onOpenViewConfirmation}
  link={Platform.OS === 'web' ? previewLink : undefined}
  target="_empty"
>
  Continue
</Button>

Now, it’s clear that we either set onPress or link props depending on the platform.

We can stop here or take it a step further, depending on the number of Platform.OS === 'web' conditions in the component or how many props we need to set conditionally

We can extract the conditional props into a separate variable:

const buttonProps =
  Platform.OS === 'web'
    ? {
        link: previewLink,
        target: '_empty'
      }
    : {
        onPress: onOpenViewConfirmation
      };

Then, use it instead of hardcoding the entire condition every time:

<Button {...buttonProps}>Continue</Button>

I also moved the target prop to the web branch because it’s not used by the app anyway.

When I was in my twenties, remembering things wasn’t much of a problem for me. I could recall books I’d read and all the functions in a project I was working on. Now that I’m in my forties, that’s no longer the case. I now value simple code that doesn’t use any tricks; I value search engines, quick access to the documentation, and tooling that help me to reason about the code and navigate the project without keeping everything in my head.

We shouldn’t write code for our present selves but for who we’ll be a few years from now. Thinking is hard, and programming demands a lot of it, even without having to decipher tricky or unclear code.

Start thinking about:

When you feel smart and write some short, clever code, think if there’s a simpler, more readable way to write it.
Whether a condition that makes code slightly different is truly necessary.
Whether a shortcut makes the code shorter but still readable, or just shorter.

If you have any feedback, mastodon me, tweet me, open an issue on GitHub, or email me at artem@sapegin.ru. Get your copy.

Washing your code: divide and conquer, or merge and relax

Artem Sapegin — Thu, 07 Nov 2024 08:35:10 +0000

You’re reading an excerpt from my book on clean code, “Washing your code.” Available as PDF, EPUB, and as a paperback and Kindle edition. Get your copy now.

Knowing how to organize code into modules or functions, and when the right time is to introduce an abstraction instead of duplicating code, is an important skill. Writing generic code that others can effectively use is yet another skill. There are just as many reasons to split the code as there are to keep it together. In this chapter, we’ll discuss some of these reasons.

Let abstractions grow

We, developers, hate to do the same work twice. DRY is a mantra for many. However, when we have two or three pieces of code that kind of do the same thing, it may be still too early to introduce an abstraction, no matter how tempting it may feel.

Info: The Don’t repeat yourself (DRY) principle demands that “every piece of knowledge must have a single, unambiguous, authoritative representation within a system”, which is often interpreted as any code duplication is strictly verboten.

Live with the pain of code duplication for a while; maybe it’s not so bad in the end, and the code is actually not exactly the same. Some level of code duplication is healthy and allows us to iterate and evolve code faster without the fear of breaking something.

It’s also hard to come up with a good API when we only consider a couple of use cases.

Managing shared code in large projects with many developers and teams is difficult. New requirements for one team may not work for another Team and break their code, or we end up with an unmaintainable spaghetti monster with dozens of conditions.

Imagine Team A is adding a comment form to their page: a name, a message, and a submit button. Then, Team B needs a feedback form, so they find Team A’s component and try to reuse it. Then, Team A also wants an email field, but they don’t know that Team B uses their component, so they add a required email field and break the feature for Team B users. Then, Team B needs a phone number field, but they know that Team A is using the component without it, so they add an option to show a phone number field. A year later, the two teams hate each other for breaking each other’s code, and the component is full of conditions and is impossible to maintain. Both teams would save a lot of time and have healthier relationships with each other if they maintained separate components composed of lower-level shared components, like an input field or a button.

Tip: It might be a good idea to forbid other teams from using our code unless it’s designed and marked as shared. The Dependency cruiser is a tool that could help set up such rules.

Sometimes, we have to roll back an abstraction. When we start adding conditions and options, we should ask ourselves: is it still a variation of the same thing or a new thing that should be separated? Adding too many conditions and parameters to a module can make the API hard to use and the code hard to maintain and test.

Duplication is cheaper and healthier than the wrong abstraction.

Info: See Sandi Metz’s article The Wrong Abstraction for a great explanation.

The higher the level of the code, the longer we should wait before we abstract it. Low-level utility abstractions are much more obvious and stable than business logic.

Size doesn’t always matter

Code reuse isn’t the only, or even most important, reason to extract a piece of code into a separate function or module.

Code length is often used as a metric for when we should split a module or a function, but size alone doesn’t make code hard to read or maintain.

Splitting a linear algorithm, even a long one, into several functions and then calling them one after another rarely makes the code more readable. Jumping between functions (and even more so — files) is harder than scrolling, and if we have to look into each function’s implementation to understand the code, then the abstraction wasn’t the right one.

Info: Egon Elbre wrote a nice article on psychology of code readability.

Here’s an example, adapted from the Google Testing Blog:

function createPizza(order) {
  const pizza = new Pizza({
    base: order.size,
    sauce: order.sauce,
    cheese: 'Mozzarella'
  });

  if (order.kind === 'Veg') {
    pizza.toppings = vegToppings;
  } else if (order.kind === 'Meat') {
    pizza.toppings = meatToppings;
  }

  const oven = new Oven();

  if (oven.temp !== cookingTemp) {
    while (oven.temp < cookingTemp) {
      time.sleep(checkOvenInterval);
      oven.temp = getOvenTemp(oven);
    }
  }

  if (!pizza.baked) {
    oven.insert(pizza);
    time.sleep(cookTime);
    oven.remove(pizza);
    pizza.baked = true;
  }

  const box = new Box();
  pizza.boxed = box.putIn(pizza);
  pizza.sliced = box.slicePizza(order.size);
  pizza.ready = box.close();

  return pizza;
}

I have so many questions about the API of the Pizza class, but let’s see what improvements the authors suggest:

function prepare(order) {
  const pizza = new Pizza({
    base: order.size,
    sauce: order.sauce,
    cheese: 'Mozzarella'
  });
  addToppings(pizza, order.kind);
  return pizza;
}

function addToppings(pizza, kind) {
  if (kind === 'Veg') {
    pizza.toppings = vegToppings;
  } else if (kind === 'Meat') {
    pizza.toppings = meatToppings;
  }
}

function bake(pizza) {
  const oven = new Oven();
  heatOven(oven);
  bakePizza(pizza, oven);
}

function heatOven(oven) {
  if (oven.temp !== cookingTemp) {
    while (oven.temp < cookingTemp) {
      time.sleep(checkOvenInterval);
      oven.temp = getOvenTemp(oven);
    }
  }
}

function bakePizza(pizza, oven) {
  if (!pizza.baked) {
    oven.insert(pizza);
    time.sleep(cookTime);
    oven.remove(pizza);
    pizza.baked = true;
  }
}

function pack(pizza) {
  const box = new Box();
  pizza.boxed = box.putIn(pizza);
  pizza.sliced = box.slicePizza(pizza.size);
  pizza.ready = box.close();
}

function createPizza(order) {
  const pizza = prepare(order);
  bake(pizza);
  pack(pizza);
  return pizza;
}

What was already complex and convoluted is now even more complex and convoluted, and half of the code is just function calls. This doesn’t make the code any easier to understand, but it does make it almost impossible to work with. The article doesn’t show the complete code of the refactored version, perhaps to make the point more compelling.

Pierre “catwell” Chapuis suggests in his blog post to add comments instead of new functions:

function createPizza(order) {
  // Prepare pizza
  const pizza = new Pizza({
    base: order.size,
    sauce: order.sauce,
    cheese: 'Mozzarella'
  });

  // Add toppings
  if (order.kind == 'Veg') {
    pizza.toppings = vegToppings;
  } else if (order.kind == 'Meat') {
    pizza.toppings = meatToppings;
  }

  const oven = new Oven();

  if (oven.temp !== cookingTemp) {
    // Heat oven
    while (oven.temp < cookingTemp) {
      time.sleep(checkOvenInterval);
      oven.temp = getOvenTemp(oven);
    }
  }

  if (!pizza.baked) {
    // Bake pizza
    oven.insert(pizza);
    time.sleep(cookTime);
    oven.remove(pizza);
    pizza.baked = true;
  }

  // Box and slice
  const box = new Box();
  pizza.boxed = box.putIn(pizza);
  pizza.sliced = box.slicePizza(order.size);
  pizza.ready = box.close();

  return pizza;
}

This is already much better than the split version. An even better solution would be improving the APIs and making the code more clear. Pierre suggests that preheating the oven shouldn’t be part of the createPizza() function (and baking many pizzas myself, I totally agree!) because in real life the oven is already there and probably already hot from the previous pizza. Pierre also suggests that the function should return the box, not the pizza, because in the original code, the box kind of disappears after all the slicing and packaging magic, and we end up with the sliced pizza in our hands.

There are many ways to cook a pizza, just as there are many ways to code a problem. The result may look the same, but some solutions are easier to understand, modify, reuse, and delete than others.

Naming can also be a problem too when all the extracted functions are parts of the same algorithm. We need to invent names that are clearer than the code and shorter than comments — not an easy task.

Info: We talk about commenting code in the Avoid comments chapter, and about naming in the Naming is hard chapter.

You probably won’t find many small functions in my code. In my experience, the most useful reasons to split code are change frequency and change reason.

Separate code that changes often

Let’s start with change frequency. Business logic changes much more often than utility functions. It makes sense to separate often-changing code from code that is very stable.

The comment form we discussed earlier in this chapter is an example of the former; a function that converts camelCase strings to kebab-case is an example of the latter. The comment form is likely to change and diverge over time when new business requirements arise; the case conversion function is unlikely to change at all and it’s safe to reuse in many places.

Imagine that we’re making a nice-looking table to display some data. We may think we’ll never need this table design again, so we decide to keep all the code for the table in a single module.

Next sprint, we get a task to add another column to the table, so we copy the code of an existing column and change a few lines there. Next sprint, we need to add another table with the same design. Next sprint, we need to change the design of the tables…

Our table module has at least three reasons to change, or responsibilities:

new business requirements, like a new table column;
UI or behavior changes, like adding sorting or column resizing;
design changes, like replacing borders with striped row backgrounds.

This makes the module harder to understand and harder to change. Presentational code adds a lot of verbosity, making it harder to understand the business logic. To make a change in any of the responsibilities, we need to read and modify more code. This makes it harder and slower to iterate on either.

Having a generic table as a separate module solves this problem. Now, to add another column to a table, we only need to understand and modify one of the two modules. We don’t need to know anything about the generic table module except its public API. To change the design of all tables, we only need to change the generic table module’s code and likely don’t need to touch individual tables at all.

However, depending on the complexity of the problem, it’s okay, and often better, to start with a monolithic approach and extract an abstraction later.

Even code reuse can be a valid reason to separate code: if we use some component on one page, we’ll likely need it on another page soon.

Keep together code that changes at the same time

It might be tempting to extract every function into its own module. However, it has downsides too:

Other developers may think that they can reuse the function somewhere else, but in reality, this function is likely not generic or tested enough to be reused.
Creating, importing, and switching between multiple files creates unnecessary overhead when the function is only used in one place.
Such functions often stay in the codebase long after the code that used them is gone.

I prefer to keep small functions that are used only in one module at the beginning of the module. This way, we don’t need to import them to use in the same module, but reusing them somewhere else would be awkward.

function FormattedAddress({ address, city, country, district, zip }) {
  return [address, zip, district, city, country]
    .filter(Boolean)
    .join(', ');
}

function getMapLink({ name, address, city, country, zip }) {
  return `https://www.google.com/maps/?q=${encodeURIComponent(
    [name, address, zip, city, country].filter(Boolean).join(', ')
  )}`;
}

function ShopsPage({ url, title, shops }) {
  return (
    <PageWithTitle url={url} title={title}>
      <Stack as="ul" gap="l">
        {shops.map(shop => (
          <Stack key={shop.name} as="li" gap="m">
            <Heading level={2}>
              <Link href={shop.url}>{shop.name}</Link>
            </Heading>
            {shop.address && (
              <Text variant="small">
                <Link href={getMapLink(shop)}>
                  <FormattedAddress {...shop} />
                </Link>
              </Text>
            )}
          </Stack>
        ))}
      </Stack>
    </PageWithTitle>
  );
}

In the code above, we have a component (FormattedAddress) and a function (getMapLink()) that are only used in this module, so they’re defined at the top of the file.

If we need to test these functions (and we should!), we can export them from the module and test them together with the main function of the module.

The same applies to functions that are intended to be used only together with a certain function or component. Keeping them in the same module makes it clearer that all functions belong together and makes these functions more discoverable.

Another benefit is that when we delete a module, we automatically delete its dependencies. Code in shared modules often stays in the codebase forever because it’s hard to know if it’s still used (though TypeScript makes this easier).

Info: Such modules are sometimes called deep modules: a relatively large modules that encapsulate complex problems but has a simple APIs. The opposite of deep modules are shallow modules: many small modules that need to interact with each other.

If we often have to change several modules or functions at the same time, it might be better to merge them into a single module or function. This approach is sometimes called colocation.

Here are a couple of examples of colocation:

React components: keeping everything a component needs in the same file, including markup (JSX), styles (CSS in JS), and logic, rather than separating each into its own file, likely in a separate folder.
Tests: keeping tests next to the module file rather than in a separate folder.
Ducks convention for Redux: keep related actions, action creators, and reducers in the same file rather than having them in three files in separate folders.

Here’s how the file tree changes with colocation:

Separated	Colocated
React components
`src/components/Button.tsx`	`src/components/Button.tsx`
`styles/Button.css`
Tests
`src/util/formatDate.ts`	`src/util/formatDate.ts`
`tests/formatDate.ts`	`src/util/formatDate.test.ts`
Ducks
`src/actions/feature.js`	`src/ducks/feature.js`
`src/actionCreators/feature.js`
`src/reducers/feature.js`

Info: To learn more about colocation, read Kent C. Dodds’s article.

A common complaint about colocation is that it makes components too large. In such cases, it’s better to extract some parts into their own components, along with the markup, styles, and logic.

The idea of colocation also conflicts with separation of concerns — an outdated idea that led web developers to keep HTML, CSS, and JavaScript in separate files (and often in separate parts of the file tree) for too long, forcing us edit three files at the same time to make even the most basic changes to web pages.

Info: The change reason is also known as the single responsibility principle, which states that “every module, class, or function should have responsibility over a single part of the functionality provided by the software, and that responsibility should be entirely encapsulated by the class.”

Sweep that ugly code under the rug

Sometimes, we have to work with an API that’s especially difficult to use or prone to errors. For example, it requires several steps in a specific order or calling a function with multiple parameters that are always the same. This is a good reason to create a utility function to make sure we always do it right. As a bonus, we can now write tests for this piece of code.

String manipulations — such as URLs, filenames, case conversion, or formatting — are good candidates for abstraction. Most likely, there’s already a library for what we’re trying to do.

Consider this example:

const file = 'pizza.jpg';
const prefix = file.slice(0, -4);
// → 'pizza'

It takes some time to realize that this code removes the file extension and returns the base name. Not only is it unnecessary and hard to read, but it also assumes the extension is always three characters, which might not be the case.

Let’s rewrite it using a library, the built-in Node.js’ path module:

const file = 'pizza.jpg';
const prefix = path.parse(file).name;
// → 'pizza'

Now, it’s clear what’s happening, there are no magic numbers, and it works with file extensions of any length.

Other candidates for abstraction include dates, device capabilities, forms, data validation, internationalization, and more. I recommend looking for an existing library before writing a new utility function. We often underestimate the complexity of seemingly simple functions.

Here are a few examples of such libraries:

Lodash: utility functions of all kinds.
Date-fns: functions to work with dates, such as parsing, manipulation, and formatting.
Zod: schema validation for TypeScript.

Bless the inline refactoring!

Sometimes, we get carried away and create abstractions that neither simplify the code nor make it shorter:

// my_feature_util.js
const noop = () => {};

export const Utility = {
  noop
  // Many more functions…
};

// MyComponent.js
function MyComponent({ onClick }) {
  return <button onClick={onClick}>Hola!</button>;
}

MyComponent.defaultProps = {
  onClick: Utility.noop
};

Another example:

const findByReference = (wrapper, reference) =>
  wrapper.find(reference);

const favoriteTaco = findByReference(
  ['Al pastor', 'Cochinita pibil', 'Barbacoa'],
  x => x === 'Cochinita pibil'
);

// → 'Cochinita pibil'

The best thing we can do in such cases is to apply the almighty inline refactoring: replace each function call with its body. No abstraction, no problem.

The first example becomes:

function MyComponent({ onClick }) {
  return <button onClick={onClick}>Hola!</button>;
}

MyComponent.defaultProps = {
  onClick: () => {}
};

And the second example becomes:

const favoriteTaco = [
  'Al pastor',
  'Cochinita pibil',
  'Barbacoa'
].find(x => x === 'Cochinita pibil');

// → 'Cochinita pibil'

The result is not just shorter and more readable; now readers don’t need to guess what these functions do, as we now use JavaScript native functions and features without home-baked abstractions.

In many cases, a bit of repetition is good. Consider this example:

const baseSpacing = 8;
const spacing = {
  tiny: baseSpacing / 2,
  small: baseSpacing,
  medium: baseSpacing * 2,
  large: baseSpacing * 3,
  xlarge: baseSpacing * 4,
  xxlarge: baseSpacing * 5
};

It looks perfectly fine and won’t raise any questions during code review. However, when we try to use these values, autocompletion only shows number instead of the actual values (see an illustration). This makes it harder to choose the right value.

We could inline the baseSpacing constant:

const spacing = {
  tiny: 4,
  small: 8,
  medium: 16,
  large: 24,
  xlarge: 32,
  xxlarge: 40
};

Now, we have less code, it’s just as easy to understand, and autocompletion shows the actual values (see the illustration). And I don’t think this code will change often — probably never.

Separate “what” and “how”

Consider this excerpt from a form validation function:

function validate(values) {
  const errors = {};

  if (!values.name || (values.name && values.name.trim() === '')) {
    errors.name = 'Name is required';
  }

  if (!values.login || (values.login && values.login.trim() === '')) {
    errors.login = 'Login is required';
  }

  if (values.login && values.login.indexOf(' ') > 0) {
    errors.login = 'No spaces are allowed in login';
  }

  // This goes on and on for a dozen of other fields…

  return errors;
}

It’s quite difficult to grasp what’s going on here: validation logic is mixed with error messages, many checks are repeated…

We can split this function into several pieces, each responsible for one thing only:

a list of validations for a particular form;
a collection of validation functions, such as isEmail();
a function that validates all form values using a list of validations.

We can describe the validations declaratively as an array:

const validations = [
  {
    field: 'name',
    validation: hasStringValue,
    message: 'Name is required'
  },
  {
    field: 'login',
    validation: hasStringValue,
    message: 'Login is required'
  },
  {
    field: 'login',
    validation: hasNoSpaces,
    message: 'No spaces are allowed in login'
  }
  // All other validations…
];

Each validation function and the function that runs validations are pretty generic, so we can either abstract them or use a third-party library.

Now, we can add validation for any form by describing which fields need which validations and which error to show when a certain check fails.

Info: See the Avoid conditions chapter for the complete code and a more detailed explanation of this example.

I call this process separation of “what” and “how”:

the “what” is the data — the list of validations for a particular form;
the “how” is the algorithms — the validation functions and the validation runner function.

The benefits are:

Readability: often, we can define the “what” declaratively, using basic data structures such as arrays and objects.
Maintainability: we change the “what” more often than the “how”, and now they are separated. We can import the “what” from a file, such as JSON, or load it from a database, making updates possible without code changes, or allowing non-developers to do them.
Reusability: often, the “how” is generic, and we can reuse it, or even import it from a third-party library.
Testability: each validation and the validation runner function are isolated, and we can test them separately.

Avoid monster utility files

Many projects have a file called utils.js, helpers.js, or misc.js where developers throw in utility functions when they can’t find a better place for them. Often, these functions are never reused anywhere else and stay in the utility file forever, so it keeps growing. That’s how monster utility files are born.

Monster utility files have several issues:

Poor discoverability: since all functions are in the same file, we can’t use the fuzzy file opener in our code editor to find them.
They may outlive their callers: often such functions are never reused again and stay in the codebase, even after the code that was using them is removed.
Not generic enough: such functions are often made for a single use case and won’t cover other use cases.

These are my rules of thumb:

If the function is small and used only once, keep it in the same module where it’s used.
If the function is long or used more than once, put it in a separate file inside util, shared, or helpers folder.
If we want more organization, instead of creating files like utils/validators.js, we can group related functions (each in its own file) into a folder: utils/validators/isEmail.js.

Avoid default exports

JavaScript modules have two types of exports. The first is named exports:

// button.js
export function Button() {
  /* … */
}

Which can be imported like this:

import { Button } from './button';

And the second is default exports:

// button.js
export default function Button() {
  /* … */
}

Which can be imported like this:

import Button from './button';

I don’t really see any advantages to default exports, but they have several issues:

Poor refactoring: renaming a module with a default export often leaves existing imports unchanged. This doesn’t happen with named exports, where all imports are updated after renaming a function.
Inconsistency: default-exported modules can be imported using any name, which reduces the consistency and greppability of the codebase. Named exports can also be imported using a different name using the as keyword to avoid naming conflicts, but it’s more explicit and is rarely done by accident.

Info: We talk more about greppability in the Write greppable code section of the Other techniques chapter.

Unfortunately, some third-party APIs, such as React.lazy() require default exports, but for all other cases, I stick to named exports.

Avoid barrel files

A barrel file is a module (usually named index.js or index.ts) that reexports a bunch of other modules:

// components/index.js
export { Box } from './Box';
export { Button } from './Button';
export { Link } from './Link';

The main advantage is cleaner imports. Instead of importing each module individually:

import { Box } from '../components/Box';
import { Button } from '../components/Button';
import { Link } from '../components/Link';

We can import all components from a barrel file:

import { Box, Button, Link } from '../components';

However, barrel files have several issues:

Maintenance cost: we need to add an export of each new component in a barrel file, along with additional items such as types of utility functions.
Performance cost: setting up tree shaking is complex, and barrel files often lead to increased bundle size or runtime costs. This can also slow down hot reload, unit tests, and linters.
Circular imports: importing from a barrel file can cause a circular import when both modules are imported from the same barrel files (for example, the Button component imports the Box component).
Developer experience: navigation to function definition navigates to the barrel file instead of the function’s source code; and autoimport can be confused whether to import from a barrel file instead of a source file.

Info: TkDodo explains the drawbacks of barrel files in great detail.

The benefits of barrel files are too minor to justify their use, so I recommend avoiding them.

One type of barrel files I especially dislike is those that export a single component just to allow importing it as ./components/button instead of ./components/button/button.

Stay hydrated

To troll the DRYers (developers who never repeat their code), someone coined another term: WET, write everything twice, or we enjoy typing, suggesting we should duplicate code at least twice until we replace it with an abstraction. It is a joke, and I don’t fully agree with the idea (sometimes it’s okay to duplicate some code more than twice), but it’s a good reminder that all good things are best in moderation.

Consider this example:

const stories = {
  YOUR_RECIPES: 'page--your-recipes',
  ALL_RECIPES: 'page--all-recipes',
  CUISINES: 'page--cuisines',
  RECIPE: 'page--recipe'
};

const testIds = {
  ADD_TO_FAVORITES: 'add-to-favs-button',
  QR_CLOSE: 'qr-close-button',
  QR_CODE: 'qr-code',
  MOBILE_CTA: 'transfer-button'
};

const copyTesters = {
  titleRecipe: /Cochinita Pibil Tacos/,
  titleYourRecipes: /Your favorite recipes on a single page/,
  addedToFavorites: /In favorites/
  // Many more lines…
};

it('your recipes', () => {
  visitStory(stories.RECIPE);

  cy.findByText(copyTesters.titleRecipe).should('exist');

  cy.findByTestId(testIds.ADD_TO_FAVORITES).click();
  cy.findByText(copyTesters.addedToFavorites).should('exist');

  // Lots of lines in similar style…
});

This is an extreme example of code DRYing, which doesn’t make the code more readable or maintainable, especially when most of these constants are used only once. Seeing variable names instead of actual strings here is unhelpful.

Let’s inline all these extra variables. (Unfortunately, inline refactoring in Visual Studio Code doesn’t support inlining object properties, so we have to do it manually.)

it('your recipes', () => {
  visitStory('page--recipe');

  cy.findByText(/Cochinita Pibil Tacos/).should('exist');

  cy.findByTestId('add-to-favs-button').click();
  cy.findByText(/In favorites/).should('exist');

  // Lots of lines in similar style…
});

Now, we have significantly less code, and it’s easier to understand what’s going on and easier to update or delete tests.

I’ve encountered so many hopeless abstractions in tests. For example, this pattern is very common:

let wrapper;
beforeEach(() => {
  wrapper = mount(<Pony color="pink" />);
});

test('pony has pink tail', () => {
  expect(wrapper.find('.tail').prop('value')).toBe('pink');
});

// More tests that use `wrapper`…

This pattern tries to avoid repeating mount(...) calls in each test case, but it makes tests more confusing than they need to be. Let’s inline the mount() calls:

test('pony has pink tail', () => {
  const wrapper = mount(<Pony color="pink" />);
  expect(wrapper.find('.tail').prop('value')).toBe('pink');
});

// More tests that use `wrapper`…

Additionally, the beforeEach pattern works only when we want to initialize each test case with the same values, which is rarely the case:

test('pony has pink tail', () => {
  const wrapper = mount(<Pony color="pink" />);
  expect(wrapper.find('.tail').prop('value')).toBe('pink');
});

test('pony can breath fire', () => {
  const wrapper = mount(<Pony color="pink" breathFire />);
  expect(wrapper.find('.fire')).toBeVisible();
});

To avoid some duplication when testing React components, I often add a defaultProps object and spread it inside each test case:

const defaultProps = { color: 'pink' };

test('pony has pink tail', () => {
  const wrapper = mount(<Pony {...defaultProps} />);
  expect(wrapper.find('.tail').prop('value')).toBe('pink');
});

test('pony can breath fire', () => {
  const wrapper = mount(<Pony {...defaultProps} breathFire />);
  expect(wrapper.find('.fire')).toBeVisible();
});

This way, we don’t have too much duplication, but at the same time, each test case is isolated and readable. The difference between test cases is now clearer because it’s easier to see the unique props of each test case.

Here’s a more extreme variation of the same problem:

let css;
let res;

beforeEach(() => {
  css = '';
  res = '';
});

test('works with basic selectors', () => {
  css = 'div\n{}';
  res = 'div\n';
  expect(getSelector(css)).toBe(res);
});

test('works with lobotomized owl selector', () => {
  css = '.stack > * + *\n{}';
  res = '.stack > * + *\n';
  expect(getSelector(css)).toBe(res);
});

// More tests that use `css` and `res`…

We can inline the beforeEach() function the same way we did in the previous example:

test('works with basic selectors', () => {
  const css = 'div\n{}';
  const expected = 'div\n';
  expect(getSelector(css)).toBe(expected);
});

test('works with lobotomized owl selector', () => {
  const css = '.stack > * + *\n{}';
  const expected = '.stack > * + *\n';
  expect(getSelector(css)).toBe(expected);
});

// More tests that use `css` and `res`…

I’d go even further and use test.each() method because we run the same test with a bunch of different inputs:

test.each([
  ['div\n{}', 'div\n'],
  ['.stack > * + *\n{}', '.stack > * + *\n']
  // More inputs…
])('selector: %s', (css, expected) => {
  expect(getSelector(css)).toBe(expected);
});

Now, we’ve gathered all the test inputs with their expected results in one place, making it easier to add new test cases.

Info: Check out my Jest and Vitest cheat sheets.

The biggest challenge with abstractions is finding a balance between being too rigid and too flexible, and knowing when to start abstracting things and when to stop. It’s often worth waiting to see if we really need to abstract something — many times, it’s better not to.

It’s nice to have a global button component, but if it’s too flexible and has a dozen boolean props to switch between different variations, it will be difficult to use. However, if it’s too rigid, developers will create their own button components instead of using a shared one.

We should be vigilant about letting others reuse our code. Too often, this creates tight coupling between parts of the codebase that should be independent, slowing down development and leading to bugs.

Start thinking about:

Colocating related code in the same file or folder to make it easier to change, move, or delete.
Before adding another option to an abstraction, think whether this new use case truly belongs there.
Before merging several pieces of code that look similar, think whether they actually solve the same problems or just happened to look the same.
Before making tests DRY, think whether it would make them more readable and maintainable, or a bit of code duplication isn’t an issue.

If you have any feedback, mastodon me, tweet me, open an issue on GitHub, or email me at artem@sapegin.ru. Get your copy.

Washing your code. A book on clean code for frontend developers

Artem Sapegin — Tue, 22 Oct 2024 09:39:19 +0000

After five years of writing, I’ve finally finished my book! It took a lot of energy (and coffee!) to complete, but it’s finally done, and I’m really happy with the result. When I started writing this book, I thought it would be a small thing — maybe 100 pages or so. I never expected it to end up being over 400 pages. I also didn’t expect writing a programming book to be such a huge effort. It involved more than just writing but a lot of tooling for text and code linting, custom unit testing, PDF/EPUB generation, and more. I learned a lot during this process and even changed some of my opinions along the way. I hope you’ll like it!

We read code much more often than we write it — often to make a one-line change you have to read and understand hundreds of lines of code scattered among dozens of files. That’s why code readability is so important.

On dozens of examples, based on production code, I’ll show you how to make your code more readable and maintainable, and how to avoid hard-to-track bugs. I’ll show you code smells and antipatterns I often see during code reviews (and I review lots of code every day!) and will walk you through the refactoring process to make your code better.

These techniques and patterns help me every day to write code that my colleagues will have no problems working with. All book’s examples are written in JavaScript with a bit of TypeScript, React, CSS, and HTML.

Get the book with 50% launch discount

Better autosave and autoformat in Visual Studio Code

Artem Sapegin — Mon, 16 Sep 2024 09:26:19 +0000

Subscribe to my newsletter if you enjoyed this article.

This setup assumes that you have the ESLint and Prettier extensions installed in Visual Studio Code.

I like the autosave feature in editors: when you switch to another app — usually a browser — the file is automatically saved, causing the hot reload to apply the changes to the page right before you look at it.

One thing I’ve struggled with for a long time is that autoformatting (using Prettier) on autosave isn’t always desirable. For example, I start typing something, then google how to use a certain API, come back to the editor, and now everything is messed up by autoformatting.

I solved this by disabling autoformatting on save and running autoformat and save on a custom Cmd+S hotkey.

Two other useful things I like to do here:

Disable autosave when there’s a syntax error in the file, so autosave doesn’t break the dev server, which could cause loss of state, such as scroll position or form data.
Hide all autofixable ESLint issues so they don’t distract me while I’m writing code, since these issues don’t require any action from me and will be autofixed the next time I save the file.

The Visual Studio Code config to achieve this could look like this:

// settings.json
{
  // Don’t format files on save
  "editor.formatOnSave": false,
  // Autosave files on focus change
  "files.autoSave": "onFocusChange",
  // Don’t autosave files with syntax errors
  "files.autoSaveWhenNoErrors": true,
  "editor.codeActionsOnSave": {
    // Trigger lint autofixing on explicit save (not on autosave)
    "source.fixAll": "explicit"
  },
  "eslint.rules.customizations": [
    // Change the severity of all autofixable issues to `off`
    { "rule": "*", "fixable": true, "severity": "off" }
  ]
}

And the keybinding config could look like this:

// keybindings.json
[
  {
    "comment": "Format and Save (to make autosave save files without formatting)",
    "key": "cmd+s",
    "command": "runCommands",
    "args": {
      "commands": [
        "editor.action.format",
        "workbench.action.files.save"
      ]
    }
  },
  // Disable the default keybinding
  {
    "key": "cmd+s",
    "command": "-workbench.action.files.save"
  }
]

One downside of this setup is that it’s sometimes unclear why a linter autofixed something, as there’s no log of any kind.

Subscribe to my newsletter if you enjoyed this article.

P.S. Check out my other Visual Studio Code extensions: Emoji Console Log, Just Blame, Mini Markdown, New File Now, Notebox, Todo Tomorrow; and my themes: Squirrelsong Light, Squirrelsong Dark.

Just Blame for VS Code 🪲

Artem Sapegin — Fri, 09 Aug 2024 05:02:56 +0000

When I switched to VS Code from JetBrains editors, I was missing the blame view. I couldn’t find any decent extension, so I made my own:

Here are the main features of the extension:

Very minimal and fast.
Heatmap like in JetBrains editors.
Supports light and dark modes out of the box, and doesn’t come with insanely bright colors by default.
Doesn’t use any resources until you turn on the annotations.
Doesn’t pollute the editor with too many commands and hotkeys.

Try it now in VS Code!

You can also look at the source code on GitHub.

Notebox for VS Code 📝

Artem Sapegin — Mon, 15 Jul 2024 05:31:12 +0000

There are several extensions for writing notes inside VS Code, but all are either too complex, or not working at all. I wanted something simple, a place to write a short reminder for myself, or store a piece of text or code that will be useful later.

The notes are persisted even if you close VS Code or switch to another workspace.

Try it now in VS Code!

You can also look at the source code on GitHub.

Todo Tomorrow for VS Code ✅

Artem Sapegin — Thu, 13 Jun 2024 08:43:48 +0000

I've tried many similar extensions to highlight TODO and FIXME comments, but all were either doing too much or too little, and hard to configure. That's why I created my own.

Here are the main features of the extension:

Very minimal and fast
Useful defaults to cover most use cases
Supports Bash, CSS, Elixir, Erlang, HTML, JavaScript, Lua, Markdown, Perl, PHP, Python, R, Ruby, SQL, TypeScript, and any other language with C-style comments (// or /* */)
Doesn't add distracting highlights to the scrollbar
Supports light and dark modes out of the box, and doesn’t come with insanely bright colors by default

Try it now in VS Code!

You can also look at the source code on GitHub.

Squirrelsong Light: low-contrast light theme for Visual Studio Code

Artem Sapegin — Fri, 17 May 2024 06:15:58 +0000

After more than a month of tweaking, I finally finished a new version of my low-contrast light theme for Visual Studio Code — Squirrelsong.

New and more cohesive grayscale palette, better UI readability and visual hierarchy, fewer distractions, lots of new colors.

I can’t use dark themes, and most light themes because the contrast is too high and colors are too bright. Such colors are too distracting for me, and I quickly get tired — not something you want if your job is to write code all day. Squirrelsong theme is low-contrast and uses soft colors, but still provide enough color and style variety to distinguish various elements of the code and avoid long chains of code printed in the same style.

I created the first version of this theme long before I learned about my neurodiversity, long before I learned that bright colors are, indeed, not good for my brain, and I need softer and milder colors and UI with fewer distractions.

Soft colors and low contrast are beneficial for neurodiverse people, such as those with attention-deficit/hyperactivity disorder (ADHD), autism, or high sensitivity (HSP). Such colors help reduce sensory overload and create a calming environment; they reduce distractions and visual clutter, so it’s easier to stay focused on your code instead of being distracted and overwhelmed by bright colors.

This might be the only color theme made specifically for neurodiverse and highly-sensitive developers, at least I haven’t seen any other so far…

Get it from Visual Studio Marketplace

P. S. Squirrelsong is also available for Alfred, CotEditor, Chrome, iTerm2, JetBrains, Marta File Manager, Midnight Commander, Nimble Commander, Prism, Slack, Sublime Text, Telegram, Terminal.app, Vivaldi, Warp, WezTerm, and more…

Modern React testing, part 5: Playwright

Artem Sapegin — Mon, 06 May 2024 06:42:53 +0000

Subscribe to my newsletter if you enjoyed this article.

Playwright is a framework-agnostic end-to-end testing (also known as E2E, or integration testing) tool for web apps. Playwright has great developer experience and makes writing good and resilient to changes tests straightforward.

Check out the GitHub repository with all the examples.

Getting started with Playwright

We’ll set up and use these tools:

Playwright, an end-to-end test runner;
Mock Service Worker, mocking network requests.

Why Playwright

Playwright has many benefits over other end-to-end test runners:

The best experience writing and debugging tests.
An ability to inspect the page at any moment during the test run using the browser developer tools.
All commands wait for the DOM to change when necessary, which simplifies testing async behavior.
Tests better resemble real user behavior. For example, Playwright checks that a button is present in the DOM, isn’t disabled, and isn’t hidden behind another element or offscreen before clicking it.
Supports Chromium, WebKit, Firefox, as well as Google Chrome for Android and Mobile Safari.
Convenient semantic queries, like finding elements by their label text or ARIA role, similar to React Testing Library.
It’s very fast.

Semantic queries help us write good tests and make writing bad tests difficult. It allows us to interact with the app in a way that is similar to how a real user would do that: for example, find form elements and buttons by their labels. It helps us avoid testing implementation details, making our tests resilient to code changes that don’t change the behavior.

Why not Cypress

Playwright is similar to the combination of Cypress, Cypress Testing Library, and start-server-and-test, which have been my choice for end-to-end testing for many years, but gives us all the necessary tools in a single package. Also, the API feels more cohesive and intentional. There wasn’t a lot of new things to learn.

Some of the benefits of Playwright over Cypress:

better API;
easier setup;
multi-tabs support;
speed.

Setting up Playwright

First, run the installation wizard:

npm init playwright@latest

This will install all the dependencies and generate the config files. We’ll need to choose:

whether to use TypeScript or JavaScript (we’ll use JavaScript in this article);
where to put the tests (tests folder in the project root);
whether to generate GitHub Actions to run the tests on CI (we won’t cover this here);
whether we want to install the browsers (it’s a good idea; we’ll need them anyway).

Then add two scripts to our package.json file:

{
  "name": "pizza",
  "version": "1.0.0",
  "scripts": {
    "start": "react-scripts start",
    "build": "react-scripts build",
    "test:e2e": "npx playwright test --ui",
    "test:e2e:ci": "npx playwright test"
  },
  "dependencies": {
    "react": "18.2.0",
    "react-dom": "18.2.0",
    "react-scripts": "5.0.1"
  },
  "devDependencies": {
    "@playwright/test": "^1.41.2"
  }
}

Playwright, unlike React Testing Library or Enzyme, tests a real app in a real browser, so we need to run our development server before running Playwright. We can run both commands manually in separate terminal windows — good enough for local development — or we can set up Playwright to run them for us (see below) and have a single command that we can also use on a continuous integration (CI) server.

As a development server, we can use an actual development server of our app, like Create React App (that we use for the examples) or Vite, or another tool like React Styleguidist or Storybook, to test isolated components.

We’ve added two scripts to run the development server and Playwright together:

npm run test:e2e to run a development server and Playwright ready for local development;
npm run test:e2e:ci to run a development server and all Playwright tests in headless mode, ideal for CI.

Then, edit the Playwright config file, playwright.config.js, in the project root folder:

const { defineConfig, devices } = require('@playwright/test');

module.exports = defineConfig({
  testDir: './tests',
  // Run tests in files in parallel
  fullyParallel: true,
  // Fail the build on CI if you accidentally left test.only
  // in the source code
  forbidOnly: !!process.env.CI,
  // Retry on CI only
  retries: process.env.CI ? 2 : 0,
  // Opt out of parallel tests on CI
  workers: process.env.CI ? 1 : undefined,
  // Reporter to use
  reporter: 'html',
  // Shared settings for all the projects below
  use: {
    // Base URL to use in actions like `await page.goto('/')`
    baseURL: 'http://localhost:3000',
    // Collect trace when retrying the failed test
    trace: 'on-first-retry',
  },
  // Configure projects for major browsers
  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },

    {
      name: 'firefox',
      use: { ...devices['Desktop Firefox'] },
    },

    {
      name: 'webkit',
      use: { ...devices['Desktop Safari'] },
    },
  ],
  // Run your local dev server before starting the tests
  webServer: {
    command: 'npm run start',
    url: 'http://localhost:3000',
    reuseExistingServer: !process.env.CI,
  },
});

The options we’ve changed are:

use.baseURL is the URL of our development server to avoid writing it in every test;
webServer block describes how to a run development server; we also want to reuse an already-running server unless we’re in the CI environment.

Tip: Read more about all Playwright config options in the docs.

Setting up Mock Service Worker

We’re going to use Mock Service Worker (MSW) for mocking network requests in our integration tests and in the app during development.

It uses Service Workers, so it intercepts all network requests, no matter how they are made.
A single place to define mocks for the project, with the ability to override responses for particular tests.
An ability to reuse mocks in integration tests and during development.
Requests are still visible in the network panel of the browser developer tools.
Supports REST API and GraphQL.

First, install MSW from npm:

npm install --save-dev msw

Create mock definitions, src/mocks/handlers.js:

import { http, HttpResponse } from 'msw';

export const handlers = [
  // GET requests to https://httpbin.org/anything with any parameters
  http.get('https://httpbin.org/anything', () => {
    // Return OK status with a JSON object
    return HttpResponse.json({
      args: {
        ingredients: ['bacon', 'tomato', 'mozzarella', 'pineapples'],
      },
    });
  }),
];

Note: To mock GraphQL requests instead of REST, use the graphql namespace.

Here, we’re intercepting GET requests to https://httpbin.org/anything with any parameters and returning a JSON object with an OK (200) status.

Now we need to generate the Service Worker script:

npx msw init ./public --save

The --save flag will save the public directory path to package.json so we can update the worker script later by running just msw init.

Note: The public directory may be different for projects not using Create React App.

Then, create another JavaScript module that will register our Service Worker with our mocks, src/mocks/browser.js:

import { setupWorker } from 'msw/browser';
import { http, HttpResponse } from 'msw';
import { handlers } from './handlers';

// Configure a Service Worker with the given request handlers
export const worker = setupWorker(...handlers);

// Expose methods globally to make them available in integration tests
window.msw = { worker, http, HttpResponse };

And the last step is to start the worker function when we run our app in development mode. Add these lines to our app root module (src/index.js for Create React App):

async function enableMocking() {
  if (process.env.NODE_ENV !== 'development') {
    return;
  }

  const { worker } = await import('./mocks/browser');

  // `worker.start()` returns a Promise that resolves
  // once the Service Worker is up and ready to intercept requests.
  return worker.start();
}

And update the way we render the React app to await the Promise returned by enableMocking() function before rendering anything:

enableMocking().then(() => {
  const root = createRoot(document.getElementById('root'));
  root.render(<App />);
});

Now, every time we run our app in the development mode or on CI, network requests will be mocked without any changes to the application code or tests, except these few lines of code in the root module.

Creating our first test

As defined in our config file, Playwright looks for test files inside the tests/ folder. Feel free to remove the example.spec.js file from there — we won’t need it.

So, let’s create our first test, tests/hello.spec.js:

const { test, expect } = require('@playwright/test');

test('hello world', async ({ page }) => {
  await page.goto('/');
  await expect(page.getByText('welcome back')).toBeVisible();
});

Here, we’re visiting the homepage of our app running on the development server, then validating that the text “welcome back” is present on the page using Playwright’s getByText() locator, and toBeVisible() assertion.

Running tests

Start Playwright in the UI mode by running npm run test:e2e. From here, either run a single test or all tests. We can press an eye icon next to a single test or a group to automatically rerun them on every change in the code of the test.

When I write tests, I usually watch a single test (meaning Playwright reruns it for me on every change), otherwise it’s too slow and too hard to see what’s wrong if there are any issues.

Run npm run test:e2e:ci to run all tests in the headless mode, meaning we won’t see the browser window:

Querying DOM elements for tests

Tests should resemble how users interact with the app. That means we shouldn’t rely on implementation details because the implementation can change and we’ll have to update our tests. This also increases the chance of false positives when tests are passing but the actual feature is broken.

Let’s compare different methods of querying DOM elements:

Selector	Recommended	Notes
`button`	Never	Worst: too generic
`.btn.btn-large`	Never	Bad: coupled to styles
`#main`	Never	Bad: avoid IDs in general
`[data-testid="cookButton"]`	Sometimes	Okay: not visible to the user, but not an implementation detail; use when better options aren’t available
`[alt="Chuck Norris"]`, `[role="banner"]`	Often	Good: still not visible to users, but already part of the app UI
`[children="Cook pizza!"]`	Always	Best: visible to the user part of the app UI

To summarize:

Prefer to query elements by their visible (for example, button label) or accessible name (for example, image alt).
Use test IDs as the last resort. They clutter the markup with props we only need in tests. Test IDs are also something that users of our app don’t see: if we remove a label from a button, a test with test ID will still pass.

Note: I often hear this complaint about using labels to query elements: they break when the app copy is updated. I consider this a feature: I’ve seen more than once that a button label change on one screen broke some other screen where this change was undesired.

Playwright has methods for all good queries, which are called locators:

page.getByAltText() finds an image by its alt text;
page.getByLabel() finds a form element by its <label>;
page.getByPlaceholder() finds a form element by its placeholder text;
page.getByRole() finds an element by its ARIA role;
page.getByTestId() finds an element by its test ID;
page.getByText() finds an element by its text content;
page.getByTitle() finds an element by its title attribute.

Let’s see how to use locators. To select this button in a test:

<button data-testid="cookButton">Cook pizza!</button>

We can either query it by its test ID:

page.getByTestId('cookButton');

Or query it by its text content:

page.getByText('cook pizza');

Note: Text locators are partial and case-insensitive by default, which makes them more resilient to small tweaks and changes in the content. For an exact match, use the exact option: page.getByText('Cook pizza!', {exact: true}).

Or, the best method is to query it by its ARIA role and label:

page.getByRole('button', { name: 'cook pizza' });

Benefits of the last method are:

doesn’t clutter the markup with test IDs that aren’t perceived by users;
doesn’t give false positives when the same text is used in non-interactive content;
makes sure that the button is an actual button element or at least has the button ARIA role.

Check the Playwright docs for more details on best practices, and inherent roles of HTML elements.

Testing React apps end-to-end

Testing basic user interaction

A typical integration test looks like this: visit the page, interact with it, and check the changes on the page after the interaction. For example:

const { test, expect } = require('@playwright/test');

test('navigates to another page', async ({ page }) => {
  await page.goto('/');

  // Opening the pizza page
  await page.getByRole('link', { name: 'remotepizza' }).click();

  // We are on the pizza page
  await expect(
    page.getByRole('heading', { name: 'pizza' }),
  ).toBeVisible();
});

Here, we’re finding a link by its ARIA role (link) and text using the Playwright’s getByRole() locator, and clicking it using the click() method. Then we’re verifying that we’re on the correct page by checking its heading, first by finding it the same way we found the link before, and testing the heading with the toBeVisible() assertion.

With Playwright, we generally don’t have to care if the actions are synchronous or asynchronous: each command will wait for some time for the queried element to appear on the page. Though we should explicitly await most operations. This avoids the flakiness and complexity of asynchronous testing and keeps the code straightforward.

Testing forms

Playwright’s locators allow us to access any form element by its visible (for example, <label> element) or accessible (for example, aria-label attribute) label.

For example, we have a registration form with a bunch of text inputs, select boxes, checkboxes, and radio buttons. This is how we can test it:

const { test, expect } = require('@playwright/test');

test('should show success page after submission', async ({
  page,
}) => {
  await page.goto('/signup');

  // Filling the form
  await page.getByLabel('first name').fill('Chuck');
  await page.getByLabel('last name').fill('Norris');
  await page.getByLabel('country').selectOption({ label: 'Russia' });
  await page.getByLabel('english').check();
  await page.getByLabel('subscribe to our newsletter').check();

  // Submit the form
  await page.getByRole('button', { name: 'sign in' }).click();

  // We are on the success page
  await expect(
    page.getByText('thank you for signing up'),
  ).toBeVisible();
});

Here we’re using getByLabel() and getByRole() locators to find elements by their label texts or ARIA roles. Then we use the fill(), selectOption(), and check() methods to fill the form, and the click() method to submit it by clicking the submit button.

Testing complex forms

In the previous example, we used the getByLabel() locator to find form elements, which works when all form elements have unique labels, but this isn’t always the case.

For example, we have a passport number section in our registration form where multiple inputs have the same label, like “year” of the issue date and “year” of the expiration date. The markup of each field group looks like so:

<fieldset>
  <legend>Passport issue date</legend>
  <input type="number" aria-label="Day" placeholder="Day" />
  <select aria-label="Month">
    <option value="1">Jan</option>
    <option value="2">Feb</option>
    ...
  </select>
  <input type="number" aria-label="Year" placeholder="Year" />
</fieldset>

To access a particular field, we can select a fieldset by its legend text first, and then select an input by its label inside the fieldset.

const passportIssueDateGroup = page.getByRole('group', {
  name: 'passport issue date',
});
await passportIssueDateGroup.getByLabel('day').fill('12');
await passportIssueDateGroup
  .getByLabel('month')
  .selectOption({ label: 'May' });
await passportIssueDateGroup.getByLabel('year').fill('2004');

We call getByRole() locator with the ARIA role of fieldset (group) and the text of itslegend. Then we chain the getByLabel() locator to query form fields by their labels.

Testing links

There are several ways to test links that open in a new tab:

check the link’s href attribute without clicking it;
click the link, and then get the handle of the new page and use it instead of the current one (page).

In the first method, we query the link by its ARIA role and text, and verify that the URL in its href attribute is correct:

await expect(
  page.getByRole('link', { name: 'terms and conditions' }),
).toHaveAttribute('href', /\/toc/);

The main drawback of this method is that we’re not testing whether the link is actually clickable. It might be hidden, or it might have a click handler that prevents the default browser behavior.

In the second method, we query the link by its ARIA role and text again, click it, get the handle of the new page, and use the new page handle instead of the current one:

const pagePromise = context.waitForEvent('page');
await page
  .getByRole('link', { name: 'terms and conditions' })
  .click();
const newPage = await pagePromise;
await expect(newPage.getByText("i'm baby")).toBeVisible();

Now, we could verify that we’re on the correct page by finding some text unique to this page.

I recommend the second method because it better resembles the actual user behavior.

There are other solutions, but I don’t think they are any better than these two.

Testing network requests, and mocks

Having MSW mocks setup (see “Setting up Mock Service Worker” above), happy path tests of pages with asynchronous data fetching aren’t different from any other tests.

For example, we have an API that returns a list of pizza ingredients:

const { test, expect } = require('@playwright/test');

const ingredients = ['bacon', 'tomato', 'mozzarella', 'pineapples'];

test('load ingredients asynchronously', async ({ page }) => {
  await page.goto('/remote-pizza');

  // Ingredients list is not visible
  await expect(page.getByText(ingredients[0])).toBeHidden();

  // Load ingredients
  await page.getByRole('button', { name: 'cook' }).click();

  // All ingredients appear on the screen
  for (const ingredient of ingredients) {
    await expect(page.getByText(ingredient)).toBeVisible();
  }

  // The button is not clickable anymore
  await expect(
    page.getByRole('button', { name: 'cook' }),
  ).toBeDisabled();
});

Playwright will wait until the data is fetched and rendered on the screen, and thanks to network calls mocking it won’t be long.

For not-so-happy-path tests, we may need to override global mocks inside a particular test. For example, we could test what happens when our API returns an error:

test('shows an error message', async ({ page }) => {
  await page.goto('/remote-pizza');

  await page.evaluate(() => {
    // Reference global instances set in src/browser.js
    const { worker, http, HttpResponse } = window.msw;
    worker.use(
      http.get(
        'https://httpbin.org/anything',
        () => HttpResponse.json(null, { status: 500 }),
        { once: true },
      ),
    );
  });

  // Ingredients list is not visible
  await expect(page.getByText(ingredients[0])).toBeHidden();

  // Load ingredients
  await page.getByRole('button', { name: 'cook' }).click();

  // Ingredients list is still not visible and error message appears
  await expect(page.getByText(ingredients[0])).toBeHidden();
  await expect(page.getByText('something went wrong')).toBeVisible();
});

Here, we’re using the MSW’s use() method to override the default mock response for our endpoint during a single test. Also note that we’re using the once option of the http.get() method; otherwise the override will be added permanently and may interfere with other tests.

Testing complex pages

We should avoid test IDs wherever possible and use more semantic queries instead. However, sometimes we need to be more precise. For example, we have a “delete profile” button on our user profile page that shows a confirmation modal with “delete profile” and “cancel” buttons inside. We need to know which of the two delete buttons we’re pressing in our tests.

The markup could look like so:

<button type="button">Delete profile</button>
<div
  role="dialog"
  aria-label="Delete profile modal"
  aria-modal="true"
>
  <h1>Delete profile</h1>
  <button type="button">Delete profile</button>
  <button type="button">Cancel</button>
</div>

The first “delete profile” isn’t a problem because when we click it, it’s the only one present on the page. However, when the modal is open, we have two buttons with the same label.

So, how do we click the one inside the modal dialog?

The first option would be to assign a test ID to this button, and sometimes that’s the only way. Usually, though, we can do better. We can nest locators, so we could target the container (the modal dialog) first, and then the button we need inside the container:

await page
  // Locate the dialog by its aria-label
  .getByRole('dialog', { name: 'delete profile modal' })
  // Locate the button by its label inside the dialog
  .getByRole('button', { name: 'delete profile' })
  // Click the button
  .click();

It’s slightly more complex when the container doesn’t have any semantic way to target it, like a section with a heading (h1, h2, and so on) inside. In this case, we can target all sections on a page and then filter them to find the one we’re looking for.

Imagine markup like so:

<section>
  <h2>Our newsletter</h2>
  <form>
    <input
      type="email"
      name="email"
      arial-label="Email"
      placeholder="Email"
    />
    <button type="submit">Subscribe</button>
  </form>
</section>

We can click the “Subscribe” button inside the “Our newsletter” section in a test like so:

await page
  // Locate all sections on a page
  .getByRole('section')
  .filter({
    // Filter only ones that contain "Our newsletter" heading
    has: page.getByRole('heading', { name: 'our newsletter' }),
  })
  // Locate the button inside the section
  .getByRole('button', { name: 'subscribe' })
  .click();

Coming back to our profile deletion modal, we can test it like so:

const { test, expect } = require('@playwright/test');

test('should show success message after profile deletion', async ({
  page,
}) => {
  await page.goto('/profile');

  // Attempting to delete profile
  await page.getByRole('button', { name: 'delete profile' }).click();

  // Confirming deletion
  await page
    .getByRole('dialog', { name: 'delete profile modal' })
    .getByRole('button', { name: 'delete profile' })
    .click();

  // We are on the success page
  await expect(
    page.getByRole('heading', { name: 'your profile was deleted' }),
  ).toBeVisible();
});

Here, we’re using the getByRole() locator, as in previous examples, to find all elements we need.

Debugging

Playwright docs have a thorough debugging guide.

However, it’s usually enough to check the locator or inspect the DOM for a particular step of the test after running the tests.

Click any operation in the log first, and then do one of the following:

To debug a locator the DOM, click the Pick locator button, and hover over an element we want to target. We can use the Locator tab below to edit it and see if it still matches the element we need.

To inspect the DOM, click the Open snapshot in a new tab button and use the browser developer tools the way we’d normally do.

I also often focus on a single test with test.only(), and watch a single file by toggling the eye button in the Playwright UI to make reruns faster and avoid seeing too many errors while I debug why tests are failing.

test.only('hello world', async ({ page }) => {
  // Playwright will skip other tests in this file
});

Conclusion

Good tests interact with the app similar to how a real user would do that; they don’t test implementation details, and they are resilient to code changes that don’t change the behavior.

We’ve learned how to write good end-to-end tests using Playwright, how to set it up, and how to mock network requests using Mock Service Worker.

However, Playwright has many more features that we haven’t covered in the article that may be useful one day.

Subscribe to my newsletter if you enjoyed this article.

Emoji Console Log for VS Code 🍕

Artem Sapegin — Tue, 30 Apr 2024 06:30:18 +0000

Emoji Console Log is my new Visual Studio Code extension to add console.log() statements using a hotkey — my favorite way of debugging web apps.

Here are the main features of the extension:

Hotkeys to add, comment, uncomment, and remove logs to monitor different values.
Adds random non-repeating emoji to each log to make it easier to distinguish different logs in the browser console.
Automatically detects project’s code style (quotes, semicolons, tabs/spaces, etc.).
Automagically adds new lines at the right places to keep the code neat.

Using console.log() is my favorite way of debugging JavaScript and TypeScript code. I’ve been trying to learn more fancy techniques, like a debugger, but I always come back to console.log(), because it’s the simplest and it works for me.

The way I do it is by adding a separate log for each variable I want to track, like so: console.log('🍕 variable', variable). I always add a different emoji at the beginning, so it’s easy to differentiate logs in the browser console.

Try it now in VS Code!

You can also look at the source code on GitHub.

Blank sky new tab page 🌙

Artem Sapegin — Fri, 19 Apr 2024 08:17:47 +0000

I made a little thing called Blank sky: a beautiful twilight sky inspired new tab page replacement for your browser.

It shows a random color gradient every time you open a new tab that looks a bit like a twilight sky.

I got tired of browser vendors pushing their ads and useless features every time I open a new tab, so I wanted to create something that’s calming and nice to look at.

You can install it for Chrome, Firefox, Edge, or Safari (only desktop for now), or:

Try it now in your browser!

You can also look at the source code on GitHub.