{"id":17298413,"url":"https://github.com/kamranayub/cypress-browser-permissions","last_synced_at":"2025-04-09T23:18:48.964Z","repository":{"id":38174310,"uuid":"279780286","full_name":"kamranayub/cypress-browser-permissions","owner":"kamranayub","description":"A Cypress plugin to set launched browser preferences including permissions like Geolocation, Notifications, Microphone, etc.","archived":false,"fork":false,"pushed_at":"2023-07-18T22:54:18.000Z","size":1323,"stargazers_count":65,"open_issues_count":12,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-02T16:47:31.808Z","etag":null,"topics":["browser","cypress","cypress-plugin","e2e","javascript","permissions","testing"],"latest_commit_sha":null,"homepage":"https://kamranicus.com/cypress-browser-permissions","language":"TypeScript","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/kamranayub.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null},"funding":{"github":"kamranayub"}},"created_at":"2020-07-15T06:06:37.000Z","updated_at":"2024-12-27T21:02:24.000Z","dependencies_parsed_at":"2023-12-19T01:01:37.165Z","dependency_job_id":"d676da71-6ef4-410d-8c3d-08f283f55e30","html_url":"https://github.com/kamranayub/cypress-browser-permissions","commit_stats":{"total_commits":40,"total_committers":4,"mean_commits":10.0,"dds":0.6,"last_synced_commit":"022661b5141d99a92bbe1b6938a99c26f8c5ba34"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":"kamranayub/template-typescript-package","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kamranayub%2Fcypress-browser-permissions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kamranayub%2Fcypress-browser-permissions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kamranayub%2Fcypress-browser-permissions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kamranayub%2Fcypress-browser-permissions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kamranayub","download_url":"https://codeload.github.com/kamranayub/cypress-browser-permissions/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247478317,"owners_count":20945266,"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":["browser","cypress","cypress-plugin","e2e","javascript","permissions","testing"],"created_at":"2024-10-15T11:18:59.310Z","updated_at":"2025-04-09T23:18:48.929Z","avatar_url":"https://github.com/kamranayub.png","language":"TypeScript","funding_links":["https://github.com/sponsors/kamranayub"],"categories":[],"sub_categories":[],"readme":"# cypress-browser-permissions\n\n![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/kamranayub/cypress-browser-permissions.svg)\n![GitHub repo size](https://img.shields.io/github/repo-size/kamranayub/cypress-browser-permissions.svg)\n![npm](https://img.shields.io/npm/dw/cypress-browser-permissions.svg)\n![npm](https://img.shields.io/npm/dm/cypress-browser-permissions.svg)\n![npm](https://img.shields.io/npm/dy/cypress-browser-permissions.svg)\n![npm](https://img.shields.io/npm/dt/cypress-browser-permissions.svg)\n![NPM](https://img.shields.io/npm/l/cypress-browser-permissions.svg)\n![npm](https://img.shields.io/npm/v/cypress-browser-permissions.svg)\n![GitHub last commit](https://img.shields.io/github/last-commit/kamranayub/cypress-browser-permissions.svg)\n![npm collaborators](https://img.shields.io/npm/collaborators/cypress-browser-permissions.svg)\n\nA Cypress plugin to manage browser launch permissions for various APIs such as Notifications, Geolocation, Cookies, Images, and more.\n\n![Video of notification being displayed](https://user-images.githubusercontent.com/563819/87746293-d254c400-c7b5-11ea-9d22-d5613b9dae47.gif)\n\nThese APIs can be controlled using browser profile preferences which this plugin will generate and pass for you, as well as resetting them for each test run (otherwise they will be persisted).\n\nThis enables you to effectively test permissions-based APIs in continuous integration environments and in headed browsers _without prompts._ :tada:\n\n## Table of Contents\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n\n- [Usage](#usage)\n  - [Install the package](#install-the-package)\n    - [npm](#npm)\n    - [yarn](#yarn)\n  - [Import and initialize the plugin](#import-and-initialize-the-plugin)\n  - [Setting Permissions](#setting-permissions)\n  - [In `cypress.json`](#in-cypressjson)\n    - [In `cypress.env.json`](#in-cypressenvjson)\n    - [Via `cypress open` or `cypress run`](#via-cypress-open-or-cypress-run)\n    - [Via machine environment variables](#via-machine-environment-variables)\n    - [Supported Permissions](#supported-permissions)\n      - [Chrome / Edge (Chromium)](#chrome--edge-chromium)\n      - [Firefox](#firefox)\n  - [Supported Values](#supported-values)\n  - [Checking Permissions](#checking-permissions)\n    - [Usage Example](#usage-example)\n- [API Reference](#api-reference)\n- [Resetting Permissions](#resetting-permissions)\n- [Details](#details)\n  - [How It Works](#how-it-works)\n  - [Chrome / Edge / Chromium Preferences](#chrome--edge--chromium-preferences)\n  - [Firefox](#firefox-1)\n- [Credits](#credits)\n- [MIT License](#mit-license)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n## Usage\n\n\u003e :wave: Read the [dev.to introduction post for a quick start guide and an example](https://dev.to/kamranayub/controlling-browser-permissions-in-cypress-end-to-end-tests-5d7b)!\n\n### Install the package\n\n#### npm\n\n```bash\nnpm i cypress-browser-permissions --save-dev\n```\n\n#### yarn\n\n```bash\nyarn add cypress-browser-permissions --save-dev\n```\n\n### Import and initialize the plugin\n\nIn `cypress/plugins/index.js`:\n\n**CommonJS**\n\n```js\nconst { cypressBrowserPermissionsPlugin } = require('cypress-browser-permissions')\n\nmodule.exports = (on, config) =\u003e {\n  // The plugin may modify the Cypress config, so be sure\n  // to return it\n  config = cypressBrowserPermissionsPlugin(on, config)\n\n  //\n  // Any existing plugins you are using\n  //\n\n  return config\n}\n```\n\n**ES2015**\n\n```js\nimport { cypressBrowserPermissionsPlugin } from 'cypress-browser-permissions'\n\nmodule.exports = (on, config) =\u003e {\n  // The plugin may modify the Cypress config, so be sure\n  // to return it\n  config = cypressBrowserPermissionsPlugin(on, config)\n\n  //\n  // Any existing plugins you are using\n  //\n\n  return config\n}\n```\n\n### Setting Permissions\n\nSetting permissions should work in Chromium (Google Chrome, Microsoft Edge Chromium) and Firefox. They won't take effect in other browser families.\n\nPermissions can be set using [Cypress environment variables](https://docs.cypress.io/guides/guides/environment-variables.html). The plugin reads permissions from `Cypress.env.browserPermissions` and supports all the existing ways to set Cypress environment variables.\n\n![Example of enabling permissions](https://user-images.githubusercontent.com/563819/87628826-63b13100-c6f7-11ea-956a-ca84a137d464.png)\n\n### In `cypress.json`\n\nIn `cypress.json`, set the `env.browserPermissions` property with a map of permissions:\n\n```json\n{\n  \"env\": {\n    \"browserPermissions\": {\n      \"notifications\": \"allow\",\n      \"geolocation\": \"allow\",\n      \"camera\": \"block\",\n      \"microphone\": \"block\",\n      \"images\": \"allow\",\n      \"javascript\": \"allow\",\n      \"popups\": \"ask\",\n      \"plugins\": \"ask\",\n      \"cookies\": \"allow\"\n    }\n  }\n}\n```\n\n#### In `cypress.env.json`\n\nIn `cypress.env.json`, it follows the same convention:\n\n```json\n{\n  \"browserPermissions\": {\n    \"notifications\": \"allow\",\n    \"geolocation\": \"allow\",\n    \"camera\": \"block\",\n    \"microphone\": \"block\",\n    \"images\": \"allow\",\n    \"javascript\": \"allow\",\n    \"popups\": \"ask\",\n    \"plugins\": \"ask\",\n    \"cookies\": \"allow\"\n  }\n}\n```\n\n#### Via `cypress open` or `cypress run`\n\nSince the configuration is nested, you must pass in the permissions as a stringified JSON object:\n\n```bash\n$ cypress run  --env '{\\\"browserPermissions\\\": {\\\"notifications\\\": 1}}'\n$ cypress open --env '{\\\"browserPermissions\\\": {\\\"notifications\\\": 1}}'\n```\n\n#### Via machine environment variables\n\nBy default, Cypress cannot handle nested variable objects but this plugin will correctly find environment variables that match what it expects and will translate them properly for you automatically:\n\n```bash\nCYPRESS_browser_permissions_notifications=allow cypress run\n```\n\n\u003e **Remember:** When passing Cypress env vars from the outside, such as from a script, prefix them with `CYPRESS_` e.g. `CYPRESS_browser_permissions_notifications=allow`. Cypress automatically strips the prefix when passing to `Cypress.env`\n\n#### Supported Permissions\n\nThese are the supported permission names of the plugin:\n\n##### Chrome / Edge (Chromium)\n\n- `notifications`\n- `geolocation`\n- `camera`\n- `microphone`\n- `images`\n- `popups`\n- `javascript`\n- `cookies`\n- `plugins`\n\n##### Firefox\n\n- `notifications`\n- `geolocation`\n- `camera`\n- `microphone`\n- `images`\n\n### Supported Values\n\nValues for a permission can be any of the following:\n\n- `0` or `ask` - The default permission, which is to prompt the user\n- `1` or `allow` - Allow the permission\n- `2` or `block` - Block the permission\n\n### Checking Permissions\n\nIn your Cypress test suites, you can import permissions helpers from the the package.\n\n#### Usage Example\n\n**my-test.spec.js**\n\n```js\nimport { isPermissionAllowed, isPermissionBlocked, isPermissionAsk } from 'cypress-browser-permissions'\n\ndescribe('my site', () =\u003e {\n  before(() =\u003e cy.visit('/'))\n\n  isPermissionAllowed('notifications') \u0026\u0026\n    it('should show desktop notification', () =\u003e {\n      /* ... */\n    })\n\n  isPermissionBlocked('notifications') \u0026\u0026\n    it('should warn user desktop notifications are disabled', () =\u003e {\n      /* ... */\n    })\n\n  isPermissionAsk('notifications') \u0026\u0026\n    it('should prompt user to allow desktop notifications', () =\u003e {\n      /* ... */\n    })\n})\n```\n\nAlso see [cypress/integration/](cypress/integration) folder for e2e examples.\n\n## API Reference\n\nSee [API reference](https://kamranicus.com/cypress-browser-permissions/modules/_index_.html) for documented methods.\n\n## Resetting Permissions\n\nThis plugin automatically resets each supported permission to the browser default for each test run since otherwise profile preferences are persisted across sessions, which may not be what you intend.\n\n## Details\n\n### How It Works\n\nCypress can pass [preferences](https://docs.cypress.io/api/plugins/browser-launch-api.html#Modify-browser-launch-arguments-preferences-and-extensions) when launching browsers. This plugin adds a small abstraction over this low-level API to take care of setting the permission-related preferences in different browsers, mostly Chrome/Chromium and Firefox.\n\nYou can listen to the `before:browser:launch` event in your own Cypress application to add any additional preferences.\n\n### Chrome / Edge / Chromium Preferences\n\nDocumented in [pref_names](https://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/pref_names.cc?view=markup), the permission-related preferences are grouped under `profile.managed_default_content_settings`.\n\nThese modify the \"managed\" settings, such as when group policy is enforced. In the Chrome settings, there _is_ a way to add specific sites to allow / block lists, and this may be possible to do with the plugin if that is stored in the profile data structure.\n\n### Firefox\n\nIn `about:config` within Firefox, search for `permissions.default` to list permissions.\n\nNotably, Firefox does not have some permissions related to JavaScript, Cookies, Plugins, and Popups but those may be managed with other settings.\n\n## Credits\n\nThanks to BrowserStack for [documenting some of these permissions](https://www.browserstack.com/automate/handle-popups-alerts-prompts-in-automated-tests) as well as these StackOverflow posts:\n\n- [Selenium + Python Allow Firefox Notifications](https://stackoverflow.com/questions/55435198/selenium-python-allow-firefox-notifications)\n- [How to allow or deny notification geo-location microphone camera pop up](https://stackoverflow.com/questions/48007699/how-to-allow-or-deny-notification-geo-location-microphone-camera-pop-up)\n\nIn Web Driver testing, these are passed under capabilities, such as [shown in the test-runner configuration](https://webdriver.io/docs/configurationfile.html) and then passing as [shown here](https://stackoverflow.com/a/47654122/109458).\n\n## MIT License\n\nSee [LICENSE](LICENSE)\n\n```\n\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkamranayub%2Fcypress-browser-permissions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkamranayub%2Fcypress-browser-permissions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkamranayub%2Fcypress-browser-permissions/lists"}