Javascript

Cypress testing your IndexedDb contents with @this-dot/cypress-indexeddb

Published Jan 6, 2022

Updated Feb 13, 2023

4 min read

This article was written over 18 months ago and may contain information that is out of date. Some content may be relevant but please refer to the relevant official documentation or available resources for the latest information.

IndexedDb is a browser API for storing significant amounts of structured data locally. It is very useful when you are working on a PWA, and you need to support offline mode. Developers have been using IndexedDb to store the data changes while the user is offline, and to send those to the server when the user goes online again. But that is not the only use-case. Sometimes, there are very long forms that need to be saved locally so if the user refreshes or comes back later the previously entered data is not lost. The same scenario can be useful for a web shop's checkout logic, so users can go back to their abandoned shopping carts weeks later even.

Whether you implement your IndexedDb logic, or you use a wrapper library, such as localforage to handle IndexedDb for you, it is not that straightforward to test these implementations. If you would like to check out the source code, feel free to visit our repository.

Our example application

For our example, we have a simple user form with a few input fields. This form saves every entry that comes from the user. It uses a debounce logic that waits for 1 second before saving the form contents into indexedDb. When the user submits the form, it waits for the last write operation. After that finishes, it submits the form and then clears the indexedDb. If the proper fields are saved to the database, and if the user opens this page, those values are loaded.

This example application uses localforage to populate IndexedDb. The database name is FORM_CACHE and will have a keyvaluepairs object-store created by localforage. Inside the object-store, we will use the user_form key to store the values. Let's write our tests!

Installing the plugin

To use the helper functions, we need to install the package first.

npm install @this-dot/cypress-indexeddb

After the install finishes, go inside your Cypress support folder, and add the following line to your commands.ts file:

import '@this-dot/cypress-indexeddb';

Create a cypress-indexeddb-namespace.ts file inside the same support folder, and add the following typings:

  declare namespace Cypress {
    interface Chainable<Subject> {
      clearIndexedDb(databaseName: string): void;
      openIndexedDb(databaseName: string, version?: number): Chainable<IDBDatabase>;
      createObjectStore(storeName: string): Chainable<IDBObjectStore>;
      getStore(storeName: string): Chainable<IDBObjectStore>;
      createItem(key: string, value: unknown): Chainable<IDBObjectStore>;
      readItem<T = unknown>(key: IDBValidKey | IDBKeyRange): Chainable<T>;
      updateItem(key: string, value: unknown): Chainable<IDBObjectStore>;
      deleteItem(key: string): Chainable<IDBObjectStore>;
    }
  }

Finally, import the cypress-indexeddb-namespace.ts contents in the index.ts file of the same support folder.

import './commands';
import './namespace';

Now that you are all set up, you can use the commands in your tests.

Test setup

Since IndexedDb stores data locally, it is imperative to delete previous databases before every test run. That way, we can make sure that the tests run in isolation, and data from other tests won't leak out. After deleting the database, we also want to set up the connections so we can access and manipulate the database in our tests later.

describe(`User Form`, () => {

  beforeEach(() => {
    cy.clearIndexedDb('FORM_CACHE');
    cy.openIndexedDb('FORM_CACHE')
      .as('formCacheDB')
      .createObjectStore('keyvaluepairs')
      .as('objectStore');
  })

});

When we open a connection to the FORM_CACHE database and create the keyvaluepairs object-store, we can use the .as() method to alias them for later access. The .get() command could not be overwritten, so we have the getIndexedDb and the getStore methods to retrieve them.

Reading from the database

We have our before hook, so let's test the saving functionality of the form. We enter some values into the form with cypress, then we wait for the debounced write operation. After that, we simply access the database, read the contents and assert them.

describe(`User Form`, () => {

  // beforeEach

  it(`entering data into the form saves it to the indexedDb`, () => {
    cy.visit('/user-form');

    cy.get('#firstName').should('be.visible').type('Hans');
    cy.get('#lastName').should('be.visible').type('Gruber');
    cy.get('#country').should('be.visible').type('Germany');
    cy.get('#city').should('be.visible').type('Berlin');

    cy.log('Waiting for the debounceTime to start a db write').wait(1100);

    cy.getStore('@objectStore').readItem('user_form').should('deep.equal', {
      firstName: 'Hans',
      lastName: 'Gruber',
      country: 'Germany',
      city: 'Berlin',
      address: '',
      addressOptional: '',
    });
  });

});

