DEV Community: Oleksandr Tkachenko

Skeleton Mammoth - or how I've been solving the problem of reusable Skeleton Loaders.

Oleksandr Tkachenko — Tue, 25 Jul 2023 16:50:47 +0000

Introduction.

There are a lot of great articles on the Internet devoted to the skeleton loaders, that cover about their types, cases, and needs for their use. I will not list them here, you can easily find them in your favorite search engine.

After investigating this topic in detail, I've decided to create by myself a very simple, flexible, reusable, customizable and lightweight solution that would suit most use cases.
In this article, I will describe the process of creating this solution and turning it into a library, as well as the difficulties that I encountered while working on it.

What Skeleton Loaders are?

Note: You can skip this section if you know what skeleton loaders are.

A skeleton loader, also known as a skeleton screen or content placeholder, is a user interface design pattern used to enhance the user experience during content loading in web and mobile applications. When data is being fetched or processed in the background, instead of displaying a blank or empty screen, a skeleton loader mimics page layout by providing users with a visual cue of what to expect, reducing perceived loading times and mitigating potential frustration.

Here are examples of skeleton loaders from LinkedIn and Youtube:

Why you have to use Skeleton Loaders?

Improve user experience: Skeleton loaders enhance the user experience by providing visual feedback and reducing the perception of content loading delays.
Reduce bounce rate: Skeleton loaders can prevent users from leaving the page due to loading delays.
Smooth transitions: They create smoother transitions between different states of a page or application.
Unlike spinners, skeleton loaders attract the user's attention to progress rather than waiting time.

Problems of most existing skeletons.

Taking into account that there are a lot of examples of creating your own skeleton loaders or libraries that did it for you, there are still a number of problems with them.

Limited customization: Many existing skeletons have limited customization options. It leads to mismatch of the actual content design and skeleton style.
Although their purpose is to provide a visual representation, most of them are not adapted to users with visual impairments or those who using screen readers.
Versatility and reusability. Most approaches to creating skeletons offer either creating a shallow copy of components placeholders, resulting in many similar copies, or essentially changing the structure of existing components. Both of the approaches require a lot of additional code and assets.
Maintenance complexity: As websites evolve and content changes, keeping skeleton loaders up-to-date can become a maintenance burden.

Skeleton loaders alternatives.

There are several "alternatives" to using skeletons. Looking ahead and answering whether there really are alternatives, my answer is no rather than yes. If we talk about correct usage, then the skeleton is one of the best solutions. Below, I will still give a couple of alternatives, along with their pros and cons.

Spinner.

Spinners, are a common alternative to skeleton loaders. They consist of animated icons that rotate continuously, providing a visual cue that the content is loading.

Pros.

Simplicity: Simple implementation that, often requiring only a few lines of code or using pre-designed libraries.
Universal understanding: Spinners are widely recognized across different platforms and applications, ensuring users understand that content is loading.

Cons.

Limited information: spinners do not provide any context about the content being loaded.
Overlaps the entire page or most of it, not individual elements. What gives the feeling of loading not individual elements, but the entire site as a whole.

Spinners are an integral part of interfaces, but they're not exactly suitable for replacing skeletons.

Progress Bar.

A progress bar is a visual element that indicates the completion status of a task or process. It provides a linear representation, typically with a filled portion that grows gradually.

Pros.

Precise feedback: Provides accurate and precise feedback on the completion status of a task.
Time estimation: Progress bars can give users an estimate of the remaining time required for completion.
Multi-Purpose: Progress bars can be used in various contexts and scenarios, making them a versatile component in web and application development.

Cons.

Lack of context: In some cases, progress bars might not provide sufficient context about the actual task or process they represent.
Implementation complexity: Creating progress bars with accurate representation and smooth animations can be complex, especially when dealing with varying task durations and responsiveness.

Progress bars are more suitable for scenarios showing the progress of a file upload, or quantitative progress. They are often used at the top of pages to show the progress of an entire page loading. But they cannot serve as an equivalent replacement for the skeleton, because they are intended for other purposes.

The absence of any visual.

Yes, not having any loaders or placeholders is also an alternative. And in some cases, this will be a better solution than using unsuitable elements.
The main and probably the only pros is that you don't need an additional time and resources spent on implementations. But here comes the obvious cons – a less attractive design for your site, and the perception of slower loading time.

Creating versatile and reusable skeleton loader.

After I had gained enough knowledge of what a skeletons are, when to use it, what they are, and approaches to their development, I tried to determine for myself what my final result should be.

Versatile and Reusable.
There are a lot of examples over the internet, with overcomplicated approaches, where you have to create a separate skeleton for every component you want to have them on. In my case, I wanted it to be something singular that can be reused for most cases and not stick to any JavaScript framework (like React.js or Vue.js).

Configuration Flexibility.
Since every project and every case can be very different, my skeleton needed to be able to be configurable.

Feature rich.
In addition to the standard set of features, I wanted to fill it with support for additional useful and necessary features.

Lightweight and Dependencies-Free.
Lightweight and as free as possible from other 3rd party dependencies.

All of these expectations and investigations, had led me to the fact, that my future skeleton had to be written in pure CSS, without any JavaScript, and third party dependencies. This makes it possible to be lightweight, and dependencies free. The main idea is that it inherits layouts of components it applied to, and customize them with their own styles.
Perhaps in the future, for development purposes, it would make more sense to rewrite all this to the SCSS syntax, since this will make the code shorter and more reusable, and the final assembly will still compile to pure CSS.

