LibreChat/e2e
Danny Avila 0b4dc238b3
🗄️ refactor: Portable Admin Config Store with Revisions, Key Encoding and Coherent Writes (#17326)
* 🗄️ refactor: Portable Admin Config Store with Revisions, Key Encoding and Coherent Writes

Admin config writes went straight to MongoDB with dotted-path `$set`, `$unset`, `$pull` and `$addToSet`, and nothing checked `configVersion`. That caused six problems.

* 🔁 fix: Reload librechat.yaml on Admin Config Writes

Base-only sections such as `filters` and `messageFilter` live only in librechat.yaml, and an admin
config write was how a running server picked up an edit to them. The coherent-cache change limited
admin-write invalidation to the override and MCP caches, so the YAML base was never re-read after
startup: the content-filter e2e suite, which activates filters by editing the YAML and writing a
reload sentinel, saw `filters: undefined` from GET /base and every activation timed out.

Admin config writes clear the YAML base config again, alongside the override and MCP caches, and
the clear is broadcast with the others, so every instance reloads its YAML. The reload keeps the
last good config on failure and republishes the tools derived from it, so the global tool cache is
left for it to overwrite rather than emptied first.

* 🧭 fix: Cap Dotted Field Path Depth and Hold Revision Preconditions on No-Op Writes

A dotted fieldPath was split without the 32-segment cap that segments already had, so a deep path reached the recursive path writer and failed with a 500. Both spellings now share MAX_CONFIG_PATH_DEPTH and answer 400 CONFIG_PATH_INVALID / too_deep on PATCH, tombstone and DELETE /fields.

Writes reduced to nothing (protected interface permissions, base-only or dedicated sections) answered 200 without checking expectedRevision. They now compare it with the stored document and answer 409 CONFIG_VERSION_CONFLICT with currentRevision on a mismatch, as the write itself would.

* 📡 fix: Retry the Config Invalidation Subscription When Redis Comes Back

A SUBSCRIBE that failed at startup (Redis unreachable, the client's retries spent) was only logged, and ioredis resubscribes only to channels it has joined, so the instance missed every other instance's config invalidation until it restarted. The subscription is now sent again each time the subscriber becomes ready until one succeeds; after that the client's own resubscribe takes over, and closing stops the retries.

* 🔁 fix: Drop YAML Reloads and Merges Overtaken by a Config Write

Admin config writes clear the YAML base config on every instance, so a write is how a running
server picks up an edit to librechat.yaml. Two races could undo that:

- A base reload that read the old YAML before a write's clear cached it after the clear, and the
  base has no TTL, so the old base was served until the next write.
- A request that read the old base before the clear, and was still resolving principals, cached
  its merge under the new override generation for the override TTL.

The config service now keeps a base-config generation that `clearAppConfigCache` bumps. A reload
publishes the base, the tools and the last good config only if its generation is still current,
a read after a clear never joins a reload started before it, and the newer reload starts once the
stale one settles so the loader's process-wide side effects end with the newest YAML. Merges
capture the generation, base included, before they read the base config.

Tests:
- service.spec: a clear during a reload (stale success, stale failure, a read waiting on the newer
  reload) and a merge built on the pre-clear base.
- invalidation.redis.spec: a write on one instance makes another reload librechat.yaml.
- admin-config-reload.spec (api): every admin config write route, through the real router,
  handlers, database and config service, reloads librechat.yaml; a request with nothing to write
  does not.
- invalidateConfigCaches.spec no longer asserts an order the parallel clears do not have.

* 🧬 fix: Encode Config Keys in Objects Built in Another Realm

The key encoder treated an object as plain only when its prototype was this realm's
Object.prototype, and returned any other object unchanged, keys and all. Under Jest,
structuredClone (which the secret pipeline uses) returns objects from the host realm, so the
items of an array the pipeline had cloned, such as Azure groups or custom endpoints, reached
the engine with their dotted keys raw. Node in production has one realm, but the encoding must
not depend on prototype identity: a skipped object stores its dotted keys raw without an error.

A plain object is now one whose prototype is null or a root Object.prototype from any realm.
The encoding spec covers an object built in a vm context.

* 🧪 test: Check Dotted Record Keys Reach the Store's Whole-Document Write

dev's admin config route test asserted the keys on patchConfigFields, which the handlers no
longer call; it now asserts them on the draft writeConfigDocument receives.

* 🚩 feat: Publish the expectedRevision, prunesEmptyParents and awaitedInvalidation Config Flags

GET /api/admin/config/meta now reports the three write-coherence behaviours this branch
implements, so an admin client can drop the workarounds each one replaces:

- expectedRevision: responses carry `revision`; PUT, PATCH /fields, POST /fields/tombstone and
  PATCH /active take `expectedRevision` in the body and both DELETE routes in the query. A
  mismatch answers 409 CONFIG_VERSION_CONFLICT with currentRevision, a malformed value 400
  INVALID_EXPECTED_REVISION; unpinned writes re-read and re-apply up to 3 times.
- prunesEmptyParents: a field delete or tombstone removes the objects it empties, stopping at
  arrays; shells-only documents count as empty for assign-only lifecycle calls.
- awaitedInvalidation: writes answer after the config caches are cleared (broadcast with Redis),
  GET /base bypasses the merged-config cache, and a merge read before a clear is never cached.

meta.spec probes each one against the behaviour: a stale and a malformed precondition on a
PATCH, the store operations' unset and tombstone on nested objects and an array element, and a
held invalidation, the GET /base read options and a merge raced by a clear.

* 🔀 fix: Keep Config Keys Raw Where the Engine Stores Them, So Older Servers Read Them During Upgrades

Servers before the key encoding (v0.8.9-rc1 among them) read every override key literally.
The Mongoose binding encoded every write, so during a rolling upgrade the first write from an
upgraded server turned a stored `gpt-4.1` or Bedrock inference profile into `gpt-4%2E1` for
every server not yet upgraded, and an older server's restore of a deleted group or role
config dropped the `keyEncoding` marker its schema lacks, after which upgraded servers read
the encoded keys literally.

The binding now sends keys raw first and encodes them only when the engine refuses a raw
field name (DocumentDB, Cosmos, FerretDB or MongoDB 4.4 for `$` names): the refused write
changed nothing, so it runs again encoded under the same revision precondition, and that
process encodes later writes holding such keys directly. MongoDB 4.4+ stores dotted names
(5.0+ also `$` names inside a value), so there an older server reads exactly what it wrote. A
document whose raw keys spell escape sequences while none holds a raw `.`, `$` or NUL is
still written encoded, since a raw read would decode it. A raw write clears the marker.

Reads decode a marked document (raw keys an older server added beside encoded ones, or wrote
under a marker it left, carry no escape sequence and read as stored) and an unmarked one
unless some key holds a raw `.`, `$` or NUL, which no encoded document does; that reads an
encoded document whose marker an older server dropped. Encoding stays in the binding for
every engine that needs it (decision #15); the residual cases are in documentdb-compat.md.

* ⏱️ fix: Remove Config Cache Writes a Clear Overtook in Flight

With an asynchronous APP_CONFIG store (Redis or a custom Keyv store), a clear can bump the
generation and finish its delete after a reload or merge checked the generation but before its
`set` landed. The older value then repopulated `_BASE_` until the next write, or a merged
config for the full override TTL.

The base reload, the last-good restoration and the merge cache now check the generation again
once their write lands and delete what they wrote if a clear overtook it. A deleted entry only
costs the next read a reload or a merge; a newer base load cannot be removed this way, since it
starts only after the stale one settles.
2026-10-22 13:04:35 +02:00
..
benchmarks
benchmarks-mobile-chat
benchmarks-navigation
benchmarks-reasoning
benchmarks-tree
bombadil
byom 💉 chore: Upgrade Node.js to Security Release 24.22.1 (#17332) 2026-10-22 09:34:02 +02:00
config ⏱️ fix: Bound Outbound Calls Made Inside a Request (#17263) 2026-10-21 19:10:13 +02:00
fixtures
lighthouse
mcp-apps
perf
recordings
rum feat: add masked session replay lifecycle (#17194) 2026-10-21 14:51:15 -04:00
screenshots
setup ⏱️ fix: Bound Outbound Calls Made Inside a Request (#17263) 2026-10-21 19:10:13 +02:00
specs 🗄️ refactor: Portable Admin Config Store with Revisions, Key Encoding and Coherent Writes (#17326) 2026-10-22 13:04:35 +02:00
client-build.test.mjs
config.local.example.ts
jestSetup.js 🐣 chore: Prepare v0.8.9-rc1 Release (#17336) 2026-10-22 08:56:53 +00:00
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.mcp-apps.ts
playwright.config.mermaid.ts
playwright.config.mobile-chat-perf.ts
playwright.config.mock.ts ⏱️ ci: Balance Playwright Shards by Recorded Duration (#17019) 2026-10-16 07:00:43 -04:00
playwright.config.navigation-perf.ts
playwright.config.real.ts
playwright.config.reasoning-perf.ts
playwright.config.redis.ts
playwright.config.rum.ts feat: add masked session replay lifecycle (#17194) 2026-10-21 14:51:15 -04:00
playwright.config.tree-parity.ts
playwright.config.tree-perf-prod.ts
playwright.config.tree-perf.ts
playwright.config.ts
README.md feat: add masked session replay lifecycle (#17194) 2026-10-21 14:51:15 -04:00
timings.mock.json ⏱️ ci: Balance Playwright Shards by Recorded Duration (#17019) 2026-10-16 07:00:43 -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.

RUM privacy export regressions

Run the real HyperDX/OpenTelemetry SDK export checks without a running LibreChat, database, collector, or model provider:

npx playwright test --config=e2e/playwright.config.rum.ts

The fixture bundles the production RUM adapter, records a synthetic DOM in Chromium, and inspects the actual OTLP requests (including gzip/protobuf replay batches). It checks proxy and direct-token modes, metadata/DOM URL redaction, and fresh and already-recording transitions to a two-factor URL containing a fake login token. Playwright traces are disabled so authentication-shaped test data is not retained in HAR/trace artifacts.

Automatic title regressions

The standard mock profile disables automatic titles. CI runs the title-enabled cases once on the first memory shard. To run them locally after building the app:

E2E_TITLE_CONVO=true npx playwright test --config=e2e/playwright.config.mock.ts \
  conversation-management.spec.ts --grep 'first-turn|final-title polling'

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 ten shards, plus a focused Redis transport suite across two. 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/10
npm run e2e:mock:redis:transport

The nightly schedule and manual workflow dispatch run the complete mock suite in both stream modes across ten shards per mode. Every shard keeps one worker so tests do not contend for its authenticated user and database.

CI splits the complete suite by recorded duration rather than test count: each shard lists the suite, and .github/scripts/playwright-shards.mjs plan hands out whole spec files longest-first to the least-loaded shard using e2e/timings.mock.json. A spec with no recorded time is estimated from its test count, so new specs need nothing; refresh the timings when the shards drift apart. Each shard's report artifact carries a results.json, so download a recent run's playwright-report-memory-* artifacts and rebuild the file from them:

gh run download <run-id> --pattern 'playwright-report-memory-*' --dir /tmp/e2e-reports
node .github/scripts/playwright-shards.mjs record --out e2e/timings.mock.json /tmp/e2e-reports

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.

Running-chat rename rollout

interface.runningChatRename defaults to true. Set it to false during rolling upgrades from a version without title ownership. After every API replica supports title ownership, drain all title-generation tasks started on older replicas, then remove the override. The client also requires the server's title-ownership capability; an old replica cannot advertise it.

With the fence off, running rows and unowned placeholder titles cannot be renamed. Other menu actions remain available. Settled non-placeholder chats retain Rename. The isolated mock profile enables the option because it contains no older replicas.