We can use the .getStore('@objectStore') method to retrieve a previously aliased store instance for ourselves. The .readItem(key) method retrieves the contents of that key in the store. We can use the .should() method to assert the retrieved value. Here we use the deep.equal assertion.

Deleting from the database

Sometimes users delete everything that is stored locally. They can do it from the developer tools, or maybe they run clean-up software that removes these for them. Anyways, if something like that happens, they cannot get back to the state they left the form in. Let's simulate it by deleting items from the database.

describe(`User Form`, () => {

  // beforeEach

  it(`when the indexedDb is deleted manually and then the page reloaded, the form does not populate`, () => {
    cy.visit('/user-form');

    cy.get('#firstName').should('be.visible').type('Hans');
    cy.get('#lastName').should('be.visible').type('Gruber');
    cy.get('#country').should('be.visible').type('Germany');
    cy.get('#city').should('be.visible').type('Berlin');

    cy.log('Waiting for the debounceTime to start a db write').wait(1100);

    cy.log('user manually clears the IndexedDb')
      .getStore('@objectStore')
      .deleteItem('user_form')
      .reload();

    cy.get('#firstName').should('be.visible').and('have.value', '');
    cy.get('#lastName').should('be.visible').and('have.value', '');
    cy.get('#country').should('be.visible').and('have.value', '');
    cy.get('#city').should('be.visible').and('have.value', '');
  });

});

We again get the previously aliased store and we call the .deleteItem(key) method on it. After that, we can chain other cypress methods off. For example, we reload the page in this particular test.

Adding data to the database

We can see that if we empty the database, the values won't load into the form. We should write a test to populate these values before loading the page and test if they are loaded into the form properly.

describe(`User Form`, () => {

  // beforeEach

  it(`when there is relevant data in the indexedDb, the form gets populated when the page opens`, () => {
    cy.getStore('@objectStore').createItem('user_form', {
      firstName: 'John',
      lastName: 'McClane',
      country: 'USA',
      city: 'New York',
    });

    cy.visit('/user-form');

    cy.get('#firstName').should('be.visible').and('have.value', 'John');
    cy.get('#lastName').should('be.visible').and('have.value', 'McClane');
    cy.get('#country').should('be.visible').and('have.value', 'USA');
    cy.get('#city').should('be.visible').and('have.value', 'New York');
  });

});

We can call the .createItem(key, value) method to populate the provided key in an object-store. We can use any value.

Testing if our code clears the database properly

We can create/update and read data in our database. We can even delete values from it using our library, but what about testing our code? We have a wrapper class around localforage in the codebase that handles database deletion on submit. We should test that functionality as well!

describe(`User Form`, () => {

  // beforeEach

  it(`submitting the form clears the indexedDb`, () => {
    cy.getStore('@objectStore').createItem('user_form', {
      firstName: 'John',
      lastName: 'McClane',
      country: 'USA',
      city: 'New York',
    });

    cy.visit('/user-form');

    cy.get('#address').type('23rd Street 12');
    cy.get(`[data-test-id="submit button"]`).should('be.visible').and('not.be.disabled').click();

    cy.log('Waiting for the save event and DB write to occur').wait(1100);

    cy.getStore('@objectStore').readItem('user_form').should('be.undefined');
  });

});

We use the .createItem() method to make sure that there are values populated into the database. Then, we use cypress to make our app put some other values into the database. After, we submit the form we wait for the debounce handlers to handle the operations and lastly, we validate that the value that we previously populated should now be undefined.

How to run the above tests

If you would like to see it in action, please check out our git repository. After running npm install you should be able to start the tests by running the npm run e2e:debug command.

This Dot is a consultancy dedicated to guiding companies through their modernization and digital transformation journeys. Specializing in replatforming, modernizing, and launching new initiatives, we stand out by taking true ownership of your engineering projects.

We love helping teams with projects that have missed their deadlines or helping keep your strategic digital initiatives on course. Check out our case studies and our clients that trust us with their engineering.

About the author(s)

