mirror of
https://github.com/tester-army/e2e.git
synced 2026-11-22 18:19:48 +08:00
* fix(config): refuse secrets and credentials sharing an override env var * docs(environment): name both credential override vars in collision rule
348 lines
11 KiB
Plaintext
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>
|