Function session

lib/session.js:18–138

* @param {CodeceptJS.LocatorOrString} sessionName * @param {Function | Object } config * @param {Function} [fn] * @return {any}

(sessionName, config, fn)

 * @return {any}
 */
function session(sessionName, config, fn) {
  if (typeof config === 'function') {
    if (typeof fn === 'function') {
      config = config()
    } else {
      // no config but with function
      fn = config
      config = {}
    }
  }
  // session helpers won't use beforeSuite and afterSuite hooks...
  // restart: false options are not allowed as well
  // but those helpers should be already started so inside listener/helpers.js the `_init` method should already be called

  const helpers = container.helpers()

  if (!savedSessions[sessionName]) {
    for (const helper in helpers) {
      if (!helpers[helper]._session) continue
      savedSessions[sessionName] = {
        start: () => null,
        stop: () => null,
        loadVars: () => null,
        restoreVars: () => null,
        ...(store.dryRun ? {} : helpers[helper]._session()),
      }
      break
    }

    const closeBrowsers = () => {
      const session = savedSessions[sessionName]
      if (!session) return
      session.stop(session.vars)
      delete savedSessions[sessionName]
    }

    event.dispatcher.once(event.test.after, () => {
      recorder.add('close session browsers', closeBrowsers)
    })

    if (!savedSessions[sessionName]) {
      throw new Error('Configured helpers do not support starting sessions. Please use a helper with session support.')
    }

    recorder.add('save vars', async () => {
      savedSessions[sessionName].vars = await savedSessions[sessionName].start(sessionName, config)
    })
  }

  // pick random color
  const color = sessionColors[Object.keys(savedSessions).indexOf(sessionName) % sessionColors.length]

  const addContextToStep = step => {
    step.actor = `${output.colors[color](sessionName)}: I`
  }

  if (!fn) return // no current session steps