DEV Community: Christian Ascone

Syncing dotfiles across PCs with GNU Stow

Christian Ascone — Sat, 01 Mar 2025 16:39:49 +0000

Whether I’m on my old laptop, my shiny work machine, or even a random PC I’ve borrowed for a weekend, I want my tools, shortcuts, and configs to feel like home.

Bash, vim, terminal emulators, tmux, all those things that make your system yours.

Copying them over manually, dealing with version mismatches or forgetting where I stashed the latest tweaks? Yeah, that was a mess.

What’s Stow, anyway?

So, what’s this Stow that saved me from my dotfile nightmare? At its core, Stow is a tool for Linux that helps you manage files using symbolic links; think of them as shortcuts that point to where your actual files live.

"Symbolic links" might sound fancy or intimidating if you’re not familiar with them, but it’s really just a way to keep things tidy without copying files all over the place.

Instead of scattering my .bashrc, .vimrc, and other dotfiles across every machine I use, I keep them all in one neat folder. Then, Stow steps in and “links” them to the right places, like my home directory, so everything works as if I’d put them there myself. No more duplicating files or wondering which version is the latest.

For example, here is my configuration structure:

.
├── ghostty
│   └── .config
│       └── ghostty
│           └── config
├── ideavimrc
│   └── .ideavimrc
├── vimrc
│   └── .vimrc
├── bashrc
│   └── .bashrc
├── kitty
│   └── .config
│       └── kitty
│           └── kitty.conf
├── tmux
│   └── .config
│       └── tmux
│           └── tmux.conf
└── zsh
    └── .zshrc

Every folder in there is for a tool I use, like Kitty or Zsh, and I can put in one file, a couple of files, or even a whole subfolder. Stow grabs whatever’s inside and makes it work.

Getting started with Stow

Okay, so how do you actually use Stow to make this magic happen? First, you need Stow on your machine.

On most Linux systems it’s a quick install:

#Debian/Ubuntu
sudo apt-get install stow
#Fedora
sudo dnf install stow
#Arch Linux
sudo pacman -S stow

On macOS it’s available with brew:

brew install stow

Once it’s there, you’re ready to roll.

Setting up my dotfiles folder

Before Stow can work, you’ll need to organize your dotfiles. Start by creating a folder called dotfiles (I assume to place it in home directory, so the full path is ~/dotfiles).

Next, create a structure similar to the one shown above, with a separate folder for each tool. Ensure the file structure adheres to the following rule:

Main directory (in this case dotfiles) is just the name of the container folder
The subfolder should be named after the tool. While it's best to use the tool's actual name for clarity, you can choose any name to distinguish it. For example, you could name it foobar and Stow will still work correctly.
Finally, the rest is the structure of your config files

Once you set it up you can cd into dotfiles directory and run stow:

cd dotfiles
stow kitty

Stow will locate the dotfiles/kitty directory, take its contents, and create symlinks in your home directory while preserving the same structure. For example, ~/dotfiles/kitty/.config/kitty/config will be symlinked as ~/.config/kitty/config.

If the .config folder doesn’t exist in my home directory, Stow will create it automatically. Pretty neat, right?

It might take a bit of time to get everything sorted, but once it’s done, you’ll have all your configs in one place, ready for Stow to link up. And trust me, it feels great to bring some order to that chaos!

Need to link all your configurations at once? No problem, Stow supports wildcard patterns:

stow * # Create symlinks for every tool

That’s it!

Managing your configs: Deleting and Adopting

So, you’ve got your dotfiles linked up with Stow, and everything’s running smoothly. But what if you want to undo one of those links, like, say, you’re done with your old Kitty setup and want to clean it out? Or maybe you’ve tweaked a config directly in your home directory and want Stow to take it over? No worries, Stow’s got you covered for both.

Deleting a linked configuration

To remove those symlinks, Stow offers a handy delete option. Just head to your ~/dotfiles folder in the terminal and run:

stow -D kitty

The -D flag tells Stow to delete the symlinks it created for the kitty folder. It will unlink ~/.config/kitty/kitty.conf (or whatever’s in there) without touching the original files in ~/dotfiles/kitty. Those stay safe in your dotfiles folder, so you can always bring them back later with a quick stow kitty if you change your mind.

