* feat: passkey authentication with WebAuthn sign-in and management * refactor: tighten passkey account protections Require password confirmation before adding or removing a passkey, and rate limit those confirmations per user in their own namespace. Restrict passkey enrollment and sign-in to local accounts, and re-evaluate account status once the credential owner is resolved. Require user verification on the sign-in ceremony. Invalidate outstanding access tokens on password reset. Tighten redirect target validation and sanitize ceremony failure logs. Adds coverage across the passkey controller, the WebAuthn helpers, the step-up limiter, both JWT strategies, the redirect utility and the passkey settings UI. * fix: localize passkey default name and respect router basename Send a localized default credential label at enrollment so non-English locales no longer persist the server's English fallback, and route the passkey post-login and 2FA navigations through the deployment base path so subdirectory installs stay inside the router. Also mock syncStaticTools in the server boot specs; without it the post-listen MCP initialization calls undefined and exits the worker. * fix: harden passkey counter checks and reach stranded credentials Make the signature counter write a compare-and-swap so two assertions that verified against the same stored counter cannot both commit, and reject the losing one; a cloned authenticator is otherwise accepted inside that window. Counterless authenticators keep restamping at 0. Keep the passkey panel reachable for identity-provider accounts, which already get passwordless removal server-side but had no way in, while hiding the add control they cannot use. Cascade passkey deletion from the admin user-deletion path so credential IDs are not stranded. * fix: reject stale 2FA temp tokens and surface passkey load failures A temporary 2FA token proves only the first factor, so honouring one minted before a password reset let anyone holding the second factor survive account recovery. Apply the same credentials-changed cutoff the JWT strategy uses. Also distinguish a failed passkey query from an empty list; the error state previously rendered as "no passkeys yet", which misreports what is protecting the account. * fix: fail closed when the passkey counter write cannot commit Returning success on a storage error bypassed the compare-and-swap it exists to enforce, so a cloned authenticator could be accepted while the stored counter stayed stale. A database that cannot take this write cannot mint the session either, so little is gained by failing open. Counterless credentials carry no clone signal and keep their old path. * fix: keep the passkey 2FA handoff inside the router A full-page navigation to the 2FA screen remounted AuthContextProvider, which silent-refreshes on mount; no refresh session exists yet at that point, so it bounced back to login before the code could be entered. Route through the router like the password flow does. Also reveal the removal step-up field when the server refuses a passwordless attempt, so an account migrated to an identity provider without its old hash cleared can still clear its credentials; drop the staged password when the dialog closes; and revoke passkeys in the CLI password reset, which bypassed the HTTP controller's cleanup. * fix: apply one email-verification policy across login methods Accounts predating mandatory verification are marked verified as they sign in when no email is configured, but only the password strategy did it, so the same legacy account was admitted by password and refused by passkey. Extract the rule into a shared helper and call it from both. * fix: refuse a passkey sign-in when the ban check cannot complete checkBan defaults next to a no-op, so calling it bare discarded any internal failure and left req.banned unset, letting the request fall through and be issued tokens. Capture the error the middleware chain would have propagated and reject instead. * fix: refine passkey management dialogs * test: stabilize passkey tooltip assertions * test: reconcile passkey specs with the canary reset and deletion flows The credentialsChangedAt stamp now lives in commitPasswordReset, so its assertion moves to the passwordReset unit spec. Restores the describe blocks the rebase merged together. * test: mock passkey routes in the cross-site login suite * refactor: move passkey handlers and credential checks into packages/api The passkey controller, the credentialsChangedAt predicate and the legacy email-verification grandfathering now live in TypeScript with injected dependencies; /api keeps only the wiring that builds the handlers. * style: align passkey UI with Tailwind v4 order and design-rule lint * fix: revoke earlier access tokens on a CLI password reset passwordVersion is not a user schema field, so the write was dropped and tokens issued before the reset kept verifying. * test: cover passkey sign-in and credential revocation end to end * fix: hide passkey sign-in when email login is disabled The passkey endpoints already refuse under ALLOW_EMAIL_LOGIN=false, so advertising the button only led to a 403. * fix: let only one concurrent verification consume a passkey challenge Without a native getDel the challenge was read then deleted, so two concurrent verifications could both use it. The delete now arbitrates: only the caller whose delete removed the key gets the challenge. * test: run passkey ceremonies on the localhost relying party WebAuthn refuses an IP address as the RP ID, and the harness serves the app on 127.0.0.1. The reset scenario runs once per project, so the mock harness lifts the per-IP reset request limit as it does for forks. * fix: keep passkey management when email login is disabled Gate only the sign-in button on emailLoginEnabled, since only the sign-in routes sit behind that gate; list, rename and remove stay reachable. * fix: build the passkey credential index before the first registration With MONGO_AUTO_INDEX=false the unique credentialId index was never created, so concurrent registrations could store the same credential. * test: enable password reset in the mock harness and cover email-login-off passkeys * fix: stop re-exporting the passkey cap from data-schemas The bundler left every import of methods/passkey.ts unlinked while that module re-exported MAX_PASSKEYS_PER_USER from librechat-data-provider, so the index build and the counter-failure log threw ReferenceError at runtime. Consumers now import the cap from librechat-data-provider. * test: close nested settings dialogs before logging out in passkey scenarios * fix: reject cross-site passkey assertions The verify route accepted a form posted from another site, which let an attacker sign a victim into the attacker's account. It now runs the same requireSameOrigin guard as password login and the 2FA step. * fix: end refresh sessions on a CLI password reset A surviving refresh session could mint an access token issued after the credentialsChangedAt stamp, so the CLI now deletes sessions like the web reset does. * fix: keep the passkey button locked when it supersedes autofill Starting the modal ceremony aborts the pending autofill one, and the autofill error path cleared the shared lock and busy state while the modal ceremony was still running. |
||
|---|---|---|
| .. | ||
| benchmarks | ||
| benchmarks-mobile-chat | ||
| benchmarks-navigation | ||
| benchmarks-reasoning | ||
| benchmarks-tree | ||
| bombadil | ||
| byom | ||
| config | ||
| fixtures | ||
| lighthouse | ||
| perf | ||
| recordings | ||
| screenshots | ||
| setup | ||
| specs | ||
| client-build.test.mjs | ||
| config.local.example.ts | ||
| jestSetup.js | ||
| playwright.config.a11y.ts | ||
| playwright.config.benchmark.ts | ||
| playwright.config.bombadil.ts | ||
| playwright.config.deployed.ts | ||
| playwright.config.email.ts | ||
| playwright.config.lighthouse.ts | ||
| playwright.config.local.ts | ||
| playwright.config.mermaid.ts | ||
| playwright.config.mobile-chat-perf.ts | ||
| playwright.config.mock.ts | ||
| playwright.config.navigation-perf.ts | ||
| playwright.config.real.ts | ||
| playwright.config.reasoning-perf.ts | ||
| playwright.config.redis.ts | ||
| playwright.config.tree-parity.ts | ||
| playwright.config.tree-perf-prod.ts | ||
| playwright.config.tree-perf.ts | ||
| playwright.config.ts | ||
| README.md | ||
| types.ts | ||
LibreChat e2e
The mock e2e profile is the safest default for generated tests. It starts LibreChat with e2e/config/librechat.e2e.yaml, injects an in-process fake LLM (via LIBRECHAT_TEST_RUN_HOOK), creates an authenticated e2e user, and avoids real provider credentials.
Deployed-instance smoke test
The deployed profile exercises an existing LibreChat deployment without starting another app or database. It uses the deployment's configured model provider and persists a real conversation, so run it only with a dedicated test account in an environment where that traffic is expected.
First, create Playwright storage state by signing in through the deployment's normal login flow:
npx playwright codegen \
--save-storage=e2e/storageState.json \
https://librechat.example.com/c/new
Close codegen after sign-in, then run the smoke test:
E2E_BASE_URL=https://librechat.example.com \
npm run e2e:deployed
The storage-state file contains session credentials. The default path is ignored by Git; do not commit it or include it in test artifacts.
Set E2E_STORAGE_STATE when the auth file is mounted elsewhere. If the account has no default
model, set E2E_DEPLOYED_MODEL to the exact configured model label. E2E_DEPLOYED_PROMPT can
replace the short default prompt, and E2E_IGNORE_HTTPS_ERRORS=true supports deployments using a
self-signed certificate.
The profile deliberately has no global setup, database access, or web server. It verifies the authenticated shell, sends one real prompt, reloads the resulting conversation, and deletes only the conversation created by that run through LibreChat's authenticated API. Keep deterministic provider behavior and destructive database fixtures in the mock profile instead.
Email Delivery
The registered-email flow has a dedicated profile because enabling SMTP changes registration into a verification-required workflow. It starts a disposable local SMTP mailbox, verifies the setup account from the delivered message, and then tests the Settings → Account email change, verification link, notifications to both addresses, and login with the new address:
npm run e2e:email-change
The disabled-mode profile verifies that ALLOW_EMAIL_CHANGE=false hides the Account control,
rejects both request and confirmation endpoints, and sends no email:
npm run e2e:email-change:disabled
Override E2E_SMTP_PORT or E2E_MAILBOX_PORT if ports 1025 or 8025 are already in use. The mailbox binds only to 127.0.0.1 and is discarded with the test process.
Stream Stores and Shards
The mock profile uses the in-memory generation stream store by default. To exercise the same browser scenarios through a real Redis job store and pub/sub transport, start Redis on port 6379 and run:
npm run e2e:mock:redis
Memory mode explicitly disables Redis. Redis mode defaults to database 15 with a LibreChatE2E key prefix, and fails closed: the test server pings Redis and verifies that the generation job manager did not silently fall back to memory. Override REDIS_URI or E2E_REDIS_KEY_PREFIX when needed.
Pull request CI runs the complete mock suite in memory mode across three shards, plus a focused Redis transport suite. The Redis suite covers streaming fidelity, steering, interrupts, resumptions, HITL approvals, completion, thread folding, model icons, and usage:
npx playwright test --config=e2e/playwright.config.mock.ts --shard=1/3
npm run e2e:mock:redis:transport
The nightly schedule and manual workflow dispatch run the complete mock suite in both stream modes across two shards per mode. Every shard keeps one worker so tests do not contend for its authenticated user and database.
Property-based browser testing
Bombadil explores randomized sequences across the core chat loop, message branches, parallel multi-conversation responses, model changes, reloads, and sidebar conversation lifecycle operations:
npm run e2e:bombadil
Set BOMBADIL_TIME_LIMIT for longer local or scheduled runs. Failures leave a
reproducible trace under e2e/.generated/bombadil-output; rerun it with:
BOMBADIL_REPRODUCE=e2e/.generated/bombadil-output npm run e2e:bombadil:run
Reproducing a real violation is expected to fail the Playwright test. Before a
new run overwrites the active output, the harness archives it under
e2e/.generated/bombadil-history/. Reproduction can diverge when streaming
timing changes; Bombadil reports that explicitly.
The harness uses the credential-free mock-LLM profile, so exploration never sends billable provider requests.
CI runs the broad property exploration for five minutes in the non-blocking
Bombadil Property Exploration workflow. If a property fails, download the
bombadil-reproduction-* artifact into
e2e/.generated/bombadil-output/, then reproduce it locally:
BOMBADIL_REPRODUCE=e2e/.generated/bombadil-output npm run e2e:bombadil:run
The accompanying bombadil-diagnostics-* artifact contains the captured CI log,
Playwright HTML report, and Playwright test results. A Bombadil failure produces
a workflow warning but does not block merge.
The default instruments inline JavaScript only because instrumenting LibreChat's
full Vite bundle can exceed Bombadil's driver timeout during stateful runs. Set
BOMBADIL_INSTRUMENT_JAVASCRIPT=files,inline for shorter coverage-guided
experiments.
The branch reload, fork submission, model/conversation, HITL pause/resume, and mid-run steering lifecycle properties can be run independently:
npm run e2e:bombadil:branch-reload
npm run e2e:bombadil:fork-lifecycle
npm run e2e:bombadil:model-lifecycle
npm run e2e:bombadil:hitl
npm run e2e:bombadil:steering
These focused commands are diagnostic properties: they exit nonzero when they
reproduce a product invariant violation. Reproduce a focused trace with its
matching :run script and output directory, for example:
BOMBADIL_REPRODUCE=e2e/.generated/bombadil-output-hitl npm run e2e:bombadil:hitl:run
HITL drives a real ask_user_question checkpoint through the answer/resume
controller, reloads while the question is paused, answers it once, and reloads
the completed conversation. Steering submits an in-flight steer during a slow
MCP-backed run, checks that it moves exactly once from the composer anchor into
the response at the tool boundary, and reloads the applied state. The model
lifecycle property is the passing control. The branch reload and fork
properties preserve their minimal failing traces.
Recording Tests
Use Playwright codegen when you want to turn an exploratory browser session into a draft test:
npm run e2e:record
That command builds the app, starts the LibreChat test server (with an in-process fake LLM) when needed, writes e2e/storageState.json, and opens Playwright codegen at /c/new. The npm script uses http://localhost:3333 so it does not collide with a normal dev server on 3080. Raw recordings are written to e2e/recordings/ and ignored by git.
For a real local LibreChat config instead of the mock profile:
npm run e2e:record:local
Useful direct options:
node e2e/setup/record.js --url=http://localhost:3080/c/new
node e2e/setup/record.js --profile=local --no-output
node e2e/setup/record.js --auth-only
node e2e/setup/record.js --output=e2e/recordings/settings-draft.spec.ts
LLM-Assisted Loop
- Start
npm run e2e:record. - Let the LLM use Computer Use to operate the headed Playwright browser.
- Stop codegen after the workflow is captured.
- Move the useful parts from
e2e/recordings/into a committed spec undere2e/specs/mock/. - Replace brittle generated selectors with role, label, text, or
data-testidlocators. - Add assertions that prove the behavior, not just the clicked path.
- Run the finished spec with
npm run e2e:mock -- <spec name>.
Generated recordings are a draft, not the final test. The committed version should use the shared helpers in e2e/specs/mock/helpers.ts where possible, wait on network or visible UI state instead of fixed sleeps, and keep test data deterministic.
PR screenshot pilot
e2e/screenshots/playwright.config.ts is an opt-in evidence capture lane, not a pixel-baseline suite. It runs the real app with the mock profile and a private ephemeral MongoDB, then captures welcome screens at desktop/mobile sizes in both themes. Desktop captures also include temporary chat and the settings dialog. No model request is made. Motion is reduced, so these stills do not prove transitions or streaming behavior.
Build and run each revision in its own clean worktree with its own locked install:
npm ci
npm run frontend
npx playwright install chromium
E2E_CAPTURE_SHA=$(git rev-parse HEAD) \
E2E_CAPTURE_DIR="$PWD/e2e/.generated/evidence-before" \
E2E_USE_MEMORY_MONGO=true \
E2E_BASE_URL=http://127.0.0.1:3333 \
npx playwright test --config=e2e/screenshots/playwright.config.ts
For a historical revision without this lane, copy the two e2e/screenshots/*.ts files into its worktree, leaving its application code and lockfile unchanged. Run the same scenario source on both revisions. Use a new output directory for every attempt: existing images are never overwritten. Run revisions sequentially, or give every fixture service its own port using the mock profile's E2E_*_PORT settings. Do not reuse a running development server or a real user's database.
Each PNG has a JSON sidecar containing the revision, browser version, viewport, theme, scenario hash, lockfile hash, built HTML hash, and image hash. Visible images must decode, fonts must finish loading, greeting springs must settle, and consecutive captures must match. A passing run and human inspection are both required before treating the pair as reviewed evidence; sidecars from a failed run are not complete evidence. Compare matching filenames between revisions. Pin the browser and font environment as well as the app revisions.
Keep storage state, traces, logs, and session data private. Check that the PNGs contain only intended synthetic test data before uploading with the attachment-capable gh described in the PR template, then read back the PR body to verify real asset URLs. Mark any pending visual review explicitly. Do not commit the images. A new surface has no before state; label it accordingly rather than substituting another screen.