agentskills-testing 0.4.0__py3-none-any.whl

agentskills_testing/__init__.py

@@ -0,0 +1,60 @@
+"""Conformance suite and test doubles for Agent Skills providers.
+
+Two things live here:
+
+* :class:`ProviderConformanceSuite` — subclass it, supply a ``provider``
+  fixture, and pytest runs the whole provider contract against your
+  implementation.
+* :class:`InMemorySkillProvider` — a real, spec-compliant provider
+  backed by a dict, for tests that need a skill but not a disk.
+
+See https://github.com/pratikxpanda/agentskills-sdk for the guide.
+"""
+
+from agentskills_testing.conformance import (
+    ASSET_BYTES,
+    ASSET_NAME,
+    CONTRACT,
+    MISSING_ID,
+    MISSING_RESOURCE,
+    REFERENCE_BYTES,
+    REFERENCE_NAME,
+    SCRIPT_BYTES,
+    SCRIPT_NAME,
+    SKILL_ID,
+    TRAVERSAL_IDENTIFIERS,
+    ContentLimitConformanceSuite,
+    ProviderConformanceSuite,
+)
+from agentskills_testing.memory import (
+    DEFAULT_BODY,
+    DEFAULT_DESCRIPTION,
+    DEFAULT_SKILL_ID,
+    InMemorySkill,
+    InMemorySkillProvider,
+    build_skill,
+    render_skill_md,
+)
+
+__all__ = [
+    "ASSET_BYTES",
+    "ASSET_NAME",
+    "CONTRACT",
+    "DEFAULT_BODY",
+    "DEFAULT_DESCRIPTION",
+    "DEFAULT_SKILL_ID",
+    "MISSING_ID",
+    "MISSING_RESOURCE",
+    "REFERENCE_BYTES",
+    "REFERENCE_NAME",
+    "SCRIPT_BYTES",
+    "SCRIPT_NAME",
+    "SKILL_ID",
+    "TRAVERSAL_IDENTIFIERS",
+    "ContentLimitConformanceSuite",
+    "InMemorySkill",
+    "InMemorySkillProvider",
+    "ProviderConformanceSuite",
+    "build_skill",
+    "render_skill_md",
+]

agentskills_testing/conformance.py