It’s like hitting an undo button, simple and stress-free.

Adopting existing configs

Now, here’s a cool trick Stow can do: adopting configs you’ve already got in your home directory.

Picture this: you’ve been tweaking your .zshrc right in ~/.zshrc, but now you want it to live in your ~/dotfiles/zsh folder under Stow’s control. Instead of moving it manually, Stow can “adopt” it for you.

Here’s how it works. First, make sure your zsh folder exists in ~/dotfiles/ with the right structure, like ~/dotfiles/zsh/.zshrc, but leave it empty or with an older version. Then, from your ~/dotfiles directory, run:

stow --adopt zsh

What happens next is pretty slick. Stow sees the existing ~/.zshrc in your home directory, grabs it, and moves it into ~/dotfiles/zsh/.zshrc, replacing whatever was there. Then it creates a symlink back to ~/.zshrc, ensuring that everything continues to work as before.

It’s like Stow saying, 'Hey, I’ll take this off your hands and keep it organized for you'. Just be careful: if you already have a different .zshrc in ~/dotfiles/zsh already, it will get overwritten, so maybe back it up first if you’re not sure.

Wrapping it up

Stow takes the chaos of managing dotfiles and turns it into a simple, structured process, maybe even a little fun.

No more scrambling to copy configs between machines. No more version mismatches or lost tweaks. Just a clean, consistent setup that follows you wherever you go.

Setting up the structure takes a bit of effort upfront, but once it’s in place, you’ll wonder how you ever managed without it.

Laravel + React project with Authentication & User Panel in less than a minute

Christian Ascone — Mon, 14 Oct 2024 16:57:13 +0000

I recently posted a video on X where I set up a Laravel + React project with authentication and a user profile page in less than a minute! I thought it would be helpful to share a written version for anyone who prefers following along with a detailed guide.

In this guide, I'll show you how to quickly set up a new Laravel project with a React frontend and built-in authentication, all using Laravel Breeze. We'll have a functional user panel with profile editing in just a few steps.

Why Laravel?

Laravel is a popular PHP framework used for building modern web applications. It's gaining traction quickly, in fact, in September 2024, Accel announced a $57 million investment in Laravel.

According to the official site, Laravel is "The PHP Framework for Web Artisans," and it truly lives up to that description.

I won’t spend too much time on what Laravel is, there's a ton of information available on its official website and documentation. Instead, let's get right to setting up your project.

Project setup

Tech Stack

We’ll use:

Laravel (for backend APIs)
SQLite which is the default database for Laravel projects (though you can switch to another database easily)
React for the frontend (with Inertia.js)
Laravel Breeze to handle authentication and user management

Requirements

To follow this guide, make sure you have:

PHP 8 (preferably 8.3)
Composer
Node.js (v21)

Ready? Let's get started!

Step 1: Create a New Laravel Project

First, use Composer to create a new Laravel project:

composer create-project laravel/laravel laravel-project

This will create a new directory with the default Laravel setup. Move into the project directory and serve the application:

cd laravel-project
php artisan serve

If you visit http://localhost:8000, you'll see the Laravel welcome page.

Congratulations, you’ve created your first Laravel project! ✅

By default, Laravel uses an SQLite database, which has already been set up for you. You can find the database file at database/database.sqlite.

Step 2: Install Laravel Breeze

Next, we'll add Laravel Breeze, which provides a minimal implementation of authentication, including:

Login
Registration
Password Reset
Email Verification
Password Confirmation

Additionally, Breeze includes a simple profile page where users can update their information.

Add Breeze package by running:

composer require laravel/breeze --dev

Now, install Breeze into your project:

php artisan breeze:install

During installation, Breeze will prompt you for a few options:

I choose React for the frontend, but there are a few alternatives:
- Blade
- Livewire
- Vue
- API only
Optionally, you can enable Dark mode, Server-Side Rendering (SSR), Typescript, and ESLint.
When asked about a testing framework, you can choose between Pest or PHPUnit. I'll be using Pest.

Once the process is complete, Breeze will have added everything you need for authentication and user management.

It's done! 🎉

