feat: attribute inclusion/exclusions checks

azmeuk · azmeuk · commit f45673708a20 · 2026-04-02T10:19:36.000+02:00
diff --git a/doc/changelog.rst b/doc/changelog.rst
@@ -1,6 +1,13 @@
 Changelog
 =========
 
+[0.2.7] - Unreleased
+--------------------
+
+Added
+^^^^^
+- Attribute filtering compliance checkers for ``attributes`` and ``excludedAttributes`` on single resource, list, and ``.search`` endpoints (:rfc:`7644` §3.4). :issue:`20`
+
 [0.2.6] - 2026-02-19
 --------------------
 
diff --git a/scim2_tester/checkers/__init__.py b/scim2_tester/checkers/__init__.py
@@ -20,6 +20,9 @@
 from .resource_get import object_query_without_id
 from .resource_post import object_creation
 from .resource_put import object_replacement
+from .resource_query_attributes import object_list_with_attributes
+from .resource_query_attributes import object_query_with_attributes
+from .resource_query_attributes import search_with_attributes
 from .resource_types import access_invalid_resource_type
 from .resource_types import query_all_resource_types
 from .resource_types import query_resource_type_by_id
@@ -49,6 +52,9 @@
     "object_creation",
     "object_query",
     "object_query_without_id",
+    "object_query_with_attributes",
+    "object_list_with_attributes",
+    "search_with_attributes",
     "object_replacement",
     "object_deletion",
     "resource_type_tests",
diff --git a/scim2_tester/checkers/resource.py b/scim2_tester/checkers/resource.py
@@ -13,6 +13,9 @@
 from .resource_get import object_query_without_id
 from .resource_post import object_creation
 from .resource_put import object_replacement
