![\"build\"/](\"https://github.com/lirantal/cypress-social-logins/actions/workflows/main.yml/badge.svg?branch=master\"){kind=icon}
\n ![\"Security](\"https://img.shields.io/badge/Security-Responsible%20Disclosure-yellow.svg\"){kind=icon}
\n\n cypress authentication flows using social network providers\n
\n\n\n \n
\n
\n
\n \n
\n ** ⚠️ DISCLAIMER and LIMITATIONS ⚠️ **\n
\n\n\n 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.\n
\n\n# About\n\nThis Cypress library makes it possible to perform third-party logins (think oauth) for services such as GitHub, Google or Facebook.\n\nIt 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.\n\n## Support\n\nSupported identity providers:\n\n| Provider | Plugin name |\n| --------- | -------------------- |\n| Google | GoogleSocialLogin |\n| GitHub | GitHubSocialLogin |\n| Microsoft | MicrosoftSocialLogin |\n| Amazon | AmazonSocialLogin |\n| Facebook | FacebookSocialLogin |\n| Twitter | TBD |\n| LinkedIn | TBD |\n\n# Usage\n\n1. Call the declared task with a set of options for the social login flow interaction\n2. Set the cookies for the test flow with the help of `Cypress.Cookies.defaults`\n3. 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](#localstorage-isnt-persisting-through-all-tests) below.\n\n```js\ncy.clearCookies()\n\nreturn cy.task('GoogleSocialLogin', socialLoginOptions).then(results => {\n results['cookies'].forEach(cookie => {\n if (cookie.domain.includes(cookieName)) {\n cy.setCookie(cookie.name, cookie.value, {\n domain: cookie.domain,\n expiry: cookie.expires,\n httpOnly: cookie.httpOnly,\n path: cookie.path,\n secure: cookie.secure\n })\n }\n })\n cy.window().then(window => {\n Object.keys(results.ssd).forEach(key => window.sessionStorage.setItem(key, results.ssd[key]))\n Object.keys(results.lsd).forEach(key => window.localStorage.setItem(key, results.lsd[key]))\n })\n})\n```\n\nOptions passed to the task include:\n\n| Option name | Description | Example |\n| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |\n| username | |\n| password | |\n| loginUrl | The URL for the login page that includes the social network buttons | https://www.example.com/login |\n| loginUrlCredentials | Basic Authentication credentials for the `loginUrl` | `{username: user, password: demo}` |\n| args | string array which allows providing further arguments to puppeteer | `['--no-sandbox', '--disable-setuid-sandbox']` |\n| headless | Whether to run puppeteer in headless mode or not | true |\n| logs | Whether to log interaction with the loginUrl website & cookie data | false |\n| loginSelector | A selector on the page that defines the specific social network to use and can be clicked, such as a button or a link | `'a[href=\"/auth/auth0/google-oauth2\"]'` |\n| postLoginSelector | A selector on the post-login page that can be asserted upon to confirm a successful login | `'.account-panel'` |\n| preLoginSelector | a selector to find and click on before clicking on the login button (useful for accepting cookies) | `'.ind-cbar-right button'` |\n| preLoginSelectorIframe | string a selector to find a iframe for the preLoginSelector | `'div#consent iframe'` |\n| preLoginSelectorIframeDelay | number delay a specific ms after click on the preLoginSelector. Pass a falsy (false, 0, null, undefined, '') to avoid completely. | 2000 |\n| otpSecret | Secret for generating a one-time password based on OTPLIB | `'SECRET'` |\n| loginSelectorDelay | delay a specific amount of time before clicking on the login button, defaults to 250ms. Pass a boolean false to avoid completely. | `100` |\n| getAllBrowserCookies | Whether to get all browser cookies instead of just ones with the domain of loginUrl | true |\n| isPopup | boolean, is your google auth displayed like a popup | true |\n| popupDelay | number, delay a specific milliseconds before popup is shown. Pass a falsy (false, 0, null, undefined, '') to avoid completely | 2000 |\n| cookieDelay | number, delay a specific milliseconds before get a cookies. Pass a falsy (false, 0, null,undefined,'') to avoid completely | 100 |\n| postLoginClick | Optional: a selector to find and click on after clicking on the login button | `#idSIButton9` |\n| usernameField | Required for CustomizedLogin: string, a selector for the username field | |\n| usernameSubmitBtn | Optional for CustomizedLogin: string, a selector for the username button | |\n| passwordField | Required for CustomizedLogin: string, a selector for the password field | |\n| passwordSubmitBtn | Optional for CustomizedLogin: string, a selector for password submit button | |\n| screenshotOnError | Optional: will grab a screen shot if an error occurs on the username, password, or post-login page and saves in the Cypress screenshots folder. | false |\n| additionalSteps | Optional: function, to define any additional steps which may be required after executing functions for username and password, such as answering security questions, PIN, or anything which may be required to fill out after username and password process. The function and this property must be defined or referenced from index.js for Cypress Plugins directory. | `async function moreSteps({page, options} = {}) { await page.waitForSelector('#pin_Field') await page.click('#pin_Field') }` |\n| trackingConsentSelectors | Optional: selectors to find and click on after clicking the login button, but before entering details on the third-party site (useful for accepting third-party cookies e.g. Facebook login). Provide multiple if wanting to accept only essential cookies and it requires multiple clicks | `['button[data-testid=\"cookie-policy-dialog-manage-button\"]', 'button-data-testid=\"cookie-policy-manage-dialog-accept-button\"]']` |\n| preVisitLoginUrlSetCookies | Optional: array of cookies to set before visiting the `loginUrl` | `[{name: 'enable-social-login', value: 'true', domain: '.cypress.io'}]` |\n\n## Install\n\nInstall the plugin as a dependency\n\n```bash\nnpm install --save-dev cypress-social-logins\n```\n\n## Import the plugin\n\nImport the `cypress-social-logins` plugin definition for the specific social\nnetwork login you are interested of, and declare a task that performs the\nlogin.\n\nExample:\n\n```js\nconst {GoogleSocialLogin} = require('cypress-social-logins').plugins\n\nmodule.exports = (on, config) => {\n on('task', {\n GoogleSocialLogin: GoogleSocialLogin\n })\n}\n```\n\n## Using the social login\n\nOnce the Cypress task is defined we can expose a test case that makes use of\nit. The task will accept an options object with the username, password and\nother configurations that need to be specified so that the task can navigate\nthrough the page properly.\n\nOnce the task has completed it will return the list of cookies from the new\npage. Most likely these cookies need to be set for the rest of the\nsessions in the test flow, hence the example code showing the case for\n`Cypress.Cookies.defaults`.\n\n```js\ndescribe('Login', () => {\n it('Login through Google', () => {\n const username = Cypress.env('googleSocialLoginUsername')\n const password = Cypress.env('googleSocialLoginPassword')\n const loginUrl = Cypress.env('loginUrl')\n const cookieName = Cypress.env('cookieName')\n const socialLoginOptions = {\n username: username,\n password: password,\n loginUrl: loginUrl,\n headless: true,\n logs: false,\n loginSelector: '[href=\"/auth/auth0/google-oauth2\"]',\n postLoginSelector: '.account-panel'\n }\n\n return cy.task('GoogleSocialLogin', socialLoginOptions).then(({cookies}) => {\n cy.clearCookies()\n\n const cookie = cookies.filter(cookie => cookie.name === cookieName).pop()\n if (cookie) {\n cy.setCookie(cookie.name, cookie.value, {\n domain: cookie.domain,\n expiry: cookie.expires,\n httpOnly: cookie.httpOnly,\n path: cookie.path,\n secure: cookie.secure\n })\n\n Cypress.Cookies.defaults({\n preserve: cookieName\n })\n }\n })\n })\n})\n```\n\n## Defining custom login\n\n1 Alternative\nWhen 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:\n\n```js\nconst {baseLoginConnect} = require('cypress-social-logins').plugins\n\nmodule.exports = (on, config) => {\n on('task', {\n customLogin(options) {\n async function typeUsername({page, options} = {}) {\n await page.waitForSelector('input[id=\"username\"]')\n await page.type('input[id=\"username\"]', options.username)\n }\n\n async function typePassword({page, options} = {}) {\n await page.waitForSelector('input[id=\"password\"]')\n await page.type('input[id=\"password\"]', options.password)\n await page.click('button[id=\"_submit\"]')\n }\n\n return baseLoginConnect(typeUsername, typePassword, null, options)\n }\n })\n}\n```\n\n2 Alternative\nYou 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.)\n\nTest file -\n\n```js\ndescribe('Login', () => {\n it('Login through Google', () => {\n const username = Cypress.env('googleSocialLoginUsername')\n const password = Cypress.env('googleSocialLoginPassword')\n const loginUrl = Cypress.env('loginUrl')\n const cookieName = Cypress.env('cookieName')\n const socialLoginOptions = {\n username,\n password,\n loginUrl,\n usernameField: '#input_username',\n passwordField: '#input_password',\n passwordSubmitBtn: '#login_btn_sign',\n headless: true,\n logs: false,\n loginSelector: '[href=\"/auth/auth0/google-oauth2\"]',\n postLoginSelector: '.account-panel'\n }\n\n return cy.task('GoogleSocialLogin', socialLoginOptions).then(({cookies}) => {\n cy.clearCookies()\n\n const cookie = cookies.filter(cookie => cookie.name === cookieName).pop()\n if (cookie) {\n cy.setCookie(cookie.name, cookie.value, {\n domain: cookie.domain,\n expiry: cookie.expires,\n httpOnly: cookie.httpOnly,\n path: cookie.path,\n secure: cookie.secure\n })\n\n Cypress.Cookies.defaults({\n preserve: cookieName\n })\n }\n })\n })\n})\n```\n\nPlugns -\n\n```js\n/**\n * @type {Cypress.PluginConfig}\n */\nconst {CustomizedLogin} = require('cypress-social-logins').plugins\n\nmodule.exports = (on, config) => {\n // `on` is used to hook into various events Cypress emits\n // `config` is the resolved Cypress config\n on('task', {\n customizedLogin: options => {\n return CustomizedLogin(options)\n }\n })\n}\n```\n\n## Using AmazonSocialLogin with OneTimePassword\n\nYou need an Amazon account with activated 2fa. The QR-Code is provided by Amazon and contains a SECRET to\ncalculate an OTP. This is mandatory due the enforcement of 2fa of new amazon-accounts. SMS or E-Mail is not supported.\nYou can extract the Secret from the QR-Code:\n\n```\notpauth://totp/Amazon%3ASomeUser%40Example?secret=IBU3VLM........&issuer=Amazon\n```\n\nYou need to set up the account in Amazon with GoogleAuthenticator or any password-manager which supports OTP. Further\ninformation here:\nhttps://www.amazon.com/gp/help/customer/display.html?nodeId=GE6SLZ5J9GCNRW44\n\n## Adding AdditionalSteps to login work flow\n\nIf 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.\n\n```js\n/**\n * @type {Cypress.PluginConfig}\n */\nasync function fewMoreSteps({page, options} = {}) {\n // ... define steps\n}\n\nmodule.exports = (on, config) => {\n // `on` is used to hook into various events Cypress emits\n // `config` is the resolved Cypress config\n on('task', {\n customizedLogin: options => {\n options.additionalSteps = fewMoreSteps\n\n return CustomizedLogin(options)\n }\n })\n}\n```\n\n## Defining custom login\n\nWhen 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:\n\n```js\nconst {baseLoginConnect} = require('cypress-social-logins').plugins\n\nmodule.exports = (on, config) => {\n on('task', {\n customLogin(options) {\n async function typeUsername({page, options} = {}) {\n await page.waitForSelector('input[id=\"username\"')\n await page.type('input[id=\"username\"', options.username)\n }\n\n async function typePassword({page, options} = {}) {\n await page.waitForSelector('input[id=\"password\"]')\n await page.type('input[id=\"password\"]', options.password)\n await page.click('button[id=\"_submit\"]')\n }\n\n return baseLoginConnect(typeUsername, typePassword, null, options)\n }\n })\n}\n```\n\n## Using AmazonSocialLogin with OneTimePassword\n\nYou need an Amazon account with activated 2fa. The QR-Code is provided by Amazon and contains a SECRET to\ncalculate an OTP. This is mandatory due the enforcement of 2fa of new amazon-accounts. SMS or E-Mail is not supported.\nYou can extract the Secret from the QR-Code:\n\n```\notpauth://totp/Amazon%3ASomeUser%40Example?secret=IBU3VLM........&issuer=Amazon\n```\n\nYou need to set up the account in Amazon with GoogleAuthenticator or any password-manager which supports OTP. Further\ninformation here:\nhttps://www.amazon.com/gp/help/customer/display.html?nodeId=GE6SLZ5J9GCNRW44\n\n# Troubleshooting\n\n## Timeout while trying to enter username\n\nMake 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`\n\nIf your application uses popup auth, make sure you are providing `isPopup: true` configuration parameter.\n\n## Timeout error with Selectors\n\nPuppeteer uses `document.querySelectors`. If you use selectors such as jQuery, you might face timeout errors because Puppeteer may not understand.\n\nYou can check these links to get examples for valid selectors:\n[document.querySelector()](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector)\n[CSS Selectors](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors)\n\n## Failed to launch the browser process\n\nIf you're getting an error on a Linux server such as:\n\n```\nError: Failed to launch the browser process!\n[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.\nTROUBLESHOOTING:\n```\n\nYou should pass the argument `--no-sandbox` to the plugin as extra arguments.\n\n## localStorage isn't persisting through all tests\n\nIf 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).\n\nTo use:\n\n`npm install --save-dev cypress-localstorage-commands`\n\n```js\nimport 'cypress-localstorage-commands'\n\nbefore(() => {\n describe('Login through Google', () => {\n const username = Cypress.env('googleSocialLoginUsername')\n const password = Cypress.env('googleSocialLoginPassword')\n const loginUrl = Cypress.env('loginUrl')\n const localStorageItem = Cypress.env('lsdItemName')\n const socialLoginOptions = {\n username: username,\n password: password,\n loginUrl: loginUrl,\n headless: true,\n logs: false,\n loginSelector: '[href=\"/auth/auth0/google-oauth2\"]',\n postLoginSelector: '.account-panel'\n }\n\n // Clears localStorage prior to getting any new localStorage items\n cy.clearLocalStorageSnapshot()\n\n return cy.task('GoogleSocialLogin', socialLoginOptions).then(({lsd}) => {\n // Check for localStorage item, such as a JWT or similar\n const hasLsd = Object.keys(lsd)\n .filter(item => item === localStorageItem)\n .pop()\n\n if (hasLsd) {\n cy.window().then(() => {\n Object.keys(lsd).forEach(key => {\n cy.setLocalStorage(key, lsd[key])\n })\n })\n\n // Saves a snapshot of localStorage\n cy.saveLocalStorage()\n }\n })\n })\n})\n\n// Restore the saved localStorage snapshot prior to each test\nbeforeEach(() => {\n cy.restoreLocalStorage()\n})\n\n// Save the localStorage snapshot after each test\nafterEach(() => {\n cy.saveLocalStorage()\n})\n```\n\n## Error: module not found: \"ws\" from file\n\nIf you're getting an error message such as:\n\n```\nError: module not found: \"ws\" from file ..... node_modules/puppeteer/lib/WebSocketTransport.js #17\n```\n\nIt 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.\n\nSee discussion about [in this issue](https://github.com/lirantal/cypress-social-logins/issues/17).\n\n## Amazon OTP not accepted\n\nPlease be aware of proper time on your machine. Make sure you are using ntp to be in sync.\n\n## additionalSteps not a function\n\nPlease avoid defining your additionalSteps function inside your test file. It will cause errors when you pass your `options` object through `cy.task()`.\n\nIf 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.\n\nExample:\n\n```js\n/**\n * @type {Cypress.PluginConfig}\n */\nasync function fewMoreStepsPin({page, options} = {}) {\n // ... define steps to enter PIN\n}\n\nasync function fewMoreStepsSecurityQ({page, option} = {}) {\n // ... define steps to enter secuirty question\n}\n\nmodule.exports = (on, config) => {\n // `on` is used to hook into various events Cypress emits\n // `config` is the resolved Cypress config\n on('task', {\n customizedLogin: options => {\n if (options.moreSteps === 'pin') {\n // assign options.addtionalSteps pin function\n options.additionalSteps = fewMoreStepsPin\n } else if (options.moreSteps === 'securityQ') {\n // assign options.additionalSteps securityQ\n options.additionalSteps = fewMoreStepsSecurityQ\n }\n return CustomizedLogin(options)\n }\n })\n}\n```\n\n## Documentation\n\n- [Project documentation](./docs/README.md) - development, testing, architecture, and conventions.\n\n## Contributing\n\nPlease consult [CONTRIBUTING](./CONTRIBUTING.md) for guidelines on contributing to this project.\n\n# Author\n\nLiran Tal