Step 3: Run Your Application

Now that Breeze is set up your application is ready and you can run it again:

php artisan serve

Visit http://localhost:8000/register to create a new user.

You'll start with an empty dashboard and can navigate to your profile page to edit your user details and update your password.

The data are already stored in your SQLite database, and your app is essentially ready to be deployed!

Conclusion

By following these steps, you've successfully bootstrapped a full-stack web application using Laravel and React, complete with authentication and a user profile management system.

Breeze gives you a great starting point, but from here you can focus on adding custom business logic, improving UI/UX, or integrating third-party services, all while standing on the shoulders of Laravel’s ecosystem.

I switched from Notion to Obsidian

Christian Ascone — Tue, 23 Apr 2024 10:06:30 +0000

One of the funniest and most annoying (yes) thing is possible to do nowadays is to try many different tools with the exact same purpose. Need to write a document? Google Docs, Notion, Word, Libreoffice, Coda, Apple notes and so on.

Usually even if the purpose is the same what obviously change are the features provided by any of them and one of the biggest mistake anyone can make is to seek the perfect tool.

Spoiler: the perfect tool does not exist. And I can hear you saying: "What an obvious thing you're stating! But if I choose a tool with a lot of features, surely I can find what I need and ignore the rest."

And that would be the real mistake.

Work in the present

Trying many tools is funny, but as mentioned it can also become quite annoying and frustrating. You spend time in something that you might later abandon, all while continuously chasing after perfection.

My perfection had a name: Notion.

Notion is a versatile workspace that offers a set of features for both solo work and team collaboration. It includes blank pages, databases, interconnected data and a wide array of ready-to-use templates.

Honestly I think it's an amazing tool. Amazing, really. Once you learn how to use it it's pretty easy and straightforward because every page is basically a markdown file (except for databases) so you must not deal with complicated logic behind the scene.

But in my case there was a problem: too much noise.

I worked with Notion throughout 2023 and the beginning of 2024 using some stuff always saying: "it's powerful, I'm not using many features but I could in the future" and I don't know if that future will ever come.

I was basically using it as a cauldron for ideas or notes, something that could be done with a paper notebook. That was (and is) my present.

Control, not power

Power was useless for my personal use case.

I use Notion in team, but the problem lies with my use case and data. All that power was wasted, and meanwhile I was overcomplicating my life for a hypothetical future.

The solution was already installed on both my computer and my phone: Obsidian.

For those who don't know it, Obsidian is ssentially a straightforward writing app (similar to the ones I mentioned earlier) that utilizes markdown as its file format.

Obsidian is not the focus of this article; rather, it’s the thought process that led me to it, but I need to cover a few topics to explain what Obsidian does:

Markdown is an open and widely spread format. No more "docx to pdf" conversion or formatting mess while copying content away.
Markdown is a markup language. Any file is human readable, there's no binary content. This makes its management really easy (you can use git for versioning for example).
Obsidian workspace let you connect documents. While your workspace grows you create a map of your files.
Obsidian features can be extended using plugins. If you don't need them you can use the "vanilla version".
Obsidian workspace is just a folder with files and subfolders. Nothing more. You can browse it with your file manager, edit them with your preferred editor, reopen Obsidian and you will see the changes.

My two requirements were the following:

Independence (and consequently simplicity)
Connections among notes

Notion is strong on the second point, but not on the first one. It's bloated by default and you don't have direct access to the files; hence, you're strongly connected to it.

Obsidian, on the other hand, provides the same type of connection but complete independence. Folder and files are stored directly on the filesystem, allowing synchronization with cloud storage services and compatibility with any text editor.

With this goal in mind, I needed to figure out how to efficiently transfer a substantial amount of content from Notion to Obsidian. Fortunately, both platforms offer dedicated options for export and import: https://help.obsidian.md/import/notion

As mentioned, Notion’s features are more complex than Obsidian’s, so some notes may appear differently. To replicate certain functionality, you’ll need to find a suitable plugin.

Sync

The big drawback, if we can call it that, is that Obsidian is not cloud by default, because we have seen that it's just a tool able to open a directory of markdown files.

However it is still possible to sync our workspaces in order to enter our vaults from many devices:

