| name | ui-testing |
| description | Write and run the mod's UI tests with bun (pure-logic tests and React component tests). Use when writing or running UI tests, when a component test must render against the real game bundle / cs2/* modules, when configuring value bindings or asserting outbound triggers in a test, or when the game bundle fails to load / react injection anchors drift after a game update. |
UI Testing
The mod's UI tests run under bun test and come in two tiers, set apart by one fact: a component
test renders real mod components against the real, prebuilt game UI bundle loaded into the
test process, while a pure-logic test imports only TYPES from cs2/* and bindings, which bun
erases, so it runs bare (no DOM, no game install). Everything below follows from that split.
Tests are colocated *.test.ts / *.test.tsx files next to the code they cover.
Run
mise test:ui
This runs bun test HallOfFame/UI. For a focused run during TDD, call bun test <path> directly;
the bunfig.toml preload still applies. Run mise check after, like any UI change.
The two tiers, and where logic goes
- A pure-logic test is the cheap default. It needs no bundle and no game, so it runs anywhere.
Keep extractable logic in a type-only module (one whose
cs2/* / bindings imports are all
import type) so it stays in this tier. Inject the collaborators the logic would otherwise reach
for: pass a translate that echoes its id back rather than importing the real localization.
(See screenshot-upload-panel-utils.test.ts.)
- A component test renders a real component with
@testing-library/react. Reach for it only
when the behavior lives in the rendered tree: a binding drives the DOM, or a click must fire a
command. It depends on the game bundle, so it fails wherever the bundle is absent (see
Best-effort loading).
Writing a component test
Drive the component through the mock engine exported by ../testing/game-setup:
setBinding(group, name, value) BEFORE render configures what a bindValue(group, name, default) returns. An unconfigured binding keeps its bindValue default; a default-less binding
throws, which is the intended "you forgot to configure this" signal.setMapBinding(group, name, key, value) configures one MapEntry binding (e.g. cs2/ui input
hints); unconfigured entries resolve to null, which is enough for game widgets to render.getTriggers() returns the outbound command triggers ({ event, args }) recorded since the last
reset. Assert on these instead of mocking the binding layer.resetBindings() clears configured bindings and recorded triggers; call it in afterEach
alongside @testing-library/react's cleanup().useLocalization().translate(id, fallback) returns the fallback, or the id when none is given,
so a rendered label's text is its localization id; match on that.
See panel-city-info.test.tsx for a binding-driven render and panel-footer.test.tsx for a
click-fires-a-trigger assertion.
Best-effort loading and harness repair
The bundle is loaded by the game-setup.ts preload (wired in bunfig.toml), reading the game from
CSII_INSTALLATIONPATH. Loading is best-effort: if the game is not installed, or the two react
injection anchors in game-setup.ts drift after a game update, only component tests fail
(with a clear "anchor not found" message); pure-logic tests are untouched.
When a game update breaks the harness, or you need to understand how it injects react and aliases
the cs2/* modules, read harness-internals.md.
