musickit-api-mock-playwright 0.0.1__tar.gz

musickit_api_mock_playwright-0.0.1/LICENSE.txt

@@ -0,0 +1,121 @@
+Creative Commons Legal Code
+
+CC0 1.0 Universal
+
+    CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
+    LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
+    ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
+    INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
+    REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
+    PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
+    THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
+    HEREUNDER.
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator
+and subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for
+the purpose of contributing to a commons of creative, cultural and
+scientific works ("Commons") that the public can reliably and without fear
+of later claims of infringement build upon, modify, incorporate in other
+works, reuse and redistribute as freely as possible in any form whatsoever
+and for any purposes, including without limitation commercial purposes.
+These owners may contribute to the Commons to promote the ideal of a free
+culture and the further production of creative, cultural and scientific
+works, or to gain reputation or greater distribution for their Work in
+part through the use and efforts of others.
+
+For these and/or other purposes and motivations, and without any
+expectation of additional consideration or compensation, the person
+associating CC0 with a Work (the "Affirmer"), to the extent that he or she
+is an owner of Copyright and Related Rights in the Work, voluntarily
+elects to apply CC0 to the Work and publicly distribute the Work under its
+terms, with knowledge of his or her Copyright and Related Rights in the
+Work and the meaning and intended legal effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not
+limited to, the following:
+
+  i. the right to reproduce, adapt, distribute, perform, display,
+     communicate, and translate a Work;
+ ii. moral rights retained by the original author(s) and/or performer(s);
+iii. publicity and privacy rights pertaining to a person's image or
+     likeness depicted in a Work;
+ iv. rights protecting against unfair competition in regards to a Work,
+     subject to the limitations in paragraph 4(a), below;
+  v. rights protecting the extraction, dissemination, use and reuse of data
+     in a Work;
+ vi. database rights (such as those arising under Directive 96/9/EC of the
+     European Parliament and of the Council of 11 March 1996 on the legal
+     protection of databases, and under any national implementation
+     thereof, including any amended or successor version of such
+     directive); and
+vii. other similar, equivalent or corresponding rights throughout the
+     world based on applicable law or treaty, and any national
+     implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention
+of, applicable law, Affirmer hereby overtly, fully, permanently,
+irrevocably and unconditionally waives, abandons, and surrenders all of
+Affirmer's Copyright and Related Rights and associated claims and causes
+of action, whether now known or unknown (including existing as well as
+future claims and causes of action), in the Work (i) in all territories
+worldwide, (ii) for the maximum duration provided by applicable law or
+treaty (including future time extensions), (iii) in any current or future
+medium and for any number of copies, and (iv) for any purpose whatsoever,
+including without limitation commercial, advertising or promotional
+purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
+member of the public at large and to the detriment of Affirmer's heirs and
+successors, fully intending that such Waiver shall not be subject to
+revocation, rescission, cancellation, termination, or any other legal or
+equitable action to disrupt the quiet enjoyment of the Work by the public
+as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason
+be judged legally invalid or ineffective under applicable law, then the
+Waiver shall be preserved to the maximum extent permitted taking into
+account Affirmer's express Statement of Purpose. In addition, to the
+extent the Waiver is so judged Affirmer hereby grants to each affected
+person a royalty-free, non transferable, non sublicensable, non exclusive,
+irrevocable and unconditional license to exercise Affirmer's Copyright and
+Related Rights in the Work (i) in all territories worldwide, (ii) for the
+maximum duration provided by applicable law or treaty (including future
+time extensions), (iii) in any current or future medium and for any number
+of copies, and (iv) for any purpose whatsoever, including without
+limitation commercial, advertising or promotional purposes (the
+"License"). The License shall be deemed effective as of the date CC0 was
+applied by Affirmer to the Work. Should any part of the License for any
+reason be judged legally invalid or ineffective under applicable law, such
+partial invalidity or ineffectiveness shall not invalidate the remainder
+of the License, and in such case Affirmer hereby affirms that he or she
+will not (i) exercise any of his or her remaining Copyright and Related
+Rights in the Work or (ii) assert any associated claims and causes of
+action with respect to the Work, in either case contrary to Affirmer's
+express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+ a. No trademark or patent rights held by Affirmer are waived, abandoned,
+    surrendered, licensed or otherwise affected by this document.
+ b. Affirmer offers the Work as-is and makes no representations or
+    warranties of any kind concerning the Work, express, implied,
+    statutory or otherwise, including without limitation warranties of
+    title, merchantability, fitness for a particular purpose, non
+    infringement, or the absence of latent or other defects, accuracy, or
+    the present or absence of errors, whether or not discoverable, all to
+    the greatest extent permissible under applicable law.
+ c. Affirmer disclaims responsibility for clearing rights of other persons
+    that may apply to the Work or any use thereof, including without
+    limitation any person's Copyright and Related Rights in the Work.
+    Further, Affirmer disclaims responsibility for obtaining any necessary
+    consents, permissions or other rights required for any use of the
+    Work.
+ d. Affirmer understands and acknowledges that Creative Commons is not a
+    party to this document and has no duty or obligation with respect to
+    this CC0 or use of the Work.

