lirantal/cypress-social-logins

cypress-social-logins

cypress authentication flows using social network providers

** ⚠️ DISCLAIMER and LIMITATIONS ⚠️ **

This plugin doesn't work well in a CI environment, due to the anti-fraud detection mechanisms employed by the likes of Google, GitHub etc. Why? If you attempt to login from a CI machine which has different IPs, geolocation and other fingerprint identification which the account you use isn't normally attempting a login from, then this will trigger Multi Factor Authentication, CAPTCHA, or other means of confirming the identity. When those extra steps are needed, this plugin doesn't work well around them.

About

This Cypress library makes it possible to perform third-party logins (think oauth) for services such as GitHub, Google or Facebook.

It does so by delegating the login process to a puppeteer flow that performs the login and returns the cookies for the application under test, so they can be set by the calling Cypress flow for the duration of the test.

Support

Supported identity providers:

Usage

1. Call the declared task with a set of options for the social login flow interaction
2. Set the cookies for the test flow with the help of Cypress.Cookies.defaults
3. Copy over all or some (or none) of the local & session storage objects from puppeteer to local instance. Note: If you want to persist localStorage through all tests, see localStorage Troubleshooting below.

cy.clearCookies()

return cy.task('GoogleSocialLogin', socialLoginOptions).then(results => {
  results['cookies'].forEach(cookie => {
    if (cookie.domain.includes(cookieName)) {
      cy.setCookie(cookie.name, cookie.value, {
        domain: cookie.domain,
        expiry: cookie.expires,
        httpOnly: cookie.httpOnly,
        path: cookie.path,
        secure: cookie.secure
      })
    }
  })
  cy.window().then(window => {
    Object.keys(results.ssd).forEach(key => window.sessionStorage.setItem(key, results.ssd[key]))
    Object.keys(results.lsd).forEach(key => window.localStorage.setItem(key, results.lsd[key]))
  })
})

Options passed to the task include:

Install

Install the plugin as a dependency

npm install --save-dev cypress-social-logins

Import the plugin

Import the cypress-social-logins plugin definition for the specific social network login you are interested of, and declare a task that performs the login.

Example:

const {GoogleSocialLogin} = require('cypress-social-logins').plugins

module.exports = (on, config) => {
  on('task', {
    GoogleSocialLogin: GoogleSocialLogin
  })
}

Using the social login

Once the Cypress task is defined we can expose a test case that makes use of it. The task will accept an options object with the username, password and other configurations that need to be specified so that the task can navigate through the page properly.

Once the task has completed it will return the list of cookies from the new page. Most likely these cookies need to be set for the rest of the sessions in the test flow, hence the example code showing the case for Cypress.Cookies.defaults.

describe('Login', () => {
  it('Login through Google', () => {
    const username = Cypress.env('googleSocialLoginUsername')
    const password = Cypress.env('googleSocialLoginPassword')
    const loginUrl = Cypress.env('loginUrl')
    const cookieName = Cypress.env('cookieName')
    const socialLoginOptions = {
      username: username,
      password: password,
      loginUrl: loginUrl,
      headless: true,
      logs: false,
      loginSelector: '[href="/auth/auth0/google-oauth2"]',
      postLoginSelector: '.account-panel'
    }

    return cy.task('GoogleSocialLogin', socialLoginOptions).then(({cookies}) => {
      cy.clearCookies()

      const cookie = cookies.filter(cookie => cookie.name === cookieName).pop()
      if (cookie) {
        cy.setCookie(cookie.name, cookie.value, {
          domain: cookie.domain,
          expiry: cookie.expires,
          httpOnly: cookie.httpOnly,
          path: cookie.path,
          secure: cookie.secure
        })

        Cypress.Cookies.defaults({
          preserve: cookieName
        })
      }
    })
  })
})

Defining custom login

1 Alternative When you need to use social logins which aren't supported by this plugin you can make use of the baseLoginConnect() function that is exported as part of the plugin like so:

const {baseLoginConnect} = require('cypress-social-logins').plugins

module.exports = (on, config) => {
  on('task', {
    customLogin(options) {
      async function typeUsername({page, options} = {}) {
        await page.waitForSelector('input[id="username"]')
        await page.type('input[id="username"]', options.username)
      }

      async function typePassword({page, options} = {}) {
        await page.waitForSelector('input[id="password"]')
        await page.type('input[id="password"]', options.password)
        await page.click('button[id="_submit"]')
      }

      return baseLoginConnect(typeUsername, typePassword, null, options)
    }
  })
}

