beatsaber-overlay/docs/testing.md

Testing in a browser

The overlay is a static page. You can exercise the UI and wiring without OBS by opening it in any Chromium-based browser (Chrome, Edge) or Firefox.

Open the page

Use a file:// URL (same idea as OBS): absolute path to index.html, forward slashes. This clone:

file:///C:/Users/example/src/BeatSaber-Overlay/index.html

Paste that into the address bar, or drag index.html into a browser window.

Settings are stored in the URL fragment (after #). Using a full file:// URL (not only picking “Open file” in a way that strips the hash) keeps hash-based settings working, same idea as in the README.

Debug mode (no Beat Saber)

Without the game, the overlay normally hides outside Playing (and during BeatSaver loading). Add a query parameter so it stays visible for layout or WebSocket checks:

• Enable: ?debug=1
• Example: file:///C:/Users/example/src/BeatSaber-Overlay/index.html?debug=1

Put ?debug before the # hash if you use both: index.html?debug=1#…

What you should see

• The overlay layout with placeholder labels until live data arrives.
• 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 the preview / settings visibility.
• 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 server.

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