Base Card.

As a basis example and for demo purposes, I'll use React.js and take some base card markup, to show how it works. But I remind you, that it's not tied to any of the frameworks, and at the end of the article there are will be links for source code of the library and demo.

Here is a card markup example, that has it its own styles and doesn't know about the existence of skeleton yet.



<div className='card'>
    <div className='card__img-wrapper'>
        <img className='card__img' src={require(`../../images/cards/${imgUrl}`)}/>
    </div>
    <div className='card__body'>
        <div className='card__details'>
            <p className='card__title'>{title}</p>
            <p className='card__subtitle'>{subtitle}</p>
        </div>
    </div>
</div>

In order for the skeleton to become active, it is only necessary to apply the parent class sm-loading to the card itself and the child classes sm-item-primary or sm-item-secondary to those elements on which we want to see the skeleton. So the updated result will look like this:



<div className={`card ${dataState.dataStatus === 'loading' ? "sm-loading" : ""}`}>
    <div className='card__img-wrapper sm-item-primary'>
        <img className='card__img' src={require(`../../images/cards/${imgUrl}`)}/>
    </div>
        <div className='card__body'>
            <div className='card__details'>
                <p className='card__title sm-item-secondary'>{title}</p>
                <p className='card__subtitle sm-item-secondary'>{subtitle}</p>
            </div>
    </div>
</div>

Let me break it down and explain a few moments:
In the following line of code



<div className={`card ${dataState.dataStatus === 'loading' ? "sm-loading" : ""}`}>

I apply the sm-loading class depending on the condition. If the status of the dataState.dataStatus is loading then class will be applied, otherwise - no. The sm-loading class should only be set/present while your data is loading. It's kind of a switcher. Only when it is present, child elements with the presence of appropriate classes sm-item-primary or sm-item-secondary will display the skeleton. So, only 3 classes that will make this skeleton work.

Base skeleton styles.

Root variables.

In order to have a neat and reusable code, as well as the possibility of further configuration (overriding), I've created root variables with basic styles.



/* Root variables.
--------------------------------------------------------------------------------*/
:root {
    /* Light theme colors. */
    --sm-color-light-primary: 204, 204, 204, 1;
    --sm-color-light-secondary: 227, 227, 227, 1;
    --sm-color-light-animation-primary: color-mix(
            in srgb,
            #fff 15%,
            rgba(var(--sm-color-light-primary))
    );
    --sm-color-light-animation-secondary: color-mix(
            in srgb,
            #fff 15%,
            rgba(var(--sm-color-light-secondary))
    );

    /* Dark theme colors. */
    --sm-color-dark-primary: 37, 37, 37, 1;
    --sm-color-dark-secondary: 41, 41, 41, 1;
    --sm-color-dark-animation-primary: color-mix(
            in srgb,
            #fff 2%,
            rgba(var(--sm-color-dark-primary))
    );
    --sm-color-dark-animation-secondary: color-mix(
            in srgb,
            #fff 2%,
            rgba(var(--sm-color-dark-secondary))
    );

    /* Animations. */
    --sm-animation-duration: 1.5s;
    --sm-animation-timing-function: linear;
    --sm-animation-iteration-count: infinite;
}

Here the color values for the static (with no animation) and animated skeleton are set, as well as the animation settings.

Base styles.

The next section of the file is dedicated to the base styles, that doesn't relate to any color scheme or configuration.



/* Base styles.
Applied by default and not related to any of the color scheme.
--------------------------------------------------------------------------------*/
.sm-loading .sm-item-primary,
.sm-loading .sm-item-secondary {
    border-color: transparent !important;
    color: transparent !important;
    cursor: wait;
    outline: none;
    position: relative;
    user-select: none;
}

.sm-loading .sm-item-primary:before,
.sm-loading .sm-item-secondary:before {
    clip: rect(1px, 1px, 1px, 1px);
    content: "Loading, please wait.";
    inset: 0;
    overflow: hidden;
    position: absolute;
    white-space: nowrap;
}

.sm-loading .sm-item-primary::placeholder,
.sm-loading .sm-item-secondary::placeholder {
    color: transparent !important;
}

.sm-loading .sm-item-primary *,
.sm-loading .sm-item-secondary * {
    visibility: hidden;
}

.sm-loading .sm-item-primary :empty:after,
.sm-loading .sm-item-primary:empty:after,
.sm-loading .sm-item-secondary :empty:after,
.sm-loading .sm-item-secondary:empty:after {
    content: "\00a0";
}

/* Animations related styles. */
@keyframes --sm--animation-wave {
    to {
        background-position-x: -200%;
    }
}

@keyframes --sm--animation-wave-reverse {
    to {
        background-position-x: 200%;
    }
}

@keyframes --sm--animation-pulse {
    0% {
        opacity: 1;
    }
    50% {
        opacity: 0.6;
    }
    100% {
        opacity: 1;
    }
}

.sm-loading .sm-item-primary,
.sm-loading .sm-item-secondary {
    animation: var(--sm-animation-duration) --sm--animation-wave
    var(--sm-animation-timing-function) var(--sm-animation-iteration-count);
}

As stated earlier, parent class sm-loading is used to activate the skeleton loader style. The sm-item-primary and sm-item-secondary classes overrides element’s styles and displays a skeleton.

