feat: add MediaBackend-v2-aware test harness

[JarbasAl]

🤖 Auto-generated by Claude Fable 5 (claude-fable-5) via Claude Code — NOT human-reviewed. Verify before acting.

ovos-media's feat/media-backend-v2-port branch replaces the v1 MediaBackend contract with a report()/bind_event_reporter() one: plugins report physical PlaybackEvents (TRACK_START, PAUSED, RESUMED, STOPPED, END_OF_MEDIA, ERROR) instead of emitting bus messages themselves, load_track returns a bool instead of a None, and stop() becomes a concrete template method that delegates to a plugin's _stop(). The daemon (ovos-media's BaseMediaService) is now the sole translator from those events to ovos.common_play.* wire messages, via _handle_backend_event — and it has dropped handle_media_state_change entirely. ovoscope's media harnesses predate this port and needed updating to keep exercising the real daemon shape.

This adds MediaBackendHarness (ovoscope/media_backend.py), a harness for a plugin author testing their own MediaBackend v2 class in isolation: it binds a capturing spy reporter onto a backend instance and asserts the event sequence and per-event data it reports, without any daemon involved. The v2 template it targets (ovos_plugin_manager.templates.media) only exists on the unreleased OPM branch, so both the module import and the ovoscope/__init__.py re-export are guarded: import ovoscope is always safe against a released ovos-plugin-manager, and MediaBackendHarness() raises a clear ImportError only when actually constructed without the v2 template installed. Its own test module carries the equivalent guard at collection time, since its plugin stand-in subclasses the v2 template directly.

It also adds MockOCPBackendV2 (ovoscope/media.py), the v2 counterpart to the existing MockOCPBackend (kept unmodified, still importable, for plugin repos that haven't ported yet), and makes it OCPPlayerHarness's default injected backend. OCPPlayerHarness.__enter__ now binds each injected backend's event reporter, and guards the v1-only set_track_start_callback call on whether the service it reads track_start from actually has that attribute — not on the backend, which a v1 backend always has regardless of which ovos-media build is installed; guarding on the backend alone still crashed with AttributeError against a v2 build. In the default (no backend_factory) mode, audio_service is a MagicMock with no real _handle_backend_event behind it, so the backend's reporter is bound to a small shim reproducing the daemon's END_OF_MEDIA/ERROR wire translation — the only two events that mode's own control methods can actually drive — with its docstring naming the two daemon guards (currency, staleness) it deliberately skips, so a test needing those knows to go through the real daemon (backend_factory) instead. MockOCPBackendV2.load_track now clears current_uri on a failed load, so a failed load doesn't leave a stale, previous track's uri behind for a following simulate_invalid_stream()/report_track_end() to report against.

Every v2-only test class and cell is now gated on whether the v2 template actually imported, not merely on ovos-media being installed, and the backend_factory stand-in several pre-existing cells share (_RecordingBackend) now has a v1 variant selected the same way — including fixing that variant to emit LOADED_MEDIA on the topic a real v1 BaseMediaService actually subscribes to (ovos.common_play.media.state), not the per-namespace one MockOCPBackend emits, which no real BaseMediaService instance has ever listened on. The full suite now collects and runs clean against both a released ovos-plugin-manager (v2 cells skip) and the unreleased branches (v2 cells run) — collection used to abort entirely against released deps because a test module imported the v2 template unguarded at collection time.

Fail-before (source reverted with the test kept, run foreground, then restored): the set_track_start_callback guard turned 16 of 42 test_media.py tests failing with AttributeError across every OCPPlayerHarness-based class; the default-mode event-reporter shim's two new cells failed with no wire message emitted at all when reverted to binding straight into the MagicMock's _handle_backend_event; test_failed_load_clears_current_uri failed with the current_uri clear removed.

Full suite against released PyPI deps on python 3.10, foreground: 655 passed, 55 skipped, 0 failed. The 55 skips are exactly the v2-only cells gated off without the v2 template.

No workflow installs from git. coverage-pages.yml and release-workflow.yml's build_tests job gain the media, listener and bench extras, which they lacked, and that is the whole CI change. The released ovos-plugin-manager is 2.12.1a1 (latest alpha; its templates/media.py is still the v1 one, no PlaybackEvent, no bind_event_reporter) and released ovos-media is 2.2.5a1, so neither carries the v2 backend template. The [media] floor therefore stays at ovos-media>=2.0.0a9 and the v2 cells skip on the template guard they already carry; they start running once ovos-plugin-manager publishes the v2 template and the floor can be raised to it.

That also settles the build_tests (3.10) failure on TestOCPHarnessWithoutHandlePlay::test_enter_and_play_succeed_when_handle_play_is_absent: it was specific to the git-branch ovos-media those pre_install_pip lines installed, not to dev. Against released deps that cell passes, as does the rest of the suite.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Fresh off the press! I've got some check results for you. 🗞️

I've aggregated the results of the automated checks for this PR below.

🔍 Lint

A quick update on the progress of your PR checks. 📈

❌ ruff: issues found — see job log

📊 Coverage

Checking the structural integrity of our tests. 🏗️

⚠️ 61.5% total coverage

Files below 80% coverage (16 files)

File	Coverage	Missing lines
ovoscope/media_backend.py	0.0%	53
ovoscope/simple_listener.py	0.0%	63
ovoscope/version.py	0.0%	5
ovoscope/classic_listener.py	18.2%	117
ovoscope/intent_cases.py	22.3%	153
ovoscope/media.py	44.7%	167
ovoscope/pytest_plugin.py	47.0%	210
ovoscope/cli.py	47.8%	132
ovoscope/ocp.py	47.9%	61
ovoscope/tts_intelligibility.py	49.0%	102
ovoscope/e2e.py	56.2%	67
ovoscope/listener.py	57.1%	127
ovoscope/voice_loop.py	59.0%	119
ovoscope/__init__.py	63.2%	424
ovoscope/audio.py	64.4%	126
ovoscope/media_provider.py	67.6%	23

Full report: download the coverage-report artifact.

⚖️ License Check

I've verified the license compliance for your changes. ✅

✅ No license violations found.

Policy: Apache 2.0 (universal donor). StrongCopyleft / NetworkCopyleft / WeakCopyleft / Other / Error categories fail. MPL allowed.

📋 Repo Health

Scanning for any signs of 'comment' bad breath. 🌬️

✅ All required files present.

Latest Version: 1.8.1a1

✅ ovoscope/version.py — Version file
✅ README.md — README
✅ LICENSE — License file
✅ pyproject.toml — pyproject.toml
⚠️ setup.py — setup.py
✅ CHANGELOG.md — Changelog
✅ ovoscope/version.py has valid version block markers

🔒 Security (pip-audit)

Looking for any Trojan horses in the dependencies. 🐎

✅ No known vulnerabilities found (129 packages scanned).

🏷️ Release Preview

I've performed a final polish on the release notes. 🧼

Current: 1.8.1a1 → Next: 1.9.0a1

Signal	Value
Label	feature
PR title	feat: add MediaBackend-v2-aware test harness
Bump	minor

✅ PR title follows conventional commit format.

---

🚀 Release Channel Compatibility

Predicted next version: 1.9.0a1

Channel	Status	Note	Current Constraint
Stable	⚪	Not in channel	-
Testing	❌	Too new (must be <1.0.0)	ovoscope>=0.7.2,<1.0.0
Alpha	✅	Compatible	ovoscope>=1.6.15a1

🔨 Build Tests

The compiler has spoken! Here is the verdict. 📜

✅ All versions pass

Python	Build	Install	Tests
3.10	✅	✅	✅
3.11	✅	✅	✅
3.12	✅	✅	✅
3.13	✅	✅	✅
3.14	✅	✅	✅

---

Powered by OVOS scripts and a bit of magic. ✨