improve the check method (#3935)

Author: kobenguyent

docs/plugins.md

@@ -89,7 +89,7 @@ Scenario('log me in', ( {I, login} ) => {
 #### 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.
+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.
@@ -240,6 +240,40 @@ Scenario('login', async ( {I, login} ) => {
 })
 ```
 
+#### 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
+autoLogin: {
+  enabled: true,
+  saveToFile: true,
+  inject: 'login',
+  users: {
+    admin: {
+      login: async (I) => {  // If you use async function in the autoLogin 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`
+})
+```
+
 ### Parameters
 
 -   `config`  

lib/plugin/autoLogin.js

@@ -61,7 +61,7 @@ const defaultConfig = {
  * #### 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.
+ * 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.
@@ -212,6 +212,38 @@ const defaultConfig = {
  * })
  * ```
  *
+ * #### 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
+ * autoLogin: {
+ *   enabled: true,
+ *   saveToFile: true,
+ *   inject: 'login',
+ *   users: {
+ *     admin: {
+ *       login: async (I) => {  // If you use async function in the autoLogin 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`
+ * })
  *
  *
 */
@@ -264,10 +296,10 @@ module.exports = function (config) {
     recorder.session.start('check login');
     if (shouldAwait) {
       await userSession.restore(I, cookies);
-      await userSession.check(I);
+      await userSession.check(I, cookies);
     } else {
       userSession.restore(I, cookies);
-      userSession.check(I);
+      userSession.check(I, cookies);
     }
     recorder.session.catch((err) => {
       debug(`Failed auto login for ${name} due to ${err}`);