In this way, the layout styles and dimensions of elements (card component in our case) are persisted and inherited by the skeleton loader. Additionally, I would like to say that with this approach, we guarantee that all child elements of sm-item-primary or sm-item-secondary classes are hidden and at least have a Non-breaking space character. If an element contains no content at all, this symbol ensures that the element is displayed and rendered. There is also a part that is responsible for users of screen readers, and lets them know that the content is in the process of loading.

Further, there is a division into thematic sections, such as color scheme, animations, accessibility. Let's look at the color styles for the light theme.



/* Light theme.
The library's default color scheme.
Styles applied to the light color scheme.
--------------------------------------------------------------------------------*/
.sm-loading .sm-item-primary {
    background: rgba(var(--sm-color-light-primary));
}

.sm-loading .sm-item-secondary {
    background: rgba(var(--sm-color-light-secondary));
}

/* Animations related styles. */
.sm-loading .sm-item-primary {
    background: linear-gradient(
            90deg,
            transparent 40%,
            var(--sm-color-light-animation-primary) 50%,
            transparent 60%
    )
    rgba(var(--sm-color-light-primary));
    background-size: 200% 100%;
}

.sm-loading .sm-item-secondary {
    background: linear-gradient(
            90deg,
            transparent 40%,
            var(--sm-color-light-animation-secondary) 50%,
            transparent 60%
    )
    rgba(var(--sm-color-light-secondary));
    background-size: 200% 100%;
}

Color scheme.

With a CSS media feature prefers-color-scheme I've implemented automatic support of the light and dark themes. Depending on users' settings, it will be applied automatically. Of course, it's possible to set it manually, I'll talk about it later in the article.



/* Dark theme.
Styles to apply if a user's device settings are set to use dark color scheme.
https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme
--------------------------------------------------------------------------------*/
@media (prefers-color-scheme: dark) {
    /*Omitted pieces of code.*/
}

Accessibility.

Animations.

By default, in the skeleton, I decided to make animation enabled, but there are cases when developers or users would prefer not to have it. And if for the former this may be dictated by design and requirements, then for the latter it may be due to vestibular motion disorders.
For this, the CSS media feature prefers-reduced-motion comes to the rescue.



/* Accessibility.
Disable animations if a user's device settings are set to reduced motion.
https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion
--------------------------------------------------------------------------------*/
@media (prefers-reduced-motion) {
    /*Omitted pieces of code.*/

    .sm-loading .sm-item-primary,
    .sm-loading .sm-item-secondary {
        animation: none;
    }

    /*Omitted pieces of code.*/
}

Configuration.

At this stage, the main styles are over, and the skeleton can be considered ready. But, I was haunted by the thought that I should be able to configure all of the above. What if I want to turn off the animation if I want to always have a dark theme?
Since it is not possible for CSS to receive any values as arguments, like JavaScript functions do, the addition of JavaScript was excluded (at least at this stage). Because it would completely break the main concept of being as simple and lightweight as possible.
But still, we can implement something similar to arguments if we know their values in advance. And here data-* attributes come to our aid. With their help, we can check for the presence of the value we need in the attribute, and apply the desired styles.
I will show you how I've implemented it on a small piece of code, and you can find the full implementation in the source code at the link at the end of the article.

For example, if you want to explicitly use a dark theme, you need to make a JSON object:



const config = JSON.stringify({
  theme: "dark",
})

Note:
data-* attributes can only work with strings, so it's significant to apply JSON.stringify() method to the configuration object.

Next, pass this object to the custom attribute data-sm-config:



<div class="card sm-loading" data-sm-config={config}>
    <!-- Omitted pieces of code. -->
</div>

This is how it looks in the CSS file. If there is a value "theme":"dark" in the data-sm-config, apply desired styles.



.sm-loading[data-sm-config='"theme":"dark"'] .sm-item-primary,

.sm-loading[data-sm-config='"theme":"dark"'] .sm-item-secondary {

    /* Omitted pieces of code. */

}

Advanced usage.

Overriding styles with global variables.

Each project and case are unique, and it is impossible to predict and make everything versatile. Especially when it comes to colors. That is why, as was said at the beginning of the article, most of the values are placed in variables. If you want to adjust the default styles, just override appropriate variables in your own *.css file inside the :root CSS pseudo-class.
So, for example, if you want to change the color of the primary item (with a class sm-item-primary), you only need to overwrite the corresponding variable:



/* Your own custom.css file: */

:root {

  --sm-color-light-primary: 255, 0, 0, 0.5;

}

Live demo.

You can try out the finished result in action at the following link: Live demo.

Let's wrap it up.

After I had studied the topic of skeleton loaders for a long time, their varieties, usage, approaches to develop, I managed to collect the essence of useful information and turn it into a final product. Having collected best practices, improved them and combined into a single entity, I've created the library called Skeleton Mammoth. I believe that I managed to achieve my goals and create a pretty good library with all the advantages described in this article. I hope that this library is able to benefit people when using it, or provide new knowledge and experience to create something of their own.

Show your support.

If you find my library useful and would like to show your support, there are simple ways to do so:
Star the GitHub Repository: This helps to increase its visibility and lets others know that the library has a strong user base.

Spread the Word: You can introduce new users to the library by sharing information about it on any platform. Such as writing about it on a blog post, mentioning it on social media, or discussing it in relevant developer communities, it would be immensely helpful.

Below, I will post a list of useful links, including a link to the library.

Useful links.

Skeleton Mammoth - GitHub repository of the library.
NPM package.
Live demo.
Live demo source code - Live demo GitHub repository.

