README.md

Test suite

These tests cover logic in spotify_monitor.py and the debug/ utilities that can run without network access. Functions that normally contact Spotify or Last.fm are replaced with test doubles. See test_monitoring_loop.py for an example.

The default suite also builds and installs the project wheel to test the shipped console commands. Integration tests bind local loopback HTTP and SMTP servers and never leave the machine.

Running

From the repository root:

pip install -e '.[test]'
python -m pytest

pyproject.toml puts the repository root first on sys.path, so the tests use the working tree instead of an installed copy of the module.

Optional extras are needed only for the code paths that use them:

pip install -e '.[test,browser,legacy-oauth]'

Without them, test_browser_cookie_import.py and the legacy OAuth metadata paths fall back to the same absent-dependency behavior a user would see.

Layout

File	Area under test
test_codeql_workflow.py	Source suppression filtering, retained security findings, invalid reports and CodeQL upload ordering
test_notification_receipts.py	SMTP acceptance despite cleanup failures, receipt controls and unchanged notification content
test_oauth_validation_boundaries.py	Fresh OAuth validation and immediate resource failure with real HTTP clients
test_configuration_notification_boundaries.py	Invalid output settings, CLI precedence and strict webhook fields with legacy JSON support
test_boundary_regressions.py	Real notification transports, literal secret resolution and malformed startup paths
test_resource_boundaries.py	Optional network work stops after real transport resource exhaustion
test_release_boundaries.py	Real HTTP retries, Discord mention safety, unrenderable templates, SMTP password round trips, split terminal writes and the width cap without wcwidth
test_compact_commands.py	Literal short command prefixes, real help output and dependency hints
test_release_safety.py	Credential preservation, private errors, timing checks and scrobble-health state recovery
test_recovery_safety.py	Real dotenv reloads, setup backups, oversized counts and provider-error privacy
test_secret_policy.py	Shared credential priority, reload ownership and setup destination conflicts
test_smtp_error_privacy.py	Short and escaped passwords in rejected SMTP sign-ins through commands, setup, Doctor and delivery
test_setup_resolution_regressions.py	Saved dotenv destinations, empty secrets, export precedence and recovery paths
test_spotipy_request_policy.py	TLS policy at the Spotipy request boundary for token exchanges and refreshes
test_dotenv_quoted_keys.py	Quoted dotenv keys, export prefixes, multiline values and duplicate removal
test_config_and_inputs.py	Target normalization, CLI and config precedence, duration parsing, URI to URL conversion
test_config_effects.py	Config-file settings reaching their consumers, including check interval, connectivity and TLS verification
test_setup_wizard.py	Prompt helpers, validation, reprompting and the generated configuration
test_set_sp_dc.py	--set-sp-dc interactivity guards, atomic dotenv updates and failure rollback
test_set_lastfm_credentials.py	--set-lastfm-credentials prompts, partial updates and replacement confirmation
test_browser_cookie_import.py	Firefox and Chromium profile discovery, selection and cookie extraction
test_spotify_web_backends.py	TOTP generation, token validity probes, metadata backend selection and running without spotipy
test_startup_summary_channels.py	Summary rows naming the webhook provider, the mail server, the masked recipient, the delivery confirmations and the runtime
test_totp_secret_extraction.py	Secret extraction from bundles and the debug utility's destination and redirect restrictions
test_monitoring_loop.py	Friend Activity loop error and auth recovery, retry timing, activity flags and track-change recording
test_listening_activity.py	Activity source selection, live feed normalization, metadata enrichment and pause, resume and inactivity behavior
test_scrobble_health.py	Spotify to Last.fm authorization, token retries, play matching and missing-scrobble alerts
test_webhook_notifications.py	Webhook URL validation, provider detection, ntfy normalization and SIGHUP reload
test_email_html.py	HTML notification bodies: escaping, the Discord markdown form and the plain-text match
test_notification_escaping.py	Source-level sweep proving every HTML email body and attribute escapes Spotify-supplied text
test_local_transports.py	Real loopback HTTP and SMTP delivery, marked integration
test_runtime_security.py	Request deadlines and watchdog nesting, playback argument lists, cookie polling and terminal-safe Spotify output
test_terminal_color.py	Coloured terminal output: theme resolution, line rules, the colour-aware sanitizer, plain log files and the uncoloured Doctor progress line
test_help_screen.py	The --help screen: the shared argument group names, the task-grouped examples and the startup banner
test_tls_verification.py	Every connection honouring VERIFY_SSL and the single shared TLS context builder
test_recovery_errors.py	Error classification and install-method-aware recovery advice
test_doctor.py	--doctor report structure, sections, detail indentation and exit status
test_startup_ui.py	Startup banner rendering, alignment and machine-friendly --version and --generate-config output
test_install_method_commands.py	Install-method detection and the command prefixes shown for pip, manual, Docker and Compose
test_properties.py	Property-based parsing, serialization and secret-safety round-trips
test_offline_e2e.py	One complete CLI monitoring iteration against a loopback Spotify fixture, marked e2e
test_documentation.py	Semantic documentation contracts, community health files, issue templates and security workflows plus repository metadata: citation, funding, line endings, the declared editor style, the pinned linter and release integrity
test_container_assets.py	Dockerfile, Compose and publishing workflow contracts
test_packaging.py	Wheel contents, installed console commands, action pinning and version consistency
test_moved_private_settings.py	Kept credentials across dotenv destination changes and startup error handling
conftest.py	Shared fixture resetting the dotenv and secret state that the monitor mutates in place

Conventions

• Keep everything offline. If a code path needs network access, stub it with monkeypatch rather than skipping the test.
• Restore module-level globals you change. Tests share one imported module, so a leaked global affects whatever runs next.
• Mark tests that bind a local server integration, and full-flow CLI tests e2e.
• Never use a real cookie, refresh token, API key, SMTP password or webhook URL. Loopback tests use fake credentials that only the temporary local servers accept.

Online tests that authenticate against Spotify are excluded, because automated logins could trigger account protection. A change to token handling, the monitoring loop or a metadata backend is not verified by this suite alone. Exercise it against a real account and say so in the pull request.

See Testing for the CI jobs, supply chain checks and focused test commands.