From cc8c254e8145f45720a29f9fd58f3e4f6542100a Mon Sep 17 00:00:00 2001
From: Florian Spreckelsen <f.spreckelsen@indiscale.com>
Date: Thu, 16 Jan 2025 13:05:55 +0100
Subject: [PATCH] DOC: Fix and extend docstrings of
linkahead.utils.register_tests
---
src/linkahead/utils/register_tests.py | 72 +++++++++++++++++----------
1 file changed, 47 insertions(+), 25 deletions(-)
diff --git a/src/linkahead/utils/register_tests.py b/src/linkahead/utils/register_tests.py
index 6909544f..66fd4553 100644
--- a/src/linkahead/utils/register_tests.py
+++ b/src/linkahead/utils/register_tests.py
@@ -18,44 +18,62 @@
#
# You should have received a copy of the GNU Affero General Public License
# along with this program. If not, see <https://www.gnu.org/licenses/>.
-
-import linkahead as db
-from linkahead import administration as admin
-
-"""
-This module implements a registration procedure for integration tests which
+"""This module implements a registration procedure for integration tests which
need a running LinkAhead instance.
-It ensures that tests do not accidentally overwrite data in real LinkAhead
-instances, as it checks whether the running LinkAhead instance is actually the
-correct one, that
-should be used for these tests.
-
-The test files have to define a global variable TEST_KEY which must be unique
-for each test using
+It ensures that tests do not accidentally overwrite data in real
+LinkAhead instances, as it checks whether the running LinkAhead
+instance is actually the correct one, that should be used for these
+tests.
-set_test_key("ABCDE")
+The test files have to define a global variable ``TEST_KEY`` which
+must be unique for each test using
+:py:meth:`~linkahead.utils.register_tests.set_test_key`.
The test procedure (invoked by pytest) checks whether a registration
information is stored in one of the server properties or otherwise
-- offers to register this test in the currently running database ONLY if this
- is empty.
+
+- offers to register this test in the currently running database ONLY if this is
+ empty.
- fails otherwise with a RuntimeError
-NOTE: you probably need to use pytest with the -s option to be able to
- register the test interactively. Otherwise, the server property has to be
- set before server start-up in the server.conf of the LinkAhead server.
+.. note::
+
+ you probably need to use pytest with the -s option to be able to
+ register the test interactively. Otherwise, the server property
+ has to be set before server start-up in the server.conf of the
+ LinkAhead server.
This module is intended to be used with pytest.
-There is a pytest fixture "clear_database" that performs the above mentioned
-checks and clears the database in case of success.
+There is a pytest fixture
+:py:meth:`~linkahead.utils.register_tests.clear_database` that
+performs the above mentioned checks and clears the database in case of
+success.
+
"""
+import linkahead as db
+from linkahead import administration as admin
+
TEST_KEY = None
-def set_test_key(KEY):
+def set_test_key(KEY: str):
+ """Set the global ``TEST_KEY`` variable to `KEY`. Afterwards, if
+ `KEY` matches the ``_CAOSDB_INTEGRATION_TEST_SUITE_KEY`` server
+ environment variable, mehtods like :py:meth:`clear_database` can
+ be used. Call this function in the beginning of your test file.
+
+ Parameters
+ ----------
+ KEY : str
+ key with which the test using this function is registered and
+ which is checked against the
+ ``_CAOSDB_INTEGRATION_TEST_SUITE_KEY`` server environment
+ variable.
+
+ """
global TEST_KEY
TEST_KEY = KEY
@@ -122,10 +140,14 @@ try:
@pytest.fixture
def clear_database():
- """Remove Records, RecordTypes, Properties, and Files ONLY IF the LinkAhead
- server the current connection points to was registered with the appropriate key.
+ """Remove Records, RecordTypes, Properties, and Files ONLY IF
+ the LinkAhead server the current connection points to was
+ registered with the appropriate key using
+ :py:meth:`set_test_key`.
+
+ PyTestInfo Records and the corresponding RecordType and
+ Property are preserved.
- PyTestInfo Records and the corresponding RecordType and Property are preserved.
"""
_assure_test_is_registered()
yield _clear_database() # called before the test function
--
GitLab