@@ -0,0 +1,326 @@
+"""The provider conformance suite.
+
+``SkillProvider`` is an ABC, which enforces that five methods exist and
+nothing about what they do.  The requirements that actually matter are
+the ones an ABC cannot express: that an unknown ID raises the documented
+exception rather than returning ``None``, that a traversal-shaped
+identifier is refused rather than resolved, and that a provider
+advertising resource listing or discovery can actually deliver it.
+
+Subclass :class:`ProviderConformanceSuite`, supply a ``provider``
+fixture populated per :data:`CONTRACT`, and pytest collects the whole
+suite against your implementation.
+
+Every test is marked ``asyncio`` explicitly so the suite runs under
+``pytest-asyncio`` in either strict or auto mode — a kit that only works
+under one project's configuration is not a kit.
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+import pytest
+
+from agentskills_core import (
+    RESOURCE_KINDS,
+    AgentSkillsError,
+    DiscoveryNotSupportedError,
+    ResourceListingNotSupportedError,
+    ResourceNotFoundError,
+    SkillNotFoundError,
+    SkillProvider,
+)
+
+#: The skill a conforming ``provider`` fixture must expose.
+SKILL_ID = "conformance-skill"
+
+#: The reference document that skill must contain, and its exact bytes.
+REFERENCE_NAME = "notes.md"
+REFERENCE_BYTES = b"# Notes\n\nA reference document.\n"
+
+#: The script that skill must contain, and its exact bytes.
+SCRIPT_NAME = "run.sh"
+SCRIPT_BYTES = b"#!/bin/sh\necho conformance\n"
+
+#: The asset that skill must contain, and its exact bytes.
+ASSET_NAME = "diagram.svg"
+ASSET_BYTES = b"<svg></svg>\n"
+
+#: An ID no conforming fixture may define.
+MISSING_ID = "no-such-skill-anywhere"
+
+#: A resource name no conforming fixture may define.
+MISSING_RESOURCE = "no-such-resource.txt"
+
+CONTRACT = f"""\
+The `provider` fixture must expose exactly one skill:
+
+  id           {SKILL_ID}
+  metadata     name == {SKILL_ID!r}, plus a non-empty description
+  body         non-empty markdown
+  references/  {REFERENCE_NAME} containing {REFERENCE_BYTES!r}
+  scripts/     {SCRIPT_NAME} containing {SCRIPT_BYTES!r}
+  assets/      {ASSET_NAME} containing {ASSET_BYTES!r}
+
+It must not define a skill called {MISSING_ID!r} or any resource called
+{MISSING_RESOURCE!r}.  A provider that sets `supports_discovery` must
+report exactly one skill, {SKILL_ID!r}.
+"""
+
+#: Identifiers a provider must refuse rather than resolve.  Each is a
+#: real technique: parent traversal, an absolute path, a Windows path, a
+#: percent-encoded traversal that a URL-building backend may decode, and
+#: a NUL byte that truncates a C string.
+TRAVERSAL_IDENTIFIERS = (
+    "../etc/passwd",
+    "..",
+    "a/../../b",
+    "/etc/passwd",
+    "..\\..\\windows\\system32",
+    "%2e%2e%2fetc%2fpasswd",
+    "ok\x00.md",
+)
+
+_RESOURCE_GETTERS = {
+    "references": "get_reference",
+    "scripts": "get_script",
+    "assets": "get_asset",
+}
+
+_EXPECTED_RESOURCES = {
+    "references": (REFERENCE_NAME, REFERENCE_BYTES),
+    "scripts": (SCRIPT_NAME, SCRIPT_BYTES),
+    "assets": (ASSET_NAME, ASSET_BYTES),
+}
+
+
+class ProviderConformanceSuite:
+    """Assertions every :class:`~agentskills_core.SkillProvider` must satisfy.
+
+    Subclass it and provide a ``provider`` fixture::
+
+        class TestMyProvider(ProviderConformanceSuite):
+            @pytest.fixture
+            def provider(self):
+                return MyProvider(...)
+
+    The fixture must be populated per :data:`CONTRACT`.  Nothing here is
+    opt-out: a provider that cannot pass these is not a provider, it is
+    a class with the right method names.
+    """
+
+    @pytest.fixture
+    def provider(self) -> SkillProvider:
+        """Return the provider under test, populated per :data:`CONTRACT`."""
+        raise NotImplementedError(f"Override the 'provider' fixture.\n\n{CONTRACT}")
+
+    # -- Identity -------------------------------------------------------
+
+    def test_is_a_skill_provider(self, provider: SkillProvider) -> None:
+        assert isinstance(provider, SkillProvider)
+
+    # -- Metadata and body ---------------------------------------------
+
+    @pytest.mark.asyncio
+    async def test_metadata_has_the_required_fields(self, provider: SkillProvider) -> None:
+        metadata = await provider.get_metadata(SKILL_ID)
+
+        assert isinstance(metadata, dict)
+        assert metadata.get("name") == SKILL_ID
+        assert isinstance(metadata.get("description"), str)
+        assert metadata["description"].strip()
+
+    @pytest.mark.asyncio
+    async def test_metadata_excludes_the_body(self, provider: SkillProvider) -> None:
+        metadata = await provider.get_metadata(SKILL_ID)
+        body = await provider.get_body(SKILL_ID)
+
+        assert body.strip()
+        # Progressive disclosure is the whole point: a metadata call that
+        # carries the body has already spent the tokens it exists to save.
+        assert all(value != body for value in metadata.values())
+
+    @pytest.mark.asyncio
+    async def test_metadata_is_not_shared_mutable_state(self, provider: SkillProvider) -> None:
+        first = await provider.get_metadata(SKILL_ID)
+        first["description"] = "mutated by a caller"
+
+        second = await provider.get_metadata(SKILL_ID)
+
+        assert second["description"] != "mutated by a caller"
+
+    @pytest.mark.asyncio
+    async def test_repeated_reads_agree(self, provider: SkillProvider) -> None:
+        # A provider that streams without buffering passes once and then
+        # returns empty. Caching bugs surface the same way.
+        assert await provider.get_body(SKILL_ID) == await provider.get_body(SKILL_ID)
+        assert await provider.get_metadata(SKILL_ID) == await provider.get_metadata(SKILL_ID)
+
+    @pytest.mark.asyncio
+    async def test_unknown_skill_raises_skill_not_found(self, provider: SkillProvider) -> None:
+        with pytest.raises(SkillNotFoundError):
+            await provider.get_metadata(MISSING_ID)
+        with pytest.raises(SkillNotFoundError):
+            await provider.get_body(MISSING_ID)
+
+    # -- Resources ------------------------------------------------------
+
+    @pytest.mark.parametrize("kind", RESOURCE_KINDS)
+    @pytest.mark.asyncio
+    async def test_resource_returns_exact_bytes(self, provider: SkillProvider, kind: str) -> None:
+        name, expected = _EXPECTED_RESOURCES[kind]
+
+        data = await getattr(provider, _RESOURCE_GETTERS[kind])(SKILL_ID, name)
+
+        # bytes, not str: a resource may be a PNG, and decoding it on the
+        # way out makes that unreachable.
+        assert isinstance(data, bytes)
+        assert data == expected
+
+    @pytest.mark.parametrize("kind", RESOURCE_KINDS)
+    @pytest.mark.asyncio
+    async def test_unknown_resource_raises_resource_not_found(
+        self, provider: SkillProvider, kind: str
+    ) -> None:
+        with pytest.raises(ResourceNotFoundError):
+            await getattr(provider, _RESOURCE_GETTERS[kind])(SKILL_ID, MISSING_RESOURCE)
+
+    @pytest.mark.parametrize("kind", RESOURCE_KINDS)
+    @pytest.mark.asyncio
+    async def test_resource_of_unknown_skill_is_refused(
+        self, provider: SkillProvider, kind: str
+    ) -> None:
+        name, _ = _EXPECTED_RESOURCES[kind]
+
+        with pytest.raises((SkillNotFoundError, ResourceNotFoundError)):
+            await getattr(provider, _RESOURCE_GETTERS[kind])(MISSING_ID, name)
+
+    # -- Resource listing ----------------------------------------------
+
+    @pytest.mark.asyncio
+    async def test_listing_matches_the_declared_capability(self, provider: SkillProvider) -> None:
+        # The flag is what callers branch on, so a provider whose flag
+        # and behaviour disagree breaks them whichever way it lies.
+        if provider.supports_resource_listing:
+            try:
+                listing = await provider.list_resources(SKILL_ID)
+            except ResourceListingNotSupportedError as exc:
+                pytest.fail(
+                    f"supports_resource_listing is True but list_resources() refused to list: {exc}"
+                )
+            assert set(listing) == set(RESOURCE_KINDS)
+            for kind in RESOURCE_KINDS:
+                assert listing[kind] == sorted(listing[kind])
+                expected_name, _ = _EXPECTED_RESOURCES[kind]
+                assert expected_name in listing[kind]
+        else:
+            with pytest.raises(ResourceListingNotSupportedError):
+                await provider.list_resources(SKILL_ID)
+
+    @pytest.mark.asyncio
+    async def test_listing_of_unknown_skill_is_refused(self, provider: SkillProvider) -> None:
+        if not provider.supports_resource_listing:
+            pytest.skip("provider does not support resource listing")
+
+        with pytest.raises(SkillNotFoundError):
+            await provider.list_resources(MISSING_ID)
+
+    # -- Skill discovery ------------------------------------------------
+
+    @pytest.mark.asyncio
+    async def test_discovery_matches_the_declared_capability(self, provider: SkillProvider) -> None:
+        if provider.supports_discovery:
+            try:
+                skill_ids = await provider.discover()
+            except DiscoveryNotSupportedError as exc:
+                pytest.fail(f"supports_discovery is True but discover() refused: {exc}")
+            assert isinstance(skill_ids, list)
+            # The contract fixture holds exactly one skill, so this also
+            # pins sortedness and the absence of duplicates.
+            assert skill_ids == [SKILL_ID]
+        else:
+            with pytest.raises(DiscoveryNotSupportedError):
+                await provider.discover()
+
+    @pytest.mark.asyncio
+    async def test_discovered_skills_are_readable(self, provider: SkillProvider) -> None:
+        if not provider.supports_discovery:
+            pytest.skip("provider does not support discovery")
+
+        # register_all() validates everything discover() returns, so an ID
+        # that cannot be read poisons the whole registration.
+        for skill_id in await provider.discover():
+            assert await provider.get_metadata(skill_id)
+
+    # -- Security -------------------------------------------------------
+
+    @pytest.mark.parametrize("identifier", TRAVERSAL_IDENTIFIERS)
+    @pytest.mark.asyncio
+    async def test_traversal_skill_id_is_refused(
+        self, provider: SkillProvider, identifier: str
+    ) -> None:
+        with pytest.raises(SkillNotFoundError):
+            await provider.get_metadata(identifier)
+
+    @pytest.mark.parametrize("identifier", TRAVERSAL_IDENTIFIERS)
+    @pytest.mark.parametrize("kind", RESOURCE_KINDS)
+    @pytest.mark.asyncio
+    async def test_traversal_resource_name_is_refused(
+        self, provider: SkillProvider, kind: str, identifier: str
+    ) -> None:
+        with pytest.raises(ResourceNotFoundError):
+            await getattr(provider, _RESOURCE_GETTERS[kind])(SKILL_ID, identifier)
+
+    # -- Concurrency ----------------------------------------------------
+
+    @pytest.mark.asyncio
+    async def test_reads_are_concurrency_safe(self, provider: SkillProvider) -> None:
+        # Twenty overlapping reads through one provider instance. A
+        # provider holding per-call state on self returns the wrong
+        # skill's content here and nowhere else.
+        bodies = await asyncio.gather(*(provider.get_body(SKILL_ID) for _ in range(20)))
+
+        assert len(set(bodies)) == 1
+
+
+class ContentLimitConformanceSuite:
+    """Assertions for providers that read bytes they did not author.
+
+    A size limit is not part of the universal contract — an in-memory
+    provider has nothing to bound, and demanding one would be asserting a
+    filesystem's constraints against a dict.  It *is* required of any
+    provider reading from disk, a network, or anything else a caller can
+    grow without asking.
+
+    Supply a ``limited_provider`` fixture whose limit is small enough
+    that the fixture's own content exceeds it::
+
+        class TestMyProviderLimits(ContentLimitConformanceSuite):
+            @pytest.fixture
+            def limited_provider(self):
+                return MyProvider(..., max_bytes=8)
+    """
+
+    @pytest.fixture
+    def limited_provider(self) -> SkillProvider:
+        """Return a provider whose size limit the contract skill exceeds."""
+        raise NotImplementedError(
+            "Override the 'limited_provider' fixture with a provider whose "
+            "size limit is smaller than the contract skill."
+        )
+
+    @pytest.mark.asyncio
+    async def test_oversized_skill_md_is_refused(self, limited_provider: SkillProvider) -> None:
+        with pytest.raises(AgentSkillsError):
+            await limited_provider.get_metadata(SKILL_ID)
+
+    @pytest.mark.parametrize("kind", RESOURCE_KINDS)
+    @pytest.mark.asyncio
+    async def test_oversized_resource_is_refused(
+        self, limited_provider: SkillProvider, kind: str
+    ) -> None:
+        name, _ = _EXPECTED_RESOURCES[kind]
+
+        with pytest.raises(AgentSkillsError):
+            await getattr(limited_provider, _RESOURCE_GETTERS[kind])(SKILL_ID, name)

agentskills_testing/fixtures.py

@@ -0,0 +1,45 @@
+"""Pytest fixtures, registered automatically as a plugin.
+
+Installing ``agentskills-testing`` makes these available in any test
+without an import or a ``conftest.py`` entry, via the ``pytest11``
+entry point.
+"""
+
+from __future__ import annotations
+
+import pytest
+import pytest_asyncio
+
+from agentskills_core import SkillRegistry
+from agentskills_testing.memory import (
+    DEFAULT_SKILL_ID,
+    InMemorySkill,
+    InMemorySkillProvider,
+    build_skill,
+)
+
+
+@pytest.fixture
+def sample_skill() -> InMemorySkill:
+    """A single valid skill with one resource of each kind."""
+    return build_skill(
+        DEFAULT_SKILL_ID,
+        version="1.0.0",
+        references={"severity-levels.md": b"# Severity\n\nSEV1 is customer-visible.\n"},
+        scripts={"page-oncall.sh": b"#!/bin/sh\necho paging\n"},
+        assets={"flowchart.mermaid": b"graph TD; A-->B\n"},
+    )
+
+
+@pytest.fixture
+def skill_provider(sample_skill: InMemorySkill) -> InMemorySkillProvider:
+    """An :class:`InMemorySkillProvider` holding :func:`sample_skill`."""
+    return InMemorySkillProvider({DEFAULT_SKILL_ID: sample_skill})
+
+
+@pytest_asyncio.fixture
+async def skill_registry(skill_provider: InMemorySkillProvider) -> SkillRegistry:
+    """A registry with :func:`skill_provider`'s skill already registered."""
+    registry = SkillRegistry()
+    await registry.register(DEFAULT_SKILL_ID, skill_provider)
+    return registry

