beatsaber-overlay/docs/testing.md

Testing in a browser

Run deno task serve from the repo (see README), then open the overlay in Chromium (Chrome, Edge) or Firefox.

Open the page

Use the URL the server prints, for example:

http://127.0.0.1:8080/index.html?scale=1.5

Settings live in the URL fragment (after #). Put query parameters before the hash if you use both: index.html?debug=1#…

Preview the song overlay (no Beat Saber)

Click anywhere on the page (outside the settings dialog) to toggle preview mode. The song overlay appears with the built-in placeholder labels so you can check layout, toggles, scale, and fade without a game connection.

Request list simulation

Enable Debug in the settings dialog (or add ?debug=1 to the URL). The song requests list then uses the history array from the JSON instead of queue, so you can see how entries look with the same shape as real data (key, rqn, npr, etc.). The header title is unchanged.

The Deno server exposes Beat Saber Plus data as ChatRequest.json and database.json (same file). With debug, the page tries ChatRequest.json first, then database.json. To load a different filename, add ?requests=yourfile.json.

What you should see

• Developer tools → Console: log lines such as Connecting to ws://localhost:2947/socket on load. If Beat Saber Plus is not running with the Song Overlay module listening on that port, the socket will close and the script retries every 10 seconds—that is expected.
• With Beat Saber running and BS+ Song Overlay enabled: you should see Connection open. when the WebSocket succeeds, and map info, time, and score update while you play.

Quick UI checks without the game

• Click the page (outside the settings dialog) to toggle preview and open the settings strip.
• Change checkboxes and values in the dialog; the URL hash should update and layout should reflect toggles and scale.

Live data path

End-to-end testing needs the same pieces as streaming: Beat Saber, Beat Saber Plus with the Song Overlay module active, so ws://localhost:2947/socket accepts connections. The browser page only connects to that local WebSocket; it does not start the game server.

For custom maps, the overlay may request BeatSaver over HTTPS; use Network in devtools if those requests fail (offline, blocked, or API errors).