Balázs Tápai
He is a Software Engineer with a passion for automated testing. He loves Angular on the Front-End and NestJS on the Back-End. He also uses Cypress to reduce developer anxiety before demo meetings.
@TapaiBalazs @TapaiBalazs

The Journey To Making A New Framework: TanStack Start with Tanner Linsley

Danny Thompson, Director of Technology at This Dot Labs, talks with Tanner Linsley, Creator of TanStack, about his latest project, TanStack Start. They discuss the challenges of existing frameworks like Next.js and Remix, the development of TanStack Router, and the future of React Server Components. Tanner also explains how caching strategies and fine-grained invalidation can transform the user experience. Chapters - - Introduction & Tanner’s Background (00:00) - Going Full-Time on TanStack (01:00) - The Birth of TanStack Router (02:21) - Why Build Another Framework? (04:00) - React Server Components: Potential & Limitations (07:05) - Fine-Grained Cache Invalidation & UX (09:02) - Parallel Data Fetching in Routing (13:39) - TanStack Start: Alpha & Future Plans (16:41) - Where to Learn More About TanStack (18:48) Find Tanner Linsley on Social Media Twitter: https://x.com/tannerlinsley Linkedin: https://www.linkedin.com/in/tannerlinsley/ Github: https://github.com/tannerlinsley TanStack: https://tanstack.com/ Sponsored by Wix Studio...

Oct 9, 2024

1 min

TanStack QueryJavaScriptReact

The HTML Dialog Element: Enhancing Accessibility and Ease of Use