agentskills_testing/memory.py

@@ -0,0 +1,242 @@
+"""In-memory skill provider and content helpers.
+
+A test that needs a skill should not need a directory or an HTTP server,
+and it should not need an ``AsyncMock`` either: a mock agrees with
+whatever the test asserts, including the assertions that are wrong.
+:class:`InMemorySkillProvider` is a real provider that passes the same
+conformance suite the filesystem and HTTP providers do.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+import yaml
+
+from agentskills_core import (
+    RESOURCE_KINDS,
+    DiscoveryNotSupportedError,
+    ResourceListingNotSupportedError,
+    ResourceNotFoundError,
+    SkillNotFoundError,
+    SkillProvider,
+    get_logger,
+)
+
+_logger = get_logger(__name__)
+
+DEFAULT_SKILL_ID = "incident-response"
+DEFAULT_DESCRIPTION = "Diagnose and mitigate a production incident."
+DEFAULT_BODY = "# Incident Response\n\nPage the on-call engineer, then open a channel.\n"
+
+# A provider is addressed by skill ID and resource name, and both reach a
+# backend that may treat them as a path segment. Anything that could
+# escape one is refused before it gets that far.
+_UNSAFE = ("..", "/", "\\", "\x00")
+
+
+@dataclass(frozen=True)
+class InMemorySkill:
+    """One skill's content, held in memory.
+
+    Attributes:
+        metadata: Parsed frontmatter. Must carry ``name`` and
+            ``description`` to satisfy the specification.
+        body: Markdown instructions.
+        references: Reference documents by filename.
+        scripts: Scripts by filename.
+        assets: Assets by filename.
+    """
+
+    metadata: dict[str, Any]
+    body: str = DEFAULT_BODY
+    references: dict[str, bytes] = field(default_factory=dict)
+    scripts: dict[str, bytes] = field(default_factory=dict)
+    assets: dict[str, bytes] = field(default_factory=dict)
+
+    def resources(self, kind: str) -> dict[str, bytes]:
+        """Return the resource mapping for *kind*."""
+        return {"references": self.references, "scripts": self.scripts, "assets": self.assets}[kind]
+
+
+def build_skill(
+    skill_id: str = DEFAULT_SKILL_ID,
+    *,
+    description: str = DEFAULT_DESCRIPTION,
+    body: str = DEFAULT_BODY,
+    version: str | None = None,
+    metadata: Mapping[str, Any] | None = None,
+    references: Mapping[str, bytes] | None = None,
+    scripts: Mapping[str, bytes] | None = None,
+    assets: Mapping[str, bytes] | None = None,
+) -> InMemorySkill:
+    """Build a valid :class:`InMemorySkill`.
+
+    The defaults produce a skill that passes ``validate_skill()``, so a
+    test that does not care about content does not have to invent any.
+
+    Args:
+        skill_id: Becomes the ``name`` in the frontmatter.
+        description: Frontmatter description.
+        body: Markdown instructions.
+        version: Optional semver string.
+        metadata: Extra frontmatter, merged over the generated fields.
+        references: Reference documents by filename.
+        scripts: Scripts by filename.
+        assets: Assets by filename.
+
+    Returns:
+        A skill ready to hand to :class:`InMemorySkillProvider`.
+    """
+    frontmatter: dict[str, Any] = {"name": skill_id, "description": description}
+    if version is not None:
+        frontmatter["version"] = version
+    if metadata:
+        frontmatter.update(metadata)
+
+    return InMemorySkill(
+        metadata=frontmatter,
+        body=body,
+        references=dict(references or {}),
+        scripts=dict(scripts or {}),
+        assets=dict(assets or {}),
+    )
+
+
+def render_skill_md(skill: InMemorySkill) -> str:
+    """Render *skill* as the ``SKILL.md`` text a file-backed provider would hold.
+
+    Useful for populating a temporary directory when a test needs the
+    filesystem provider rather than this one.
+    """
+    frontmatter = yaml.safe_dump(skill.metadata, sort_keys=False).strip()
+    return f"---\n{frontmatter}\n---\n\n{skill.body}"
+
+
+class InMemorySkillProvider(SkillProvider):
+    """A spec-compliant :class:`~agentskills_core.SkillProvider` backed by a dict.
+
+    Args:
+        skills: Skills by ID. A plain string value is taken as the body
+            of a default skill, so the common case stays short.
+        supports_resource_listing: Set ``False`` to emulate a backend
+            that cannot enumerate, which is what the HTTP provider does
+            without a manifest.
+        supports_discovery: Set ``False`` to emulate a backend that
+            cannot list the skills it holds.
+
+    Example::
+
+        provider = InMemorySkillProvider({"incident-response": build_skill()})
+        registry = SkillRegistry()
+        await registry.register("incident-response", provider)
+    """
+
+    def __init__(
+        self,
+        skills: Mapping[str, InMemorySkill | str] | None = None,
+        *,
+        supports_resource_listing: bool = True,
+        supports_discovery: bool = True,
+    ) -> None:
+        self._skills: dict[str, InMemorySkill] = {}
+        self.supports_resource_listing = supports_resource_listing
+        self.supports_discovery = supports_discovery
+        for skill_id, skill in (skills or {}).items():
+            self.add(skill_id, skill)
+
+    def add(self, skill_id: str, skill: InMemorySkill | str | None = None) -> InMemorySkill:
+        """Add or replace a skill.
+
+        Args:
+            skill_id: ID to register the skill under.
+            skill: The skill, or a string taken as its body. Omit it for
+                a default skill named after *skill_id*.
+
+        Returns:
+            The stored skill.
+        """
+        if skill is None:
+            skill = build_skill(skill_id)
+        elif isinstance(skill, str):
+            skill = build_skill(skill_id, body=skill)
+        self._skills[skill_id] = skill
+        _logger.debug("Added in-memory skill %r", skill_id)
+        return skill
+
+    def skill_ids(self) -> list[str]:
+        """Return the registered skill IDs, sorted."""
+        return sorted(self._skills)
+
+    async def get_metadata(self, skill_id: str) -> dict[str, Any]:
+        """Return a copy of the skill's frontmatter."""
+        return dict(self._get(skill_id).metadata)
+
+    async def get_body(self, skill_id: str) -> str:
+        """Return the skill's markdown body."""
+        return self._get(skill_id).body
+
+    async def get_reference(self, skill_id: str, name: str) -> bytes:
+        """Return a reference document."""
+        return self._resource(skill_id, "references", name)
+
+    async def get_script(self, skill_id: str, name: str) -> bytes:
+        """Return a script."""
+        return self._resource(skill_id, "scripts", name)
+
+    async def get_asset(self, skill_id: str, name: str) -> bytes:
+        """Return an asset."""
+        return self._resource(skill_id, "assets", name)
+
+    async def list_resources(self, skill_id: str) -> dict[str, list[str]]:
+        """Return the skill's resource names, grouped by kind and sorted.
+
+        Raises:
+            ResourceListingNotSupportedError: If the provider was built
+                with ``supports_resource_listing=False``.
+            SkillNotFoundError: If the skill is unknown.
+        """
+        if not self.supports_resource_listing:
+            raise ResourceListingNotSupportedError(
+                "InMemorySkillProvider was built with resource listing disabled."
+            )
+        skill = self._get(skill_id)
+        return {kind: sorted(skill.resources(kind)) for kind in RESOURCE_KINDS}
+
+    async def discover(self) -> list[str]:
+        """Return the stored skill IDs, sorted.
+
+        Raises:
+            DiscoveryNotSupportedError: If the provider was built with
+                ``supports_discovery=False``.
+        """
+        if not self.supports_discovery:
+            raise DiscoveryNotSupportedError(
+                "InMemorySkillProvider was built with discovery disabled."
+            )
+        return self.skill_ids()
+
+    def _get(self, skill_id: str) -> InMemorySkill:
+        _reject_unsafe(skill_id, SkillNotFoundError, "skill_id")
+        try:
+            return self._skills[skill_id]
+        except KeyError:
+            raise SkillNotFoundError(f"Skill not found: {skill_id!r}") from None
+
+    def _resource(self, skill_id: str, kind: str, name: str) -> bytes:
+        skill = self._get(skill_id)
+        _reject_unsafe(name, ResourceNotFoundError, "resource name")
+        try:
+            return skill.resources(kind)[name]
+        except KeyError:
+            raise ResourceNotFoundError(
+                f"Resource {name!r} not found in {kind}/ for skill {skill_id!r}"
+            ) from None
+
+
+def _reject_unsafe(value: str, error: type[Exception], label: str) -> None:
+    """Refuse an identifier that could escape its container."""
+    if not value or any(part in value for part in _UNSAFE):
+        raise error(f"Invalid {label}: {value!r}")

