auth

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

Enable this plugin and configure as described below
Define user session names (example: user, editor, admin, etc).
Define how users are logged in and how to check that user is logged in
Use login object inside your tests to log in:

// 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

restore method is executed. It should open a page and set credentials.
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.
If restore and check were not successful, login is executed
login should fill in login form
After successful login, fetch is executed to save cookies into memory or file.

Example: Simple login

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

auth: {
  enabled: true,
  saveToFile: true,
  inject: 'loginAs', // use `loginAs` instead of login
  users: {
    user: {
      login: (I) => {
         I.amOnPage('/login');
         I.fillField('email', '[email protected]');
         I.fillField('password', '123456');
         I.click('Login');
      },
      check: (I) => {
         I.amOnPage('/');
         I.see('User', '.navbar');
      },
    },
    admin: {
      login: (I) => {
         I.amOnPage('/login');
         I.fillField('email', '[email protected]');
         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.

helpers: {
   WebDriver: {
     // config goes here
     keepCookies: true; // keep cookies for all tests
   }
},
plugins: {
   auth: {
     users: {
       admin: {
         login: (I) => {
           I.amOnPage('/login');
           I.fillField('email', '[email protected]');
           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.

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.

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');
      },
    }
  }
}

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

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');
        }
      },
    }
  }
}

Scenario('login', async ( {I, login} ) => {
  await login('admin') // you should use `await`
})

Parameters

config