2 Alternative You can also use the CustomizedLogin function and just provide the selectors inside the options object to pass into the function. Properties usernameField and passwordField are required, otherwise the function will throw an Error with a message for requirements. Properties usernameSubmitBtn and passwordSubmitBtn are optional. (It is recommended to define passwordSubmitBtn to help proceed login flow.)

Test file -

describe('Login', () => {
  it('Login through Google', () => {
    const username = Cypress.env('googleSocialLoginUsername')
    const password = Cypress.env('googleSocialLoginPassword')
    const loginUrl = Cypress.env('loginUrl')
    const cookieName = Cypress.env('cookieName')
    const socialLoginOptions = {
      username,
      password,
      loginUrl,
      usernameField: '#input_username',
      passwordField: '#input_password',
      passwordSubmitBtn: '#login_btn_sign',
      headless: true,
      logs: false,
      loginSelector: '[href="/auth/auth0/google-oauth2"]',
      postLoginSelector: '.account-panel'
    }

    return cy.task('GoogleSocialLogin', socialLoginOptions).then(({cookies}) => {
      cy.clearCookies()

      const cookie = cookies.filter(cookie => cookie.name === cookieName).pop()
      if (cookie) {
        cy.setCookie(cookie.name, cookie.value, {
          domain: cookie.domain,
          expiry: cookie.expires,
          httpOnly: cookie.httpOnly,
          path: cookie.path,
          secure: cookie.secure
        })

        Cypress.Cookies.defaults({
          preserve: cookieName
        })
      }
    })
  })
})

Plugns -

/**
 * @type {Cypress.PluginConfig}
 */
const {CustomizedLogin} = require('cypress-social-logins').plugins

module.exports = (on, config) => {
  // `on` is used to hook into various events Cypress emits
  // `config` is the resolved Cypress config
  on('task', {
    customizedLogin: options => {
      return CustomizedLogin(options)
    }
  })
}

Using AmazonSocialLogin with OneTimePassword

You need an Amazon account with activated 2fa. The QR-Code is provided by Amazon and contains a SECRET to calculate an OTP. This is mandatory due the enforcement of 2fa of new amazon-accounts. SMS or E-Mail is not supported. You can extract the Secret from the QR-Code:

otpauth://totp/Amazon%3ASomeUser%40Example?secret=IBU3VLM........&issuer=Amazon

You need to set up the account in Amazon with GoogleAuthenticator or any password-manager which supports OTP. Further information here: https://www.amazon.com/gp/help/customer/display.html?nodeId=GE6SLZ5J9GCNRW44

Adding AdditionalSteps to login work flow

If there more steps to your login work-flow after submitting username and pass, you can define your functions for these extra steps, then assign them to the options.additionalSteps property in Cypress plugins file.

/**
 * @type {Cypress.PluginConfig}
 */
async function fewMoreSteps({page, options} = {}) {
  // ... define steps
}

module.exports = (on, config) => {
  // `on` is used to hook into various events Cypress emits
  // `config` is the resolved Cypress config
  on('task', {
    customizedLogin: options => {
      options.additionalSteps = fewMoreSteps

      return CustomizedLogin(options)
    }
  })
}

Defining custom login

When you need to use social logins which aren't supported by this plugin you can make use of the baseLoginConnect() function that is exported as part of the plugin like so:

const {baseLoginConnect} = require('cypress-social-logins').plugins

module.exports = (on, config) => {
  on('task', {
    customLogin(options) {
      async function typeUsername({page, options} = {}) {
        await page.waitForSelector('input[id="username"')
        await page.type('input[id="username"', options.username)
      }

      async function typePassword({page, options} = {}) {
        await page.waitForSelector('input[id="password"]')
        await page.type('input[id="password"]', options.password)
        await page.click('button[id="_submit"]')
      }

      return baseLoginConnect(typeUsername, typePassword, null, options)
    }
  })
}

Using AmazonSocialLogin with OneTimePassword

You need an Amazon account with activated 2fa. The QR-Code is provided by Amazon and contains a SECRET to calculate an OTP. This is mandatory due the enforcement of 2fa of new amazon-accounts. SMS or E-Mail is not supported. You can extract the Secret from the QR-Code:

otpauth://totp/Amazon%3ASomeUser%40Example?secret=IBU3VLM........&issuer=Amazon

You need to set up the account in Amazon with GoogleAuthenticator or any password-manager which supports OTP. Further information here: https://www.amazon.com/gp/help/customer/display.html?nodeId=GE6SLZ5J9GCNRW44

Troubleshooting

Timeout while trying to enter username