musickit_api_mock_playwright-0.0.1/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: musickit-api-mock-playwright
+Version: 0.0.1
+Summary: Playwright host adapter for musickit-api-mock.
+Keywords: apple-music,musickit,mock,testing,playwright,browser-automation
+Author: HotariTobu
+Author-email: HotariTobu <hotari24tools@gmail.com>
+License-Expression: CC0-1.0
+License-File: LICENSE.txt
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Software Development :: Testing :: Mocking
+Classifier: Typing :: Typed
+Requires-Dist: musickit-api-mock
+Requires-Dist: playwright>=1.58.0
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/HotariTobu/musickit-api-mock
+Project-URL: Repository, https://github.com/HotariTobu/musickit-api-mock
+Project-URL: Issues, https://github.com/HotariTobu/musickit-api-mock/issues
+Description-Content-Type: text/markdown
+
+# musickit-api-mock
+
+Apple Music API mock for [MusicKit JS](https://developer.apple.com/musickit/). 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.
+
+## Packages
+
+This repository is a uv workspace with a thin core / adapter split:
+
+- **`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.
+
+## Install
+
+```bash
+pip install musickit-api-mock-playwright
+```
+
+The Playwright adapter depends on the core package transitively. Install only the core package if you write your own host adapter for a different browser-automation framework.
+
+## Quick start
+
+### Sync Playwright
+
+```python
+from musickit_api_mock import (
+    MusicKitApiMock,
+    Song,
+    Storefront,
+    StorefrontResponseSuccess,
+)
+from musickit_api_mock_playwright import intercept
+from playwright.sync_api import sync_playwright
+
+mock = MusicKitApiMock()
+
+# Shared resource data: songs keyed by catalog id.
+mock.data.songs = {
+    "1000000001": Song.from_file("tests/fixtures/silence.m4a"),
+}
+
+# Endpoint-level response: storefront resolution.
+mock.endpoints.storefront = StorefrontResponseSuccess(
+    storefront=Storefront(
+        id="us",
+        name="United States",
+        default_language_tag="en-US",
+        supported_language_tags=["en-US"],
+        explicit_content_policy="allowed",
+    ),
+)
+
+with sync_playwright() as pw:
+    browser = pw.chromium.launch()
+    page = browser.new_page()
+    intercept(mock, page)
+    page.goto("https://your-app.example/")
+    # ... drive MusicKit JS through your app and assert ...
+    browser.close()
+```
+
+### Async Playwright
+
+```python
+from musickit_api_mock_playwright import intercept_async
+
+await intercept_async(mock, page)
+```
+
+`intercept` and `intercept_async` accept either a `Page` (binds to that single page) or a `BrowserContext` (covers every page in the context, including popups and pages opened later).
+
+## Surfaces
+
+A `MusicKitApiMock` instance exposes three configuration surfaces. The split is load-bearing — each surface has a distinct semantic role:
+
+- **`mock.data.*`** — shared resource sources (songs, albums, playlists, artists, library items, ...). Read by multiple endpoints when composing responses. Each field accepts a `dict[str, T]` keyed by id, or a `Callable[[LookupContext], T]` for dynamic resolution.
+- **`mock.endpoints.*`** — per-endpoint response overrides (storefront, account, license, web playback, ...). Each field accepts a response value, a dict keyed by id, or a callable returning a response. Use these to shape the HTTP response itself (status, error variants, ...).
+- **`mock.browser.*`** — state consumed by the in-page JS shim, e.g. the authorize response delivered when the page calls `music.authorize()`, and the EME key system flavor the shim should expose.
+
+All fields default to `None`, which is the unset sentinel. Reading an unset field at request time raises `ValueError` — the mock does not invent fallback values for fields you didn't configure.
+
+## Scope
+
+- **Target audience**: third-party developers using the default MusicKit JS configuration, i.e. `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](LICENSE.txt) — public domain dedication.

musickit_api_mock_playwright-0.0.1/README.md

