test: readme example checks

Author: ricellis

modules/examples/output/CreateDbAndDoc.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",
-  "joined": "2019-01-24T10:42:99.000Z",
-  "name": "Bob Smith"
-}
+  "id": "example",
+  "rev": "1-1b403633540686aa32d013fda9041a5d",
+  "ok": true
+}

modules/examples/output/DeleteDoc.txt

@@ -1 +1 @@
-You have deleted the document.
+You have deleted the document.

modules/examples/output/DeleteDoc2.txt

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

modules/examples/output/GetInfoFromExistingDatabase.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",
+  "name": "Bob Smith"
+}

modules/examples/output/UpdateDoc.txt

@@ -4,4 +4,4 @@ You have updated the document:
   "_rev": "2-4e2178e85cffb32d38ba4e451f6ca376",
   "address": "19 Front Street, Darlington, DL5 1TY",
   "name": "Bob Smith"
-}
+}

modules/examples/output/UpdateDoc2.txt

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

modules/examples/pom.xml

@@ -33,6 +33,11 @@
             <artifactId>slf4j-jdk14</artifactId>
             <version>${slf4j-version}</version>
         </dependency>
+        <dependency>
+            <groupId>org.testng</groupId>
+            <artifactId>testng</artifactId>
+            <scope>test</scope>
+        </dependency>
     </dependencies>
 
     <build>
@@ -45,6 +50,16 @@
                     <doclint>all,-missing</doclint>
                 </configuration>
             </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-surefire-plugin</artifactId>
+                <version>${surefire-version}</version>
+                <configuration>
+                    <environmentVariables>
+                        <IBM_CREDENTIALS_FILE>${project.parent.basedir}/cloudant_v1.env</IBM_CREDENTIALS_FILE>
+                    </environmentVariables>
+                </configuration>
+            </plugin>
         </plugins>
     </build>
     <developers>

modules/examples/src/main/java/CreateDbAndDoc.java

@@ -94,7 +94,7 @@ public static void main(String[] args) {
         // Keeping track of the revision number of the document object
         // is necessary for further UPDATE/DELETE operations:
         exampleDocument.setRev(createDocumentResponse.getRev());
-        System.out.println("You have created the document:\n" +
-            exampleDocument);
+        System.out.println("You have created the document. Response body:\n" +
+            createDocumentResponse);
     }
 }

modules/examples/src/test/java/ReadmeIntegrationTest.java

@@ -0,0 +1,96 @@
+/**
+ * © 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.
+ */
+
+import java.io.BufferedOutputStream;
+import java.io.ByteArrayOutputStream;
+import java.io.File;
+import java.io.PrintStream;
+import java.net.URI;
+import java.net.http.HttpClient;
+import java.net.http.HttpRequest;
+import java.net.http.HttpRequest.BodyPublishers;
+import java.net.http.HttpResponse;
+import java.net.http.HttpResponse.BodyHandlers;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.time.Duration;
+import org.testng.Assert;
+import org.testng.annotations.BeforeClass;
+import org.testng.annotations.Test;
+
+public class ReadmeIntegrationTest {
+
+  @BeforeClass
+  void resetWiremockScenarios() throws Exception {
+    String wiremockUrl = System.getenv("WIREMOCK_URL");
+    Assert.assertNotNull(wiremockUrl, "WIREMOCK_URL environment variable should be set.");
+    HttpClient client = HttpClient.newHttpClient();
+    HttpRequest request = HttpRequest.newBuilder()
+      .uri(URI.create(wiremockUrl + "/__admin/scenarios/reset"))
+      .timeout(Duration.ofMinutes(1))
+      .header("Content-Type", "application/json")
+      .POST(BodyPublishers.ofString("{}"))
+      .build();
+    HttpResponse<Void> response = client.send(request, BodyHandlers.discarding());
+    Assert.assertEquals(response.statusCode(), 200, "Resetting wiremock scenarios should receive status 200.");
+  }
+
+  void runTest(Runnable test, String pathToExpectedOutputFile) throws Exception {
+    String expectedOutput = new String(
+        Files.readAllBytes(new File(pathToExpectedOutputFile).toPath()), StandardCharsets.UTF_8);
+    PrintStream originalStdOut = System.out;
+    String capturedOutput = null;
+    try (ByteArrayOutputStream out = new ByteArrayOutputStream();
+        PrintStream capturedStdOut =
+            new PrintStream(new BufferedOutputStream(out), true, StandardCharsets.UTF_8)) {
+      System.setOut(capturedStdOut);
+      test.run();
+      capturedOutput = out.toString(StandardCharsets.UTF_8);
+    } finally {
+      System.setOut(originalStdOut);
+    }
+    Assert.assertEquals(capturedOutput, expectedOutput);
+  }
+
+  @Test
+  void createDbAndDocFirstTime() throws Exception {
+    runTest(() -> CreateDbAndDoc.main(new String[0]), "output/CreateDbAndDoc.txt");
+  }
+
+  @Test(dependsOnMethods = {"createDbAndDocFirstTime"})
+  void getDocumentFromOrdersDatabase() throws Exception {
+    runTest(() -> GetInfoFromExistingDatabase.main(new String[0]),
+        "output/GetInfoFromExistingDatabase.txt");
+  }
+
+  @Test(dependsOnMethods = {"getDocumentFromOrdersDatabase"})
+  void updateDocFirstTime() throws Exception {
+    runTest(() -> UpdateDoc.main(new String[0]), "output/UpdateDoc.txt");
+  }
+
+  @Test(dependsOnMethods = {"updateDocFirstTime"})
+  void updateDocSecondTime() throws Exception {
+    runTest(() -> UpdateDoc.main(new String[0]), "output/UpdateDoc2.txt");
+  }
+
+  @Test(dependsOnMethods = {"updateDocSecondTime"})
+  void deleteExistingDoc() throws Exception {
+    runTest(() -> DeleteDoc.main(new String[0]), "output/DeleteDoc.txt");
+  }
+
+  @Test(dependsOnMethods = {"deleteExistingDoc"})
+  void deleteNonExistantDoc() throws Exception {
+    runTest(() -> DeleteDoc.main(new String[0]), "output/DeleteDoc2.txt");
+  }
+
+}