codeceptjs 4.0.0-beta.3 → 4.0.0-beta.5

package/lib/plugin/auth.js

@@ -0,0 +1,435 @@
+const fs = require('fs')
+const path = require('path')
+const { fileExists } = require('../utils')
+const CommentStep = require('../step/comment')
+const Section = require('../step/section')
+const container = require('../container')
+const store = require('../store')
+const event = require('../event')
+const recorder = require('../recorder')
+const { debug } = require('../output')
+const { isAsyncFunction } = require('../utils')
+
+const defaultUser = {
+  fetch: I => I.grabCookie(),
+  check: () => {},
+  restore: (I, cookies) => {
+    I.amOnPage('/') // open a page
+    I.setCookie(cookies)
+  },
+}
+
+const defaultConfig = {
+  saveToFile: false,
+  inject: 'login',
+}
+
+/**
+ * Logs user in for the first test and reuses session for next tests.
+ * Works by saving cookies into memory or file.
+ * If a session expires automatically logs in again.
+ *
+ * > For better development experience cookies can be saved into file, so a session can be reused while writing tests.
+ *
+ * #### Usage
+ *
+ * 1. Enable this plugin and configure as described below
+ * 2. Define user session names (example: `user`, `editor`, `admin`, etc).
+ * 3. Define how users are logged in and how to check that user is logged in
+ * 4. Use `login` object inside your tests to log in:
+ *
+ * ```js
+ * // inside a test file
+ * // use login to inject auto-login function
+ * Feature('Login');
+ *
+ * Before(({ login }) => {
+ *    login('user'); // login using user session
+ * });
+ *
+ * // Alternatively log in for one scenario.
+ * Scenario('log me in', ( { I, login } ) => {
+ *    login('admin');
+ *    I.see('I am logged in');
+ * });
+ * ```
+ *
+ * #### Configuration
+ *
+ * * `saveToFile` (default: false) - save cookies to file. Allows to reuse session between execution.
+ * * `inject` (default: `login`) - name of the login function to use
+ * * `users` - an array containing different session names and functions to:
+ *    * `login` - sign in into the system
+ *     * `check` - check that user is logged in
+ *     * `fetch` - to get current cookies (by default `I.grabCookie()`)
+ *     * `restore` - to set cookies (by default `I.amOnPage('/'); I.setCookie(cookie)`)
+ *
+ * #### How It Works
+ *
+ * 1. `restore` method is executed. It should open a page and set credentials.
+ * 2. `check` method is executed. It should reload a page (so cookies are applied) and check that this page belongs to logged-in user. When you pass the second args `session`, you could perform the validation using passed session.
+ * 3. If `restore` and `check` were not successful, `login` is executed
+ * 4. `login` should fill in login form
+ * 5. After successful login, `fetch` is executed to save cookies into memory or file.
+ *
+ * #### Example: Simple login
+ *
+ * ```js
+ * auth: {
+ *   enabled: true,
+ *   saveToFile: true,
+ *   inject: 'login',
+ *   users: {
+ *     admin: {
+ *       // loginAdmin function is defined in `steps_file.js`
+ *       login: (I) => I.loginAdmin(),
+ *       // if we see `Admin` on page, we assume we are logged in
+ *       check: (I) => {
+ *          I.amOnPage('/');
+ *          I.see('Admin');
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * #### Example: Multiple users
+ *
+ * ```js
+ * auth: {
+ *   enabled: true,
+ *   saveToFile: true,
+ *   inject: 'loginAs', // use `loginAs` instead of login
+ *   users: {
+ *     user: {
+ *       login: (I) => {
+ *          I.amOnPage('/login');
+ *          I.fillField('email', 'user@site.com');
+ *          I.fillField('password', '123456');
+ *          I.click('Login');
+ *       },
+ *       check: (I) => {
+ *          I.amOnPage('/');
+ *          I.see('User', '.navbar');
+ *       },
+ *     },
+ *     admin: {
+ *       login: (I) => {
+ *          I.amOnPage('/login');
+ *          I.fillField('email', 'admin@site.com');
+ *          I.fillField('password', '123456');
+ *          I.click('Login');
+ *       },
+ *       check: (I) => {
+ *          I.amOnPage('/');
+ *          I.see('Admin', '.navbar');
+ *       },
+ *     },
+ *   }
+ * }
+ * ```
+ *
+ * #### Example: Keep cookies between tests
+ *
+ * If you decide to keep cookies between tests you don't need to save/retrieve cookies between tests.
+ * But you need to login once work until session expires.
+ * For this case, disable `fetch` and `restore` methods.
+ *
+ * ```js
+ * helpers: {
+ *    WebDriver: {
+ *      // config goes here
+ *      keepCookies: true; // keep cookies for all tests
+ *    }
+ * },
+ * plugins: {
+ *    auth: {
+ *      users: {
+ *        admin: {
+ *          login: (I) => {
+ *            I.amOnPage('/login');
+ *            I.fillField('email', 'admin@site.com');
+ *            I.fillField('password', '123456');
+ *            I.click('Login');
+ *          },
+ *          check: (I) => {
+ *            I.amOnPage('/dashboard');
+ *            I.see('Admin', '.navbar');
+ *          },
+ *          fetch: () => {}, // empty function
+ *          restore: () => {}, // empty funciton
+ *        }
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * #### Example: Getting sessions from local storage
+ *
+ * If your session is stored in local storage instead of cookies you still can obtain sessions.
+ *
+ * ```js
+ * plugins: {
+ *    auth: {
+ *     admin: {
+ *       login: (I) => I.loginAsAdmin(),
+ *       check: (I) => I.see('Admin', '.navbar'),
+ *       fetch: (I) => {
+ *         return I.executeScript(() => localStorage.getItem('session_id'));
+ *       },
+ *       restore: (I, session) => {
+ *         I.amOnPage('/');
+ *         I.executeScript((session) => localStorage.setItem('session_id', session), session);
+ *       },
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * #### Tips: Using async function in the auth
+ *
+ * If you use async functions in the auth plugin, login function should be used with `await` keyword.
+ *
+ * ```js
+ * auth: {
+ *   enabled: true,
+ *   saveToFile: true,
+ *   inject: 'login',
+ *   users: {
+ *     admin: {
+ *       login: async (I) => {  // If you use async function in the auth plugin
+ *          const phrase = await I.grabTextFrom('#phrase')
+ *          I.fillField('username', 'admin'),
+ *          I.fillField('password', 'password')
+ *          I.fillField('phrase', phrase)
+ *       },
+ *       check: (I) => {
+ *          I.amOnPage('/');
+ *          I.see('Admin');
+ *       },
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * ```js
+ * Scenario('login', async ( {I, login} ) => {
+ *   await login('admin') // you should use `await`
+ * })
+ * ```
+ *
+ * #### Tips: Using session to validate user
+ *
+ * Instead of asserting on page elements for the current user in `check`, you can use the `session` you saved in `fetch`
+ *
+ * ```js
+ * auth: {
+ *   enabled: true,
+ *   saveToFile: true,
+ *   inject: 'login',
+ *   users: {
+ *     admin: {
+ *       login: async (I) => {  // If you use async function in the auth plugin
+ *          const phrase = await I.grabTextFrom('#phrase')
+ *          I.fillField('username', 'admin'),
+ *          I.fillField('password', 'password')
+ *          I.fillField('phrase', phrase)
+ *       },
+ *       check: (I, session) => {
+ *          // Throwing an error in `check` will make CodeceptJS perform the login step for the user
+ *          if (session.profile.email !== the.email.you.expect@some-mail.com) {
+ *               throw new Error ('Wrong user signed in');
+ *         }
+ *       },
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * ```js
+ * Scenario('login', async ( {I, login} ) => {
+ *   await login('admin') // you should use `await`
+ * })
+ *
+ *
+ */
+module.exports = function (config) {
+  config = Object.assign(defaultConfig, config)
+  Object.keys(config.users).map(
+    u =>
+      (config.users[u] = {
+        ...defaultUser,
+        ...config.users[u],
+      }),
+  )
+
+  if (config.saveToFile) {
+    // loading from file
+    loadCookiesFromFile(config)
+  }
+
+  const loginFunction = async name => {
+    const I = container.support('I')
+    const userSession = config.users[name]
+
+    if (!userSession) {
+      throw new Error(`User '${name}' was not configured for authorization in auth plugin. Add it to the plugin config`)
+    }
+
+    const test = store.currentTest
+
+    // we are in BeforeSuite hook
+    if (!test) {
+      enableAuthBeforeEachTest(name)
+      return
+    }
+
+    const section = new Section(`I am logged in as ${name}`)
+
+    if (config.saveToFile && !store[`${name}_session`]) {
+      loadCookiesFromFile(config)
+    }
+
+    if (isPlaywrightSession() && test?.opts?.cookies) {
+      if (test.opts.user == name) {
+        debug(`Cookies already loaded for ${name}`)
+
+        alreadyLoggedIn(name)
+        return
+      } else {
+        debug(`Cookies already loaded for ${test.opts.user}, but not for ${name}`)
+        await I.deleteCookie()
+      }
+    }
+
+    section.start()
+
+    const cookies = store[`${name}_session`]
+    const shouldAwait = isAsyncFunction(userSession.login) || isAsyncFunction(userSession.restore) || isAsyncFunction(userSession.check)
+
+    const loginAndSave = async () => {
+      if (shouldAwait) {
+        await userSession.login(I)
+      } else {
+        userSession.login(I)
+      }
+
+      section.end()
+      const cookies = await userSession.fetch(I)
+      if (!cookies) {
+        debug("Cannot save user session with empty cookies from auto login's fetch method")
+        return
+      }
+      if (config.saveToFile) {
+        debug(`Saved user session into file for ${name}`)
+        fs.writeFileSync(path.join(global.output_dir, `${name}_session.json`), JSON.stringify(cookies))
+      }
+      store[`${name}_session`] = cookies
+    }
+
+    if (!cookies) return loginAndSave()
+
+    recorder.session.start('check login')
+    if (shouldAwait) {
+      await userSession.restore(I, cookies)
+      await userSession.check(I, cookies)
+    } else {
+      userSession.restore(I, cookies)
+      userSession.check(I, cookies)
+    }
+    section.end()
+    recorder.session.catch(err => {
+      debug(`Failed auto login for ${name} due to ${err}`)
+      debug('Logging in again')
+      recorder.session.start('auto login')
+      return loginAndSave()
+        .then(() => {
+          recorder.add(() => recorder.session.restore('auto login'))
+          recorder.catch(() => debug('continue'))
+        })
+        .catch(err => {
+          recorder.session.restore('auto login')
+          recorder.session.restore('check login')
+          section.end()
+          recorder.throw(err)
+        })
+    })
+    recorder.add(() => {
+      recorder.session.restore('check login')
+    })
+
+    return recorder.promise()
+  }
+
+  function enableAuthBeforeEachTest(name) {
+    const suite = store.currentSuite
+    if (!suite) return
+
+    debug(`enabling auth as ${name} for each test of suite ${suite.title}`)
+
+    // we are setting test opts so they can be picked up by Playwright if it starts browser for this test
+    suite.eachTest(test => {
+      // preload from store
+      if (store[`${name}_session`]) {
+        test.opts.cookies = store[`${name}_session`]
+        test.opts.user = name
+        return
+      }
+
+      if (!config.saveToFile) return
+      const cookieFile = path.join(global.output_dir, `${name}_session.json`)
+
+      if (!fileExists(cookieFile)) {
+        return
+      }
+
+      const context = fs.readFileSync(cookieFile).toString()
+      test.opts.cookies = JSON.parse(context)
+      test.opts.user = name
+    })
+
+    function runLoginFunctionForTest(test) {
+      if (!suite.tests.includes(test)) return
+      // let's call this function to ensure that authorization happened
+      // if no cookies, it will login and save them
+      loginFunction(name)
+    }
+
+    // we are in BeforeSuite hook
+    event.dispatcher.on(event.test.started, runLoginFunctionForTest)
+    event.dispatcher.on(event.suite.after, () => {
+      event.dispatcher.off(event.test.started, runLoginFunctionForTest)
+    })
+  }
+
+  // adding this to DI container
+  const support = {}
+  support[config.inject] = loginFunction
+  container.append({ support })
+
+  return loginFunction
+}
+
+function loadCookiesFromFile(config) {
+  for (const name in config.users) {
+    const fileName = path.join(global.output_dir, `${name}_session.json`)
+    if (!fileExists(fileName)) continue
+    const data = fs.readFileSync(fileName).toString()
+    try {
+      store[`${name}_session`] = JSON.parse(data)
+    } catch (err) {
+      throw new Error(`Could not load session from ${fileName}\n${err}`)
+    }
+    debug(`Loaded user session for ${name}`)
+  }
+}
+
+function isPlaywrightSession() {
+  return !!container.helpers('Playwright')
+}
+
+function alreadyLoggedIn(name) {
+  const step = new CommentStep('am logged in as')
+  step.actor = 'I'
+  return step.addToRecorder([name])
+}

