doc: tutorial page

Author: azmeuk

README.md

@@ -20,20 +20,7 @@ pip install scim2-tester
 
 ## Usage
 
-scim2-tester provides a very basic command line:
-
-```console
-python scim2_tester/checker.py https://scim.example
-```
-
-However, a more complete integration is achieved through [scim2-cli](https://scim2-cli.readthedocs.io):
-
-```console
-pip install scim2-cli
-scim https://scim.example test
-```
-
-You can check the [scim2-cli test command reference](https://scim2-cli.readthedocs.io/en/latest/reference.html#scim-url-test) for more details.
+Check the [tutorial](https://scim2-tester.readthedocs.io/en/latest/tutorial.html) and the [reference](https://scim2-client.readthedocs.io/en/latest/reference.html) for more details.
 
 scim2-tester belongs in a collection of SCIM tools developed by [Yaal Coop](https://yaal.coop),
 with [scim2-models](https://github.com/python-scim/scim2-models),

doc/conf.py

@@ -46,6 +46,7 @@
     "scim2_models": ("https://scim2-models.readthedocs.io/en/latest/", None),
     "scim2_client": ("https://scim2-client.readthedocs.io/en/latest/", None),
     "scim2_cli": ("https://scim2-cli.readthedocs.io/en/latest/", None),
+    "werkzeug": ("https://werkzeug.palletsprojects.com", None),
 }
 
 # -- Options for HTML output ----------------------------------------------

doc/index.rst

@@ -7,6 +7,7 @@ Table of contents
 .. toctree::
     :maxdepth: 2
 
+    tutorial
     reference
     contributing
     changelog

doc/tutorial.rst

@@ -0,0 +1,47 @@
+Tutorial
+--------
+
+Basic CLI
+=========
+
+scim2-tester provides a very basic command line:
+
+.. code-block:: console
+
+    python scim2_tester/checker.py https://scim.example
+
+However, we encourage you to use the more complete integration in :doc:`scim2-cli <scim2_cli:index>`:
+
+.. code-block:: console
+
+    pip install scim2-cli
+    scim https://scim.example test
+
+You can check the :ref:`scim2-cli test command reference <scim2_cli:test>` for more details.
+
+Unit test suite integration
+===========================
+
+If you build a Python SCIM sever application and need a complete test suite to check you implementation, you can integrate `scim2-tester` in your test suite with little effort.
+Thanks to scim2-client :class:`~scim2_client.engines.werkzeug.TestSCIMClient` engine, no real HTTP request is made, but the server code is directly executed.
+This allows you to catch server exceptions in the test contexts, which is very handy for development.
+
+As :class:`~scim2_client.engines.werkzeug.TestSCIMClient` relies on :doc:`Werkzeug <werkzeug:index>`, you need to check that you have installed the right dependencies to use it:
+
+.. code-block:: console
+
+   uv add --group dev scim2-models[werkzeug]
+
+.. code-block:: python
+
+    from scim2_models import User, Group
+    from scim2_client.engines.werkzeug import TestSCIMClient
+    from scim2_tester import check_server, Status
+    from myapp import create_app
+
+    def test_scim_tester():
+        app = create_app(...)
+        client = TestSCIMClient(app=app, scim_prefix="/scim/v2", resource_models=(User, Group))
+        results = check_server(client)
+        for result in results:
+            assert result.status == Status.SUCCESS