Developing and testing sortable Drag and Drop components. Part 2 - Testing.

Oleksandr Tkachenko — Fri, 09 Dec 2022 14:57:21 +0000

Foreword.

In the previous article, you learned how to develop reorderable drag-and-drop components, now it's time to test them. In this part, you'll cover the application with unit tests with the BDD approach. I will not try to prove the usefulness or uselessness of unit tests in your projects, the final decision always depends on you, I'll just learn you how to do it. If you are not familiar with unit testing, take your time, to find and read a few articles to have a solid knowledge of what it is and how it works.

Technologies and libraries used:

Cucumber and BDD approach.

If you are already familiar with the Cucumber and BDD approach, you can safely skip this section and go to the next one.

What is BDD?

In simple words, this:

Behavior-driven development (BDD) it's a methodology in testing practice that allows to describe how the application should behave in a very simple and human-readable language, that will be understood by all the team members. The idea is to create a specification, that will document your application in the manner the behavior a user expects to experience when interacting with it.

Here is how Cucumber describes what is BDD:

BDD is a way for software teams to work that closes the gap between business people and technical people by:

Encouraging collaboration across roles to build shared understanding of the problem to be solved

Working in rapid, small iterations to increase feedback and the flow of value

Producing system documentation that is automatically checked against the system’s behavior

We do this by focusing collaborative work around concrete, real-world examples that illustrate how we want the system to behave. We use those examples to guide us from concept through to implementation, in a process of continuous collaboration.

For a complete understanding, feel free to read the Cucumber documentation explanation or googling a few articles explaining this topic.

What is Cucumber?

According to the Cucumber documentation:

Cucumber reads executable specifications written in plain text and validates that the software does what those specifications say. The specifications consists of multiple examples, or scenarios. For example:
Scenario: Breaker guesses a word Given the Maker has chosen a word When the Breaker makes a guess Then the Maker is asked to score
Each scenario is a list of steps for Cucumber to work through. Cucumber verifies that the software conforms with the specification and generates a report indicating ✅ success or ❌ failure for each scenario.

I guess, for now, you have a shallow picture of how it works, and you can proceed further, but anyway, I'll explain the process step by step.

Dependency installation and configuration.

Dependencies installation.

There are many ways, articles, and best practices on how to install and configure unit tests, and explaining it, will require a separate (or maybe more than one) article. And my goal here is to acquire basic knowledge of unit testing with Cucumber and cover the main functionality of the application that you developed in the last part. Therefore, all dependencies and configurations will be as simple as possible and minimally necessary for writing tests.
Here is the list of required dependencies and dev-dependencies, which you also can find in the package.json file:

devDependencies.
File: package.json

// Omitted pieces of code.
"@testing-library/jest-dom"
"@testing-library/react"
"@testing-library/user-event"
"@types/jest"
"cross-env"
"jest-circus"
"jest-cucumber"
"jest-watch-typeahead"
"react-test-renderer"
// Omitted pieces of code.

Some of them will be installed automatically with the Create React App, and the rest you’ll install yourself.

Configuration.

The easiest and quickest way to configure Jest is to specify the jest key in the package.json file. We only need one configuration, which concerns the React DnD library, it’s transformIgnorePatterns:

File: package.json

// Omitted pieces of code.
"jest": {
 "transformIgnorePatterns": [
   "node_modules/(?!react-dnd)/"
 ]
}
// Omitted pieces of code.

By default, React already has the command to run tests, but you need to modify it a little bit, so it will look the following:

// Omitted pieces of code.
"test": "cross-env RTL_SKIP_AUTO_CLEANUP=true react-scripts test",
// Omitted pieces of code.

Using the cross-env library, you'll tell the React Testing Library to skip auto cleanup after each test. More info and ways to configure here: Skipping Auto Cleanup.
Now your configuration is enough to start writing tests, let's get started.

Writing Feature File - Specification.

In order for Cucumber to understand the scenarios, they must follow some basic syntax rules, called Gherkin. Gherkin documents are stored in *.feature text files and are typically versioned in source control alongside the software. For more information, you can refer to the documentation, but the easiest way is to see this with a real example.
Create the Container.feature file alongside the Container.tsx file. This file consists of sections beginning with keywords.

Feature.

The purpose of the Feature keyword is to provide a high-level description of a software feature, and to group related scenarios. The first primary keyword in a Gherkin document must always be Feature, followed by a : and a short text that describes the feature.

In your case, you’ll test drag-and-drop functionality, so no need to complicate and let’s call it as it is:

File: src/components/Container/Container.feature

// Omitted pieces of code.
Feature: Drag and Drop
// Omitted pieces of code.

Rule.

The purpose of the Rule keyword is to represent one business rule that should be implemented. It provides additional information for a feature. A Rule is used to group together several scenarios that belong to this business rule. A Rule should contain one or more scenarios that illustrate the particular rule.

Although this word is optional, let's include it for general development.

File: src/components/Container/Container.feature

// Omitted pieces of code.
Rule: Check drag and drop behavior
// Omitted pieces of code.

Scenario (Example).

This is a concrete example that illustrates a business rule. It consists of a list of steps.

File: src/components/Container/Container.feature

// Omitted pieces of code.
Scenario: DropBoxContainer appearance
// Omitted pieces of code.

Steps.

Each step starts with Given, When, Then, And, or But.
Cucumber executes each step in a scenario one at a time, in the sequence you’ve written them in. When Cucumber tries to execute a step, it looks for a matching step definition to execute.