Obsidian Sync: This is the paid plan and it offers a set of fancy features.
Homemade sync: Simply synchronize the workspace folder with your cloud storage.

In my opinion what's more interesting about the paid plan is the "Shared vaults" feature which let you collaborate with your team in real-time, but as I already said this is for my personal workspace so I decided to build my homemade sync solution.

The workspace is stored on Google Drive which is mounted on my computers allowing me to open it as if it were on my hard drive.

Finally I also periodically backup it on git (Obsidian has a plugin for that too) so I keep the total control of my data.

In conclusion, I don’t miss Notion because I haven’t lost any features I was using before. However, this assessment is based on my specific needs. My advice: don’t be afraid to experiment and embrace tools that meet your current requirements—even if other options offer more functionalities that you might use later.

Focus on what you need, the perfect tool does not exist, but the perfect tool for the current you does.

Lazy loading React components

Christian Ascone — Wed, 10 Apr 2024 16:06:48 +0000

Over the life of an application, performance optimization can play a crucial role in its success or failure and I recently encountered an issue that severely impacted the user experience.

Providing some context, my requirement was to show a list of N items using React. Unfortunately, I couldn’t use infinite scrolling, and each item needed to fetch its own data via separate HTTP calls.

Initially, I successfully implemented a component able to fetch data during initialization, nothing difficult, but performance was really bad when there were many items on screen and as previously mentioned I could not use infinite scrolling or pagination due to backend limitations, leaving frontend adjustments as the sole option.

Setup

Let’s walk through a sample project that illustrates the problem and demonstrates a solution.

I chose:

Javascript: To avoid compiling so we focus on our goal. This same approach works with typescript as well.
https://jsonplaceholder.typicode.com: For fetching sample data. It's a "Free fake and reliable API for testing and prototyping."
Vite: Recommended after create-react-app deprecation.
npm: So that everyone can feel comfortable.

You’ll find the link to the complete project at the end of this post, but let’s cover all the steps here.

Our goal is to initiate the (potentially) resource-intensive fetch only when the component becomes visible to the user, otherwise we would be performing unnecessary work that could compromise the overall performance.

Let's start creating a new react project using Vite.

❯ npm create vite@latest
✔ Project name: … react-render-visible
✔ Select a framework: › React
✔ Select a variant: › JavaScript

Scaffolding project in react-render-visible...

First, we need a very simple component that fetches data from APIs and renders it in DOM. This is how it initially looks:

import React, { useState, useEffect } from 'react';

const NinjaComponent = () => {
    const [data, setData] = useState(null);

    useEffect(() => {
        // fetch data
    }, []);

    return (
        <div>
        {/* Show data */}
        </div>
    );
};

export default NinjaComponent;

Now, let's add some logic retrieving fake data from https://jsonplaceholder.typicode.com. It offers a set of basic CRUD operations hence we are going to implement a GET by id provided as input parameter of the component.

Example: https://jsonplaceholder.typicode.com/photos/1

// 1) Add `id` parameter
const NinjaComponent = ({ id }) => {
    const [data, setData] = useState(null);

// 2) Fetch data using `id` in url and update `data`
    useEffect(() => {
        fetch(`https://jsonplaceholder.typicode.com/photos/${id}`)
          .then((response) => response.json())
          .then((data) => setData(data))
          .catch((error) => console.error("Error:", error));
    }, []);

// 3) If `data` is set we render id, title and an image, else it shows a loading text
  return (
    <div style={{border: '1px dashed yellow'}}>
      {data ? (<>
        <p>{data.id}</p>
        <p>{data.title}</p>
        <img src={data.thumbnailUrl} />
      </>
      ) : (
        <p>Loading...</p>
      )}
    </div>
  );
};

We can add it to our home page to check how it works. Let's make the necessary edits in App.jsx.

import "./App.css";
import NinjaComponent from "./components/NinjaComponent";

function App() {
  return (
    <>
      <h1>Ding Dong Bug</h1>
      <div className="card">
        <NinjaComponent id={1} />
      </div>
    </>
  );
}

export default App;

With the initial setup complete, we’ve built our data component and integrated it into the homepage to display sample data. Now, let’s address a performance concern.

