test: add testsuite for README code, fix messages, align example outputs

Author: Kornel-Toth

test/examples/output/create_db_and_doc.txt

@@ -1,8 +1,7 @@
 "orders" database created.
-You have created the document:
+You have created the document. Response body:
 {
-  "_id": "example",
-  "_rev": "1-1b403633540686aa32d013fda9041a5d",
-  "name": "Bob Smith",
-  "joined": "2019-01-24T10:42:99.000Z"
+  "ok": true,
+  "id": "example",
+  "rev": "1-1b403633540686aa32d013fda9041a5d"
 }

test/examples/output/delete_doc2.txt

@@ -0,0 +1 @@
+Cannot delete document because either "orders" database or "example" document was not found.

test/examples/output/get_info_from_existing_database.txt

@@ -1,9 +1,9 @@
-Server Version: 2.1.1
+Server Version: 3.2.1
 Document count in "orders" database is 1.
 Document retrieved from database:
 {
   "_id": "example",
   "_rev": "1-1b403633540686aa32d013fda9041a5d",
   "name": "Bob Smith",
-  "joined": "2019-01-24T10:42:99.000Z"
+  "joined": "2019-01-24T10:42:59.000Z"
 }

test/examples/output/update_doc.txt

@@ -1,3 +1,4 @@
+You have updated the document:
 {
   "_id": "example",
   "_rev": "2-4e2178e85cffb32d38ba4e451f6ca376",

test/examples/output/update_doc2.txt

@@ -0,0 +1,7 @@
+You have updated the document:
+{
+  "_id": "example",
+  "_rev": "3-4f1787d7a0520f825bd36822d7be627a",
+  "name": "Bob Smith",
+  "address": "19 Front Street, Darlington, DL5 1TY"
+}

test/examples/src/create_db_and_doc.py

@@ -14,6 +14,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+import json
+
 from ibm_cloud_sdk_core import ApiException
 from ibmcloudant.cloudant_v1 import CloudantV1, Document
 
@@ -65,7 +67,5 @@
 """
 # =====================================================================
 
-# Keeping track of the revision number of the document object
-# is necessary for further UPDATE/DELETE operations:
-example_document.rev = create_document_response["rev"]
-print(f'You have created the document:\n{example_document}')
+response_body = json.dumps(create_document_response, indent=2)
+print(f'You have created the document. Response body:\n{response_body}')

test/examples/src/delete_doc.py

@@ -43,5 +43,5 @@
 except ApiException as ae:
     if ae.status_code == 404:
         print('Cannot delete document because either ' +
-              f'"{example_db_name}" database or "{example_doc_id}"' +
+              f'"{example_db_name}" database or "{example_doc_id}" ' +
               'document was not found.')

test/examples/src/test_readme.py

@@ -0,0 +1,110 @@
+# © Copyright IBM Corporation 2025. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+# Testsuite for the examples in the README file.
+
+import unittest
+import subprocess
+import sys
+import os
+import requests
+from pathlib import Path
+
+parent_dir = Path(__file__).resolve().parent.parent
+
+
+class TestReadmeExamples(unittest.TestCase):
+
+    @classmethod
+    def setUpClass(cls):
+        """Set up test environment before all tests"""
+        # Get WireMock URL from environment
+        wiremock_url = os.environ.get('WIREMOCK_URL')
+
+        # Reset WireMock scenarios
+        requests.post(f"{wiremock_url}/__admin/scenarios/reset")
+
+        # Set authentication environment variables
+        os.environ['CLOUDANT_URL'] = wiremock_url
+        os.environ['CLOUDANT_AUTH_TYPE'] = 'noauth'
+
+    def run_example_and_check_output(self, script_path, expected_output_path):
+        env = os.environ.copy()
+
+        # Ensure the subprocess uses the same site-packages
+        python_path = sys.path.copy()
+        if 'PYTHONPATH' in env:
+            python_path.append(env['PYTHONPATH'])
+        env['PYTHONPATH'] = os.pathsep.join(python_path)
+
+        result = subprocess.run(
+            [sys.executable, str(script_path)],
+            capture_output=True,
+            text=True,
+            timeout=5,
+            env=env,
+        )
+        if result.returncode != 0:
+            self.fail(f"Script failed with return code {result.returncode}\n"
+                      f"STDOUT:\n{result.stdout}\n"
+                      f"STDERR:\n{result.stderr}")
+
+        with open(expected_output_path, 'r') as f:
+            expected_output = f.read().strip()
+
+        actual_output = result.stdout.strip()
+
+        self.assertEqual(actual_output, expected_output,
+                         f"Output mismatch.\nExpected:\n{expected_output}\n\nGot:\n{actual_output}")
+
+    def test_1_create_db_and_doc_example(self):
+        """Creates db and doc for the first time"""
+        script = parent_dir / "src" / "create_db_and_doc.py"
+        output = parent_dir / "output" / "create_db_and_doc.txt"
+        self.run_example_and_check_output(script, output)
+
+    def test_2_get_info_from_existing_database_example(self):
+        """Gets document from orders database"""
+        script = parent_dir / "src" / "get_info_from_existing_database.py"
+        output = parent_dir / "output" / "get_info_from_existing_database.txt"
+        self.run_example_and_check_output(script, output)
+
+    def test_3_update_doc_example_first_time(self):
+        """Updates doc for the first time"""
+        script = parent_dir / "src" / "update_doc.py"
+        output = parent_dir / "output" / "update_doc.txt"
+        self.run_example_and_check_output(script, output)
+
+    def test_4_update_doc_example_second_time(self):
+        """Updates doc for the second time"""
+        script = parent_dir / "src" / "update_doc.py"
+        output = parent_dir / "output" / "update_doc2.txt"
+        self.run_example_and_check_output(script, output)
+
+    def test_5_delete_doc_example_existing(self):
+        """Deletes existing doc"""
+        script = parent_dir / "src" / "delete_doc.py"
+        output = parent_dir / "output" / "delete_doc.txt"
+        self.run_example_and_check_output(script, output)
+
+    def test_6_delete_doc_example_non_existing(self):
+        """Deletes non-existing doc"""
+        script = parent_dir / "src" / "delete_doc.py"
+        output = parent_dir / "output" / "delete_doc2.txt"
+        self.run_example_and_check_output(script, output)
+
+
+if __name__ == '__main__':
+    unittest.main()

test/examples/src/update_doc.py

@@ -89,6 +89,6 @@
 
 except ApiException as ae:
     if ae.status_code == 404:
-        print('Cannot delete document because either ' +
+        print('Cannot update document because either ' +
               f'"{example_db_name}" database or "{example_doc_id}" ' +
               'document was not found.')