Unit-test the shipped frontend JavaScript with standard JS tooling (vitest) #7611

Problem

The JavaScript Reflex ships to every app (state.js, react-theme.js, upload.js, client state, the helpers and components under .templates/web/utils/) has no test suite of its own. Its behavior is only reachable through compiled output: Python unit tests can assert on generated source but not on runtime behavior, and Playwright integration tests are slow and indirect for things like provider teardown, SSR-versus-client branches, subscription bookkeeping, reconnect backoff or event-queue ordering. The two existing runtime checks (tests/units/compiler/state_js.test.mjs, tests/units/reflex_base/client_event_queue_runtime.mjs) are bespoke node scripts driven from pytest.

Proposal

Test the shipped JS with standard tooling: vitest + jsdom, with its own package.json and a committed package-lock.json, installed with npm ci and run as a js-unit-tests job in unit_tests.yml that blocks merges through unit-tests-gate.

• Tests must not live inside the template tree that reflex init copies verbatim into a user's .web. While the runtime is still a template tree they live in tests/js/ and resolve $/... through a vitest alias; once the runtime ships as a package (Ship the frontend runtime JavaScript as an installable npm package #7609) they move into the package at reflex_base/frontend/tests/.
• $/utils/state has to be stubbed today because the real module imports socket.io, react-router and the per-app generated utils/context.js. Decoupling the runtime from generated artifacts (part of Ship the frontend runtime JavaScript as an installable npm package #7609) makes state.js itself unit-testable.
• Where JS and Python share a constant (for example the client-state registry key in constants/state.py, or the _download payload matcher in state.js versus the Var's _js_expr), a test asserts the two definitions agree so they cannot drift.
• Document the suite, and when to reach for it versus Playwright, in AGENTS.md (npm --prefix tests/js ci && npm --prefix tests/js test).
• New JS test files are formatted with biome under pre-commit; codespell skips committed lockfiles.

Pending work

• Promote client state to rx.client_state with a scoped store #6936 (ClientStateVar refactor, Refactor ClientStateVar: scoped client state via a useClientState hook (rx.client_state) #7610) introduces tests/js/: vitest.config.js, client_state.test.js, the js-unit-tests CI job and its gate wiring, and the AGENTS.md section.
• The npm package branch for Ship the frontend runtime JavaScript as an installable npm package #7609 adds reflex_base/frontend/tests/ with state.test.js, runtime.test.js and helpers.test.js, and makes state.js importable in tests.
• Land the suite with whichever of the two merges first, then reconcile the other so there is one package.json/lockfile and one CI job.
• Follow-up: fold the existing .mjs runtime checks into the vitest suite so there is a single JS test entry point.

Related

• Ship the frontend runtime JavaScript as an installable npm package #7609 installable npm package
• Refactor ClientStateVar: scoped client state via a useClientState hook (rx.client_state) #7610 ClientStateVar refactor (Promote client state to rx.client_state with a scoped store #6936)