Time to start the project: npm run dev

Good, but I've got 1000 elements!

While the NinjaComponent works well, it’s not exactly stealthy. What if we need to render a ton of that?

Try updating the App.jsx with 500 or 1000 instances of NinjaComponent.

...
{Array.from({ length: 1000 }, (_, index) => (
    <NinjaComponent id={index+1} />
))}
...

After relaunching the project, check the console:

This is an insane amount of wasted resources especially if you are not "using" all those components because only the first one or two are on screen.

1000 requests for fetching data (x2 because we have StrictMode in dev)
1000 images to download

Solution: IntersectionObserver

The green area represents what the user actually sees on the screen, while the red area includes elements already in DOM, but currently off-screen.

To manage on-screen visibility, the IntersectionObserver API comes to our aid. It "provides a way to asynchronously observe changes in the intersection of a target element with an ancestor element or with a top-level document's viewport" so basically it can determine exactly what we need.

More in detail we will use two methods provided by IntersectionObserver:

The observe() method is like telling the IntersectionObserver to start keeping an eye on a specific element. When the element’s visibility changes in relation to the viewport or a specified ancestor element, the IntersectionObserver will take note and execute its callback function. This function will receive an array of IntersectionObserverEntry objects, each representing a visibility change event.
The disconnect() method tells the IntersectionObserver to stop watching all of its target elements. It’s like saying, “You can rest now, no need to track any more changes.” This is particularly useful when you no longer need to monitor the visibility changes of the target elements.

With this in mind it is possible to proceed creating a custom hook that will be integrated in NinjaComponent so that it knows when fetch can start effectively filling data.

import { useEffect, useState } from "react";

const useFetchOnVisible = (ref, fetchFn) => {
  const [data, setData] = useState(null); // the state to store the fetched data
  const [loading, setLoading] = useState(false); // the state to indicate the loading status

  useEffect(() => {
    // create a new intersection observer
    const observer = new IntersectionObserver(
      (entries) => {
        // get the first entry
        const entry = entries[0];

        // if the entry is visible and not loading (and we still don't have data)
        if (entry.isIntersecting && !loading && !data) {
          // set the loading state to true
          setLoading(true);

          // call the fetch function and set the data state
          fetchFn().then((data) => {
            console.log("data", data);
            setData(data);
            setLoading(false);
          });
        }
      },
      { threshold: 0.1 }, // the ratio of the element's area that is visible
    );

    // observe the ref element
    observer.observe(ref.current);

    // unobserve the ref element when the component unmounts
    return () => {
      observer.disconnect();
    };
  }, [ref, data, fetchFn, loading]); // the dependencies of the effect

  // return the data and loading state
  return [data, loading];
};

export default useFetchOnVisible;

The threshold in IntersectionObserver is like a visibility marker for your target element. It tells the IntersectionObserver when to notify you about the visibility changes of the target element.

A threshold of 0.0 means that even a single visible pixel counts as the target being visible.
A threshold of 1.0 means that the entire target element must be visible for the callback to be invoked.

With hook available we just need to update the NinjaComponent behaviour moving the fetch function inside the hook itself.

import React, { useRef } from "react";
import useFetchOnVisible from "../hooks/useFetchOnVisible";

const NinjaComponent = ({ id }) => {
  // `ref` places a target on object to track 
  const ref = useRef(null);

  // fetch function has been moved out of the useEffect hook.
  // it just fetches data and parse json.
  const getSource = () =>
    fetch(`https://jsonplaceholder.typicode.com/photos/${id}`) // replace with your API endpoint
      .then((response) => response.json());

  // !!! use the custom hook with `ref` and fetch function
  const [data, loading] = useFetchOnVisible(ref, getSource);

  // UI does not change, it just add the `ref` tag in order to track div
  return (
    <div ref={ref} style={{ border: "1px dashed yellow" }}>
      {data && !loading ? (
        <>
          <p>{data.id}</p>
          <p>{data.title}</p>
          <img src={data.thumbnailUrl} />
        </>
      ) : (
        <p>Loading...</p>
      )}
    </div>
  );
};

export default NinjaComponent;

