cypress-browser-permissions
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.5 • Public • Published

    cypress-browser-permissions

    GitHub code size in bytes GitHub repo size npm npm npm npm NPM npm GitHub last commit npm collaborators

    A Cypress plugin to manage browser launch permissions for various APIs such as Notifications, Geolocation, Cookies, Images, and more.

    Video of notification being displayed

    These 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).

    This enables you to effectively test permissions-based APIs in continuous integration environments and in headed browsers without prompts. 🎉

    Table of Contents

    Usage

    👋 Read the dev.to introduction post for a quick start guide and an example!

    Install the package

    npm

    npm i cypress-browser-permissions --save-dev

    yarn

    yarn install cypress-browser-permissions --save-dev

    Import and initialize the plugin

    In cypress/plugins/index.js:

    CommonJS

    const { cypressBrowserPermissionsPlugin } = require('cypress-browser-permissions')
     
    module.exports = (on, config) => {
      // The plugin may modify the Cypress config, so be sure
      // to return it
      config = cypressBrowserPermissionsPlugin(on, config)
     
      //
      // Any existing plugins you are using
      //
     
      return config
    }

    ES2015

    import { cypressBrowserPermissionsPlugin } from 'cypress-browser-permissions'
     
    module.exports = (on, config) => {
      // The plugin may modify the Cypress config, so be sure
      // to return it
      config = cypressBrowserPermissionsPlugin(on, config)
     
      //
      // Any existing plugins you are using
      //
     
      return config
    }

    Setting Permissions

    Setting permissions should work in Chromium (Google Chrome, Microsoft Edge Chromium) and Firefox. They won't take effect in other browser families.

    Permissions can be set using Cypress environment variables. The plugin reads permissions from Cypress.env.browserPermissions and supports all the existing ways to set Cypress environment variables.

    Example of enabling permissions

    In cypress.json

    In cypress.json, set the env.browserPermissions property with a map of permissions:

    {
      "env": {
        "browserPermissions": {
          "notifications": "allow",
          "geolocation": "allow",
          "camera": "block",
          "microphone": "block",
          "images": "allow",
          "javascript": "allow",
          "popups": "ask",
          "plugins": "ask",
          "cookies": "allow"
        }
      }
    }

    In cypress.env.json

    In cypress.env.json, it follows the same convention:

    {
      "browserPermissions": {
        "notifications": "allow",
        "geolocation": "allow",
        "camera": "block",
        "microphone": "block",
        "images": "allow",
        "javascript": "allow",
        "popups": "ask",
        "plugins": "ask",
        "cookies": "allow"
      }
    }

    Via cypress open or cypress run

    Since the configuration is nested, you must pass in the permissions as a stringified JSON object:

    $ cypress run  --env '{\"browserPermissions\": {\"notifications\": 1}}'
    $ cypress open --env '{\"browserPermissions\": {\"notifications\": 1}}'

    Via machine environment variables

    By 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:

    CYPRESS_browser_permissions_notifications=allow cypress run

    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

    Supported Permissions

    These are the supported permission names of the plugin:

    Chrome / Edge (Chromium)
    • notifications
    • geolocation
    • camera
    • microphone
    • images
    • popups
    • javascript
    • cookies
    • plugins
    Firefox
    • notifications
    • geolocation
    • camera
    • microphone
    • images

    Supported Values

    Values for a permission can be any of the following:

    • 0 or ask - The default permission, which is to prompt the user
    • 1 or allow - Allow the permission
    • 2 or block - Block the permission

    Checking Permissions

    In your Cypress test suites, you can import permissions helpers from the the package.

    Usage Example

    my-test.spec.js

    import { isPermissionAllowed, isPermissionBlocked, isPermissionAsk } from 'cypress-browser-permissions'
     
    describe('my site', () => {
      before(() => cy.visit('/'))
     
      isPermissionAllowed('notifications') &&
        it('should show desktop notification', () => {
          /* ... */
        })
     
      isPermissionBlocked('notifications') &&
        it('should warn user desktop notifications are disabled', () => {
          /* ... */
        })
     
      isPermissionAsk('notifications') &&
        it('should prompt user to allow desktop notifications', () => {
          /* ... */
        })
    })

    Also see cypress/integration/ folder for e2e examples.

    API Reference

    See API reference for documented methods.

    Resetting Permissions

    This 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.

    Details

    How It Works

    Cypress can pass preferences 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.

    You can listen to the before:browser:launch event in your own Cypress application to add any additional preferences.

    Chrome / Edge / Chromium Preferences

    Documented in pref_names, the permission-related preferences are grouped under profile.managed_default_content_settings.

    These 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.

    Firefox

    In about:config within Firefox, search for permissions.default to list permissions.

    Notably, Firefox does not have some permissions related to JavaScript, Cookies, Plugins, and Popups but those may be managed with other settings.

    Credits

    Thanks to BrowserStack for documenting some of these permissions as well as these StackOverflow posts:

    In Web Driver testing, these are passed under capabilities, such as shown in the test-runner configuration and then passing as shown here.

    MIT License

    See LICENSE

    
    

    Install

    npm i cypress-browser-permissions

    DownloadsWeekly Downloads

    2,446

    Version

    1.0.5

    License

    MIT

    Unpacked Size

    210 kB

    Total Files

    20

    Last publish

    Collaborators

    • avatar