@@ -0,0 +1,97 @@
+# musickit-api-mock
+
+Apple Music API mock for [MusicKit JS](https://developer.apple.com/musickit/). 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.
+
+## Packages
+
+This repository is a uv workspace with a thin core / adapter split:
+
+- **`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.
+
+## Install
+
+```bash
+pip install musickit-api-mock-playwright
+```
+
+The Playwright adapter depends on the core package transitively. Install only the core package if you write your own host adapter for a different browser-automation framework.
+
+## Quick start
+
+### Sync Playwright
+
+```python
+from musickit_api_mock import (
+    MusicKitApiMock,
+    Song,
+    Storefront,
+    StorefrontResponseSuccess,
+)
+from musickit_api_mock_playwright import intercept
+from playwright.sync_api import sync_playwright
+
+mock = MusicKitApiMock()
+
+# Shared resource data: songs keyed by catalog id.
+mock.data.songs = {
+    "1000000001": Song.from_file("tests/fixtures/silence.m4a"),
+}
+
+# Endpoint-level response: storefront resolution.
+mock.endpoints.storefront = StorefrontResponseSuccess(
+    storefront=Storefront(
+        id="us",
+        name="United States",
+        default_language_tag="en-US",
+        supported_language_tags=["en-US"],
+        explicit_content_policy="allowed",
+    ),
+)
+
+with sync_playwright() as pw:
+    browser = pw.chromium.launch()
+    page = browser.new_page()
+    intercept(mock, page)
+    page.goto("https://your-app.example/")
+    # ... drive MusicKit JS through your app and assert ...
+    browser.close()
+```
+
+### Async Playwright
+
+```python
+from musickit_api_mock_playwright import intercept_async
+
+await intercept_async(mock, page)
+```
+
+`intercept` and `intercept_async` accept either a `Page` (binds to that single page) or a `BrowserContext` (covers every page in the context, including popups and pages opened later).
+
+## Surfaces
+
+A `MusicKitApiMock` instance exposes three configuration surfaces. The split is load-bearing — each surface has a distinct semantic role:
+
+- **`mock.data.*`** — shared resource sources (songs, albums, playlists, artists, library items, ...). Read by multiple endpoints when composing responses. Each field accepts a `dict[str, T]` keyed by id, or a `Callable[[LookupContext], T]` for dynamic resolution.
+- **`mock.endpoints.*`** — per-endpoint response overrides (storefront, account, license, web playback, ...). Each field accepts a response value, a dict keyed by id, or a callable returning a response. Use these to shape the HTTP response itself (status, error variants, ...).
+- **`mock.browser.*`** — state consumed by the in-page JS shim, e.g. the authorize response delivered when the page calls `music.authorize()`, and the EME key system flavor the shim should expose.
+
+All fields default to `None`, which is the unset sentinel. Reading an unset field at request time raises `ValueError` — the mock does not invent fallback values for fields you didn't configure.
+
+## Scope
+
+- **Target audience**: third-party developers using the default MusicKit JS configuration, i.e. `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](LICENSE.txt) — public domain dedication.

musickit_api_mock_playwright-0.0.1/pyproject.toml