Ready to test?

Lazy loading in action

Assuming everything is properly configured, let’s open the page and observe what happens in the console. We’ll pay close attention to loading times and downloaded resources.

The page opening now requires few requests, consumes fewer resources, and the total loading time has dramatically improved — from around 10 seconds to a mere 0.5 seconds!

As we scroll down the page, the IntersectionObserver detects the moment when a component becomes visible and triggers the fetch function to retrieve data as needed.

Even increasing the number of components to 2000, the request count at startup remains unchanged and performance does not suffer. All thanks to fetching data precisely when it’s required, rather than preemptively! 🎉

GitHub: Source code

Committing to Clarity

Christian Ascone — Wed, 27 Dec 2023 07:45:09 +0000

Nowadays every developer should know Git but in case you don't (listen to me, go studying that and you will save a lot of headaches) here is a brief explanation:

Git is a distributed version control system that allows multiple developers to collaborate on a project simultaneously without overwriting each other's work. It keeps track of changes made to files and allows users to revert to previous versions, branch out to work on new features, and merge changes back together.

The git commit message is a way to document and describe the changes being made to a file or a set of files in a Git repository. It is entered by the developer as part of the commit process and serves as a summary of the changes made.

And "Commit message" itself is the protagonist of this article.

"Who cares"

"What should I write as commit message?"

"Who cares"

This is what I heard many times when someone needed to write a message for a commit, with the consequence that after a few commits the repository was unreadable and unintelligible.

In small teams or individual projects, this is not a problem, however, a git repository represents the history of our code: what's been added, removed, edited, which features we merged and which ones are still in progress.

Therefore writing a good commit message should be a strict rule, even when we are working on individual projects, otherwise we are going to miss pieces of information and we will be forced to rely only on our memory.

That said, another big issue is how to standardize messages.

# 4 different commit messages for the same
> Add new String utils class
> * new String utils class
> New class: String utils
> Added String utils

I edited these a bit to hide confidential information, but they are real commit messages from different people working on the same repository and as you can see the style is always different.

This introduces a few issues:

It's time-consuming: every time you have to think about how to format your message (What verbal tense do I use? Lowercase or not?).
Heterogeneous history: as seen above the history is not linear due to different styles (even the same person could adopt several styles at various moments).

Hence, what is needed is a standardized way of building a commit message which can be shared among people, allowing us to write something as similar as possible to other commits.

Solution: Conventional Commits

The Conventional Commits specification is a lightweight convention on top of commit messages. It provides an easy set of rules for creating an explicit commit history; which makes it easier to write automated tools on top of.

Conventional Commits 1.0.0

Since I discovered Conventional Commits my approach to commits changed and improved drastically. Its specification provides practical "tools" (nothing magical, but very powerful) which help developers to use git smarter and easier.

First, let's see the structure of a message:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

# Or simply

<type>: <description>

So easy? Yes. The magic lies beneath the type argument.

It describes the scope and context of a commit quickly and easily:

fix
feat
docs
refactor
test

These are just a few examples, but all of them immediately give a hint to readers about what has been added or edited, even without knowing anything about Conventional Commits.

As stated in official website it is inspired by, and based heavily on, the Angular Commit Guidelines, which include other nice features.

Angular commit history looks so clean and easy to read.

Moreover, with this standard it is possible to automate changelogs generation and and semantic version bump (check SemVer) while keeping git history consistent: it's a win win.

Go try it out

In conclusion, Conventional Commits is not something you install, it's a set of rules that a team (or an individual) can adopt in its git workflow without any cost, enhancing collaboration within your development team.

By adopting this structured approach to commit messages, you can improve communication, simplify code reviews, automate release notes generation, and ultimately build a more organized and efficient development process.

So why not give Conventional Commits a shot and experience the benefits for yourself? Happy coding!

Cracking the code coverage myth

Christian Ascone — Fri, 22 Sep 2023 16:47:20 +0000

Writing software tests is one of those activities that can dramatically increase its robustness and reliability, allowing developers to correct and refactor code knowing that nothing has been damaged, however, test suites are made of code as well, written by humans and subject to bugs and incompleteness.

