LibreChat/e2e
Marco Beretta 8ffdee3b4b 🗂️ feat: Chat List Properties Menu and Project-Scoped Chats (#16246)
* feat(client): Rebuild the chat list filter as a properties menu

The old menu listed every option at once. It now opens on three rows that
state where the list stands, Show, Sort and Filter, each with its current
value and a submenu holding the choices. Reading the list's state no longer
means reading the whole menu.

Filter holds the five facets and a search field that looks inside them, so
typing openai finds the endpoint rather than the category that contains it,
and typing a category name offers everything under it. Reset sits in the
header next to the title, and the active facet count rides on the trigger.

The facets are one derived atom, so the query key and the request are built
from the same description of the filter. Date cutoffs snap to local
midnight: taken from the current instant they would differ on every render
and refetch the list each time.

The panels also fade their content at the foot when a list runs past the
fold, and the chat list's loading label shimmers the way every other
in-flight label in the app does.

* feat(client): Show a project's chats under that project only

A chat assigned to a project was listed twice in one sidebar: once under
the project and once in Chats. The chats list now asks for the chats that
belong to no project, which the list query and its cache helpers already
knew how to answer.

Search and the archived view keep asking for everything. Projects is not
rendered while a search is on, and an archived chat has no project row to
appear under, so excluding them from either would leave a chat with no way
back to it.

* fix(client): Keep facet-filtered caches honest and the facets session-scoped

Cache writers judged list membership only by project, archive, tags and
sort, so an SSE update or a fork could insert a chat the server's filter
had excluded. The endpoint and date facets are decided from the row
itself, and the attachment and sharing facets mark their variants for a
refetch, since only the server can place a row in them.

The date cutoffs now derive from a day anchor a mounted consumer
advances at local midnight, so a tab left open stops serving
yesterday's today. Facets reset at the authentication boundary with the
rest of the session state, the bookmark query stops firing for roles
without BOOKMARKS:USE, an empty Chats section under existing projects
says so instead of claiming the account is empty, and the design-rule
violations this branch had suppressed in Conversations and
ChatFilterMenu are fixed and their entries pruned.

* test(client): Mock the projects query the chats section now reads

* test(e2e): Acceptance scenarios for the chat list properties menu

* fix(client): Call the account empty only once its projects have loaded

An empty Chats list read as "No chats yet" whenever the projects query
had not succeeded, so a slow or failed projects request claimed an
account was empty when its chats may all live under projects. The
account-level wording now needs a loaded, empty project list; otherwise
the section says only that nothing sits outside a project.

* test(e2e): Scenario for the Filter submenu under a role without bookmarks

* fix(client): Drop a cached chat from an endpoint filter it no longer matches

The endpoint facet only guarded insertion, so a chat already in an
endpoint-filtered list stayed there after switching provider until the
next refetch. List membership now includes the endpoint for existing
rows as well; a row with no endpoint stays until the server decides.

* fix(client): List every chat when the projects fail to load

Scoping Chats to unassigned chats hid every project chat behind the
Projects section, which shows nothing when its request fails. A failed
project list without cached data now leaves Chats unscoped, so those
chats stay reachable, and an empty unscoped list reads as an empty
account.

* test(e2e): Scenario for project chats when the projects fail to load

* fix(client): Count the bookmark filter once in the menu trigger

The trigger added one per selected bookmark while the Filter row counts
the whole bookmark group as one, so a screen reader heard two different
totals for the same state. Bookmarks now count once, like the endpoint
facet.

* fix(client): Stop the endpoint filter at the configured limit

The Endpoint facet let a user pick more endpoints than
conversationList.maxEndpointFilters allows, and the list request past it
answered 400, leaving Chats in its error state. The post-login startup
config now publishes the limit, resolved by the same helper the list
parser uses, and the facet disables further endpoints once the
selection reaches it, with a note saying why.

* test(e2e): Scenario for the endpoint filter limit

* fix(client): Hold the endpoint filter until its limit is known

The sidebar renders before the post-login startup config resolves, and
until then the Endpoint facet had no limit to enforce, so a selection
made in that window could pass conversationList.maxEndpointFilters.
Endpoints are now offered disabled until that config has loaded.

* fix(client): Keep a chosen bookmark removable and a failed config unlocked

A selected bookmark whose last chat dropped it fell out of both bookmark
lists, so only Reset could clear it; a selected tag now stays listed.
The Endpoint facet waits only while the startup config is loading, so a
config that failed no longer locks every endpoint without saying why.

* test(e2e): Scenario for a chosen bookmark whose count drops to zero

* fix(client): Keep a chosen endpoint removable when the deployment stops listing it

An endpoint that left the endpoints config, or a config that failed to
load, dropped out of both endpoint lists while it stayed selected, so it
kept narrowing the chats and could not be turned off. Both lists now come
from one helper that keeps the selection listed.

* docs(client): Punctuate the list membership comments without dashes

* fix: Publish the chat list filter limits the list route enforces

The startup config published maxEndpointFilters from the caller's merged
config while the list route reads the deployment's base config, so a
principal override could let the sidebar allow a selection the route
refused, or disable one it accepted; and the endpoint name limit was not
published at all, so a long custom endpoint name could be selected and
turn the list into a 400. Both limits now come from one loader the list
route also uses and are published together as conversationListLimits;
the Endpoint facet leaves out names past the length limit.

* fix(client): Keep a deleted bookmark removable from the filter

A selected bookmark that was deleted no longer came back from the tags
query, so neither bookmark list could show it and only Reset cleared it.
Both lists now come from one helper that keeps every selected bookmark.

* fix(client): Offer a retry when a project's chats fail to load

Chats lists only chats outside any project, so a project whose own chat
request failed hid its chats behind the empty state. The project now says
its chats could not load and offers a retry.

* test(e2e): Scenario for a project whose chats fail to load

(cherry picked from commit 1160c802ed)

Original-PR: https://github.com/LibreChat-AI/LibreChat/pull/16246
2026-10-01 03:46:18 +00:00
..
benchmarks ⚡ perf: Reduce Agent Chat Startup Latency (#14423) 2026-07-25 07:58:20 -04:00
benchmarks-mobile-chat 📴 fix: Stop Hidden Code Spinners (#15846) 2026-09-11 21:37:49 -04:00
benchmarks-navigation 🔀 perf: Swap the Transcript With the URL on Conversation Switch (#15054) 2026-08-21 11:28:18 -04:00
benchmarks-reasoning 🔀 perf: Swap the Transcript With the URL on Conversation Switch (#15054) 2026-08-21 11:28:18 -04:00
benchmarks-tree 🏎️ perf: Re-render Only the Tail Rows When a Message Is Sent (#16572) 2026-09-30 10:19:49 -04:00
bombadil 🔔 feat: Unseen Reply Indicators, Reply Notifications, and Mark as Unread (#15025) 2026-10-01 03:46:16 +00:00
byom 🧲 feat: Attach or Leave a Workspace on a Saved Chat (#16124) 2026-09-25 10:08:28 -04:00
config 🧩 feat: MCP Apps support (#13831) 2026-10-01 03:46:16 +00:00
fixtures 🎬 test: Record-Once/Replay-Forever Model Fixtures for Mock E2E (#15210) 2026-08-25 18:29:55 -04:00
lighthouse 🚚 chore: Point Repository and Image References at LibreChat-AI (#16005) 2026-09-23 23:08:36 -04:00
mcp-apps 🫸 fix: Gate MCP App Views and Actions on User Intent (#16297) 2026-10-01 03:46:17 +00:00
perf 📱 test: Add Mobile Chat Performance Benchmark (#15510) 2026-09-02 10:36:33 -04:00
recordings 🎭 feat: Add Credential-Free Playwright Smoke Suite with a Local Mock LLM (#13472) 2026-06-02 16:36:39 -04:00
screenshots 🥧 feat: Show Last-Turn Token Usage Beside Conversation Totals (#16230) 2026-10-01 03:46:16 +00:00
setup 🧩 feat: MCP Apps support (#13831) 2026-10-01 03:46:16 +00:00
specs 🗂️ feat: Chat List Properties Menu and Project-Scoped Chats (#16246) 2026-10-01 03:46:18 +00:00
client-build.test.mjs 🛩️ ci: Allow More Time for Chrome Startup in Client Build Recovery (#16330) 2026-10-01 03:46:17 +00:00
config.local.example.ts
jestSetup.js 🚀 v0.8.8 (#15735) 2026-09-29 23:55:37 -04:00
playwright.config.a11y.ts
playwright.config.benchmark.ts ⚡ perf: Reduce Agent Chat Startup Latency (#14423) 2026-07-25 07:58:20 -04:00
playwright.config.bombadil.ts 🧪 test(e2e): add Bombadil property exploration (#14462) 2026-08-10 02:11:06 +02:00
playwright.config.deployed.ts 📍 test: Add Deployed Smoke Profile (#16135) 2026-09-20 12:34:02 -04:00
playwright.config.email.ts 📧 feat: add email address change (#14597) 2026-10-01 03:46:16 +00:00
playwright.config.lighthouse.ts 🎈 ci: Gate Page Loads Under Database Latency (#15646) 2026-09-06 12:01:44 -04:00
playwright.config.local.ts 🛟 test: Restore Playwright Smoke E2E (#13020) 2026-05-14 09:49:26 -04:00
playwright.config.mcp-apps.ts 🧩 feat: MCP Apps support (#13831) 2026-10-01 03:46:16 +00:00
playwright.config.mermaid.ts 🧜 feat: Open Mermaid Diagrams as Artifacts with SVG/PNG Export (#14713) 2026-08-09 09:02:42 -04:00
playwright.config.mobile-chat-perf.ts 📱 test: Add Mobile Chat Performance Benchmark (#15510) 2026-09-02 10:36:33 -04:00
playwright.config.mock.ts 🧩 feat: MCP Apps support (#13831) 2026-10-01 03:46:16 +00:00
playwright.config.navigation-perf.ts 🔀 perf: Swap the Transcript With the URL on Conversation Switch (#15054) 2026-08-21 11:28:18 -04:00
playwright.config.real.ts 🎯 feat: Tool Intent Label Capability (tool_intents) (#14499) 2026-07-29 15:40:52 -04:00
playwright.config.reasoning-perf.ts 🧪 test: Reasoning-Stream Render Perf Benchmark via react-scan (#14494) 2026-07-28 22:18:24 -04:00
playwright.config.redis.ts 🔑 fix: Invalidate the Auth User Cache After a CLI Password Reset (#16257) 2026-10-01 03:46:17 +00:00
playwright.config.tree-parity.ts 🎖️ perf: Promote Flat Thread Rendering to Default (#15660) 2026-09-06 18:31:08 +00:00
playwright.config.tree-perf-prod.ts 🎖️ perf: Promote Flat Thread Rendering to Default (#15660) 2026-09-06 18:31:08 +00:00
playwright.config.tree-perf.ts 🧶 feat: Flatten Active Message Threads Behind a Flag (#15633) 2026-09-06 14:30:50 -04:00
playwright.config.ts 🎭 feat: Add Credential-Free Playwright Smoke Suite with a Local Mock LLM (#13472) 2026-06-02 16:36:39 -04:00
README.md 📧 feat: add email address change (#14597) 2026-10-01 03:46:16 +00:00
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

  1. Start npm run e2e:record.
  2. Let the LLM use Computer Use to operate the headed Playwright browser.
  3. Stop codegen after the workflow is captured.
  4. Move the useful parts from e2e/recordings/ into a committed spec under e2e/specs/mock/.
  5. Replace brittle generated selectors with role, label, text, or data-testid locators.
  6. Add assertions that prove the behavior, not just the clicked path.
  7. 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.