agentskills_testing-0.4.0.dist-info/METADATA

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: agentskills-testing
+Version: 0.4.0
+Summary: Conformance suite and test doubles for Agent Skills providers (https://agentskills.io)
+License: MIT
+Author: Pratik Panda
+Requires-Python: >=3.12,<4.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Testing
+Requires-Dist: agentskills-core (>=0.4.0,<1.0)
+Requires-Dist: pytest (>=8.0)
+Requires-Dist: pytest-asyncio (>=0.24)
+Requires-Dist: pyyaml (>=6.0,<7.0)
+Project-URL: Homepage, https://agentskills.io
+Project-URL: Repository, https://github.com/pratikxpanda/agentskills-sdk
+Description-Content-Type: text/markdown
+
+# agentskills-testing
+
+Conformance suite and test doubles for [Agent Skills](https://agentskills.io) providers.
+
+`SkillProvider` is an abstract base class, which enforces that five methods exist
+and nothing whatsoever about what they do. The requirements that actually matter
+are the ones an ABC cannot express: that an unknown skill ID raises
+`SkillNotFoundError` rather than returning `{}`, that `../../etc/passwd` is
+refused rather than resolved, and that a provider advertising resource listing
+can actually list. This package turns those into tests you inherit.
+
+```bash
+pip install agentskills-testing
+```
+
+## Conformance suite
+
+Subclass `ProviderConformanceSuite`, supply a `provider` fixture, and pytest
+collects the entire provider contract against your implementation:
+
+```python
+import pytest
+
+from agentskills_testing import ProviderConformanceSuite
+
+from my_package import MyProvider
+
+
+class TestMyProvider(ProviderConformanceSuite):
+    @pytest.fixture
+    def provider(self):
+        return MyProvider(...)
+```
+
+### Fixture contract
+
+The `provider` fixture must expose exactly one skill:
+
+| | |
+| --- | --- |
+| id | `conformance-skill` |
+| metadata | `name == "conformance-skill"`, plus a non-empty `description` |
+| body | non-empty markdown |
+| `references/` | `notes.md` containing `b"# Notes\n\nA reference document.\n"` |
+| `scripts/` | `run.sh` containing `b"#!/bin/sh\necho conformance\n"` |
+| `assets/` | `diagram.svg` containing `b"<svg></svg>\n"` |
+
+It must not define a skill called `no-such-skill-anywhere`, or any resource
+called `no-such-resource.txt`.
+
+Every name and byte string above is exported as a constant (`SKILL_ID`,
+`REFERENCE_NAME`, `REFERENCE_BYTES`, and so on), so a fixture can be built from
+them rather than from copied literals. `CONTRACT` holds the same description as
+a string, and is what the default fixture prints when you forget to override it.
+
+### What it checks
+
+- Metadata carries `name` and a non-empty `description`, and does **not** carry
+  the body — a metadata call that includes the body has already spent the tokens
+  progressive disclosure exists to save.
+- Metadata is not shared mutable state: one caller mutating the returned dict
+  must not affect the next.
+- Repeated reads agree. A provider that streams without buffering passes the
+  first read and returns empty on the second; caching bugs look the same.
+- Each resource getter returns exact `bytes`, not `str`. A resource may be a
+  PNG, and decoding on the way out makes that unreachable.
+- Unknown skills raise `SkillNotFoundError`; unknown resources raise
+  `ResourceNotFoundError`.
+- `list_resources()` agrees with `supports_resource_listing`. Callers branch on
+  that flag, so a provider whose flag and behaviour disagree breaks them
+  whichever way it lies.
+- `discover()` agrees with `supports_discovery`, and everything it reports can
+  actually be read. `register_all()` validates the whole list, so one phantom ID
+  fails the entire registration.
+- **Traversal identifiers are refused** — parent traversal, absolute paths,
+  Windows separators, percent-encoded traversal, and embedded NUL bytes, as both
+  skill IDs and resource names. These are not opt-out.
+- Concurrent reads through a single instance return consistent content, which
+  catches per-call state stored on `self`.
+
+### Size limits
+
+`ContentLimitConformanceSuite` is separate and opt-in. A size limit is not part
+of the universal contract — an in-memory provider has no external source to
+bound, and demanding one would assert a filesystem's constraints against a dict.
+It **is** required of any provider that reads bytes it did not author: from
+disk, from a network, from anywhere a caller can grow without asking.
+
+```python
+from agentskills_testing import ContentLimitConformanceSuite
+
+
+class TestMyProviderLimits(ContentLimitConformanceSuite):
+    @pytest.fixture
+    def limited_provider(self):
+        return MyProvider(..., max_bytes=8)
+```
+
+The fixture holds the same skill, with a limit small enough that the skill
+exceeds it.
+
+## Test doubles
+
+`InMemorySkillProvider` is a real, spec-compliant provider backed by a dict — it
+passes the conformance suite above. Prefer it to an `AsyncMock`: a mock agrees
+with whatever the test asserts, including the assertions that are wrong.
+
+```python
+from agentskills_core import SkillRegistry
+from agentskills_testing import InMemorySkillProvider, build_skill
+
+provider = InMemorySkillProvider(
+    {
+        "incident-response": build_skill(
+            "incident-response",
+            description="Diagnose and mitigate a production incident.",
+            body="# Incident Response\n\nPage the on-call engineer.\n",
+            references={"severity-levels.md": b"SEV1 is customer-visible.\n"},
+        )
+    }
+)
+
+registry = SkillRegistry()
+await registry.register_all(provider)
+```
+
+A string value is taken as the body, for the common case where the content does
+not matter:
+
+```python
+provider = InMemorySkillProvider({"a": "body of a", "b": "body of b"})
+provider.add("c")  # a default skill named "c"
+```
+
+`build_skill()` produces frontmatter that passes `validate_skill()`, so a test
+that does not care about metadata does not have to invent any.
+`render_skill_md(skill)` renders one back to `SKILL.md` text, which is how you
+populate a temporary directory for the filesystem provider.
+
+To emulate a backend that cannot enumerate — a static HTTP host without a
+manifest, for instance — pass `supports_resource_listing=False`, or
+`supports_discovery=False`, or both.
+
+## Fixtures
+
+Installing the package registers a pytest plugin, so these are available with no
+import and no `conftest.py` entry:
+
+| Fixture | What you get |
+| --- | --- |
+| `sample_skill` | An `InMemorySkill` with one reference, one script, and one asset |
+| `skill_provider` | An `InMemorySkillProvider` serving `sample_skill` |
+| `skill_registry` | A `SkillRegistry` with that skill already registered |
+
+```python
+async def test_my_agent(skill_registry):
+    catalog = await skill_registry.get_skills_catalog()
+    assert "incident-response" in catalog
+```
+
+## License
+
+MIT — see [LICENSE](https://github.com/pratikxpanda/agentskills-sdk/blob/main/LICENSE).
+
+Part of the [Agent Skills SDK](https://github.com/pratikxpanda/agentskills-sdk).
+

agentskills_testing-0.4.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+agentskills_testing/__init__.py,sha256=fGjXcSFSFAU_TOrRpHXdoVs6UWmRApJx1R9Y3QvQrjw,1433
+agentskills_testing/conformance.py,sha256=gnxgFnlIlaLisdq6LUxPksaSooD1mvBEfdFLgBnRdsE,12968
+agentskills_testing/fixtures.py,sha256=xoYu1RuCC4fRv4Zsi5WCLEDpmyqUuU4Lnvw3jKHvquM,1401
+agentskills_testing/memory.py,sha256=bwZUHRjY_0r2VgGh5a9cXIAjx_jX-RLj-qvKHj_1Xgs,8800
+agentskills_testing/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agentskills_testing-0.4.0.dist-info/METADATA,sha256=CR-kTsh38fsuOI0BJ9ZQFquL3sedAANXdPQGFOxmF5g,7292
+agentskills_testing-0.4.0.dist-info/WHEEL,sha256=EGEvSphFYqXKs23-kQBeyNoJP1nrT8ZJKQoi5p5DYL8,88
+agentskills_testing-0.4.0.dist-info/entry_points.txt,sha256=kXFwN-oLaNClC3yOwIEjYIaM1fRi6KgIfFGVV8w1yx4,61
+agentskills_testing-0.4.0.dist-info/RECORD,,

agentskills_testing-0.4.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.4.0
+Root-Is-Purelib: true
+Tag: py3-none-any

agentskills_testing-0.4.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[pytest11]
+agentskills_testing=agentskills_testing.fixtures
+