Files
e2e/docs/authentication.mdx
T
Oskar Kwaśniewski 94ddbfe46f fix(config): refuse secrets or credentials sharing an override env var (#721)
* fix(config): refuse secrets and credentials sharing an override env var

* docs(environment): name both credential override vars in collision rule
2026-10-03 12:58:30 +02:00

348 lines
11 KiB
Plaintext

---
title: Signing in
description: Sign in once, reuse the session across tests, and pass secrets without exposing them to the model.
---
Sign in once in a setup test and save a named session. Other tests restore
that session to start signed in.
<Tabs>
<Tab title="tests/auth.setup.e2e.ts">
```ts
import { test } from '@e2e-dev/web';
import { expect, credentials } from 'e2e';
test.setup('authenticate as admin', { sessions: ['admin'] }, async ({ app, screen, session, browser }) => {
const admin = credentials.user('admin');
await app.open('/login');
await screen.getByLabel('Username').fill(admin.username);
await screen.getByLabel('Password').fill(admin.password);
await screen.getByRole('button', 'Sign in').tap();
await expect(browser).toHaveURL('/dashboard');
await expect(screen.getByRole('status', 'Greeting')).toContainText('admin');
await session.save('admin');
});
```
</Tab>
<Tab title="tests/dashboard.e2e.ts">
```ts
import { test } from '@e2e-dev/web';
import { expect } from 'e2e';
test('the dashboard opens directly', { session: 'admin' }, async ({ app, screen, browser }) => {
await app.open('/dashboard');
await expect(browser).toHaveURL('/dashboard');
await expect(screen.getByRole('status', 'Greeting')).toHaveText(
'Welcome back, admin!',
);
});
```
</Tab>
</Tabs>
The runner runs the required setup even when you select only
`tests/dashboard.e2e.ts`.
## Sessions
| Rule | If you break it |
| --- | --- |
| Setup tests are top-level, never inside `describe` | collection error |
| Exactly one setup declares a given session name | collection error |
| Every name in `sessions` is saved by the body | `SESSION_CONTRACT` failure |
| Only declared names are saved | `SESSION_CONTRACT` failure |
| The target's engine saves and restores state | collection error, before any test runs; a hosted browser leased per attempt has none |
Setup tests run before any ordinary test for the same target. If a setup
fails, its dependents are skipped with cause `setup-failed` and unrelated
tests keep going.
<Note>
`session.save()` saves the current state without checking whether sign-in
succeeded. Assert the post-login URL or a signed-in element before saving.
</Note>
On a browser target, a session holds cookies, local storage, and IndexedDB.
It does not include server or database state. Restoring replaces the client
state and leaves no page open, so each test calls `app.open()` first.
Sessions last for one run. They are encrypted on disk with a key that lives
only in runner memory, and deleted during cleanup. A session file is a bearer
credential, so it is never reused across runs.
## Credentials
Declare credentials in config and read passwords from the environment:
```ts title="e2e.config.ts"
export default {
targets: [{ engine: web(), app: { url: 'http://127.0.0.1:3000' } }],
credentials: {
admin: {
username: 'admin@example.test',
password: process.env.ADMIN_PASSWORD ?? '',
},
},
} satisfies E2EConfig;
```
Either field can also be overridden per run. The variable is the credential
name uppercased, with every non-alphanumeric character replaced by `_`:
<CodeGroup>
```bash npm
E2E_USER_ADMIN_USERNAME=admin E2E_USER_ADMIN_PASSWORD=... npx e2e run
```
```bash pnpm
E2E_USER_ADMIN_USERNAME=admin E2E_USER_ADMIN_PASSWORD=... pnpm exec e2e run
```
```bash bun
E2E_USER_ADMIN_USERNAME=admin E2E_USER_ADMIN_PASSWORD=... bunx e2e run
```
</CodeGroup>
A string is checked when the config loads: while `ADMIN_PASSWORD` is unset,
every command, `e2e list` included, fails with `INVALID_CONFIG`.
### Keep the value out of the environment
A string from `process.env` sits in the environment of the runner and of
every process it starts, where any code in the run can read it. `password`
also accepts a function, called on every authorized fill and nowhere else,
so the value can come straight from a vault, or be a freshly computed
one-time code, and never be an environment variable (only the vault client's
own access is configured in the environment):
```ts title="e2e.config.ts"
import type { E2EConfig } from 'e2e';
import { web } from '@e2e-dev/web';
import { vault } from './support/vault.ts';
export default {
targets: [{ engine: web(), app: { url: 'http://127.0.0.1:3000' } }],
credentials: {
admin: {
username: 'admin@example.test',
password: () => vault.read('e2e/admin-password'),
},
},
} satisfies E2EConfig;
```
The function runs in the runner, after the fill is authorized, and its value
goes to the field and the redaction ledger only. A function's value is
redacted only from its first fill on, so prefer a string for a value the app
can show before a test types it. The same applies to a `secrets` entry.
## The password is a handle
```ts
import { credentials } from 'e2e';
const admin = credentials.user('admin');
admin.name; // 'admin'
admin.username; // a plain string
admin.password; // Secret: opaque, named 'admin.password', with no plaintext accessor
```
The two fields are declared alike, but only the password is a secret. A
username is an identifier the app shows on screen, in the account menu and
the audit log, so the agent reads it and tests assert on it; redacting it
would hide exactly what a test checks. The password is never shown, so the
runner keeps it away from test code and the model altogether.
A `Secret` has no `.value`. Three sinks accept one: the two below in a
test, and an engine option that declares it, as
[`basicAuth`](/starting-your-app#protected-previews) does:
<Tabs>
<Tab title="Deterministic">
```ts
await screen.getByLabel('Password').fill(admin.password);
```
</Tab>
<Tab title="Agentic">
```ts
await agent.act('Sign in', {
params: { username: admin.username, password: admin.password },
});
```
</Tab>
</Tabs>
In `agent.act`, the model sees the secret's name and purpose. The runner
authorizes the fill and supplies the value. Secret values are redacted from
model input and reports. Reading a secure field is denied, so check that
sign-in succeeded instead.
After a secret fill, screenshots are withheld for the rest of the attempt,
and in tests that restore the session it saved. See
[screenshots after a secret fill](/security#screenshots-after-a-secret-fill)
for the rule and how to sign in with screenshots kept.
## Secrets that are not passwords
Use `secrets` for API keys, webhook tokens, or other sensitive values a test
needs to enter:
```ts title="e2e.config.ts"
export default {
targets: [{ engine: web(), app: { url: 'http://127.0.0.1:3000' } }],
secrets: {
'stripe-key': process.env.STRIPE_TEST_KEY ?? '',
'webhook-token': process.env.WEBHOOK_TOKEN ?? '',
},
} satisfies E2EConfig;
```
`E2E_SECRET_<NAME>` overrides an entry per run, with the same uppercasing rule
as credentials, so a CI job can supply the value without touching the config.
Two entries that map to one variable, like `stripe-key` and `stripe_key`, fail
the config load with `INVALID_CONFIG`, as two such credentials do:
<CodeGroup>
```bash npm
E2E_SECRET_STRIPE_KEY=sk_test_... npx e2e run
```
```bash pnpm
E2E_SECRET_STRIPE_KEY=sk_test_... pnpm exec e2e run
```
```bash bun
E2E_SECRET_STRIPE_KEY=sk_test_... bunx e2e run
```
</CodeGroup>
Get a handle with `secrets.get()` and use it in `fill` or `agent.act`:
<Tabs>
<Tab title="Deterministic">
```ts
import { secrets } from 'e2e';
await screen.getByLabel('Secret key').fill(secrets.get('stripe-key'));
```
</Tab>
<Tab title="Agentic">
```ts
import { secrets } from 'e2e';
await agent.act('Connect Stripe with the given key', {
params: { apiKey: secrets.get('stripe-key') },
});
```
</Tab>
</Tabs>
When the agent fills a password, the runner requires a password field. A
`secrets` entry can fill any editable input. An unconfigured name throws
`SECRET_UNAVAILABLE`.
### Where the value goes
The model sees only the secret's name and purpose; the runner checks the
field and fills the value. Known values become `<secret:name>` in
observations and reports. The [security model](/security#secrets) has the
full rules.
<Warning>
Redaction matches full values and their encoded forms. A transformed value,
such as the last four characters of a key, can still appear. Keep secret
entry in setup tests and assert the result of submitting it. See
[where redaction stops](/security#where-redaction-stops).
</Warning>
Credentials and secrets are separate namespaces. `secrets.get()` returns
`secrets` entries only; a credential's password is `credentials.user(name).password`,
which the agent and the report know as `<name>.password`. A credential is an
account, a username with the secrets that sign it in, while a secret is one
value, so `credentials.admin` and `secrets.admin` can both exist.
In `e2e.config.ts`, `secrets.get()` hands an engine option a secret it needs
before any test runs, such as a [basic-auth password](/starting-your-app#protected-previews).
The config load checks the name, and the value is redacted once the engine
resolves it, together with the base64 `Authorization` credential it becomes.
The protection is text only: screenshots and the model's pixels are kept, so
a page that renders the password on screen is not masked in them.
## Several signed-in users
Save one session per user, then run the same tests with each session and
[agent](/agents):
<Tabs>
<Tab title="tests/personas.setup.e2e.ts">
```ts
import { test } from '@e2e-dev/web';
import { expect, credentials } from 'e2e';
const PERSONAS = ['buyer', 'admin'] as const;
test.setup('sign in each persona', { sessions: [...PERSONAS] }, async ({ app, screen, session, browser }) => {
for (const name of PERSONAS) {
const user = credentials.user(name);
await app.open('/login');
await screen.getByLabel('Username').fill(user.username);
await screen.getByLabel('Password').fill(user.password);
await screen.getByRole('button', 'Sign in').tap();
await expect(browser).toHaveURL('/dashboard');
await session.save(name);
await app.open('/logout');
}
});
```
</Tab>
<Tab title="tests/checkout.e2e.ts">
```ts
import { describe, test } from '@e2e-dev/web';
for (const persona of ['buyer', 'admin'] as const) {
describe(`checkout as ${persona}`, { agent: persona, session: persona, tags: [persona] }, () => {
test('pays for one item', async ({ app, agent }) => {
await app.open('/cart');
await agent.act('pay for the item in the cart');
await agent.assert('the order confirmation is shown');
});
});
}
```
</Tab>
</Tabs>
Each name refers to an `agents` entry, a `credentials` entry, and a saved
session. When the personas do not need separate sessions,
[run one flow as several agents](/agents#one-flow-several-personas) instead.
<CardGroup cols={2}>
<Card title="test reference" icon="flask" href="/reference/test">
`test.setup`, `sessions`, and the `session` option.
</Card>
<Card title="Config reference" icon="sliders" href="/reference/config#credentials">
The `credentials` and `secrets` blocks.
</Card>
</CardGroup>