The steps for the first test are pretty easy, and straightforward.

File: src/components/Container/Container.feature

// Omitted pieces of code.
When I load the page
Then I should see the 'drop box container'
// Omitted pieces of code.

Eventually, the Container.feature file will end up looking like this:

File: src/components/Container/Container.feature

Feature: Drag and Drop

  Rule: Check drag and drop behavior

    Scenario: DropBoxContainer appearance
      When I load the page
      Then I should see the 'drop box container'

    Scenario Outline: DropBoxContainer data appearance
      When I load the page
      Then I should see the '<dishName>' dish

      Examples:
        | dishName          |
        | Stir-Fried Cat    |
        | Whisker Omelet    |
        | Cat tails         |
        | Delicate cat paws |
        | Wool pancakes     |
        | Cat's minion      |

    Scenario: Drag and drop behavior
      When I drag the 'Stir-Fried Cat' dish from the first table and drop it on the third table with the 'Cat tails' dish
      Then I should see that the first table contains 'Cat tails' dish
      And I should see that the third table contains 'Stir-Fried Cat' dish

Data-testid.

In order to be able to access your elements on the page, you need to find them in some way. For this purpose, you'll use the data-testid attribute, by which elements can be found. It's like a Document.getElementById(), but react testing library has its own methods for it. Mostly you'll use ByTestId, but there are a lot more: Cheat sheet.
In order for the element to be found by the test id, you need to assign this attribute to it.

File: src/components/DnD/DropBox/DropBoxContainer.tsx

// Omitted pieces of code.
return (
 <div className={styles.container} data-testid={"drop box container"}>
   {selections.map((item, index) => {
     return (
       <div className={styles.itemContainer} key={index}>
         <DropBox
           index={index}
           selection={selections[index]}
           updateSelectionsOrder={updateSelectionsOrder}
         />
         <Table />
       </div>
     );
   })}
 </div>
);
// Omitted pieces of code.

For this project, you also need to assign a few more of these attributes to other components:

File: src/components/DnD/DropBox/DropBox.tsx

// Omitted pieces of code.
return (
 <div
   className={clsx(styles.dropContainer, {
     [styles.hovered]: isHovered,
   })}
   ref={drop}
   data-testid={`drop box ${index}`}
 >
   <DragBox dragItem={selection} index={index} />
 </div>
);
// Omitted pieces of code.

File: src/components/DnD/DragBox/DragBox.tsx

// Omitted pieces of code.
return (
 <div
   className={clsx(styles.container, {
     [styles.dragging]: isDragging,
   })}
   ref={drag}
   data-testid={name}
 >
   <img src={image} className={styles.icon} />
   <p className={styles.name}>{name}</p>
 </div>
);
// Omitted pieces of code.

Test file.

There are various approaches to organizing tests. As one of the approaches, I would advise separating them into separate files. One of the files will contain only the tests themselves, in this way you'll have an isolated logic and another file into which the tests will be imported will be responsible for the configuration.
Let's look at the finished file, and I'll explain all the things that happen there.

File: src/components/Container/Container.test.tsx

import React from "react";

import { loadFeature, defineFeature } from "jest-cucumber";
import { render, cleanup } from "@testing-library/react";

import { Container } from "./Container";
import { DndProvider } from "react-dnd";
import { HTML5Backend } from "react-dnd-html5-backend";

import {
  dragAndDropBehavior,
  dropBoxContainerAppearance,
  dropBoxContainerDataAppearance,
} from "./Container.definitions";

const feature = loadFeature("./Container.feature", {
  loadRelativePath: true,
});

defineFeature(feature, (test) => {
  describe("Check drag and drop behavior", () => {
    beforeAll(() => {
      render(
        <DndProvider backend={HTML5Backend}>
          <Container />
        </DndProvider>
      );
    });
    afterAll(() => {
      cleanup();
      jest.resetAllMocks();
    });
    dropBoxContainerAppearance(test);
    dropBoxContainerDataAppearance(test);
    dragAndDropBehavior(test);
  });
});

Let's talk about everything step by step.
To connect the Container.feature file with the test file:

// Omitted pieces of code.
import { loadFeature, defineFeature } from "jest-cucumber";
// Omitted pieces of code.

For rendering tested components, and cleaning up traces after testing:

// Omitted pieces of code.
import { render, cleanup } from "@testing-library/react";
// Omitted pieces of code.

Tested components and their dependencies:

// Omitted pieces of code.
import { Container } from "./Container";
import { DndProvider } from "react-dnd";
import { HTML5Backend } from "react-dnd-html5-backend";
// Omitted pieces of code.

The tests themselves. Their implementation will be explained later, for now just import them:

// Omitted pieces of code.
import {
  dragAndDropBehavior,
  dropBoxContainerAppearance,
  dropBoxContainerDataAppearance,
} from "./Container.definitions";
// Omitted pieces of code.

To use a feature file to be tested, use the loadFeature function with the loadRelativePath param.

// Omitted pieces of code.
const feature = loadFeature("./Container.feature", {
  loadRelativePath: true,
});
// Omitted pieces of code.

And, to add a jest test for each scenario in your feature file, wrap it with the defineFeature. You can separate each scenario from the feature file into a separate describe block, but in this case, it’s not needed.

