c
"}]) + rec.install(client) + result = client.search_kb_articles( + "is_faq==1", limit=3, start=1, sort="date_mod desc", language="en_GB" + ) + assert result[0].id == 1 + call = rec.calls[0] + assert call["endpoint"] == "Knowledgebase/Article" + assert call["params"]["filter"] == "is_faq==1" + assert call["params"]["limit"] == 3 + assert call["params"]["start"] == 1 + assert call["params"]["sort"] == "date_mod desc" + assert call["params"]["language"] == "en_GB" + + +def test_get_kb_article_targets_per_id_endpoint(client: GlpiClient) -> None: + rec = _Recorder(get_payload={"id": 5, "name": "Reset", "content": "c
"}) + rec.install(client) + article = client.get_kb_article(5) + assert article.id == 5 + assert rec.calls[0]["endpoint"] == "Knowledgebase/Article/5" + + +def test_create_kb_article_renders_markdown_and_returns_id(client: GlpiClient) -> None: + rec = _Recorder() + rec.install(client) + new_id = client.create_kb_article( + PostKBArticle(name="How to", content="Run **passwd**") + ) + assert new_id == 88 + call = rec.calls[0] + assert call["method"] == "POST" + assert call["endpoint"] == "Knowledgebase/Article" + assert call["json"]["name"] == "How to" + assert "passwd" in call["json"]["content"] + + +def test_update_kb_article_sends_patch(client: GlpiClient) -> None: + rec = _Recorder() + rec.install(client) + client.update_kb_article(5, PatchKBArticle(is_pinned=True)) + call = rec.calls[0] + assert call["method"] == "PATCH" + assert call["endpoint"] == "Knowledgebase/Article/5" + assert call["json"] == {"is_pinned": True} + + +def test_delete_kb_article_with_force(client: GlpiClient) -> None: + rec = _Recorder() + rec.install(client) + client.delete_kb_article(5, force=True) + call = rec.calls[0] + assert call["method"] == "DELETE" + assert call["endpoint"] == "Knowledgebase/Article/5" + assert call["json"] == {"force": True} diff --git a/glpi_python_client/clients/api/knowledgebase/tests/test_category_mixin.py b/glpi_python_client/clients/api/knowledgebase/tests/test_category_mixin.py new file mode 100644 index 0000000..a20bedb --- /dev/null +++ b/glpi_python_client/clients/api/knowledgebase/tests/test_category_mixin.py @@ -0,0 +1,127 @@ +"""Recorder-based unit tests for ``KBCategoryMixin``.""" + +from __future__ import annotations + +from typing import Any + +import pytest + +from glpi_python_client import GlpiClient, PatchKBCategory, PostKBCategory +from glpi_python_client.testing.utils import FakeResponse, make_client + + +class _Recorder: + """Transport recorder returning canned FakeResponse objects.""" + + def __init__(self, *, get_payload: Any = None) -> None: + self.calls: list[dict[str, Any]] = [] + self._get_payload = get_payload if get_payload is not None else [] + + def install(self, client: GlpiClient) -> None: + def _get( + endpoint: str, + params: dict[str, Any] | None = None, + skip_entity: bool = False, + ) -> FakeResponse: + self.calls.append( + { + "method": "GET", + "endpoint": endpoint, + "params": params, + "skip_entity": skip_entity, + } + ) + return FakeResponse(status_code=200, payload=self._get_payload) + + def _post( + endpoint: str, + json_body: dict[str, Any] | None = None, + skip_entity: bool = False, + ) -> FakeResponse: + self.calls.append( + {"method": "POST", "endpoint": endpoint, "json": json_body} + ) + return FakeResponse(status_code=201, payload={"id": 55}) + + def _patch( + endpoint: str, json_body: dict[str, Any] | None = None + ) -> FakeResponse: + self.calls.append( + {"method": "PATCH", "endpoint": endpoint, "json": json_body} + ) + return FakeResponse(status_code=204, payload={}) + + def _delete( + endpoint: str, + json_body: dict[str, Any] | None = None, + skip_entity: bool = False, + ) -> FakeResponse: + self.calls.append( + {"method": "DELETE", "endpoint": endpoint, "json": json_body} + ) + return FakeResponse(status_code=204, payload={}) + + client._get_request = _get # type: ignore[method-assign] + client._post_request = _post # type: ignore[method-assign] + client._update_request = _patch # type: ignore[method-assign] + client._delete_request = _delete # type: ignore[method-assign] + + +@pytest.fixture +def client() -> GlpiClient: + return make_client() + + +def test_search_kb_categories_forwards_filter_and_language(client: GlpiClient) -> None: + rec = _Recorder(get_payload=[{"id": 1, "name": "Network"}]) + rec.install(client) + result = client.search_kb_categories( + "name==Network", limit=5, start=2, sort="name asc", language="fr_FR" + ) + assert result[0].id == 1 + call = rec.calls[0] + assert call["endpoint"] == "Knowledgebase/Category" + assert call["params"]["filter"] == "name==Network" + assert call["params"]["limit"] == 5 + assert call["params"]["start"] == 2 + assert call["params"]["sort"] == "name asc" + assert call["params"]["language"] == "fr_FR" + + +def test_get_kb_category_targets_per_id_endpoint(client: GlpiClient) -> None: + rec = _Recorder(get_payload={"id": 9, "name": "Network"}) + rec.install(client) + category = client.get_kb_category(9) + assert category.id == 9 + assert rec.calls[0]["endpoint"] == "Knowledgebase/Category/9" + + +def test_create_kb_category_returns_new_id(client: GlpiClient) -> None: + rec = _Recorder() + rec.install(client) + new_id = client.create_kb_category(PostKBCategory(name="Network")) + assert new_id == 55 + call = rec.calls[0] + assert call["method"] == "POST" + assert call["endpoint"] == "Knowledgebase/Category" + assert call["json"] == {"name": "Network"} + + +def test_update_kb_category_sends_patch(client: GlpiClient) -> None: + rec = _Recorder() + rec.install(client) + client.update_kb_category(9, PatchKBCategory(comment="moved")) + call = rec.calls[0] + assert call["method"] == "PATCH" + assert call["endpoint"] == "Knowledgebase/Category/9" + assert call["json"] == {"comment": "moved"} + + +def test_delete_kb_category_with_force(client: GlpiClient) -> None: + rec = _Recorder() + rec.install(client) + client.delete_kb_category(9, force=True) + call = rec.calls[0] + assert call["method"] == "DELETE" + assert call["endpoint"] == "Knowledgebase/Category/9" + assert call["json"] == {"force": True} diff --git a/glpi_python_client/clients/api/knowledgebase/tests/test_comment_mixin.py b/glpi_python_client/clients/api/knowledgebase/tests/test_comment_mixin.py new file mode 100644 index 0000000..50f393a --- /dev/null +++ b/glpi_python_client/clients/api/knowledgebase/tests/test_comment_mixin.py @@ -0,0 +1,119 @@ +"""Recorder-based unit tests for ``KBArticleCommentMixin``.""" + +from __future__ import annotations + +from typing import Any + +import pytest + +from glpi_python_client import ( + GlpiClient, + PatchKBArticleComment, + PostKBArticleComment, +) +from glpi_python_client.testing.utils import FakeResponse, make_client + + +class _Recorder: + def __init__(self, *, get_payload: Any = None) -> None: + self.calls: list[dict[str, Any]] = [] + self._get_payload = get_payload if get_payload is not None else [] + + def install(self, client: GlpiClient) -> None: + def _get( + endpoint: str, + params: dict[str, Any] | None = None, + skip_entity: bool = False, + ) -> FakeResponse: + self.calls.append( + { + "method": "GET", + "endpoint": endpoint, + "params": params, + "skip_entity": skip_entity, + } + ) + return FakeResponse(status_code=200, payload=self._get_payload) + + def _post( + endpoint: str, + json_body: dict[str, Any] | None = None, + skip_entity: bool = False, + ) -> FakeResponse: + self.calls.append( + {"method": "POST", "endpoint": endpoint, "json": json_body} + ) + return FakeResponse(status_code=201, payload={"id": 77}) + + def _patch( + endpoint: str, json_body: dict[str, Any] | None = None + ) -> FakeResponse: + self.calls.append( + {"method": "PATCH", "endpoint": endpoint, "json": json_body} + ) + return FakeResponse(status_code=204, payload={}) + + def _delete( + endpoint: str, + json_body: dict[str, Any] | None = None, + skip_entity: bool = False, + ) -> FakeResponse: + self.calls.append( + {"method": "DELETE", "endpoint": endpoint, "json": json_body} + ) + return FakeResponse(status_code=204, payload={}) + + client._get_request = _get # type: ignore[method-assign] + client._post_request = _post # type: ignore[method-assign] + client._update_request = _patch # type: ignore[method-assign] + client._delete_request = _delete # type: ignore[method-assign] + + +@pytest.fixture +def client() -> GlpiClient: + return make_client() + + +def test_list_kb_article_comments_targets_nested_endpoint(client: GlpiClient) -> None: + rec = _Recorder(get_payload=[{"id": 1, "comment": "hi"}]) + rec.install(client) + comments = client.list_kb_article_comments(5) + assert comments[0].id == 1 + assert rec.calls[0]["endpoint"] == "Knowledgebase/Article/5/Comment" + + +def test_get_kb_article_comment_targets_per_id_endpoint(client: GlpiClient) -> None: + rec = _Recorder(get_payload={"id": 7, "comment": "hi"}) + rec.install(client) + comment = client.get_kb_article_comment(5, 7) + assert comment.id == 7 + assert rec.calls[0]["endpoint"] == "Knowledgebase/Article/5/Comment/7" + + +def test_create_kb_article_comment_returns_id(client: GlpiClient) -> None: + rec = _Recorder() + rec.install(client) + new_id = client.create_kb_article_comment(5, PostKBArticleComment(comment="hi")) + assert new_id == 77 + call = rec.calls[0] + assert call["endpoint"] == "Knowledgebase/Article/5/Comment" + assert call["json"] == {"comment": "hi"} + + +def test_update_kb_article_comment_sends_patch(client: GlpiClient) -> None: + rec = _Recorder() + rec.install(client) + client.update_kb_article_comment(5, 7, PatchKBArticleComment(comment="edited")) + call = rec.calls[0] + assert call["method"] == "PATCH" + assert call["endpoint"] == "Knowledgebase/Article/5/Comment/7" + + +def test_delete_kb_article_comment_with_force(client: GlpiClient) -> None: + rec = _Recorder() + rec.install(client) + client.delete_kb_article_comment(5, 7, force=True) + call = rec.calls[0] + assert call["method"] == "DELETE" + assert call["endpoint"] == "Knowledgebase/Article/5/Comment/7" + assert call["json"] == {"force": True} diff --git a/glpi_python_client/clients/api/knowledgebase/tests/test_kb_failure_paths.py b/glpi_python_client/clients/api/knowledgebase/tests/test_kb_failure_paths.py new file mode 100644 index 0000000..025efbd --- /dev/null +++ b/glpi_python_client/clients/api/knowledgebase/tests/test_kb_failure_paths.py @@ -0,0 +1,96 @@ +"""Failure-status branch coverage for the Knowledge base mixins.""" + +from __future__ import annotations + +from collections.abc import Callable +from typing import Any + +import pytest + +from glpi_python_client import ( + GlpiClient, + PatchKBArticle, + PatchKBArticleComment, + PatchKBCategory, + PostKBArticle, + PostKBArticleComment, + PostKBCategory, +) +from glpi_python_client.testing.utils import FakeResponse, make_client + + +class _FailRecorder: + """Transport stub returning a fixed non-success status for every verb.""" + + def __init__(self, status: int) -> None: + self.status = status + + def install(self, client: GlpiClient) -> None: + def _resp(*args: Any, **kwargs: Any) -> FakeResponse: + return FakeResponse(status_code=self.status, payload={"err": "x"}) + + client._get_request = _resp # type: ignore[method-assign] + client._post_request = _resp # type: ignore[method-assign] + client._update_request = _resp # type: ignore[method-assign] + client._delete_request = _resp # type: ignore[method-assign] + + +@pytest.fixture +def client() -> GlpiClient: + return make_client() + + +_READ_CALLS: list[Callable[[GlpiClient], Any]] = [ + lambda c: c.get_kb_article(1), + lambda c: c.get_kb_category(1), + lambda c: c.list_kb_article_comments(1), + lambda c: c.get_kb_article_comment(1, 2), + lambda c: c.list_kb_article_revisions(1), + lambda c: c.get_kb_article_revision(1, 2), +] + +_WRITE_CALLS: list[Callable[[GlpiClient], Any]] = [ + lambda c: c.update_kb_article(1, PatchKBArticle(name="x")), + lambda c: c.update_kb_category(1, PatchKBCategory(name="x")), + lambda c: c.update_kb_article_comment(1, 2, PatchKBArticleComment(comment="x")), +] + +_DELETE_CALLS: list[Callable[[GlpiClient], Any]] = [ + lambda c: c.delete_kb_article(1, force=True), + lambda c: c.delete_kb_category(1, force=True), + lambda c: c.delete_kb_article_comment(1, 2, force=True), +] + +_CREATE_CALLS: list[Callable[[GlpiClient], Any]] = [ + lambda c: c.create_kb_article(PostKBArticle(name="x")), + lambda c: c.create_kb_category(PostKBCategory(name="x")), + lambda c: c.create_kb_article_comment(1, PostKBArticleComment(comment="x")), +] + + +@pytest.mark.parametrize("call", _READ_CALLS) +def test_read_helpers_raise_on_failure(client: GlpiClient, call: Callable) -> None: + _FailRecorder(404).install(client) + with pytest.raises(ValueError): + call(client) + + +@pytest.mark.parametrize("call", _CREATE_CALLS) +def test_create_helpers_raise_on_failure(client: GlpiClient, call: Callable) -> None: + _FailRecorder(500).install(client) + with pytest.raises(ValueError): + call(client) + + +@pytest.mark.parametrize("call", _WRITE_CALLS) +def test_update_helpers_raise_on_failure(client: GlpiClient, call: Callable) -> None: + _FailRecorder(500).install(client) + with pytest.raises(ValueError): + call(client) + + +@pytest.mark.parametrize("call", _DELETE_CALLS) +def test_delete_helpers_raise_on_failure(client: GlpiClient, call: Callable) -> None: + _FailRecorder(500).install(client) + with pytest.raises(ValueError): + call(client) diff --git a/glpi_python_client/clients/api/knowledgebase/tests/test_revision_mixin.py b/glpi_python_client/clients/api/knowledgebase/tests/test_revision_mixin.py new file mode 100644 index 0000000..2dfd4c7 --- /dev/null +++ b/glpi_python_client/clients/api/knowledgebase/tests/test_revision_mixin.py @@ -0,0 +1,64 @@ +"""Recorder-based unit tests for the read-only ``KBArticleRevisionMixin``.""" + +from __future__ import annotations + +from typing import Any + +import pytest + +from glpi_python_client import GlpiClient +from glpi_python_client.testing.utils import FakeResponse, make_client + + +class _Recorder: + def __init__(self, *, get_payload: Any = None) -> None: + self.calls: list[dict[str, Any]] = [] + self._get_payload = get_payload if get_payload is not None else [] + + def install(self, client: GlpiClient) -> None: + def _get( + endpoint: str, + params: dict[str, Any] | None = None, + skip_entity: bool = False, + ) -> FakeResponse: + self.calls.append({"method": "GET", "endpoint": endpoint, "params": params}) + return FakeResponse(status_code=200, payload=self._get_payload) + + client._get_request = _get # type: ignore[method-assign] + + +@pytest.fixture +def client() -> GlpiClient: + return make_client() + + +def test_list_kb_article_revisions_default_language(client: GlpiClient) -> None: + rec = _Recorder(get_payload=[{"id": 11, "revision": 2}]) + rec.install(client) + revisions = client.list_kb_article_revisions(5) + assert revisions[0].revision == 2 + assert rec.calls[0]["endpoint"] == "Knowledgebase/Article/5/Revision" + + +def test_list_kb_article_revisions_with_language_uses_path_segment( + client: GlpiClient, +) -> None: + rec = _Recorder(get_payload=[{"id": 11, "revision": 2}]) + rec.install(client) + client.list_kb_article_revisions(5, language="fr_FR") + assert rec.calls[0]["endpoint"] == "Knowledgebase/Article/5/fr_FR/Revision" + + +def test_get_kb_article_revision_default_language(client: GlpiClient) -> None: + rec = _Recorder(get_payload={"id": 11, "revision": 2}) + rec.install(client) + revision = client.get_kb_article_revision(5, 2) + assert revision.revision == 2 + assert rec.calls[0]["endpoint"] == "Knowledgebase/Article/5/Revision/2" + + +def test_get_kb_article_revision_with_language(client: GlpiClient) -> None: + rec = _Recorder(get_payload={"id": 11, "revision": 2}) + rec.install(client) + client.get_kb_article_revision(5, 2, language="fr_FR") + assert rec.calls[0]["endpoint"] == "Knowledgebase/Article/5/fr_FR/Revision/2" diff --git a/glpi_python_client/clients/async_client.py b/glpi_python_client/clients/async_client.py index 2ec00d6..4cc34fd 100644 --- a/glpi_python_client/clients/async_client.py +++ b/glpi_python_client/clients/async_client.py @@ -35,6 +35,10 @@ DocumentMixin, EntityMixin, FollowupMixin, + KBArticleCommentMixin, + KBArticleMixin, + KBArticleRevisionMixin, + KBCategoryMixin, LocationMixin, PluginFieldsMixin, SolutionMixin, @@ -68,6 +72,10 @@ class AsyncGlpiClient( # type: ignore[misc] UserMixin, EntityMixin, LocationMixin, + KBCategoryMixin, + KBArticleMixin, + KBArticleCommentMixin, + KBArticleRevisionMixin, PluginFieldsMixin, AsyncTicketContextMixin, AsyncStatisticsMixin, diff --git a/glpi_python_client/clients/commons/_constants.py b/glpi_python_client/clients/commons/_constants.py index b1221cf..a066759 100644 --- a/glpi_python_client/clients/commons/_constants.py +++ b/glpi_python_client/clients/commons/_constants.py @@ -33,11 +33,21 @@ SOLUTION_SUFFIX = "Timeline/Solution" TIMELINE_DOCUMENT_SUFFIX = "Timeline/Document" +# knowledgebase/ +KB_ARTICLE_ENDPOINT = "Knowledgebase/Article" +KB_CATEGORY_ENDPOINT = "Knowledgebase/Category" +KB_COMMENT_SUFFIX = "Comment" +KB_REVISION_SUFFIX = "Revision" + __all__ = [ "DOCUMENT_ENDPOINT", "ENTITY_ENDPOINT", "FOLLOWUP_SUFFIX", + "KB_ARTICLE_ENDPOINT", + "KB_CATEGORY_ENDPOINT", + "KB_COMMENT_SUFFIX", + "KB_REVISION_SUFFIX", "LOCATION_ENDPOINT", "SOLUTION_SUFFIX", "TASK_SUFFIX", diff --git a/glpi_python_client/clients/commons/tests/test_constants.py b/glpi_python_client/clients/commons/tests/test_constants.py new file mode 100644 index 0000000..9732202 --- /dev/null +++ b/glpi_python_client/clients/commons/tests/test_constants.py @@ -0,0 +1,14 @@ +"""Tests for the GLPI Knowledge base endpoint path constants.""" + +from __future__ import annotations + +from glpi_python_client.clients.commons import _constants + + +def test_knowledgebase_endpoint_constants() -> None: + """The KB endpoint constants match the 2.3.0 contract resource paths.""" + + assert _constants.KB_ARTICLE_ENDPOINT == "Knowledgebase/Article" + assert _constants.KB_CATEGORY_ENDPOINT == "Knowledgebase/Category" + assert _constants.KB_COMMENT_SUFFIX == "Comment" + assert _constants.KB_REVISION_SUFFIX == "Revision" diff --git a/glpi_python_client/clients/sync_client.py b/glpi_python_client/clients/sync_client.py index 2c89dcd..814d051 100644 --- a/glpi_python_client/clients/sync_client.py +++ b/glpi_python_client/clients/sync_client.py @@ -29,6 +29,10 @@ DocumentMixin, EntityMixin, FollowupMixin, + KBArticleCommentMixin, + KBArticleMixin, + KBArticleRevisionMixin, + KBCategoryMixin, LocationMixin, PluginFieldsMixin, SolutionMixin, @@ -58,6 +62,10 @@ class GlpiClient( UserMixin, EntityMixin, LocationMixin, + KBCategoryMixin, + KBArticleMixin, + KBArticleCommentMixin, + KBArticleRevisionMixin, PluginFieldsMixin, TicketContextMixin, StatisticsMixin, diff --git a/glpi_python_client/models/__init__.py b/glpi_python_client/models/__init__.py index 9380e07..b0af301 100644 --- a/glpi_python_client/models/__init__.py +++ b/glpi_python_client/models/__init__.py @@ -74,6 +74,21 @@ GlpiTimelinePosition, GlpiUserAuthType, ) +from glpi_python_client.models.api_schema.knowledgebase import ( + DeleteKBArticle, + DeleteKBArticleComment, + DeleteKBCategory, + GetKBArticle, + GetKBArticleComment, + GetKBArticleRevision, + GetKBCategory, + PatchKBArticle, + PatchKBArticleComment, + PatchKBCategory, + PostKBArticle, + PostKBArticleComment, + PostKBCategory, +) from glpi_python_client.models.api_schema.management import ( DeleteDocument, GetDocument, @@ -95,6 +110,9 @@ "DeleteDocument", "DeleteEntity", "DeleteFollowup", + "DeleteKBArticle", + "DeleteKBArticleComment", + "DeleteKBCategory", "DeleteLocation", "DeleteSolution", "DeleteTeamMember", @@ -105,6 +123,10 @@ "GetDocument", "GetEntity", "GetFollowup", + "GetKBArticle", + "GetKBArticleComment", + "GetKBArticleRevision", + "GetKBCategory", "GetLocation", "GetPluginFieldsContainer", "GetPluginFieldsField", @@ -131,6 +153,9 @@ "PatchDocument", "PatchEntity", "PatchFollowup", + "PatchKBArticle", + "PatchKBArticleComment", + "PatchKBCategory", "PatchLocation", "PatchSolution", "PatchTeamMember", @@ -141,6 +166,9 @@ "PostDocument", "PostEntity", "PostFollowup", + "PostKBArticle", + "PostKBArticleComment", + "PostKBCategory", "PostLocation", "PostPluginFieldsValueRow", "PostSolution", diff --git a/glpi_python_client/models/api_schema/knowledgebase/__init__.py b/glpi_python_client/models/api_schema/knowledgebase/__init__.py new file mode 100644 index 0000000..c6688df --- /dev/null +++ b/glpi_python_client/models/api_schema/knowledgebase/__init__.py @@ -0,0 +1,45 @@ +"""Knowledge base entity schemas mirroring the ``/Knowledgebase`` endpoints. + +This subpackage exposes the per-verb Pydantic models for KB articles, +article comments, article revisions, and categories. Each module follows +the ``GetOpen the console and run passwd.
Short summary
", + "illustration": "reset.png", + "is_pinned": True, + "date_creation": "2026-01-02T09:00:00+00:00", + "date_mod": "2026-01-03T09:00:00+00:00", + "date_begin": "2026-01-01T00:00:00+00:00", + "date_end": "2026-12-31T00:00:00+00:00", + "revisions": [ + { + "id": 11, + "revision": 2, + "language": "en_GB", + "date": "2026-01-03T09:00:00+00:00", + } + ], + "translations": [{"id": 21, "language": "fr_FR", "name": "Reinitialiser"}], + } + article = GetKBArticle.model_validate(payload) + assert article.id == 5 + # HTML content is normalised to Markdown on the model boundary: the + # inbound/ markup must be gone, rendered as Markdown instead.
+ assert article.content is not None
+ assert "" not in article.content
+ assert "`passwd`" in article.content
+ assert article.description is not None
+ assert "" not in article.description
+ assert "Short summary" in article.description
+ assert article.categories is not None
+ assert article.categories[0].id == 4
+ assert article.revisions is not None
+ assert article.revisions[0].revision == 2
+ assert article.translations is not None
+ assert article.translations[0].language == "fr_FR"
+
+
+def test_post_kb_article_markdown_content_renders_html() -> None:
+ """Markdown ``content`` is rendered back to HTML on serialisation."""
+
+ article = PostKBArticle(name="How to", content="Run **passwd**")
+ body = model_to_payload(article)
+ assert body["name"] == "How to"
+ assert "passwd" in body["content"]
+
+
+def test_post_kb_article_accepts_writable_user() -> None:
+ """The contract marks ``user.id`` writable, so the author can be set."""
+
+ body = model_to_payload(PostKBArticle(name="x", user=IdNameRef(id=2)))
+ assert body["user"]["id"] == 2
+
+
+def test_post_kb_article_routes_server_managed_fields_to_extra() -> None:
+ """Server-managed fields land in ``extra_payload`` rather than typed slots."""
+
+ for forbidden in ("id", "views"):
+ article = PostKBArticle.model_validate({"name": "x", forbidden: 3})
+ assert article.extra_payload == {forbidden: 3}
+
+
+def test_patch_kb_article_partial_body() -> None:
+ """``PatchKBArticle`` accepts a partial body."""
+
+ PatchKBArticle.model_validate({"is_pinned": True})
+
+
+def test_delete_kb_article_force_default() -> None:
+ """``DeleteKBArticle`` exposes ``force`` as optional."""
+
+ assert DeleteKBArticle().force is None
diff --git a/glpi_python_client/models/api_schema/knowledgebase/tests/test_category_schema.py b/glpi_python_client/models/api_schema/knowledgebase/tests/test_category_schema.py
new file mode 100644
index 0000000..75a9664
--- /dev/null
+++ b/glpi_python_client/models/api_schema/knowledgebase/tests/test_category_schema.py
@@ -0,0 +1,52 @@
+"""Tests for the Knowledge base category api_schema models."""
+
+from __future__ import annotations
+
+from glpi_python_client.models.api_schema.knowledgebase import (
+ DeleteKBCategory,
+ GetKBCategory,
+ PatchKBCategory,
+ PostKBCategory,
+)
+
+
+def test_get_kb_category_full_payload() -> None:
+ """``GetKBCategory`` accepts every contract field of ``KBCategory``."""
+
+ payload = {
+ "id": 4,
+ "name": "Network",
+ "completename": "IT > Network",
+ "comment": "networking articles",
+ "entity": {"id": 0, "name": "root"},
+ "is_recursive": True,
+ "parent": {"id": 1, "name": "IT"},
+ "level": 2,
+ "date_creation": "2026-01-02T09:00:00+00:00",
+ "date_mod": "2026-01-03T09:00:00+00:00",
+ }
+ category = GetKBCategory.model_validate(payload)
+ assert category.id == 4
+ assert category.completename == "IT > Network"
+ assert category.parent is not None
+ assert category.parent.id == 1
+
+
+def test_post_kb_category_routes_read_only_fields_to_extra() -> None:
+ """Read-only fields land in ``extra_payload`` for server-side rejection."""
+
+ for forbidden in ("id", "completename", "level"):
+ category = PostKBCategory.model_validate({"name": "Network", forbidden: "x"})
+ assert category.extra_payload == {forbidden: "x"}
+
+
+def test_patch_kb_category_partial_body() -> None:
+ """``PatchKBCategory`` accepts a partial body."""
+
+ PatchKBCategory.model_validate({"comment": "moved"})
+
+
+def test_delete_kb_category_force_default() -> None:
+ """``DeleteKBCategory`` exposes ``force`` as optional."""
+
+ assert DeleteKBCategory().force is None
diff --git a/glpi_python_client/models/api_schema/knowledgebase/tests/test_comment_schema.py b/glpi_python_client/models/api_schema/knowledgebase/tests/test_comment_schema.py
new file mode 100644
index 0000000..ee6f144
--- /dev/null
+++ b/glpi_python_client/models/api_schema/knowledgebase/tests/test_comment_schema.py
@@ -0,0 +1,61 @@
+"""Tests for the Knowledge base article comment api_schema models."""
+
+from __future__ import annotations
+
+from glpi_python_client.clients.commons._payloads import model_to_payload
+from glpi_python_client.models.api_schema._common import IdNameRef
+from glpi_python_client.models.api_schema.knowledgebase import (
+ DeleteKBArticleComment,
+ GetKBArticleComment,
+ PatchKBArticleComment,
+ PostKBArticleComment,
+)
+
+
+def test_get_kb_article_comment_full_payload() -> None:
+ """``GetKBArticleComment`` accepts every contract field."""
+
+ payload = {
+ "id": 7,
+ "kbarticle": {"id": 5, "name": "Reset a password"},
+ "user": {"id": 2, "name": "glpi"},
+ "language": "en_GB",
+ "comment": "This helped, thanks.",
+ "parent": {"id": 0},
+ "date_creation": "2026-01-02T09:00:00+00:00",
+ "date_mod": "2026-01-03T09:00:00+00:00",
+ }
+ comment = GetKBArticleComment.model_validate(payload)
+ assert comment.id == 7
+ assert comment.kbarticle is not None
+ assert comment.kbarticle.id == 5
+ assert comment.comment == "This helped, thanks."
+
+
+def test_post_kb_article_comment_routes_read_only_to_extra() -> None:
+ """The read-only ``id`` and ``parent`` land in ``extra_payload``."""
+
+ comment = PostKBArticleComment.model_validate(
+ {"comment": "hi", "id": 9, "parent": {"id": 3}}
+ )
+ assert comment.extra_payload == {"id": 9, "parent": {"id": 3}}
+
+
+def test_post_kb_article_comment_accepts_writable_user() -> None:
+ """The contract marks ``user.id`` writable, so the author can be set."""
+
+ body = model_to_payload(PostKBArticleComment(comment="hi", user=IdNameRef(id=2)))
+ assert body["user"]["id"] == 2
+ assert body["comment"] == "hi"
+
+
+def test_patch_kb_article_comment_partial_body() -> None:
+ """``PatchKBArticleComment`` accepts a partial body."""
+
+ PatchKBArticleComment.model_validate({"comment": "edited"})
+
+
+def test_delete_kb_article_comment_force_default() -> None:
+ """``DeleteKBArticleComment`` exposes ``force`` as optional."""
+
+ assert DeleteKBArticleComment().force is None
diff --git a/glpi_python_client/models/api_schema/knowledgebase/tests/test_exports.py b/glpi_python_client/models/api_schema/knowledgebase/tests/test_exports.py
new file mode 100644
index 0000000..6c3e6e7
--- /dev/null
+++ b/glpi_python_client/models/api_schema/knowledgebase/tests/test_exports.py
@@ -0,0 +1,38 @@
+"""Assert the KB models are re-exported from the package roots."""
+
+from __future__ import annotations
+
+import glpi_python_client
+import glpi_python_client.models as models
+
+_KB_MODELS = (
+ "GetKBArticle",
+ "PostKBArticle",
+ "PatchKBArticle",
+ "DeleteKBArticle",
+ "GetKBCategory",
+ "PostKBCategory",
+ "PatchKBCategory",
+ "DeleteKBCategory",
+ "GetKBArticleComment",
+ "PostKBArticleComment",
+ "PatchKBArticleComment",
+ "DeleteKBArticleComment",
+ "GetKBArticleRevision",
+)
+
+
+def test_kb_models_exported_from_top_level() -> None:
+ """Every KB model is importable from ``glpi_python_client``."""
+
+ for name in _KB_MODELS:
+ assert hasattr(glpi_python_client, name), name
+ assert name in glpi_python_client.__all__, name
+
+
+def test_kb_models_exported_from_models_package() -> None:
+ """Every KB model is importable from ``glpi_python_client.models``."""
+
+ for name in _KB_MODELS:
+ assert hasattr(models, name), name
+ assert name in models.__all__, name
diff --git a/glpi_python_client/models/api_schema/knowledgebase/tests/test_revision_schema.py b/glpi_python_client/models/api_schema/knowledgebase/tests/test_revision_schema.py
new file mode 100644
index 0000000..be66d6e
--- /dev/null
+++ b/glpi_python_client/models/api_schema/knowledgebase/tests/test_revision_schema.py
@@ -0,0 +1,28 @@
+"""Tests for the read-only Knowledge base article revision model."""
+
+from __future__ import annotations
+
+from glpi_python_client.models.api_schema.knowledgebase import GetKBArticleRevision
+
+
+def test_get_kb_article_revision_full_payload() -> None:
+ """``GetKBArticleRevision`` accepts every contract field and normalises HTML."""
+
+ payload = {
+ "id": 11,
+ "kbarticle": {"id": 5, "name": "Reset a password"},
+ "revision": 2,
+ "name": "Reset a password",
+ "content": "
Run passwd.
",
+ "language": "en_GB",
+ "user": {"id": 2, "name": "glpi"},
+ "date": "2026-01-03T09:00:00+00:00",
+ }
+ revision = GetKBArticleRevision.model_validate(payload)
+ assert revision.revision == 2
+ # HTML content is normalised to Markdown on the model boundary.
+ assert revision.content is not None
+ assert "" not in revision.content
+ assert "`passwd`" in revision.content
+ assert revision.kbarticle is not None
+ assert revision.kbarticle.id == 5
diff --git a/integration_tests/test_integration_kb.py b/integration_tests/test_integration_kb.py
new file mode 100644
index 0000000..705fbed
--- /dev/null
+++ b/integration_tests/test_integration_kb.py
@@ -0,0 +1,220 @@
+"""Integration tests for the Knowledge base endpoints.
+
+These tests target a live GLPI instance and are skipped automatically when
+the Knowledgebase API is not served (it was introduced in High-Level API
+2.2.0; instances on 2.1.0 do not expose ``/Knowledgebase/*``). The probe
+inspects the live ``/doc.json`` schema at session scope.
+
+The assertions below were grounded against a live GLPI 2.3.0 instance:
+create responses carry an ``id`` key, article ``content``/``description``
+round-trip Markdown through GLPI's HTML storage, and the comment and
+revision list endpoints return flat arrays (no timeline envelope).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from uuid import uuid4
+
+import pytest
+
+from glpi_python_client import (
+ GlpiClient,
+ PatchKBArticle,
+ PatchKBArticleComment,
+ PatchKBCategory,
+ PostKBArticle,
+ PostKBArticleComment,
+ PostKBCategory,
+)
+from integration_tests.test_integration import _LiveGlpiConfig, _load_config
+
+pytestmark = pytest.mark.integration
+
+
+@pytest.fixture(scope="session")
+def live_config() -> _LiveGlpiConfig:
+ """Reuse the shared live-GLPI configuration loader."""
+
+ return _load_config()
+
+
+@pytest.fixture
+def client(live_config: _LiveGlpiConfig) -> Iterator[GlpiClient]:
+ """Yield one configured sync client and close it on teardown."""
+
+ glpi_client = GlpiClient(
+ glpi_api_url=live_config.api_url,
+ client_id=live_config.client_id,
+ client_secret=live_config.client_secret,
+ username=live_config.username,
+ password=live_config.password,
+ glpi_entity=live_config.entity,
+ glpi_profile=live_config.profile,
+ entity_recursive=live_config.entity_recursive,
+ verify_ssl=live_config.verify_ssl,
+ )
+ try:
+ yield glpi_client
+ finally:
+ glpi_client.close()
+
+
+@pytest.fixture
+def kb_available(client: GlpiClient) -> None:
+ """Skip the test when the live instance does not serve the KB API."""
+
+ response = client._get_request("doc.json", skip_entity=True)
+ paths = response.json().get("paths", {})
+ if not any(str(path).startswith("/Knowledgebase") for path in paths):
+ version = response.json().get("info", {}).get("version", "unknown")
+ pytest.skip(
+ "Knowledgebase API not served by this instance "
+ f"(High-Level API {version}; needs >= 2.2.0)."
+ )
+
+
+def _suffix() -> str:
+ return uuid4().hex[:12]
+
+
+@pytest.mark.usefixtures("kb_available")
+def test_kb_category_full_crud(client: GlpiClient) -> None:
+ """Exercise every category helper: create, get, update, search, delete."""
+
+ suffix = _suffix()
+ name = f"itest-kbcat-{suffix}"
+ category_id = client.create_kb_category(PostKBCategory(name=name))
+ try:
+ fetched = client.get_kb_category(category_id)
+ assert fetched.id == category_id
+ assert fetched.name == name
+
+ client.update_kb_category(
+ category_id, PatchKBCategory(comment="updated by integration test")
+ )
+ assert client.get_kb_category(category_id).comment == (
+ "updated by integration test"
+ )
+
+ matches = client.search_kb_categories(f"name=={name}")
+ assert any(c.id == category_id for c in matches)
+ finally:
+ client.delete_kb_category(category_id, force=True)
+
+ # After a forced delete the record is gone, so a fetch must fail.
+ with pytest.raises(ValueError):
+ client.get_kb_category(category_id)
+
+
+@pytest.mark.usefixtures("kb_available")
+def test_kb_article_full_crud_and_markdown(client: GlpiClient) -> None:
+ """Create/get/update/search/delete an article and check Markdown round-trip."""
+
+ suffix = _suffix()
+ name = f"itest-kb-{suffix}"
+ article_id = client.create_kb_article(
+ PostKBArticle(
+ name=name,
+ content="Run **passwd** then check `logs`.",
+ description="A *short* summary.",
+ is_faq=True,
+ )
+ )
+ try:
+ fetched = client.get_kb_article(article_id)
+ assert fetched.id == article_id
+ assert fetched.is_faq is True
+ # Markdown round-trips through GLPI's HTML storage: the client
+ # receives HTML and normalises it back to the Markdown we sent.
+ assert fetched.content is not None
+ assert "**passwd**" in fetched.content
+ assert "`logs`" in fetched.content
+ assert "" not in fetched.content
+ assert fetched.description is not None
+ assert "*short*" in fetched.description
+
+ client.update_kb_article(
+ article_id,
+ PatchKBArticle(is_pinned=True, content="Updated: run **reset**."),
+ )
+ updated = client.get_kb_article(article_id)
+ assert updated.is_pinned is True
+ assert "**reset**" in (updated.content or "")
+
+ by_name = client.search_kb_articles(f"name=={name}")
+ assert any(a.id == article_id for a in by_name)
+ # The FAQ filter returns a non-empty set including our new FAQ article.
+ faq = client.search_kb_articles("is_faq==1", limit=50)
+ assert any(a.id == article_id for a in faq)
+ finally:
+ client.delete_kb_article(article_id, force=True)
+
+ with pytest.raises(ValueError):
+ client.get_kb_article(article_id)
+
+
+@pytest.mark.usefixtures("kb_available")
+def test_kb_article_comment_full_crud(client: GlpiClient) -> None:
+ """Exercise every comment helper: create, list, get, update, delete."""
+
+ suffix = _suffix()
+ article_id = client.create_kb_article(
+ PostKBArticle(name=f"itest-kb-comments-{suffix}", content="Body.")
+ )
+ try:
+ comment_id = client.create_kb_article_comment(
+ article_id, PostKBArticleComment(comment=f"first comment {suffix}")
+ )
+ listed = client.list_kb_article_comments(article_id)
+ assert any(c.id == comment_id for c in listed)
+
+ fetched = client.get_kb_article_comment(article_id, comment_id)
+ assert fetched.id == comment_id
+ assert f"first comment {suffix}" in (fetched.comment or "")
+
+ client.update_kb_article_comment(
+ article_id, comment_id, PatchKBArticleComment(comment="edited comment")
+ )
+ assert (
+ client.get_kb_article_comment(article_id, comment_id).comment
+ == "edited comment"
+ )
+
+ client.delete_kb_article_comment(article_id, comment_id, force=True)
+ remaining = client.list_kb_article_comments(article_id)
+ assert all(c.id != comment_id for c in remaining)
+ finally:
+ client.delete_kb_article(article_id, force=True)
+
+
+@pytest.mark.usefixtures("kb_available")
+def test_kb_article_revisions(client: GlpiClient) -> None:
+ """List article revisions and fetch a single revision by number."""
+
+ suffix = _suffix()
+ article_id = client.create_kb_article(
+ PostKBArticle(
+ name=f"itest-kb-rev-{suffix}",
+ content="Original **body** with `code`.",
+ )
+ )
+ try:
+ # Editing the article produces at least the initial revision.
+ client.update_kb_article(
+ article_id, PatchKBArticle(content="Revised **body**.")
+ )
+ revisions = client.list_kb_article_revisions(article_id)
+ assert len(revisions) >= 1
+
+ target = revisions[0].revision
+ assert target is not None
+ single = client.get_kb_article_revision(article_id, target)
+ assert single.revision == target
+ assert single.kbarticle is not None
+ assert single.kbarticle.id == article_id
+ # Revision content is also normalised from HTML to Markdown.
+ assert single.content is not None
+ assert "" not in single.content
+ finally:
+ client.delete_kb_article(article_id, force=True)