@@ -0,0 +1,54 @@
+[project]
+name = "musickit-api-mock-playwright"
+version = "0.0.1"
+description = "Playwright host adapter for musickit-api-mock."
+readme = "README.md"
+authors = [
+    { name = "HotariTobu", email = "hotari24tools@gmail.com" }
+]
+license = "CC0-1.0"
+license-files = ["LICENSE.txt"]
+requires-python = ">=3.12"
+keywords = ["apple-music", "musickit", "mock", "testing", "playwright", "browser-automation"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Testing",
+    "Topic :: Software Development :: Testing :: Mocking",
+    "Typing :: Typed",
+]
+dependencies = [
+    "musickit-api-mock",
+    "playwright>=1.58.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/HotariTobu/musickit-api-mock"
+Repository = "https://github.com/HotariTobu/musickit-api-mock"
+Issues = "https://github.com/HotariTobu/musickit-api-mock/issues"
+
+[build-system]
+requires = ["uv_build>=0.11.2,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv.sources]
+musickit-api-mock = { workspace = true }
+
+[dependency-groups]
+dev = [
+    "pytest-asyncio>=1.3.0",
+    "pytest-playwright-asyncio>=0.7.2",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "session"
+asyncio_default_test_loop_scope = "session"
+markers = [
+    "sync_test: tests using the sync_playwright API",
+    "async_test: tests using the async_playwright API",
+]

musickit_api_mock_playwright-0.0.1/src/musickit_api_mock_playwright/__init__.py

@@ -0,0 +1,6 @@
+"""Playwright host adapter for musickit-api-mock."""
+
+from musickit_api_mock_playwright.async_adapter import intercept_async
+from musickit_api_mock_playwright.sync_adapter import intercept
+
+__all__ = ["intercept", "intercept_async"]

musickit_api_mock_playwright-0.0.1/src/musickit_api_mock_playwright/async_adapter.py

@@ -0,0 +1,49 @@
+"""Async Playwright adapter."""
+
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING
+
+from musickit_api_mock_playwright.shared import _to_core_request
+
+if TYPE_CHECKING:
+    from musickit_api_mock.mock import MusicKitApiMock
+    from playwright.async_api import BrowserContext as AsyncBrowserContext
+    from playwright.async_api import Page as AsyncPage
+    from playwright.async_api import Route as AsyncRoute
+
+
+async def intercept_async(
+    mock: MusicKitApiMock,
+    target: AsyncPage | AsyncBrowserContext,
+) -> None:
+    """Wire the mock into an async Playwright page or browser context.
+
+    Pass a page to bind to that single page. Pass a browser context to cover
+    every page in the context, including popups and pages opened later.
+    """
+    await target.add_init_script(mock.get_shim_script())
+    await target.route("**/*", lambda route: _handle_async(mock, route))
+
+
+async def _handle_async(mock: MusicKitApiMock, route: AsyncRoute) -> None:
+    req = _to_core_request(route.request)
+    try:
+        resp = mock.handle_request(req)
+    except Exception as e:
+        # The mock raised (e.g. a setter is unset). Surface the original
+        # message to stderr (it would otherwise be lost in the network-level
+        # abort) and end the request as a network failure rather than hanging.
+        # Returning any HTTP status here would collide with mock-produced
+        # status responses, so abort is the only collision-free choice.
+        print(
+            f"[musickit-api-mock] handler error: {type(e).__name__}: {e}",
+            file=sys.stderr,
+        )
+        await route.abort()
+        return
+    if resp is None:
+        await route.fallback()
+        return
+    await route.fulfill(status=resp.status, headers=resp.headers, body=resp.body)

musickit_api_mock_playwright-0.0.1/src/musickit_api_mock_playwright/shared.py

@@ -0,0 +1,27 @@
+"""Shared helper to convert a Playwright ``Request`` into the core ``Request`` type."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from musickit_api_mock.transport.http import Request
+
+if TYPE_CHECKING:
+    from playwright.async_api import Request as AsyncRequest
+    from playwright.sync_api import Request as SyncRequest
+
+
+def _to_core_request(playwright_request: SyncRequest | AsyncRequest) -> Request:
+    body: bytes | None = None
+    raw = playwright_request.post_data_buffer
+    if raw is not None:
+        body = bytes(raw)
+    elif playwright_request.post_data is not None:
+        body = playwright_request.post_data.encode("utf-8")
+    headers_dict: dict[str, str] = dict(playwright_request.headers or {})
+    return Request(
+        method=playwright_request.method,
+        url=playwright_request.url,
+        headers=headers_dict,
+        body=body,
+    )

musickit_api_mock_playwright-0.0.1/src/musickit_api_mock_playwright/sync_adapter.py

@@ -0,0 +1,44 @@
+"""Sync Playwright adapter."""
+
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING
+
+from musickit_api_mock_playwright.shared import _to_core_request
+
+if TYPE_CHECKING:
+    from musickit_api_mock.mock import MusicKitApiMock
+    from playwright.sync_api import BrowserContext, Page, Route
+
+
+def intercept(mock: MusicKitApiMock, target: Page | BrowserContext) -> None:
+    """Wire the mock into a sync Playwright page or browser context.
+
+    Pass a page to bind to that single page. Pass a browser context to cover
+    every page in the context, including popups and pages opened later.
+    """
+    target.add_init_script(mock.get_shim_script())
+    target.route("**/*", lambda route: _handle(mock, route))
+
+
+def _handle(mock: MusicKitApiMock, route: Route) -> None:
+    req = _to_core_request(route.request)
+    try:
+        resp = mock.handle_request(req)
+    except Exception as e:
+        # The mock raised (e.g. a setter is unset). Surface the original
+        # message to stderr (it would otherwise be lost in the network-level
+        # abort) and end the request as a network failure rather than hanging.
+        # Returning any HTTP status here would collide with mock-produced
+        # status responses, so abort is the only collision-free choice.
+        print(
+            f"[musickit-api-mock] handler error: {type(e).__name__}: {e}",
+            file=sys.stderr,
+        )
+        route.abort()
+        return
+    if resp is None:
+        route.fallback()
+        return
+    route.fulfill(status=resp.status, headers=resp.headers, body=resp.body)