Make sure you are providing the plugin with the username or password in the options when instantiating it. If you're passing it via environment variables then the plugin will look for these two: CYPRESS_googleSocialLoginUsername and CYPRESS_googleSocialLoginPassword

If your application uses popup auth, make sure you are providing isPopup: true configuration parameter.

Timeout error with Selectors

Puppeteer uses document.querySelectors. If you use selectors such as jQuery, you might face timeout errors because Puppeteer may not understand.

You can check these links to get examples for valid selectors: document.querySelector() CSS Selectors

Failed to launch the browser process

If you're getting an error on a Linux server such as:

Error: Failed to launch the browser process!
[768:768:0423/165641.025850:ERROR:zygote_host_impl_linux.cc(89)] Running as root without --no-sandbox is not supported. See https://crbug.com/638180.
TROUBLESHOOTING:

You should pass the argument --no-sandbox to the plugin as extra arguments.

localStorage isn't persisting through all tests

If you find that lsd is not persisting through tests (useful if you need a JWT from SSO in order to login before each test) using the default implementation above, then you can utilize the package cypress-localstorage-commands (https://www.npmjs.com/package/cypress-localstorage-commands).

To use:

npm install --save-dev cypress-localstorage-commands

import 'cypress-localstorage-commands'

before(() => {
  describe('Login through Google', () => {
    const username = Cypress.env('googleSocialLoginUsername')
    const password = Cypress.env('googleSocialLoginPassword')
    const loginUrl = Cypress.env('loginUrl')
    const localStorageItem = Cypress.env('lsdItemName')
    const socialLoginOptions = {
      username: username,
      password: password,
      loginUrl: loginUrl,
      headless: true,
      logs: false,
      loginSelector: '[href="/auth/auth0/google-oauth2"]',
      postLoginSelector: '.account-panel'
    }

    // Clears localStorage prior to getting any new localStorage items
    cy.clearLocalStorageSnapshot()

    return cy.task('GoogleSocialLogin', socialLoginOptions).then(({lsd}) => {
      // Check for localStorage item, such as a JWT or similar
      const hasLsd = Object.keys(lsd)
        .filter(item => item === localStorageItem)
        .pop()

      if (hasLsd) {
        cy.window().then(() => {
          Object.keys(lsd).forEach(key => {
            cy.setLocalStorage(key, lsd[key])
          })
        })

        // Saves a snapshot of localStorage
        cy.saveLocalStorage()
      }
    })
  })
})

// Restore the saved localStorage snapshot prior to each test
beforeEach(() => {
  cy.restoreLocalStorage()
})

// Save the localStorage snapshot after each test
afterEach(() => {
  cy.saveLocalStorage()
})

Error: module not found: "ws" from file

If you're getting an error message such as:

Error: module not found: "ws" from file ..... node_modules/puppeteer/lib/WebSocketTransport.js #17

It may be due to the fact that you're requiring one of the exported plugin functions, such as GoogleSocialLogin in your spec file in addition to requiring it in cypress/plugins/index.js. Remove it from your spec file, or from a support/index.js and make sure you export the GoogleSocialLogin function as a task only from the /plugins/index.js file.

See discussion about in this issue.

Amazon OTP not accepted

Please be aware of proper time on your machine. Make sure you are using ntp to be in sync.

additionalSteps not a function

Please avoid defining your additionalSteps function inside your test file. It will cause errors when you pass your options object through cy.task().

If you also have cases with multiple scenarios, such as having both cases to enter PIN or secuirty after password or enter usual username and password login flow without extra steps, you can add a property in the options object as an indicater which additional functions you wish to apply.

Example:

/**
 * @type {Cypress.PluginConfig}
 */
async function fewMoreStepsPin({page, options} = {}) {
  // ... define steps to enter PIN
}

async function fewMoreStepsSecurityQ({page, option} = {}) {
  // ... define steps to enter secuirty question
}

module.exports = (on, config) => {
  // `on` is used to hook into various events Cypress emits
  // `config` is the resolved Cypress config
  on('task', {
    customizedLogin: options => {
      if (options.moreSteps === 'pin') {
        // assign options.addtionalSteps pin function
        options.additionalSteps = fewMoreStepsPin
      } else if (options.moreSteps === 'securityQ') {
        // assign options.additionalSteps securityQ
        options.additionalSteps = fewMoreStepsSecurityQ
      }
      return CustomizedLogin(options)
    }
  })
}

Documentation

• Project documentation - development, testing, architecture, and conventions.

Contributing

Please consult CONTRIBUTING for guidelines on contributing to this project.

Author

Liran Tal [email protected]