minor doc updates and refactoring

* added 'testing' or 'using' to standardize naming * added better examples to naming in concepts * fixed some category indexing * typos here and there
SSSD · Jul 12, 2024 · e66dd6d · e66dd6d
1 parent 1cb51d3
commit e66dd6d
Show file tree

Hide file tree

Showing 10 changed files with 21 additions and 15 deletions.
diff --git a/docs/concepts.rst b/docs/concepts.rst
@@ -44,20 +44,20 @@ Core concepts
 Naming tests
 ************
 
-Name your tests as ``test_feature__case``. For example:
+Name your tests as ``test_feature__case``, or ``test_role__case``. For example:
 
 .. code-block:: python
 
     @pytest.mark.topology(KnownTopologyGroup.AnyProvider)
-    def test_id__shortname():
+    def test_identity__lookup_user_using_their_shortname():
         pass
 
     @pytest.mark.topology(KnownTopologyGroup.AnyProvider)
-    def test_id__fqn():
+    def test_identity__lookup_user_using_their_fully_qualified_name():
         pass
 
-    @pytest.mark.topology(KnownTopologyGroup.AnyProvider)
-    def test_id__name_with_space():
+    @pytest.mark.topology(KnownTopology.IPA)
+    def test_ipa_trust__lookup_user_in_ad():
         pass
 
 About using fixtures
@@ -105,6 +105,10 @@ logical to organize tests inside a class, it does not give you any benefit over
 plain function and it create just one more level of organization that must be
 correctly kept and maintained.
 
+Tests are organized by user stories, also referred to as customer scenarios.
+For example, tests related to verifying a user's *identity* will reside in
+test_identity.py. Tests related to logins, will reside in test_authentication.py.
+
 .. warning::
 
     **Avoid organizing tests into classes** *unless there is a food reason to

diff --git a/docs/guides/check-sssd-functionality.rst b/docs/guides/check-sssd-functionality.rst
@@ -40,7 +40,7 @@ Supported features
 * ``non-privileged`` - SSSD is built with support of running under non-root
 
 Checking supported functionality in other roles
-###############################################
+===============================================
 
 Even though the main purpose and default setting of the
 ``@pytest.mark.builtwith`` marker is to check built functionality of SSSD on the

diff --git a/docs/guides/index.rst b/docs/guides/index.rst
@@ -3,19 +3,19 @@ How to guides
 
 .. toctree::
 
-   using-roles
    check-sssd-functionality
-   ssh-client
-   sss_override
-   pam
+   using-roles
+   using-ssh
    testing-authentication
    testing-autofs
    testing-dbus
    testing-gpo
    testing-identity
    testing-ldap-krb5
    testing-netgroups
+   testing-sss_override
    testing-offline
    testing-passkey
+   testing-pam
    testing-ipa-trust
-   local-users
+   testing-local-users
diff --git a/docs/guides/testing-gpo.rst b/docs/guides/testing-gpo.rst
@@ -1,5 +1,5 @@
 Testing AD GPO HBAC
-====================
+###################
 
 :class:`~sssd_test_framework.roles.ad.AD.GPO`
 provides Group Policy Objects (GPO) management to configure GPO policies on AD. Allowing us

diff --git a/docs/guides/local-users.rst → docs/guides/testing-local-users.rst b/docs/guides/local-users.rst → docs/guides/testing-local-users.rst
diff --git a/docs/guides/pam.rst → docs/guides/testing-pam.rst b/docs/guides/pam.rst → docs/guides/testing-pam.rst
diff --git a/docs/guides/sss_override.rst → docs/guides/testing-sss_override.rst b/docs/guides/sss_override.rst → docs/guides/testing-sss_override.rst
diff --git a/docs/guides/ssh-client.rst → docs/guides/using-ssh.rst b/docs/guides/ssh-client.rst → docs/guides/using-ssh.rst
diff --git a/docs/marks.rst b/docs/marks.rst
@@ -5,7 +5,7 @@ Additional test metadata
 ************************
 
 The following metadata are **required** to be present in docstring of each test.
-These metadata are used to organize test in Polarion to provide evidency and
+These metadata are used to organize test in Polarion to provide evidence and
 traceability for enterprise releases.
 
 .. code-block:: python
@@ -34,6 +34,8 @@ traceability for enterprise releases.
         """
 
 * **title**: Simple test case description.
+* **description** (optional): Any information that is beneficial to understand
+  the user scenario or any uniqueness pertaining to the test.
 * **setup**: All steps required to setup the environment before assertions (e.g.
   what users are created).
 * **steps**: Individual test or assertion steps.

diff --git a/docs/writing-tests.rst b/docs/writing-tests.rst
@@ -1,5 +1,5 @@
-Writing new test
-################
+Writing new tests
+#################
 
 The tests are written using the `pytest`_ framework, `pytest-mh`_ plugin and
 SSSD specific extensions that implements related