package/lib/plugin/autoDelay.js

@@ -2,8 +2,8 @@ const Container = require('../container')
 const store = require('../store')
 const recorder = require('../recorder')
 const event = require('../event')
-const log = require('../output').log
-const supportedHelpers = require('./standardActingHelpers').slice()
+const { log } = require('../output')
+const standardActingHelpers = Container.STANDARD_ACTING_HELPERS
 
 const methodsToDelay = ['click', 'fillField', 'checkOption', 'pressKey', 'doubleClick', 'rightClick']
 
@@ -52,13 +52,13 @@ const defaultConfig = {
  *
  */
 module.exports = function (config) {
-  supportedHelpers.push('REST')
+  const affectedHelpers = [...standardActingHelpers, 'REST']
   const helpers = Container.helpers()
   let helper
 
   config = Object.assign(defaultConfig, config)
 
-  for (const helperName of supportedHelpers) {
+  for (const helperName of affectedHelpers) {
     if (Object.keys(helpers).indexOf(helperName) > -1) {
       helper = helpers[helperName]
     }
@@ -66,25 +66,25 @@ module.exports = function (config) {
 
   if (!helper) return // no helpers for auto-delay
 
-  event.dispatcher.on(event.step.before, (step) => {
+  event.dispatcher.on(event.step.before, step => {
     if (config.methods.indexOf(step.helperMethod) < 0) return // skip non-actions
 
     recorder.add('auto-delay', async () => {
       if (store.debugMode) return // no need to delay in debug
       log(`Delaying for ${config.delayBefore}ms`)
-      return new Promise((resolve) => {
+      return new Promise(resolve => {
         setTimeout(resolve, config.delayBefore)
       })
     })
   })
 
-  event.dispatcher.on(event.step.after, (step) => {
+  event.dispatcher.on(event.step.after, step => {
     if (config.methods.indexOf(step.helperMethod) < 0) return // skip non-actions
 
     recorder.add('auto-delay', async () => {
       if (store.debugMode) return // no need to delay in debug
       log(`Delaying for ${config.delayAfter}ms`)
-      return new Promise((resolve) => {
+      return new Promise(resolve => {
         setTimeout(resolve, config.delayAfter)
       })
     })