Skip to content

musickit-api-mock

Apple Music API mock for MusicKit JS. Runs as an in-process request interceptor inside browser-automation tests, so the page hits the mock instead of api.music.apple.com.

Useful for testing web apps that embed MusicKit JS without depending on Apple's servers, a developer token, or a signed-in Apple Music subscription.

Where to start

  • :material-rocket-launch: Getting started — install, minimum example, and how the pieces fit together.
  • :material-book-open-variant: Surfaces overview — what mock.data / mock.endpoints / mock.browser are for.
  • :material-puzzle: Playwright integration — sync / async, page vs. context binding.
  • :material-api: Reference — auto-generated API documentation for every public class and function.
  • :material-chef-hat: Recipes — task-oriented snippets ("simulate a subscription error", "trigger DRM failure", ...).

Packages

  • musickit-api-mock — transport-agnostic mock engine. Routes HTTP requests, composes Apple Music API response bodies, and ships the in-page JS shim that replaces MusicKit JS's browser integrations.
  • musickit-api-mock-playwright — Playwright host adapter. Bridges the engine to page.route for both sync and async Playwright APIs.

Scope

  • Target audience: third-party developers using the default MusicKit JS configuration, i.e. calling MusicKit.configure(...) without Apple-internal overrides.
  • Intercepted host: api.music.apple.com. Apple's own web-player override hosts (e.g. amp-api.music.apple.com) are out of scope.
  • Intercepted paths: every path the default-config host emits within MusicKit JS's resource set (songs, albums, artists, library-*, me/*, ...). Within an intercepted path, every form the path can accept is handled — not just the subset MusicKit JS happens to send.

Supported environments

  • Python ≥ 3.12
  • Playwright (sync and async) on Chromium, Firefox, and WebKit
  • Linux, macOS, Windows

License

CC0 1.0 Universal — public domain dedication.