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

Open
  • Is something wrong?
#7,611 1 comment 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
35/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
github-actions, javascript, node.js, python
Domain
ci-cd, frontend, testing

Research direction

Read the pending work and related issues #7609 and #7610 first: the suite depends on which branch lands first and must be reconciled into one package.json, lockfile, and CI job. The issue names tests/js/, reflex_base/frontend/tests/, vitest.config.js, AGENTS.md, and unit_tests.yml as the relevant entry points. Done means Vitest with jsdom tests the shipped JavaScript, runs through a gated CI job, and is documented; the existing runtime scripts are a follow-up.

Written by the indexing model from the issue text.

Description

roadmap

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 (#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 #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

  • #6936 (ClientStateVar refactor, #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 #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

  • #7609 installable npm package
  • #7610 ClientStateVar refactor (#6936)
Dominant language
Python
Stars
29k
Forks
1.8k
Avg merge
2d 22h
Merged PRs (30d)
143

Getting set up

Open in Codespaces

Starts the project's dev container in your browser, under your own GitHub account.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from reflex-dev/reflex

All issues in reflex-dev/reflex

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.