codeceptjs 4.0.0-rc.2 → 4.0.0-rc.20

package/docs/auth.md

@@ -0,0 +1,318 @@
+---
+permalink: /auth
+title: Authorization
+---
+
+# Authorization
+
+The `auth` plugin logs a user in once and reuses that session for every test that follows. After the first login it stores the cookies (in memory or in a file) and replays them on later tests. If the session expires, the plugin notices and logs in again.
+
+## Quick Start
+
+Enable the plugin in `codecept.conf.js` and define one user with `login` and `check` functions:
+
+```js
+plugins: {
+  auth: {
+    enabled: true,
+    users: {
+      admin: {
+        login: (I) => {
+          I.amOnPage('/login')
+          I.fillField('email', 'admin@site.com')
+          I.fillField('password', secret('123456'))
+          I.click('Sign in')
+        },
+        check: (I) => {
+          I.amOnPage('/')
+          I.see('Admin', '.navbar')
+        },
+      },
+    },
+  },
+}
+```
+
+Inject `login` into a test and call it with the user name:
+
+```js
+Feature('Dashboard')
+
+Before(({ login }) => {
+  login('admin')
+})
+
+Scenario('admin sees the dashboard', ({ I }) => {
+  I.amOnPage('/dashboard')
+  I.see('Welcome, Admin')
+})
+```
+
+## How It Works
+
+When you call `login('admin')`:
+
+1. **`restore`** opens a page and applies the saved cookies.
+2. **`check`** verifies the user is signed in. If it throws or fails an assertion, the plugin assumes the session is dead.
+3. **`login`** runs the sign-in flow when `restore` + `check` fail (or no cookies exist yet).
+4. **`fetch`** reads the new cookies and stores them for the next test.
+
+Defaults cover the common case: `fetch` calls `I.grabCookie()`, `restore` calls `I.amOnPage('/')` then `I.setCookie(cookies)`, and `check` is a no-op. Override any of them when your app needs something different.
+
+## Configuration
+
+| Option       | Default   | Purpose                                                  |
+| ------------ | --------- | -------------------------------------------------------- |
+| `users`      | —         | Map of session names to user definitions.                |
+| `inject`     | `'login'` | Name of the function injected into tests.                |
+| `saveToFile` | `false`   | Write cookies to `<output>/<name>_session.json`.         |
+
+Each user accepts four functions:
+
+- `login(I)` — sign-in flow. Required.
+- `check(I, session)` — verify the session is still valid. Throw to force a re-login.
+- `fetch(I)` — return the cookies (or token) to store. Defaults to `I.grabCookie()`.
+- `restore(I, session)` — replay the stored session. Defaults to `I.amOnPage('/')` + `I.setCookie()`.
+
+## When to Log In: `Before` vs `BeforeSuite`
+
+You can call `login()` in either hook. Pick based on how many users a suite touches.
+
+### `Before` — one login per test
+
+The default and the safe choice. Use it whenever a suite mixes users, or when you are not on Playwright.
+
+```js
+Feature('Mixed users')
+
+Scenario('admin can ban a user', ({ I, login }) => {
+  login('admin')
+  I.amOnPage('/users/42')
+  I.click('Ban')
+})
+
+Scenario('regular user cannot see the ban button', ({ I, login }) => {
+  login('user')
+  I.amOnPage('/users/42')
+  I.dontSee('Ban')
+})
+```
+
+When the user changes between tests, the plugin clears the previous user's cookies before applying the new ones.
+
+### `BeforeSuite` — one login per suite (Playwright only)
+
+Calling `login()` from `BeforeSuite` lets Playwright load cookies *before* it opens the browser, which removes the extra navigation that `restore` would otherwise need. Use this only when every test in the suite runs as the same user.
+
+```js
+Feature('Admin reports')
+
+BeforeSuite(({ login }) => {
+  login('admin')
+})
+
+Scenario('export sales report', ({ I }) => {
+  I.amOnPage('/reports/sales')
+  I.click('Export')
+})
+
+Scenario('export traffic report', ({ I }) => {
+  I.amOnPage('/reports/traffic')
+  I.click('Export')
+})
+```
+
+> ⚠ If a test inside the suite calls `login()` with a different user, the plugin resets the cookies and signs in again. That cancels the speed-up. When the suite needs more than one user, prefer `Before`.
+
+## Persisting Sessions to a File
+
+Set `saveToFile: true` to keep sessions across test runs. The plugin writes one JSON file per user into the output directory and reloads them on the next start.
+
+```js
+plugins: {
+  auth: {
+    enabled: true,
+    saveToFile: true,
+    users: { admin: { login: (I) => I.loginAsAdmin() } },
+  },
+}
+```
+
+This is most useful while writing tests: you log in once, then iterate without paying the sign-in cost on every run. Delete the JSON file (or let it expire on the server) to force a fresh login.
+
+## Examples
+
+### Reuse a `steps_file.js` helper
+
+Move the sign-in flow into a custom step and call it from the plugin:
+
+```js
+plugins: {
+  auth: {
+    enabled: true,
+    saveToFile: true,
+    users: {
+      admin: {
+        login: (I) => I.loginAdmin(),
+        check: (I) => {
+          I.amOnPage('/')
+          I.see('Admin')
+        },
+      },
+    },
+  },
+}
+```
+
+### Multiple users with a custom inject name
+
+Rename the injected function to `loginAs` for readability:
+
+```js
+plugins: {
+  auth: {
+    enabled: true,
+    inject: 'loginAs',
+    users: {
+      user: {
+        login: (I) => {
+          I.amOnPage('/login')
+          I.fillField('email', 'user@site.com')
+          I.fillField('password', secret('123456'))
+          I.click('Login')
+        },
+        check: (I) => I.see('User', '.navbar'),
+      },
+      admin: {
+        login: (I) => {
+          I.amOnPage('/login')
+          I.fillField('email', 'admin@site.com')
+          I.fillField('password', secret('123456'))
+          I.click('Login')
+        },
+        check: (I) => I.see('Admin', '.navbar'),
+      },
+    },
+  },
+}
+```
+
+Inside a test:
+
+```js
+Before(({ loginAs }) => loginAs('user'))
+```
+
+### Let the helper keep cookies, skip `fetch`/`restore`
+
+If your helper already keeps cookies between tests (e.g. WebDriver's `keepCookies: true`), disable `fetch` and `restore` so the plugin only handles the first login:
+
+```js
+helpers: {
+  WebDriver: { keepCookies: true },
+},
+plugins: {
+  auth: {
+    enabled: true,
+    users: {
+      admin: {
+        login: (I) => {
+          I.amOnPage('/login')
+          I.fillField('email', 'admin@site.com')
+          I.fillField('password', secret('123456'))
+          I.click('Login')
+        },
+        check: (I) => {
+          I.amOnPage('/dashboard')
+          I.see('Admin', '.navbar')
+        },
+        fetch: () => {},
+        restore: () => {},
+      },
+    },
+  },
+}
+```
+
+### Sessions stored in local storage
+
+Override `fetch` and `restore` to read and write a token instead of cookies:
+
+```js
+plugins: {
+  auth: {
+    enabled: true,
+    users: {
+      admin: {
+        login: (I) => I.loginAsAdmin(),
+        check: (I) => I.see('Admin', '.navbar'),
+        fetch: (I) => I.executeScript(() => localStorage.getItem('session_id')),
+        restore: (I, session) => {
+          I.amOnPage('/')
+          I.executeScript((s) => localStorage.setItem('session_id', s), session)
+        },
+      },
+    },
+  },
+}
+```
+
+### Async login
+
+When `login`, `check`, `restore`, or `fetch` is `async`, the plugin awaits it. Inside your test, `await` the injected function:
+
+```js
+plugins: {
+  auth: {
+    enabled: true,
+    users: {
+      admin: {
+        login: async (I) => {
+          const phrase = await I.grabTextFrom('#phrase')
+          I.fillField('username', 'admin')
+          I.fillField('password', secret('password'))
+          I.fillField('phrase', phrase)
+        },
+        check: (I) => {
+          I.amOnPage('/')
+          I.see('Admin')
+        },
+      },
+    },
+  },
+}
+```
+
+```js
+Scenario('login', async ({ login }) => {
+  await login('admin')
+})
+```
+
+### Validate the session inside `check`
+
+`check` receives the value returned by `fetch` as its second argument. Throw from `check` to force a fresh login:
+
+```js
+plugins: {
+  auth: {
+    enabled: true,
+    users: {
+      admin: {
+        login: (I) => I.loginAsAdmin(),
+        check: (I, session) => {
+          if (session.profile.email !== 'admin@site.com') {
+            throw new Error('Wrong user signed in')
+          }
+        },
+      },
+    },
+  },
+}
+```
+
+## Tips
+
+- **Force a re-login** by throwing inside `check` — the plugin treats it as an expired session and runs `login` again.
+- **Mask credentials** with `secret()` so passwords never appear in the test output. See [Secrets](/secrets).
+- **Switch users mid-test** with `session()` when one scenario needs two browsers signed in as different users. See [Multiple Sessions](/sessions).