The HTML Dialog Element: Enhancing Accessibility and Ease of Use Dialogs are a common component added to applications, whether on the web or in native applications. Traditionally there has not been a standard way of implementing these on the web, resulting in many ad-hoc implementations that don’t act consistently across different web applications. Often, commonly expected features are missing from dialogs due to the complexity of implementing them. However, web browsers now offer a standard dialog element. Why use the dialog element? The native dialog element streamlines the implementation of dialogs, modals, and other kinds of non-modal dialogs. It does this by implementing many of the features needed by dialogs for you that are already baked into the browser. This is helpful as it reduces the burden on the developer when making their applications accessible by ensuring that user expectations concerning interaction are met, and it can also potentially simplify the implementation of dialogs in general. Basic usage Adding a dialog using the new tag can be achieved with just a few lines of code. ` However, adding the dialog alone won’t do anything to the page. It will show up only once you call the .showModal() method against it. ` Then if you want to close it you can call the .close() method on the dialog, or press the escape key to close it, just like most other modals work. Also, note how a backdrop appears that darkens the rest of the page and prevents you from interacting with it. Neat! Accessibility and focus management Correctly handling focus is important when making your web applications accessible to all users. Typically you have to move the current focus to the active dialog when showing them, but with the dialog element that’s done for you. By default, the focus will be set on the first focusable element in the dialog. You can optionally change which element receives focus first by setting the autofocus attribute on the element you want the focus to start on, as seen in the previous example where that attribute was added to the close element. Using the .showModal() method to open the dialog also implicitly adds the dialog ARIA role to the dialog element. This helps screen readers understand that a modal has appeared and the screen so it can act accordingly. Adding forms to dialogs Forms can also be added to dialogs, and there’s even a special method value for them. If you add a element with the method set to dialog then the form will have some different behaviors that differ from the standard get and post form methods. First off, no external HTTP request will be made with this new method. What will happen instead is that when the form gets submitted, the returnValue property on the form element will be set to the value of the submit button in the form. So given this example form: ` The form element with the example-form id will have its returnValue set to Submit. In addition to that, the dialog will close immediately after the submit event is done being handled, though not before automatic form validation is done. If this fails then the invalid event will be emitted. You may have already noticed one caveat to all of this. You might not want the form to close automatically when the submit handler is done running. If you perform an asynchronous request with an API or server you may want to wait for a response and show any errors that occur before dismissing the dialog. In this case, you can call event.preventDefault() in the submit event listener like so: ` Once your desired response comes back from the server, you can close it manually by using the .close() method on the dialog. Enhancing the backdrop The backdrop behind the dialog is a mostly translucent gray background by default. However, that backdrop is fully customizable using the ::backdrop pseudo-element. With it, you can set a background-color to any value you want, including gradients, images, etc. You may also want to make clicking the backdrop dismiss the modal, as this is a commonly implemented feature of them. By default, the <dialog> element doesn’t do this for us. There are a couple of changes that we can make to the dialog to get this working. First, an event listener is needed so that we know when the user clicks away from the dialog. ` Alone this event listener looks strange. It appears to dismiss the dialog whenever the dialog is clicked, not the backdrop. That’s the opposite of what we want to do. Unfortunately, you cannot listen for a click event on the backdrop as it is considered to be part of the dialog itself. Adding this event listener by itself will effectively make clicking anywhere on the page dismiss the dialog. To correct for this we need to wrap the contents of the dialog content with another element that will effectively mask the dialog and receive the click instead. A simple element can do! ` Even this isn’t perfect though as the contents of the div may have elements with margins in them that will push the div down, resulting in clicks close to the edges of the dialog to dismiss it. This can be resolved by adding a couple of styles the the wrapping div that will make the margin stay contained within the wrapper element. The dialog element itself also has some default padding that will exacerbate this issue. ` The wrapping div can be made into an inline-block element to contain the margin, and by moving the padding from the parent dialog to the wrapper, clicks made in the padded portions of the dialog will now interact with the wrapper element instead ensuring it won’t be dismissed. Conclusion Using the dialog element offers significant advantages for creating dialogs and modals by simplifying implementation with reasonable default behavior, enhancing accessibility for users that need assistive technologies such as screen readers by using automatic ARIA role assignment, tailored support for form elements, and flexible styling options....

Oct 25, 2024

4 mins

HTMLJavaScript

BullMQ with ExpressJS

Node.js uses an event loop to process asynchronous tasks. The event loop is responsible for handling the execution of asynchronous tasks, but it does it in a single thread. If there is some CPU-intensive or long-running (blocking) logic that needs to be executed, it should not be run on the main thread. This is where BullMQ can help us. In this blog post, we are going to set up a basic queue, using BullMQ. If you'd like to jump right into developing with a queue, check out our starter.dev kit for ExpressJS, where a fully functioning queue is already provided for you. Why and when to use a queue? BullMQ is a library that can be used to implement message queues in Node.js applications. A message queue allows different parts of an application, or different applications, to communicate with each other asynchronously by sending and receiving messages. This can be useful in a variety of situations, such as when one part of the application needs to perform a task that could take a long time, or when different parts of the application need to be decoupled from each other for flexibility and scalability. If you need to process large numbers of messages in a distributed environment, it can help you solve your problems. One such scenario to use a queue is when you need to deal with webhooks. Webhook handler endpoints usually need to respond with 2xx quickly, therefore, you cannot put long running tasks inside that handler, but you also need to process the incoming data. A good way of mitigating this is to put the incoming data into the queue, and respond quickly. The processing gets taken care of with the BullMQ worker, and if it is set up correctly, it will run inside a child process not blocking the main thread. Prerequisites BullMQ utilizes Redis to handle its message queue. In development mode, we are using docker-compose to start up a redis instance. We expose the redis docker container's 6379 port to be reachable on the host machine. We also mount the /misc/data and the misc/conf folders to preserve data for our local development environments. ` We can start up our infrastructure with the docker-compose up -d command and we can stop it with the docker-compose stop command. We also need to set up connection information for BullMQ. We make it configurable by using environment variables. ` To start working with BullMQ, we also need to install it to our node project: ` Setting up a queue Creating a queue is pretty straightforward, we need to pass the queue name as a string and the connection information. ` We also create a function that can be used to add jobs to the queue from an endpoint handler. I suggest setting up a rule that removes completed and failed jobs in a timely manner. In this example we remove completed jobs after an hour from redis, and we leave failed jobs for a day. These values depend on what you want to achieve, It can very well happen that in a production app, you would keep the jobs for weeks. ` It would be called when a specific endpoint gets called. ` The queue now can store jobs, but in order for us to be able to process those jobs, we need to set up a worker. Put the processing into a thread We set up a worker with an async function at the beginning. The worker needs the same name as the queue to start consuming jobs in that queue. It also needs the same connection information as the queue we set up before. ` After we create the worker and set up event listeners, we call the setUpWorker() method in the queue.ts file after the Queue gets created. Let's set up the job processor function. ` This example processor function doesn't do much, but if we had a long running job, like complex database update operations, or sending data towards a third-party API, we would do it here. Let's make sure our worker will run these jobs on a separate thread. ` If you provide a file path to the worker as the second parameter, BullMQ will run the function exported from the file in a separate thread. That way, the main thread is not used for the CPU intense work the processor does. The above example works if you run the TypeScript compiler on your back-end code (tsc), but if you prefer keeping your code in TypeScript and run the logic with ts-node, then you should use the TypeScript file as your processor path. ` The problem with bundlers Sometimes, your back-end code gets bundled with webpack. For example, if you use NX to keep your front-end and back-end code together in one repository, you will notice that your back-end code gets bundled with webpack. In order to be able to run your processors in a separate thread, you need to tweak your project.json configuration: ` Conclusion In an ExpressJS application, running CPU intense tasks on the main thread could cause your endpoints to turn unresponsive and/or slow. Moving these tasks into a different thread can help alleviate performance issues, and using BullMQ can help you out greatly. If you want to learn more about NodeJS, check out node.framework.dev for a curated list of libraries and resources. If you are looking to start a new ExpressJS project, check out our starter kit resources at starter.dev...