Code coverage comes to our aid, but it can also be harmful.

What is the code coverage?

Let's start with the definition of Code coverage.

Code coverage is a metric that measures the extent to which the source code of a software program is tested by a test suite.

It measures the percentage of code lines executed during the testing process.

The purpose of code coverage analysis is to determine the effectiveness of the testing efforts by identifying areas of code that have been inadequately tested.

Thanks ChatGpt for this definition.

Giving a basic example, this is what happens for coverage calculation.

Nothing more than this. Simple, right?

This applies to conditional statements as well.

function myFunction(value) {
  console.log("I was here"); // COVERAGE OK
  switch (value) {
    case 1:
      console.log("It is 1"); // COVERAGE OK
      break;
    case 2:
      console.log("It is 2"); // NO COVERAGE
      break;
    case 3:
      console.log("It is 3"); // NO COVERAGE
      return false; // NO COVERAGE
      break;
  }
  return true; // COVERAGE OK
}

// Test
myFunction(1);

There are three terms when we talk of code coverage:

hit: the line of code has been executed.
partial: the line of code has been executed, but there are remaining branches that were not executed (for example an if-else statement).
miss: the line of code has NOT been executed.

These terms are needed to calculate the code coverage:

Coverage is the ratio of hits / (sum of hit + partial + miss). A code base that has 5 lines executed by tests out of 12 total lines will receive a coverage ratio of 41% (rounding down).

Codcov: About Code Coverage (Last seen in August 2023)

It quantifies how thoroughly our tests "exercise" our codebase and it's a valuable metric because it highlights untested or under-tested parts of your code, hence 100% code coverage means that every single line of code is executed by at least 1 test function.

A warm, soft blanket during a blizzard

 PASS  app/calculator.test.js
  ✓ add function (1 ms)

---------------|---------|----------|---------|---------|-------------------
File           | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
---------------|---------|----------|---------|---------|-------------------
All files      |     100 |      100 |     100 |     100 |
 calculator.js |     100 |      100 |     100 |     100 | 
---------------|---------|----------|---------|---------|-------------------
Test Suites: 1 passed, 1 total
Tests:       1 passed, 1 total
Snapshots:   0 total
Time:        0.397 s, estimated 1 s

Wow, it appears that the code is fully tested!

Code coverage can be comforting and can strengthen the confirmation bias that our code works and is robust when we are just chasing the goal of having the "green light", a seal of approval.

Reality? Code coverage is nothing when we talk about quality and it leads us to trust ourselves the code more than we should. And we're going to prove it!

Some testing

The roadmap:

Setup a javascript project with jest
Write a function to test (very simple)
Write a test suite that reaches 100% coverage
Write a test suite that doesn't

# Initialize project
> npm init

package name: (dingdongbug) codecoverage_example
version: (1.0.0)
description: Example project for code coverage
entry point: (index.js)
test command: jest
git repository:
keywords:
author:
license: (ISC)

{
  "name": "codecoverage_example",
  "version": "1.0.0",
  "description": "Example project for code coverage",
  "main": "index.js",
  "scripts": {
    "test": "jest"
  },
  "author": "",
  "license": "ISC"
}

# Install jest for testing
> npm install --save-dev jest

added 291 packages, and audited 292 packages in 31s

31 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities

The folder structure should look as follows.

> tree -L 1
.
├── node_modules
├── package-lock.json
└── package.json

2 directories, 2 files

Start coding

We are going to update the index.js adding our function to test.

function processInput(input) {
  let output = input.toUpperCase();
  let longString = false;
  if (output.length > 5) {
    output += '_longString';
    longString = true;
  }
  return {
    text: output,
    isLong: longString
  };
}
module.exports = processInput;

That's a very simple (and useless) function that just turns our string uppercase and finally adds a suffix if the text is longer than 5 characters.

It returns an object with the resulting string and a boolean flag indicating if the string was long enough for a suffix.

Let's keep going with test classes, starting from what will be called sweetLie.test.js.

const processInput = require('./index.js');

test('pass a short string', () => {
  let result = processInput('Short');
  expect(result).not.toBe(null);
});

test('pass a long string', () => {
  let result = processInput('Longer string');
  expect(result).not.toBe(null);
});

