Beetle

📄 Testing Strategy

2 min read

Testing Strategy

This document describes how to run and interpret the Beetle frontend tests.

Minimal regression suite

Use this suite when changing core flows (filters, playback, drag and drop, sidebar, AudioPlayer) or before deploying UI changes.

Core tests (matches npm run test:smoke):

  • tests/player-smoke-30s.spec.js
  • tests/playback-flows.spec.js
  • tests/dnd-sidebar.spec.js
  • tests/drawer-scroll.window.spec.js
  • tests/rating-optimistic.spec.js
  • tests/left-sidebar-toggle.spec.js
  • tests/filter-toggle-reliability.spec.js (guarded by FILTER_TOGGLE_TEST=1; skipped otherwise)

Run them with:

npm run test:smoke

To force the filter-toggle reliability spec to run in that suite:

FILTER_TOGGLE_TEST=1 npm run test:smoke

Backend-mutating specs (disposable backend only)

These specs write to the backend, so they must never run against production:

  • tests/dnd-sidebar.spec.js creates and deletes folders and playlists
  • tests/sidebar-ssot.spec.js creates folders and playlists
  • tests/verify-fixes.spec.js deletes folders
  • tests/rating-optimistic.spec.js sets a 5★ rating and does not restore it

playwright.config.ts refuses to start unless BEETLE_PROXY_TARGET points at a disposable backend (it rejects 0rk.de). On loca the disposable backend is the test library in /home/loca/beetle-testlib (about 100 free-licensed tracks, http://127.0.0.1:56669); reset it afterwards with /home/loca/beetle-testlib/bin/reset.sh.

BEETLE_PROXY_TARGET=http://127.0.0.1:56669 npx playwright test

Read-only checks of a deployed instance use playwright.prod.config.ts (tests/live-contract.spec.ts, tests/prod-visual.spec.ts).

Key playback flows & guarding tests

  • Basic playback
    • Flows: load library, start a track, let it play for ~30 seconds
    • Tests: tests/player-smoke-30s.spec.js, tests/playback-flows.spec.js
  • Seek / skip / pause-resume
    • Flows: seek within a track, skip to next/previous, pause and resume
    • Tests: tests/playback-flows.spec.js
  • Sidebar and filters
    • Flows: toggle left sidebar, open filters, verify filter toggles and drawer behaviour
    • Tests: tests/left-sidebar-toggle.spec.js, tests/drawer-scroll.window.spec.js, tests/filter-toggle-reliability.spec.js

Full suite

Use the full Playwright suite when preparing a bigger release, after dependency upgrades, or when debugging regressions:

npx playwright test

Before any E2E run on a fresh machine, ensure Playwright browsers are installed:

npx playwright install chromium

Always keep npm run verify green before and after change clusters.

Graph View