Feb 24, 2023

4 mins

Express.js

How Nuxt Studio is Redefining Developer & User Experience with Baptiste Leproux & Ferdinand Coumau

In this episode of the Modern Web Podcast, Danny Thompson sits down with Ferdinand Como and Baptiste Leproux from Nuxt Labs to uncover the story behind Nuxt Studio, a tool that's transforming how developers and non-technical users interact with Nuxt applications. Ferdinand and Baptiste share how Nuxt Studio bridges the gap between developer customization and user-friendly content management. Built to empower agencies, freelancers, and their clients, Nuxt Studio combines powerful features like live previews, Vue component integration, and schema-driven forms to make managing content seamless. The conversation also explores the broader mission of Nuxt Labs—building sustainable open-source tools that enhance developer experience and meet real-world needs. With insights into the future of Nuxt Studio and its potential to scale for larger organizations, this episode is a must-listen for anyone passionate about innovation in web development. Chapters 1. Introduction and Setting the Stage (00:00:00) 2. The Vision Behind Nuxt Studio (00:03:10) 3. Nuxt Studio’s Core Features (00:08:45) 4. Challenges in Building Nuxt Studio (00:16:20) 5. Target Audience and Use Cases (00:22:35) 6. Sustainability in Open Source (00:29:00) 7. The Future of Nuxt Studio (00:35:10) 8. Nuxt Studio’s Role in the Nuxt Ecosystem (00:42:30) 9. Closing Thoughts and What’s Next (00:48:00) 10. Sponsor Shoutout and Wrap-Up (00:53:20) Follow Baptiste Leproux and Ferdinand Coumau Baptiste Twitter: https://x.com/_larbish Ferdinand Twitter: https://x.com/CoumauFerdinand Baptiste Linkedin: https://www.linkedin.com/in/baptiste-leproux-618842b0/ Ferdinand Linkedin: https://www.linkedin.com/in/ferdinand-coumau-nuxt/ Sponsored by This Dot: thisdot.co...

Nov 20, 2024

2 mins

VueNuxtJS

Let's innovate together!

We're ready to be your trusted technical partners in your digital innovation journey.

Whether it's modernization or custom software solutions, our team of experts can guide you through best practices and how to build scalable, performant software that lasts.

Cypress testing your IndexedDb contents with @this-dot/cypress-indexeddb

Our example application

Installing the plugin

Test setup

Reading from the database

Deleting from the database

Adding data to the database

Testing if our code clears the database properly

How to run the above tests

Balázs Tápai

You might also like

The Journey To Making A New Framework: TanStack Start with Tanner Linsley

The HTML Dialog Element: Enhancing Accessibility and Ease of Use

BullMQ with ExpressJS

How Nuxt Studio is Redefining Developer & User Experience with Baptiste Leproux & Ferdinand Coumau

Let's innovate together!

You might also like

The Journey To Making A New Framework: TanStack Start with Tanner Linsley

The HTML Dialog Element: Enhancing Accessibility and Ease of Use

BullMQ with ExpressJS

How Nuxt Studio is Redefining Developer & User Experience with Baptiste Leproux & Ferdinand Coumau