This test suite runs two tests:

The first one invokes the processInput function with a short string and checks the result is not null
The second one invokes the processInput function with a string longer than 5 and checks the result is not null

Then we move on to the second suite: bitterTruth.test.js.

const processInput = require('./index.js');

test('pass a short string', () => {
  const input = 'Short';
  let result = processInput(input);
  expect(result).not.toBe(null);
  expect(result.isLong).toBe(false);
  expect(result.text).toBe(input.toUpperCase());
});

test('pass an empty string', () => {
  const input = '';
  let result = processInput(input);
  expect(result).not.toBe(null);
  expect(result.isLong).toBe(false);
  expect(result.text).toBe(input);
});

test('pass null', () => {
  expect(() => {
    processInput(null);
  }).toThrow();
});

It is immediately evident how this suite goes deeper into testing.

The first test invokes the processInput function with a short string then checks:
- The result is not null.
- The result object has the property isLong equal to false.
- The transformed text is uppercase.
The second test invokes the processInput function with an empty string then checks:
- The result is not null.
- The result object has the property isLong equal to false.
- The transformed text is equal to the initial input.
The last test invokes the processInput function with a null string checking that an error is thrown.

Coverage

Now let's try running our sweet lie suite with the coverage flag.

> npm test -- sweetLie.test --coverage

> codecoverage_example@1.0.0 test
> jest --coverage

 PASS  ./sweetLie.test.js
  ✓ pass a short string (4 ms)
  ✓ pass a long string (4 ms)

----------|---------|----------|---------|---------|-------------------
File      | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
----------|---------|----------|---------|---------|-------------------
All files |     100 |      100 |     100 |     100 |
 index.js |     100 |      100 |     100 |     100 |
----------|---------|----------|---------|---------|-------------------
Test Suites: 1 passed, 1 total
Tests:       2 passed, 2 total
Snapshots:   0 total
Time:        1.168 s
Ran all test suites.

Yuppie 🎉 All tests passed and 100% coverage! No missing statements, branches, functions or lines, not at all.

This is great, you will probably receive compliments and a pat on the back.

You could say: "Yes, but during the code review someone will stop me and ask me to test further" and I hope so, but it doesn't always go like this, or you could inherit a project with these tests, trusting what you see in the coverage report.

We can tell ourselves so many fairy tales, but this unfortunately remains a real case that can occur, if only because of the rush to release the product.

What if we run the bitter truth? Let's see.

> npm test -- bitterTruth --coverage

> codecoverage_example@1.0.0 test
> jest bitterTruth --coverage

 PASS  ./bitterTruth.test.js
  ✓ pass a short string (5 ms)
  ✓ pass an empty string (1 ms)
  ✓ pass null (14 ms)

----------|---------|----------|---------|---------|-------------------
File      | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
----------|---------|----------|---------|---------|-------------------
All files |   71.42 |       50 |     100 |   71.42 |
 index.js |   71.42 |       50 |     100 |   71.42 | 5-6
----------|---------|----------|---------|---------|-------------------
Test Suites: 1 passed, 1 total
Tests:       3 passed, 3 total
Snapshots:   0 total
Time:        2.262 s
Ran all test suites.

Apparently, the results are not so good: 50% of branches, 71% of statements which is lower than the 80% which is usually recommended.

The truth is that we built a test suite which is more robust and valuable than the previous one, even if our coverage is lower, because we are testing some edge cases and checking the values inside the result object.

Conclusions

Should I ignore code coverage?

No, code coverage is a tool like many others and is not the problem itself, what is actually problematic is how much trust we place in it because we want to satisfy our thirst for safety.

Code coverage offers simple but very important information: what's not been tested at all.

The focus of good test suites should always be on the expected behaviour, not on lines of code, however knowing that a block of code is never reached by tests helps us to be more aware that it might lead to unexpected results.

As we have seen, while high code coverage demonstrates that a significant portion of the code has been tested, it does not guarantee the effectiveness or reliability of those tests.

Well-written tests, tailored to specific functionalities and edge cases, are instrumental in ensuring that a project is robust and able to withstand real-world scenarios.

GitHub: Source code