LibreChat/e2e
Marco Beretta 7d4a3f00fe
🪶 style: Quieter Primitives, Shared Panel Headers, and Flat Management Lists (#16244)
* style: Quieten the shared primitives and the dark borders

The primitives carried the weight the screens then inherited: boxed empty
states, outlined table shells, raised composer pills. Softening them here
means a screen gets the quieter treatment by composing what it already
composes rather than by overriding it.

Dark moves its border roles one step off the page instead of two, so an
edge separates a surface from the one behind it without reading as a seam.
The values live in style.css for the pre-hydration paint and in dark.ts for
the runtime theme, so both change together.

Checkbox gains CheckboxGlyph, the presentational half of the control, for
rows that are already a button and must not nest a second one inside it.

* feat(client): Panel header and scroll fade for the side panels

Every management panel was building its own title row, so the title, the
search field and the create button sat at a different size and spacing in
each one. PanelHeader is that row, and the panels adopt it next.

PanelContent gains a fade at its foot, fed by useScrollFade, which watches
the viewport and its content and reports whether anything sits below the
fold. A list that is exactly as tall as its box shows no fade, and the
gradient is dropped under prefers-reduced-motion.

The sidebar keeps a right edge in every theme now that it shares a surface
with the content beside it, rather than only in high contrast.

* style: Apply the quieter layout to the panels and management pages

The main content now sits on the same surface as the sidebar, so the app
reads as one plane instead of a page floating on a backdrop. With the fill
gone the containers had nothing left to justify them: cards, outlines and
double borders come off the MCP, Skills, Bookmarks, Memory, Prompts and
Scheduled Chats lists, and spacing and weight carry the hierarchy instead.

The management screens adopt PanelHeader, so title, search and create sit
at one size and one rhythm across all of them, and Schedules gains the
search its siblings already had. Secondary row actions appear on hover and
focus rather than resting in the row.

Two rows also stop nesting interactive controls: the skills row splits into
sibling buttons under a focus-within ring, and the memory and prompt toggles
render CheckboxGlyph inside their button rather than a second control.

* fix(client): Keep the schedules quota and skeleton honest under filtering

The footer counted the filtered list while the create limit is enforced
against all schedules, so filtering made a full account look under quota.
The skeleton reserved a switch, a menu and three text rows the flattened
row no longer has, so the panel visibly collapsed on load; it now mirrors
the healthy row. The skill file expander announced "Show files" even
while expanded, so its label is now a neutral toggle.

* fix(client): Restore schedule row actions and settle the panels' design debt

A schedule row's actions sat in the hover-revealing slot other lists use,
but this panel's rows end at the sidebar's resize handle and a slot
collapsed to zero width put the switch's clickable point outside the
panel, under the handle, where no hover could ever reveal it; the slot
now keeps its width and the menu trigger fades in on row hover alone.

The design-rule violations this branch had suppressed are paid instead:
the tables drop restatements the Table primitives own and take a compact
header size, FilterInput gains the dialog surface instead of a
caller-side color, the projects entries move to the section-action
variant, the MCP cancel cross fades via a wrapper the caller owns, and
the panel group's backdrop moves to its host. The counts this branch had
raised come back down with the entries pruned.

* fix(client): Preserve Shared Row Actions and Verify Panel States

* fix(client): Match Schedule Skeleton Action Height

* fix(client): Preserve Panel Overflow and Schedule History Actions

* refactor(client): Derive Row Action Classes From the Reveal Variant

The reveal recipe was spelled out both in the row-action-reveal Button variant
and in rowActionClasses. The helper now starts from the variant and only adds
the open and always-visible states, and the MCP card spec asserts classes the
real recipe renders instead of a mocked string.

* fix(client): Announce Panel Filter Results and Usage Changes

The schedule filter now reports its match count through a polite live
region, as the prompt filter does. The memory usage badge keeps a status
region beside its toggle so a changed usage is announced while focus is
elsewhere, and the search count reads as a floor while more pages remain.

* fix(client): Keep Row Focus Visible and Warn on Balance-Skipped Runs

The row action slot clipped its overflow even while focus was inside it,
cutting off the focused action's ring. It now clips only while collapsed.

Skill rows drew one focus ring around the whole row, so moving between the
open and disclosure buttons changed nothing on screen. Each button now draws
its own ring.

A run skipped for balance keeps its schedule enabled only until the skip
count disables it, so the row now shows it as a warning instead of reading
as healthy.

* test(e2e): Match the always-applied skill row's full button name

* refactor(client): Render MCP Row Actions Through the Button Primitive

The MCP row actions passed a computed class string to TooltipAnchor, which
the design rules cannot check, and the file carried a new static-classes
suppression for it. They now render the shared Button with the row-action
variants, like the bookmark and memory rows, and the suppression is gone.

* fix(client): Paint Field Notches With the Page Surface and Respect IME Escape

The marketplace, skills and prompts pages moved to the primary-alt surface,
but the floating labels on their fields still painted the presentation
surface, leaving a patch across each field's border in both themes. The
labels now paint the surface they sit on. The create-skill name label is a
plain label like the edit form's, since the Label primitive owns its color
and a notch has to paint its own backdrop.

Escape in the sidebar search cleared the query even while an IME was
composing, where Escape only cancels the composition.

* fix(client): Keep the Chat Column Within the Viewport Beside the Sidebar

Moving the surface off ResizablePanelGroup put a new flex item around it
with the default auto minimum width, so a reply with a wide table grew the
chat column past the viewport and cut its right edge off. The host now
allows itself to shrink, as the group did.

Also covers the sidebar search's IME Escape guard with a unit test, since
the search field is not mounted without a search backend.
2026-09-25 11:46:09 +02: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: Promote Flat Thread Rendering to Default (#15660) 2026-09-06 18:31:08 +00:00
bombadil 🔔 feat: Unseen Reply Indicators, Reply Notifications, and Mark as Unread (#15025) 2026-09-23 13:19:32 -04:00
byom 🛫 feat: Enable Full Access for BYOM Coding (#15718) 2026-09-07 22:46:01 -04:00
config 🧩 feat: MCP Apps support (#13831) 2026-09-23 21:24:50 -04:00
fixtures 🎬 test: Record-Once/Replay-Forever Model Fixtures for Mock E2E (#15210) 2026-08-25 18:29:55 -04:00
lighthouse 🔌 feat: OpenAPI spec and docs for the public Agents API (#15928) 2026-09-16 13:50:05 -04:00
mcp-apps 🫸 fix: Gate MCP App Views and Actions on User Intent (#16297) 2026-09-24 18:00:13 -04:00
perf 📱 test: Add Mobile Chat Performance Benchmark (#15510) 2026-09-02 10:36:33 -04:00
recordings
screenshots 🥧 feat: Show Last-Turn Token Usage Beside Conversation Totals (#16230) 2026-09-23 16:44:39 -04:00
setup 🧩 feat: MCP Apps support (#13831) 2026-09-23 21:24:50 -04:00
specs 🪶 style: Quieter Primitives, Shared Panel Headers, and Flat Management Lists (#16244) 2026-09-25 11:46:09 +02:00
client-build.test.mjs 🛩️ ci: Allow More Time for Chrome Startup in Client Build Recovery (#16330) 2026-09-24 18:00:42 -04:00
config.local.example.ts
jestSetup.js 🚀 v0.8.8-rc4 (#16147) 2026-09-22 23:30:28 -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-09-23 13:19:32 -04: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
playwright.config.mcp-apps.ts 🧩 feat: MCP Apps support (#13831) 2026-09-23 21:24:50 -04: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-09-23 21:24:50 -04: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-09-24 22:16:07 +02: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
README.md 📧 feat: add email address change (#14597) 2026-09-23 13:19:32 -04: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.