+from .resource_query_attributes import object_list_with_attributes
+from .resource_query_attributes import object_query_with_attributes
+from .resource_query_attributes import search_with_attributes
 
 
 def resource_type_tests(
@@ -51,6 +54,9 @@ def resource_type_tests(
     results.extend(object_creation(context, model))
     results.extend(object_query(context, model))
     results.extend(object_query_without_id(context, model))
+    results.extend(object_query_with_attributes(context, model))
+    results.extend(object_list_with_attributes(context, model))
+    results.extend(search_with_attributes(context, model))
     results.extend(object_replacement(context, model))
     results.extend(object_deletion(context, model))
 
diff --git a/scim2_tester/checkers/resource_query_attributes.py b/scim2_tester/checkers/resource_query_attributes.py
@@ -0,0 +1,286 @@
+from typing import Any
+
+from scim2_models import ListResponse
+from scim2_models import Mutability
+from scim2_models import Required
+from scim2_models import Resource
+from scim2_models import Returned
+from scim2_models import SearchRequest
+
+from ..utils import CheckContext
+from ..utils import CheckResult
+from ..utils import Status
+from ..utils import check_result
+from ..utils import checker
+
+
+def _pick_attribute_names(
+    model: type[Resource[Any]],
+) -> tuple[str | None, str | None]:
+    """Pick two default-returned, non-required attribute names for testing.
+
+    Returns a tuple ``(included, excluded)`` of serialization aliases.
+    Either may be :data:`None` if the model does not have enough suitable attributes.
+    """
+    candidates: list[str] = []
+    for field_name, field_info in model.model_fields.items():
+        returnability = model.get_field_annotation(field_name, Returned)
+        mutability = model.get_field_annotation(field_name, Mutability)
+        required = model.get_field_annotation(field_name, Required)
+        if (
+            returnability == Returned.default
+            and mutability != Mutability.read_only
+            and required != Required.true
+            and field_name not in ("schemas", "meta", "id")
+        ):
+            alias = field_info.serialization_alias or field_name
+            candidates.append(alias)
+
+    included = candidates[0] if len(candidates) >= 1 else None
+    excluded = candidates[1] if len(candidates) >= 2 else None
+    return included, excluded
+
+
+def _check_attribute_filtering(
+    response_data: dict[str, Any],
+    included: str | None,
+    excluded: str | None,
+    model_name: str,
+    endpoint: str,
+) -> tuple[Status, str]:
+    """Verify that the response honours ``attributes`` or ``excludedAttributes``.
+
+    Returns a ``(status, reason)`` pair.
+    """
+    if included is not None and included not in response_data:
+        return (
+            Status.ERROR,
+            f"{endpoint}: requested attribute '{included}' missing "
+            f"from {model_name} response",
+        )
+
+    if excluded is not None and excluded in response_data:
+        return (
+            Status.ERROR,
+            f"{endpoint}: excluded attribute '{excluded}' still present "
+            f"in {model_name} response",
+        )
+
+    return Status.SUCCESS, f"{endpoint}: attribute filtering honoured for {model_name}"
+
+
+def _find_resource_in_list(
+    response: ListResponse[Resource[Any]] | Any,
+    resource_id: str,
+) -> dict[str, Any] | None:
+    """Find a resource by id in a list response and return its dumped dict."""
+    if isinstance(response, ListResponse):
+        for r in response.resources:
+            if r.id == resource_id:
+                return r.model_dump()
+    return None
+
+
+def _run_attribute_checks(
+    context: CheckContext,
+    model: type[Resource[Any]],
+    test_obj: Resource[Any],
+    included: str | None,
+    excluded: str | None,
+    query_fn: Any,
+    endpoint: str,
+) -> list[CheckResult]:
+    """Run inclusion and exclusion checks using the given query function.
+
+    :param query_fn: callable that takes a :class:`SearchRequest` and returns
+        a single :class:`Resource` or a :class:`ListResponse`.
+    :param endpoint: human-readable endpoint label for messages.
+    """
+    results: list[CheckResult] = []
+
+    for attr, is_inclusion in [(included, True), (excluded, False)]:
+        if attr is None:
+            continue
+
+        if is_inclusion:
+            search_request = SearchRequest(attributes=[attr])
+        else:
+            search_request = SearchRequest(excluded_attributes=[attr])
+
+        response = query_fn(search_request)
+
+        if isinstance(response, Resource) and not isinstance(response, ListResponse):
+            response_data = response.model_dump()
+        elif isinstance(response, ListResponse):
+            response_data = _find_resource_in_list(response, test_obj.id)
+            if response_data is None:
+                results.append(
+                    check_result(
+                        context,
+                        status=Status.ERROR,
+                        reason=f"{endpoint}: could not find {model.__name__} "
+                        f"with id {test_obj.id} in filtered results",
+                        data=response,
+                    )
+                )
+                continue
+        else:
+            results.append(
+                check_result(
+                    context,
+                    status=Status.ERROR,
+                    reason=f"{endpoint}: unexpected response type "
+                    f"{type(response).__name__}",
+                    data=response,
+                )
+            )
+            continue
+
+        inc = attr if is_inclusion else None
+        exc = attr if not is_inclusion else None
+        status, reason = _check_attribute_filtering(
+            response_data, inc, exc, model.__name__, endpoint
+        )
+        results.append(
+            check_result(context, status=status, reason=reason, data=response)
+        )
+
+    return results
+
+
+@checker("crud:read:attributes")
+def object_query_with_attributes(
+    context: CheckContext, model: type[Resource[Any]]
+) -> list[CheckResult]:
+    """Validate that GET on a single resource honours ``attributes`` and ``excludedAttributes``.
+
+    Creates a resource with all writable fields populated, then retrieves it
+    twice: once with ``attributes`` restricting the response to a single
+    attribute, and once with ``excludedAttributes`` hiding another attribute.
+
+    **Status:**
+
+    - :attr:`~scim2_tester.Status.SUCCESS`: Server correctly filters response attributes
+    - :attr:`~scim2_tester.Status.ERROR`: Server ignores attribute filtering parameters
+    - :attr:`~scim2_tester.Status.SKIPPED`: Model has no suitable attributes to test
+
+    .. pull-quote:: :rfc:`RFC 7644 Section 3.4.1 <7644#section-3.4.1>`
+
+       "Clients MAY request a partial resource representation on any
+       operation that returns a resource within the response by specifying
+       either of the mutually exclusive URL query parameters ``attributes``
+       or ``excludedAttributes``."
+    """
+    included, excluded = _pick_attribute_names(model)
+    if included is None and excluded is None:
+        return [
+            check_result(
+                context,
+                status=Status.SKIPPED,
+                reason=f"No suitable attributes to test filtering on {model.__name__}",
+            )
+        ]
+
+    test_obj = context.resource_manager.create_and_register(model, fill_all=True)
+
+    def query_fn(search_request: SearchRequest) -> Any:
+        return context.client.query(
+            model,
+            test_obj.id,
+            search_request=search_request,
+            expected_status_codes=context.conf.expected_status_codes or [200],
+        )
+
+    return _run_attribute_checks(
+        context, model, test_obj, included, excluded, query_fn, "GET /Resource/{id}"
+    )
+
+
+@checker("crud:read:attributes")
+def object_list_with_attributes(
+    context: CheckContext, model: type[Resource[Any]]
+) -> list[CheckResult]:
+    """Validate that GET on the collection endpoint honours ``attributes`` and ``excludedAttributes``.
+
+    Creates a resource with all writable fields populated, then lists the
+    collection twice: once with ``attributes`` and once with
+    ``excludedAttributes``.  Verifies that the created resource appears in
+    the list and that its serialized form respects the filtering parameters.
+
+    **Status:**
+
+    - :attr:`~scim2_tester.Status.SUCCESS`: Server correctly filters list response attributes
+    - :attr:`~scim2_tester.Status.ERROR`: Server ignores attribute filtering on list endpoint
+    - :attr:`~scim2_tester.Status.SKIPPED`: Model has no suitable attributes to test
+
+    .. pull-quote:: :rfc:`RFC 7644 Section 3.4.2 <7644#section-3.4.2>`
+
+       "Clients MAY use the ``attributes`` query parameter to request
+       particular attributes be included in a query response."
+    """
+    included, excluded = _pick_attribute_names(model)
+    if included is None and excluded is None:
+        return [
+            check_result(
+                context,
+                status=Status.SKIPPED,
+                reason=f"No suitable attributes to test filtering on {model.__name__}",
+            )
+        ]
+
+    test_obj = context.resource_manager.create_and_register(model, fill_all=True)
+
+    def query_fn(search_request: SearchRequest) -> Any:
+        return context.client.query(
+            model,
+            search_request=search_request,
+            expected_status_codes=context.conf.expected_status_codes or [200],
+        )
+
+    return _run_attribute_checks(
+        context, model, test_obj, included, excluded, query_fn, "GET /Resource"
+    )
+
+
+@checker("crud:read:attributes")
+def search_with_attributes(
+    context: CheckContext, model: type[Resource[Any]]
+) -> list[CheckResult]:
+    """Validate that POST ``/.search`` honours ``attributes`` and ``excludedAttributes``.
+
+    Creates a resource with all writable fields populated, then issues
+    ``/.search`` requests with attribute filtering.  Verifies that the
+    created resource appears in the results and respects the filtering.
+
+    **Status:**
+
+    - :attr:`~scim2_tester.Status.SUCCESS`: Server correctly filters search response attributes
+    - :attr:`~scim2_tester.Status.ERROR`: Server ignores attribute filtering on search endpoint
+    - :attr:`~scim2_tester.Status.SKIPPED`: Model has no suitable attributes to test
+
+    .. pull-quote:: :rfc:`RFC 7644 Section 3.4.3 <7644#section-3.4.3>`
+
+       "Clients MAY execute queries without passing parameters on the URL by
+       using the HTTP POST verb combined with the ``/.search`` path extension."
+    """
+    included, excluded = _pick_attribute_names(model)
+    if included is None and excluded is None:
+        return [
+            check_result(
+                context,
+                status=Status.SKIPPED,
+                reason=f"No suitable attributes to test filtering on {model.__name__}",
+            )
+        ]
+
+    test_obj = context.resource_manager.create_and_register(model, fill_all=True)
+
+    def query_fn(search_request: SearchRequest) -> Any:
+        return context.client.search(
+            search_request=search_request,
+            expected_status_codes=context.conf.expected_status_codes or [200],
+        )
+
+    return _run_attribute_checks(
+        context, model, test_obj, included, excluded, query_fn, "POST /.search"
+    )
diff --git a/tests/test_resource_query_attributes.py b/tests/test_resource_query_attributes.py
