DEV Community

Cover image for How to read the browser's localStorage with Cypress

Posted on • Updated on

How to read the browser's localStorage with Cypress

In today's “Pinch of Cypress”, learn how to get values saved in your browser's localStorage and then make assertions on them

Not everything that happens at the front end of a web application is visible to the end-user.

To have the experiences we have when using different tools on the web, a lot happens behind the scenes, and the browser is a big part of that.

Imagine a search application, which provides a quick search functionality, where buttons with the last searched terms are displayed next to the search field so that your users can easily search for these terms again without having to type them.

Let's say that one of the requirements of this functionality is that when the browser is closed and re-opened, or when a refresh occurs, these buttons remain available.

One way to solve this problem is to save this information in the browser's localStorage to know what to present to the user on the first visit or after a refresh. This logic must be implemented in the frontend, of course.

With graphical user interface (GUI) tests, we can verify that such elements (buttons, for example) are visible on the screen. Still, with Cypress, we can also access the localStorage itself by using the cypress-localstorage-commands library.

Among the various features of this library, in this post, I will demonstrate the cy.getLocalStorage(item) command.

Let's go back to the example of the search application with the quick search buttons.

Ah, one last requirement. Only the last 3 search terms should be displayed for quick search.

First, you need to add the following line of code to the cypress/support/commands.js file.

// cypress/support/commands.js

import 'cypress-localstorage-commands'
Enter fullscreen mode Exit fullscreen mode

And a possible implementation for the test would be as follows.

// cypress/integration/quickSearch.spec.js

describe('Last searched terms', () => {
  it('shows the last three searched terms for quick searching', () => {
    const termsToSearchFor = [


    termsToSearchFor.forEach(term => {

      .then($lastSearches => {
Enter fullscreen mode Exit fullscreen mode

Note that with the cy.getLocalStorage('lastSearches') command, I can chain a call to the .then function since that command executes asynchronously. In the callback function, I return the lastSearches item from the localStorage ($lastSearches), which in this case it's an array of strings. Finally, I verify that all three search terms are into the array, representing the last searches.

Interesting, isn't it?

From there, we could think about many other scenarios, and they could be tested from the end-user perspective and from the perspective of what happens behind the browser's scenes.

Some other scenarios that come to mind (which I will not implement, but just for you to think about) are:

  • The array with the lastSearches key returns two items when searching only for two terms
  • When searching for repeated terms, they are not duplicated in the same array at the localStorage
  • When I search for more than three terms, only the last three are available in the same array at the localStorage

What other scenarios come to your mind?

Did you like this content, or do you think your fellow frontend developer will like it?

Please share it on your networks. I'll be thankful!

This post was originally published in Portuguese on the Talking About Testing blog.

Would you like to learn about test automation with Cypress? Get to know my online courses on Udemy. Happy testing! 🎉

Top comments (2)

berns_churches profile image
Berns Fire Death

Awesome. Going to try this library you used for one of my projects where I can test the localStorage using window.localStorage.getItem('session.user') and my test passesbut when I run this in a docker testing automation set-up I get back a null. Any ideas on that or reasons?

walmyrlimaesilv profile image

I'd have to read the code to reason about it.
I'm glad you liked it though