{"id":16360098,"url":"https://github.com/javierbrea/cypress-localstorage-commands","last_synced_at":"2025-05-15T09:05:28.337Z","repository":{"id":37734030,"uuid":"217675700","full_name":"javierbrea/cypress-localstorage-commands","owner":"javierbrea","description":"Extends Cypress' cy commands with localStorage methods. Allows preserving localStorage between tests and spec files. Allows disabling localStorage.","archived":false,"fork":false,"pushed_at":"2024-12-06T12:13:02.000Z","size":10012,"stargazers_count":178,"open_issues_count":6,"forks_count":9,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-07T03:17:55.743Z","etag":null,"topics":["commands","cypress","cypress-plugin","local-storage","localstorage","methods","persistence","testing","testing-tools","utilities"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/javierbrea.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-10-26T07:59:14.000Z","updated_at":"2024-12-06T12:11:51.000Z","dependencies_parsed_at":"2023-02-09T14:25:39.072Z","dependency_job_id":"7a4bfbbb-1568-4914-9a45-4c665fc4d3e0","html_url":"https://github.com/javierbrea/cypress-localstorage-commands","commit_stats":{"total_commits":723,"total_committers":7,"mean_commits":"103.28571428571429","dds":0.5712309820193637,"last_synced_commit":"2c6502168075e9a86898923427d71d9cdd382406"},"previous_names":[],"tags_count":41,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/javierbrea%2Fcypress-localstorage-commands","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/javierbrea%2Fcypress-localstorage-commands/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/javierbrea%2Fcypress-localstorage-commands/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/javierbrea%2Fcypress-localstorage-commands/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/javierbrea","download_url":"https://codeload.github.com/javierbrea/cypress-localstorage-commands/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248890832,"owners_count":21178515,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["commands","cypress","cypress-plugin","local-storage","localstorage","methods","persistence","testing","testing-tools","utilities"],"created_at":"2024-10-11T02:10:33.168Z","updated_at":"2025-04-14T13:48:27.752Z","avatar_url":"https://github.com/javierbrea.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build status][build-image]][build-url] [![Coverage Status][coveralls-image]][coveralls-url] [![Quality Gate][quality-gate-image]][quality-gate-url] [![Mutation testing status][mutation-image]][mutation-url]\n\n[![Renovate](https://img.shields.io/badge/renovate-enabled-brightgreen.svg)](https://renovatebot.com) [![Last commit][last-commit-image]][last-commit-url] [![Last release][release-image]][release-url]\n\n[![NPM downloads][npm-downloads-image]][npm-downloads-url] [![License][license-image]][license-url]\n\n# Cypress localStorage commands\n\nExtends Cypress' cy commands with localStorage methods. Allows preserving localStorage between tests and spec files, and disabling localStorage.\n\n## The problems\n\n* You want to preserve localStorage between Cypress tests.\n* You want to preserve localStorage between Cypress spec files.\n* You want to disable localStorage to check error handling.\n\n## This solution\n\nThis solution allows you to use all browser localStorage methods through Cypress commands, and preserve it between tests and spec files. It also allows to simulate that localStorage is disabled in the browser.\n\n## Alternatives\n\nAs from Cypress 12, you can use [`cy.session`](https://docs.cypress.io/api/commands/session) and [Cypress Test Isolation](https://docs.cypress.io/guides/core-concepts/test-isolation) in order to persist localStorage between tests. __Anyway, this plugin can be still used for an easier manipulation of the localStorage, writing localStorage assertions and even disabling it for checking the error handling.__\n\n## Installation\n\nThis module is distributed via npm which is bundled with node and should be installed as one of your project's devDependencies:\n\n```bash\nnpm i --save-dev cypress-localstorage-commands\n```\n\n### Installing commands\n\n`cypress-localstorage-commands` extends Cypress' cy commands.\n\nAt the top of your Cypress' support file (usually `cypress/support/e2e.js` for `e2e` testing type):\n\n```javascript\nimport \"cypress-localstorage-commands\";\n```\n\nRead [Cypress configuration docs](https://docs.cypress.io/guides/references/configuration) for further info.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eInstalling commands in Cypress \u003c10.0\u003c/strong\u003e\u003c/summary\u003e\n\nAdd this line to your project's `cypress/support/index.js`:\n\n```js\nimport \"cypress-localstorage-commands\"\n```\n\n\u003c/details\u003e\n\n### Installing Node events\n\n__⚠ In order to support preserving localStorage across Cypress spec files, the plugin's Node events must be installed also.__ Otherwise, localStorage will be preserved only across tests in the same spec file.\n\nIn the `cypress.config.js` file:\n\n```javascript\nmodule.exports = {\n  e2e: {\n    setupNodeEvents(on, config) {\n      require(\"cypress-localstorage-commands/plugin\")(on, config);\n      return config;\n    },\n  },\n};\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eInstalling Node events in Cypress \u003c10.0\u003c/strong\u003e\u003c/summary\u003e\n\nIn the `cypress/plugins/index.js` file:\n\n```javascript\nmodule.exports = (on, config) =\u003e {\n  require(\"cypress-localstorage-commands/plugin\")(on, config);\n  return config;\n};\n```\n\n\u003c/details\u003e\n\n## Usage\n\n### Commands\n\n#### `cy.saveLocalStorage([snapshotName])`\n\nSaves current localStorage values into an internal \"snapshot\".\n\n* `snapshotName` _(String)_: Optionally, a `snapshotName` can be provided, and then data from localStorage will be saved into a snapshot with that name. So, multiple snapshots can be stored.\n\n#### `cy.restoreLocalStorage([snapshotName])`\n\nRestores localStorage to previously \"snapshot\" saved values. __\n\n* `snapshotName` _(String)_: Optional. If provided, the localStorage will be restored using data from that specific snapshot.\n\n#### `cy.clearLocalStorageSnapshot([snapshotName])`\n\nClears localStorage \"snapshot\" values, so previously saved values are cleaned.\n\n* `snapshotName` _(String)_: Optional. If provided, only data from that specific snapshot will be cleared.\n\n#### `cy.getLocalStorage(item)`\n\nGets localStorage item. Equivalent to `localStorage.getItem` in browser.\n\n* `item` _(String)_: Item to get from `localStorage`.\n\n#### `cy.setLocalStorage(item, value)`\n\nSets localStorage item. Equivalent to `localStorage.setItem` in browser.\n\n* `item` _(String)_: Item to set value.\n* `value` _(String)_: Value to be set.\n\n#### `cy.removeLocalStorage(item)`\n\nRemoves localStorage item. Equivalent to `localStorage.removeItem` in browser.\n\n* `item` _(String)_: Item to be removed.\n\n#### `cy.disableLocalStorage(options)`\n\nDisables localStorage. It produces localStorage methods to throw errors.\n\n* `options` _(Object)_: Options to use when disabling `localStorage`.\n  * `withError` _(Error)_: If provided, invocations to `localStorage` methods will throw this error.\n\n### Preserving local storage between tests\n\nUse `cy.saveLocalStorage()` to save a snapshot of current `localStorage` at the end of one test, and use the `cy.restoreLocalStorage()` command to restore it at the beginning of another one. _The usage of `beforeEach` and `afterEach` is recommended for this purpose._\n\n\u003e ⚠ When the [plugin's Node events are installed](#installing-node-events), the `cy.restoreLocalStorage()` command will be able to restore the localStorage snapshots saved in other spec files. Otherwise, snapshots are completely cleared between spec files.\n\n### Examples\n\n#### Cookies button example\n\nNext example shows how this package can be used to test a \"cookies button\" _(which in theory sets a flag into `localStorage` and can be clicked only once)_\n\n```js\ndescribe(\"Accept cookies button\", () =\u003e {\n  const COOKIES_BUTTON = \"#accept-cookies\";\n\n  before(() =\u003e {\n    cy.clearLocalStorageSnapshot();\n  });\n\n  beforeEach(() =\u003e {\n    cy.restoreLocalStorage();\n    cy.visit(\"/\");\n  });\n\n  afterEach(() =\u003e {\n    cy.saveLocalStorage();\n  });\n\n  it(\"should be visible\", () =\u003e {\n    cy.get(COOKIES_BUTTON).should(\"be.visible\");\n  });\n\n  it(\"should not be visible after clicked\", () =\u003e {\n    cy.get(COOKIES_BUTTON).click();\n    cy.get(COOKIES_BUTTON).should(\"not.be.visible\");\n  });\n\n  it(\"should not be visible after reloading\", () =\u003e {\n    cy.get(COOKIES_BUTTON).should(\"not.be.visible\");\n  });\n});\n```\n\n\u003e Note the usage of `beforeEach` and `afterEach` for preserving `localStorage` between all tests. Also `cy.clearLocalStorageSnapshot` is used in the `before` statement to avoid possible conflicts with other spec files preserving localStorage.\n\n#### localStorage assertions\n\nBased on the previous example, assertions could be added to check values of `localStorage`:\n\n```js\ndescribe(\"localStorage cookies-accepted item\", () =\u003e {\n  beforeEach(() =\u003e {\n    cy.restoreLocalStorage();\n    cy.visit(\"/\");\n  });\n\n  afterEach(() =\u003e {\n    cy.saveLocalStorage();\n  });\n\n  it(\"should be null first time page is visited\", () =\u003e {\n    cy.getLocalStorage(\"cookies-accepted\").should(\"equal\", null);\n  });\n\n  it(\"should be true after clicking cookies button\", () =\u003e {\n    cy.get(\"#accept-cookies\").click();\n    cy.getLocalStorage(\"cookies-accepted\").should(\"equal\", \"true\");\n  });\n\n  it(\"should be true after reloading\", () =\u003e {\n    cy.getLocalStorage(\"cookies-accepted\").then(cookiesAccepted =\u003e {\n      expect(cookiesAccepted).to.equal(\"true\");\n    });\n  });\n});\n```\n\n#### Named snapshots\n\nNext example shows how named snapshots can be used to storage different states of `localStorage` and restore one or another depending of the test:\n\n```js\ndescribe(\"Accept cookies button\", () =\u003e {\n  const COOKIES_BUTTON = \"#accept-cookies\";\n\n  before(() =\u003e {\n    cy.clearLocalStorageSnapshot();\n  });\n\n  it(\"should be visible\", () =\u003e {\n    cy.visit(\"/\");\n    cy.get(COOKIES_BUTTON).should(\"be.visible\");\n    cy.saveLocalStorage(\"cookies-not-accepted\");\n  });\n\n  it(\"should not exist after clicked\", () =\u003e {\n    cy.get(COOKIES_BUTTON).click();\n    cy.get(COOKIES_BUTTON).should(\"not.exist\");\n    cy.saveLocalStorage(\"cookies-accepted\");\n  });\n\n  it(\"should be visible when cookies are not accepted\", () =\u003e {\n    cy.restoreLocalStorage(\"cookies-not-accepted\");\n    cy.visit(\"/\");\n    cy.get(COOKIES_BUTTON).should(\"be.visible\");\n  });\n\n  it(\"should not exist when cookies are accepted\", () =\u003e {\n    cy.restoreLocalStorage(\"cookies-accepted\");\n    cy.visit(\"/\");\n    cy.get(COOKIES_BUTTON).should(\"not.exist\");\n  });\n});\n```\n\n### Disabling localStorage\n\nUse `cy.disableLocalStorage()` to simulate that `localStorage` is disabled, producing that any invocation to `localStorage.setItem`, `localStorage.getItem`, `localStorage.removeItem` or `localStorage.clear` will throw an error. [As MDN docs recommend](https://developer.mozilla.org/en-US/docs/Web/API/Storage/setItem), _\"developers should make sure to always catch possible exceptions from setItem()\"_. This command allows to test that possible exceptions are handled correctly.\n\nNote that:\n\n* Only pages loaded after calling this command will have `localStorage` disabled, so always use `cy.reload` or `cy.visit` after executing it.\n* The `localStorage` only remains disabled for all pages loaded during the current test. If you want to disable it for multiple tests, execute it in all of them, or in a `beforeEach` statement.\n* If any of the other plugin commands (except `clearLocalStorageSnapshot`) is executed while `localStorage` is disabled, it will do nothing but producing a Cypress log as: _\"localStorage.setItem is disabled\"_\n\n### Examples\n\n#### Disabling localStorage in a single test\n\nBased on previous \"Accept cookies button\" example, next tests could be added:\n\n```js\n//...\nconst LOCALSTORAGE_DISABLED_WARNING = \"#localstorage-disabled-warning\";\nconst LOCALSTORAGE_ERROR = \"#localstorage-error\";\n\n//... should not be visible after clicked\n\nit(\"should still be visible when reloading if localStorage is disabled\", () =\u003e {\n  cy.disableLocalStorage();\n  cy.reload();\n  cy.get(COOKIES_BUTTON).should(\"be.visible\");\n});\n\nit(\"should display warning if localStorage is disabled\", () =\u003e {\n  cy.disableLocalStorage();\n  cy.reload();\n  cy.get(LOCALSTORAGE_DISABLED_WARNING).should(\"be.visible\");\n});\n\nit(\"should display localStorage error message\", () =\u003e {\n  cy.disableLocalStorage();\n  cy.reload();\n  cy.get(LOCALSTORAGE_ERROR).should(\"have.text\", \"Error\");\n});\n\n// ...should not be visible after reloading\n```\n\n#### Disabling localStorage in multiple tests\n\n```js\ndescribe(\"when localStorage is disabled\", () =\u003e {\n  beforeEach(() =\u003e {\n    cy.disableLocalStorage({\n      withError: new Error(\"Disabled by cypress-localstorage-commands\"),\n    });\n    cy.visit(\"/\");\n  });\n\n  it(\"should display localStorage warning\", () =\u003e {\n    cy.get(\"#localstorage-disabled-warning\").should(\"be.visible\");\n  });\n\n  it(\"should display localStorage error message\", () =\u003e {\n    cy.get(\"#localstorage-error\").should(\"have.text\", \"Disabled by cypress-localstorage-commands\");\n  });\n\n  it(\"should display accept-cookies button disabled\", () =\u003e {\n    cy.get(\"#accept-cookies\").should(\"be.disabled\");\n  });\n});\n```\n\n## Usage with TypeScript\n\nFor those writing [TypesScript tests in Cypress][cypress-typescript], this package includes TypeScript declarations.\n\nAdd \"cypress-localstorage-commands\" to the `types` property of the `tsconfig.json` file:\n\n```json\n{\n  \"compilerOptions\": {\n    \"types\": [\"cypress\", \"cypress-localstorage-commands\"]\n  }\n}\n```\n\nOr reference the package in the files using it:\n\n```typescript\n/// \u003creference types=\"cypress-localstorage-commands\" /\u003e\n```\n\n## Contributing\n\nContributors are welcome.\nPlease read the [contributing guidelines](.github/CONTRIBUTING.md) and [code of conduct](.github/CODE_OF_CONDUCT.md).\n\n## License\n\nMIT, see [LICENSE](./LICENSE) for details.\n\n[coveralls-image]: https://coveralls.io/repos/github/javierbrea/cypress-localstorage-commands/badge.svg\n[coveralls-url]: https://coveralls.io/github/javierbrea/cypress-localstorage-commands\n[build-image]: https://github.com/javierbrea/cypress-localstorage-commands/workflows/build/badge.svg?branch=master\n[build-url]: https://github.com/javierbrea/cypress-localstorage-commands/actions?query=workflow%3Abuild+branch%3Amaster\n[mutation-image]: https://img.shields.io/endpoint?style=flat\u0026url=https%3A%2F%2Fbadge-api.stryker-mutator.io%2Fgithub.com%2Fjavierbrea%2Fcypress-localstorage-commands%2Fmaster\n[mutation-url]: https://dashboard.stryker-mutator.io/reports/github.com/javierbrea/cypress-localstorage-commands/master\n[last-commit-image]: https://img.shields.io/github/last-commit/javierbrea/cypress-localstorage-commands.svg\n[last-commit-url]: https://github.com/javierbrea/cypress-localstorage-commands/commits\n[license-image]: https://img.shields.io/npm/l/cypress-localstorage-commands.svg\n[license-url]: https://github.com/javierbrea/cypress-localstorage-commands/blob/master/LICENSE\n[npm-downloads-image]: https://img.shields.io/npm/dm/cypress-localstorage-commands.svg\n[npm-downloads-url]: https://www.npmjs.com/package/cypress-localstorage-commands\n[quality-gate-image]: https://sonarcloud.io/api/project_badges/measure?project=javierbrea_cypress-localstorage-commands\u0026metric=alert_status\n[quality-gate-url]: https://sonarcloud.io/dashboard?id=javierbrea_cypress-localstorage-commands\n[release-image]: https://img.shields.io/github/release-date/javierbrea/cypress-localstorage-commands.svg\n[release-url]: https://github.com/javierbrea/cypress-localstorage-commands/releases\n\n[cypress-typescript]: https://docs.cypress.io/guides/tooling/typescript-support.html\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjavierbrea%2Fcypress-localstorage-commands","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjavierbrea%2Fcypress-localstorage-commands","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjavierbrea%2Fcypress-localstorage-commands/lists"}