// Omitted pieces of code.
defineFeature(feature, (test) => {
  describe("Check drag and drop behavior", () => {
// Omitted pieces of code.

In the beforeAll function, you'll render your component to be tested with the render function.

// Omitted pieces of code.
    beforeAll(() => {
      render(
        <DndProvider backend={HTML5Backend}>
          <Container />
        </DndProvider>
      );
    });
// Omitted pieces of code.

To clean up everything that you "littered", use cleanup and resetAllMocks.

// Omitted pieces of code.
    afterAll(() => {
      cleanup();
      jest.resetAllMocks();
    });
// Omitted pieces of code.

And finally, just specify the tests that should be run.
You will start implementing them in the next chapter.

// Omitted pieces of code.
    dropBoxContainerAppearance(test);
    dropBoxContainerDataAppearance(test);
    dragAndDropBehavior(test);
// Omitted pieces of code.

Tests definitions.

This is where you will write tests for each scenario from the feature file.
Create a function with a descriptive name that will accept one argument - jest test, and implement the test inside this function. The test function accepts two arguments: name - which should match the scenario from the feature file, and test implementation, which also could be moved to a separate function.

File: src/components/Container/Container.definitions.tsx

export const dropBoxContainerAppearance = (test): void => {
  test("DropBoxContainer appearance", async ({ when, then }) => {
    // Omitted pieces of code.
  });
};

Test implementation is pretty simple, and should reflect the feature file steps. So, for the "When I load the page" step, you describe it as it is.

 // Omitted pieces of code.
    when("I load the page", async () => {
      await waitFor(() => "pending");
    });
 // Omitted pieces of code.

Since your component is rendered with the render function in the src/components/Container/Container.test.tsx file, you don't need any additional implementation here. You just wait till the component will be rendered with the waitFor function, and return some semantic description.
Next, as mentioned in the "Then I should see the 'drop box container'" step, you need to make sure that this element is present on the page. Please note that 'drop box container' has been replaced here with a wildcard, and is used as the testId argument. You can have many of these wildcards and arguments, the main thing is that you need to be consistent with the feature file.
To find the element by testId, use ByTestId function:

// Omitted pieces of code.
const dropBoxContainer = screen.getByTestId(testId);
// Omitted pieces of code.

And make sure the given element is present on the page with the expect and toBeInTheDocument functions.

// Omitted pieces of code.
expect(dropBoxContainer).toBeInTheDocument();
// Omitted pieces of code.

Ultimately, your test for the first scenario will look the following:

export const dropBoxContainerAppearance = (test): void => {
  test("DropBoxContainer appearance", async ({ when, then }) => {
    when("I load the page", async () => {
      await waitFor(() => "pending");
    });

    then(/^I should see the '(.*)'$/, async (testId) => {
      await waitFor(() => {
        const dropBoxContainer = screen.getByTestId(testId);
        expect(dropBoxContainer).toBeInTheDocument();
      });
    });
  });
};

If you'll run your first test with the npm run test command from the project root folder (without forgetting that the feature file should contain only this scenario), you'll see that it passed successfully.

The next scenario is pretty similar to the previous one, except you need to use the Scenario Outline here.

The Scenario Outline keyword can be used to run the same Scenario multiple times, with different combinations of values.

In this way, you'll test that all desired dishes are present on the tables.

File: src/components/Container/Container.feature

 // Omitted pieces of code.
    Scenario Outline: DropBoxContainer data appearance
      When I load the page
      Then I should see the '<dishName>' dish

      Examples:
        | dishName          |
        | Stir-Fried Cat    |
        | Whisker Omelet    |
        | Cat tails         |
        | Delicate cat paws |
        | Wool pancakes     |
        | Cat's minion      |
 // Omitted pieces of code.

The implementation of the test is also very similar, but here you use the getByText search method.

File: src/components/Container/Container.feature

export const dropBoxContainerDataAppearance = (test): void => {
  test("DropBoxContainer data appearance", async ({ when, then }) => {
    when("I load the page", async () => {
      await waitFor(() => "pending");
    });

    then(/^I should see the '(.*)' dish$/, async (dishNameTestId) => {
      await waitFor(() => {
        const dishName = screen.getByText(dishNameTestId);
        expect(dishName).toBeInTheDocument();
      });
    });
  });
};

Drag and Drop testing.

For testing drag-and-drop behavior (and not only), React Testing Library has a helper method, fireEvents. As the name suggests, it's intended for firing DOM events, such as "click", "change", "drag", etc.
The scenario for testing drag and drop assumes that if you take a dish from one table and put it on another table, they should "swap places". Just take a look and everything will become clear.

File: src/components/Container/Container.feature

 // Omitted pieces of code.
    Scenario: Drag and drop behavior
      When I drag the 'Stir-Fried Cat' dish from the first table and drop it on the third table with the 'Cat tails' dish
      Then I should see that the first table contains 'Cat tails' dish
      And I should see that the third table contains 'Stir-Fried Cat' dish
 // Omitted pieces of code.

In the first step, you need to perform a drag-and-drop of dishes. To do this, you need a draggable object and a target (drop area) where you want to drop this object.

File: src/components/Container/Container.definitions.tsx

// Omitted pieces of code.
const firstDragBox = screen.getByTestId(firstDragBoxTestId);
const thirdDropBox = screen.getByTestId("drop box 2");
// Omitted pieces of code.

Drag and drop is done in several steps:

Start drag of the draggable object (dish).
Enter the draggable object into the droppable area (table).
Drag over that droppable area.
Drop the draggable object.

So, the first step will look the following:

File: src/components/Container/Container.definitions.tsx

 // Omitted pieces of code.
when(
 /^I drag the '(.*)' dish from the first table and drop it on the third table with the '(.*)' dish$/,
 async (firstDragBoxTestId) => {
   await waitFor(() => {
     const firstDragBox = screen.getByTestId(firstDragBoxTestId);
     const thirdDropBox = screen.getByTestId("drop box 2");
     fireEvent.dragStart(firstDragBox);
     fireEvent.dragEnter(thirdDropBox);
     fireEvent.dragOver(thirdDropBox);
     fireEvent.drop(thirdDropBox);
   });
 }
);
 // Omitted pieces of code.

Further, it remains only to make sure that the expected dishes are placed on their tables.
To do this, you can use the help of yet another "within" method, with which you restrict the search area. That is, instead of searching the entire document.body, it will only search in the specified area. In your case, you are limiting your search to the drop boxes you want.
Full implementation of the last scenario:

File: src/components/Container/Container.definitions.tsx

export const dragAndDropBehavior = (test): void => {
  test("Drag and drop behavior", async ({ when, then, and }) => {
    when(
      /^I drag the '(.*)' dish from the first table and drop it on the third table with the '(.*)' dish$/,
      async (firstDragBoxTestId) => {
        await waitFor(() => {
          const firstDragBox = screen.getByTestId(firstDragBoxTestId);
          const thirdDropBox = screen.getByTestId("drop box 2");
          fireEvent.dragStart(firstDragBox);
          fireEvent.dragEnter(thirdDropBox);
          fireEvent.dragOver(thirdDropBox);
          fireEvent.drop(thirdDropBox);
        });
      }
    );
    then(
      /^I should see that the first table contains '(.*)' dish$/,
      async (dishNameTestId) => {
        await waitFor(() => {
          const firstDropBox = screen.getByTestId("drop box 0");
          expect(
            within(firstDropBox).getByText(dishNameTestId)
          ).toBeInTheDocument();
        });
      }
    );
    and(
      /^I should see that the third table contains '(.*)' dish$/,
      async (dishNameTestId) => {
        await waitFor(() => {
          const thirdDropBox = screen.getByTestId("drop box 2");
          expect(
            within(thirdDropBox).getByText(dishNameTestId)
          ).toBeInTheDocument();
        });
      }
    );
  });
};

At this point, your tests are written and ready to run successfully.

Debugging.

There may be cases where something may not work, and some of the values will not be as expected. To do this, instead of the usual console.log(), which is not appropriate here, the screen.debug() method will come to the rescue. It takes three arguments:

element?: Array<Element | HTMLDocument> | Element | HTMLDocument,
maxLength?: number,
options?: OptionsReceived,

If you want to display the entire element, just specify:

screen.debug(undefined, 99999);

In this way, you don't stick to a specific element and show the entire document, and the second argument it's just a large number to not restrict rendered information.
If you want to display only the area you want, it might look like this:

File: src/components/Container/Container.definitions.tsx

// Omitted pieces of code.
const firstDropBox = screen.getByTestId("drop box 0");
screen.debug(firstDropBox, 99999);
// Omitted pieces of code.

The result will be:

Conclusion.

This was the final part of this article, in which you learned how to test draggable components. As in the previous article, only high-level testing possibilities were shown here. For a deeper understanding, check the links below.

Useful links.

Developing and testing sortable Drag and Drop components. Part 1 - Development.

Oleksandr Tkachenko — Sun, 04 Dec 2022 10:31:19 +0000

Foreword.

In this series of articles, we will consider the task of developing and testing sortable Drag-and-Drop components. There are a lot of scenarios for using drag-and-drop behavior, here are a few of them:

Uploading or removing files and images (banalest).
Sortable tables.
Sortable notes or stickers.
Reorderable tabs. Look at your browser's opened tabs, you can reorder them with the drag-and-drop behavior.
Captchas validation (assembling the puzzle).
Games (chess and checkers).

In the first part of the article, we will create a small semblance of a restaurant in the style of the cult sitcom ALF, with the functionality of drag-and-drop sorting of dishes between visitors' tables. You can play with the working online demo by the following link Demo.

Let's imagine that in our restaurant, a newbie junior waiter mixed up the orders of visitors and placed all dishes incorrectly, and our task is to put everything in its place. To do this, we need to drag the desired dish and drop it on the appropriate table. Let's help our waiter and put things in order here.

Technologies and libraries used:

Project Structure.

The structure is as simple and clear as possible, with abstract naming to not stick to some particular use case. All data used is mocked, so as not to be distracted by the unnecessary implementation. Styles are used to make things more visually pleasing, but they don't affect the project in any way, so don’t focus on them. Some examples will omit optional code parts with appropriate comments:



// Omitted pieces of code.

Drag-and-Drop Provider.

To enable the drag-and-drop functionality in our application, we have to wrap the desired component in the DnD Provider along with the backend prop.

File: src/components/Container/Container.tsx



import { DndProvider } from "react-dnd";
import { HTML5Backend } from "react-dnd-html5-backend";
import { DropBoxContainer } from "../DnD/DropBox/DropBoxContainer";

// Omitted pieces of code.
<DndProvider backend={HTML5Backend}>
 <DropBoxContainer selectionsData={MOCK_DATA} />
</DndProvider>
// Omitted pieces of code.

Drop Box container.

The next step is to create the DropBoxContainer. It is responsible for keeping the data in the correct order, the sorting functionality, and displaying the DropBox components. In a real case, data storage can be taken to a higher level, like React context or Redux store, as well as sorting functionality, which can be placed into separate utils files, but for the sake of the demo, it will be pretty enough.
Inside this file, we will iterate over all of our data (visitor's food tables in our case) and render each item as a separate DropBox component.

File: src/components/DnD/DropBox/DropBoxContainer.tsx



// Omitted pieces of code.
<div className={styles.container}>
 {selections.map((item, index) => {
   return (
     <div className={styles.itemContainer}>
       <DropBox
         key={index}
         index={index}
         selection={selections[index]}
         updateSelectionsOrder={updateSelectionsOrder}
       />
       <Table />
     </div>
   );
 })}
</div>
// Omitted pieces of code.

Drop Box item.

Go ahead and create the DropBox file that will act as a separate container/box for each draggable file. For more clear understanding, I will try to explain in simple words using the example of our application:

File: src/components/DnD/DropBox/DropBoxContainer.tsx - It’s like a food court or food hall, the place where all visitors sit at their tables. It’s some kind of container where all things happen.
File: src/components/DnD/DropBox/DropBox.tsx - This is a specific table at which the visitor and their food are placed. It's a place where draggable items are dropped.
File: src/components/DnD/DragBox/DragBox.tsx - This is the plate of the food itself, or in other words, it’s a draggable item.

DropBox component accepts several props:

index - that we are taking from the map() function.
selection - it’s a data item, which in our case is a food dish.
updateSelectionsOrder - function to update items order.

And here comes the first "magic" associated with the drop behavior.

File: src/components/DnD/DropBox/DropBox.tsx



// Omitted pieces of code.
const [isHovered, setIsHovered] = useState(false);

const [_, drop] = useDrop({
 accept: [DragTypes.Card],
 drop(item: DragItem) {
   updateSelectionsOrder(item.index, index);
 },
 collect: (monitor) => {
   if (monitor.isOver()) {
     setIsHovered(true);
   } else {
     setIsHovered(false);
   }
 },
});
// Omitted pieces of code.

As the documentation says about the useDrop hook:

The useDrophook provides a way for you to wire in your component into the DnD system as a drop target. By passing in a specification into the useDrophook, you can specify including what types of data items the drop-target will accept, what props to collect, and more. This function returns an array containing a ref to attach to the Drop Target node and the collected props.

Let’s take a closer look piece by piece:
accept: Required. A string, a symbol, or an array of either. Specifies a type to which the drop target will react, it will only react to the items produced by the drag sources only of the specified type or types. Simply put, if you'll try to drag an item over the drop target that doesn't have a type specified in the "accept" property, the drop target will not react to it and will ignore it. It prevents interaction with unwanted and unspecified items.
drop(item, monitor): Optional. Called when a compatible drag item is dropped on the drop target. In our case, when we drag a dish and drop it on some table, this function is called, and we run the provided updateSelectionsOrder callback, to update the arrangement of dishes.
collect: Optional. The collecting function. It should return a plain object of the props to return for injection into your component. It receives two parameters, monitor and props. We use it with the DropTargetMonitor, to receive information on whether the drag operation is in progress. It helps to apply some visual effects when we hover a dish over the table and draw a dashed border around items.
To designate a drop target, we're attaching the drop returned value from the useDrop hook to the drop-target portion of the DOM.

File: src/components/DnD/DropBox/DropBox.tsx



// Omitted pieces of code.
return (
 <div
   className={clsx(styles.dropContainer, {
     [styles.hovered]: isHovered,
   })}
   ref={drop}
 >
   <DragBox dragItem={selection} index={index} />
 </div>
);
// Omitted pieces of code.

Drag Box item.

Finally, we reached our target and most delicious items (according to the ALF's taste). Let’s consider our DragBox dish. It receives two props:
dragItem: Data of the draggable item. For this application, it was simplified to only "id", "name", and "icon" properties.
index: Index of the draggable item, that will be used to operate with the drag behavior that we will explore further.

File: src/components/DnD/DragBox/DragBox.tsx



// Omitted pieces of code.
const [{ isDragging }, drag] = useDrag({
 type: DragTypes.Card,
 item: { type: DragTypes.Card, id, index, name, icon },
 collect: (monitor) => ({
   isDragging: monitor.isDragging(),
 }),
});
// Omitted pieces of code.

To wire our component as a drag source, we use the useDrag hook. Here we specify the type that we discussed above in the useDrop hook, item - draggable item data that will be passed to the drop function of the useDrop hook in the DropBox component, and collect function to receive info whether our item is dragging, for visual effects.
To designate a drag item, we're attaching the drag returned value from the useDrag hook to the draggable portion of the DOM.

File: src/components/DnD/DragBox/DragBox.tsx



// Omitted pieces of code.

return (

 <div

   className={clsx(styles.container, {

     [styles.dragging]: isDragging,

   })}

   ref={drag}

 >

   <img src={image} className={styles.icon} />

   <p className={styles.name}>{name}</p>

 </div>

);

// Omitted pieces of code.

Conclusion.

Finally, we have a working version of the application with sortable draggable components, which, with the necessary adaptation, will surely find its use in the real world. In this example, we have considered only a small part of the capabilities of this library, which will be enough to start creating your own implementation. For a deeper understanding, check out the documentation, which also has a great "Examples" section where you can find useful usage examples. In the next article, we will develop unit tests for these components and cover the main use cases.