feat: Upgrading to microcks-testcontainers 0.3.0 with new features

Signed-off-by: Laurent Broudoux <[email protected]>

Author: lbroudoux

package-lock.json

@@ -31,11 +31,11 @@
     "rxjs": "^7.8.1"
   },
   "devDependencies": {
-    "@microcks/microcks-testcontainers": "0.2.6",
+    "@microcks/microcks-testcontainers": "0.3.0",
     "@nestjs/cli": "^10.4.2",
     "@nestjs/schematics": "^10.2.3",
     "@nestjs/testing": "^10.4.2",
-    "@testcontainers/kafka": "^10.7.2",
+    "@testcontainers/kafka": "^10.10.4",
     "@types/express": "^4.17.17",
     "@types/jest": "^29.5.13",
     "@types/node": "^20.14.5",

package.json

@@ -50,9 +50,16 @@ describe('PastryService', () => {
     pastry = await service.getPastry('Eclair Chocolat');
     expect(pastry.name).toBe("Eclair Chocolat");
     expect(pastry.status).toBe("unknown");
+
+    // Check that the mock API has really been invoked.
+    let mockInvoked: boolean = await container.verify("API Pastries", "0.0.1");
+    expect(mockInvoked).toBe(true);
   });
 
   it('should retrieve pastries by size', async () => {
+    // Get the number of invocations before our test.
+    let beforeMockInvocations: number = await container.getServiceInvocationsCount("API Pastries", "0.0.1");
+
     let pastries: Pastry[] = await service.getPastries('S');
     expect(pastries.length).toBe(1);
 
@@ -61,5 +68,9 @@ describe('PastryService', () => {
 
     pastries = await service.getPastries('L');
     expect(pastries.length).toBe(2);
+
+    // Check our mock API has been invoked the correct number of times.
+    let afterMockInvocations: number = await container.getServiceInvocationsCount("API Pastries", "0.0.1");
+    expect(afterMockInvocations - beforeMockInvocations).toBe(3);
   });
 });

src/pastry/pastry.service.spec.ts

@@ -17,24 +17,32 @@ You need to have a [Docker](https://docs.docker.com/get-docker/) or [Podman](htt
 $ docker version
 
 Client:
- Cloud integration: v1.0.35+desktop.10
- Version:           25.0.3
- API version:       1.44
- Go version:        go1.21.6
- Git commit:        4debf41
- Built:             Tue Feb  6 21:13:26 2024
+ Version:           27.3.1
+ API version:       1.47
+ Go version:        go1.22.7
+ Git commit:        ce12230
+ Built:             Fri Sep 20 11:38:18 2024
  OS/Arch:           darwin/arm64
  Context:           desktop-linux
 
-Server: Docker Desktop 4.27.2 (137060)
+Server: Docker Desktop 4.36.0 (175267)
  Engine:
-  Version:          25.0.3
-  API version:      1.44 (minimum version 1.24)
-  Go version:       go1.21.6
-  Git commit:       f417435e5f6216828dec57958c490c4f8bae4f98
-  Built:            Wed Feb  7 00:39:16 2024
+  Version:          27.3.1
+  API version:      1.47 (minimum version 1.24)
+  Go version:       go1.22.7
+  Git commit:       41ca978
+  Built:            Fri Sep 20 11:41:19 2024
   OS/Arch:          linux/arm64
   Experimental:     false
+ containerd:
+  Version:          1.7.21
+  GitCommit:        472731909fa34bd7bc9c087e4c27943f9835f111
+ runc:
+  Version:          1.1.13
+  GitCommit:        v1.1.13-0-g58aa920
+ docker-init:
+  Version:          0.19.0
+  GitCommit:        de40ad0
 ```
 
 ## Download the project

step-1-getting-started.md

@@ -6,7 +6,7 @@ but also relies on an existing API we have [introduced in a previous post](https
 
 ![Order Service ecosystem](./assets/order-service-ecosystem.png)
 
-The `Order Service` application has been designed around 5 main components that are directly mapped on Spring Boot components and classes:
+The `Order Service` application has been designed around 5 main components that are directly mapped on NestJS components and classes:
 * The [`OrderController`](src/order/order.controller.ts) is responsible for exposing an `Order API` to the outer world.
 * The [`OrderService`](src/order/order.service.ts) is responsible for implementing the business logic around the creation of orders.
 * The [`PastryAPIClient`](src/pastry/pastry.service.ts) is responsible for calling the `Pastry API` in *Product Domain* and get details or list of pastries.

step-2-exploring-the-app.md

@@ -95,6 +95,61 @@ sequenceDiagram
     PastryAPIClient-->>-PastryAPIClientTests: List<Pastry>
 ```
 
+### 🎁 Bonus step - Check the mock endpoints are actually used
+
+While the above test is a good start, it doesn't actually check that the mock endpoints are being used. In a more complex application, it's 
+possible that the client is not correctly configured or use some cache or other mechanism that would bypass the mock endpoints. 
+In order to check that you can actually use the `verify()` method available on the Microcks container:
+
+```ts
+it('should retrieve pastry by name', async () => {
+  let pastry: Pastry = await service.getPastry('Millefeuille');
+  expect(pastry.name).toBe("Millefeuille");
+  expect(pastry.status).toBe("available");
+
+  pastry = await service.getPastry('Eclair Cafe');
+  expect(pastry.name).toBe("Eclair Cafe");
+  expect(pastry.status).toBe("available");
+
+  pastry = await service.getPastry('Eclair Chocolat');
+  expect(pastry.name).toBe("Eclair Chocolat");
+  expect(pastry.status).toBe("unknown");
+
+  // Check that the mock API has really been invoked.
+  let mockInvoked: boolean = await container.verify("API Pastries", "0.0.1");
+  expect(mockInvoked).toBe(true);
+});
+```
+
+`verify()` takes the target API name and version as arguments and returns a boolean indicating if the mock has been invoked. 
+This is a good way to ensure that the mock endpoints are actually being used in your test.
+
+If you need finer-grained control, you can also check the number of invocations with `getServiceInvocationsCount()`. This way you can check 
+that the mock has been invoked the correct number of times:
+
+```ts
+it('should retrieve pastries by size', async () => {
+  // Get the number of invocations before our test.
+  let beforeMockInvocations: number = await container.getServiceInvocationsCount("API Pastries", "0.0.1");
+
+  let pastries: Pastry[] = await service.getPastries('S');
+  expect(pastries.length).toBe(1);
+
+  pastries = await service.getPastries('M');
+  expect(pastries.length).toBe(2);
+
+  pastries = await service.getPastries('L');
+  expect(pastries.length).toBe(2);
+
+  // Check our mock API has been invoked the correct number of times.
+  let afterMockInvocations: number = await container.getServiceInvocationsCount("API Pastries", "0.0.1");
+  expect(afterMockInvocations - beforeMockInvocations).toBe(3);
+});
+```
+
+This is a super powerful way to ensure that your application logic (caching, no caching, etc.) is correctly implemented and 
+use the mock endpoints when required 🎉
+
 ## Second Test - Verify the technical conformance of Order Service API
 
 The 2nd thing we want to validate is the conformance of the `Order API` we'll expose to consumers. In this section and the next one,
@@ -133,7 +188,7 @@ test we want to run:
 * We ask for testing our endpoint against the service interface of `Order Service API` in version `0.1.0`.
   These are the identifiers found in the `order-service-openapi.yml` file.
 * We ask Microcks to validate the `OpenAPI Schema` conformance by specifying a `runnerType`.
-* We ask Microcks to validate the localhost endpoint on the dynamic port provided by the Spring Test (we use the `host.testcontainers.internal` alias for that).
+* We ask Microcks to validate the localhost endpoint on the dynamic port provided by the `beforeAll()` function (we use the `host.testcontainers.internal` alias for that).
 
 Finally, we're retrieving a `TestResult` from Microcks containers, and we can assert stuffs on this result, checking it's a success.
 
@@ -215,5 +270,56 @@ reuses Postman collection constraints.
 You're now sure that beyond the technical conformance, the `Order Service` also behaves as expected regarding business 
 constraints. 
 
+### 🎁 Bonus step - Verify the business conformance of Order Service API in pure JS/TS
+
+Even if the Postman Collection runner is a great way to validate business conformance, you may want to do it in pure JavaScript. 
+This is possible by retrieving the messages exchanged during the test and checking their content. Let's review the 
+`should conform to OpenAPI spec and Business rules` test under `test/orders.api.e2e-spec.ts`:
+
+```ts
+it('should conform to OpenAPI spec and Business rules', async () => {
+  var testRequest: TestRequest = {
+    serviceId: "Order Service API:0.1.0",
+    runnerType: TestRunnerType.OPEN_API_SCHEMA,
+    testEndpoint: "http://host.testcontainers.internal:" + appPort,
+    timeout: 3000
+  };
+
+  var testResult = await container.testEndpoint(testRequest);
+
+  console.log(JSON.stringify(testResult, null, 2));
+
+  expect(testResult.success).toBe(true);
+  expect(testResult.testCaseResults.length).toBe(1);
+  expect(testResult.testCaseResults[0].testStepResults.length).toBe(2);
+
+  // You may also check business conformance.
+  let pairs: RequestResponsePair[] = await container.getMessagesForTestCase(testResult, "POST /orders");
+
+  for (let i=0; i<pairs.length; i++) {
+    const pair = pairs[i];
+    if (pair.response.status === "201") {
+      const requestPQS = JSON.parse(pair.request.content).productQuantities;
+      const responsePQS = JSON.parse(pair.response.content).productQuantities;
+      
+      expect(responsePQS).toBeDefined();
+      expect(responsePQS.length).toBe(requestPQS.length);
+      for (let j=0; j<requestPQS.length; j++) {
+        const requestPQ = requestPQS[j];
+        const responsePQ = responsePQS[j];
+        expect(responsePQ.productName).toBe(requestPQ.productName);
+      }
+    }
+  }
+});
+```
+
+This test is a bit more complex than the previous ones. It first asks for an OpenAPI conformance test to be launched and then retrieves 
+the messages to check business conformance, following the same logic that was implemented into the Postman Collection snippet.
+
+It uses the `getMessagesForTestCase()` method to retrieve the messages exchanged during the test and then checks the content. While this 
+is done in pure JavaScript here, you may use the tool or library of your choice like [Cucumber](https://cucumber.io/docs/installation/javascript/) 
+or others.
+
 ### 
 [Next](step-5-write-async-tests.md)

step-4-write-rest-tests.md

@@ -151,9 +151,43 @@ sequenceDiagram
 ```
 
 Because the test is a success, it means that Microcks has received an `OrderEvent` on the specified topic and has validated the message
-conformance with the AsyncAPI contract or this event-driven architecture. So you're sure that all your Spring Boot configuration, Kafka JSON serializer
+conformance with the AsyncAPI contract or this event-driven architecture. So you're sure that all your NestJS configuration, Kafka JSON serializer
 configuration and network communication are actually correct!
 
+### 🎁 Bonus step - Verify the event content
+
+So you're now sure that an event has been sent to Kafka and that it's valid regarding the AsyncAPI contract. But what about the content 
+of this event? If you want to go further and check the content of the event, you can do it by asking Microcks the events read during the 
+test execution and actually check their content. This can be done adding a few lines of code:
+
+```ts
+it ('should publish an Event when Order is created', async () => {
+  // [...] Unchanged comparing previous step.
+
+  // Get the Microcks test result.
+  var testResult = await testResultPromise;
+
+  // [...] Unchanged comparing previous step.
+
+  // Check the content of the emitted event, read from Kafka topic.
+  let events: UnidirectionalEvent[] = await ensemble.getMicrocksContainer().getEventMessagesForTestCase(testResult, "SUBSCRIBE orders-created");
+  
+  expect(events.length).toBe(1);
+
+  let message: EventMessage = events[0].eventMessage;
+  let orderEvent = JSON.parse(message.content);
+
+  expect(orderEvent.changeReason).toBe('Creation');
+  let order = orderEvent.order;
+  expect(order.customerId).toBe("123-456-789");
+  expect(order.totalPrice).toBe(8.4);
+  expect(order.productQuantities.length).toBe(2);
+});
+```
+
+Here, we're using the `getEventMessagesForTestCase()` method on the Microcks container to retrieve the messages read during the test execution. 
+Using the wrapped `EventMessage` class, we can then check the content of the message and assert that it matches the order we've created.
+
 ## Second Test - Verify our OrderEventListener is processing events
 
 In this section, we'll focus on testing the `Event Consumer` + `Order Service` components of our application:
@@ -164,7 +198,41 @@ The final thing we want to test here is that our `OrderEventListener` component
 for consuming messages, for de-serializing them into correct Java objects and for triggering the processing on the `OrderService`.
 That's a lot to do and can be quite complex! But things remain very simple with Microcks 😉
 
+Let's review the test spec `order-event.listener.e2e-spec.ts` under `test`.
 
+```ts
+it ('should consume an Event and process Service', async () => {
+  let retry = 0;
+
+  while (retry < 10) {
+    try {
+      let order = orderService.getOrder('123-456-789');
+      if (orderIsValid(order)) {
+        break;
+      }
+    } catch (e) {
+      if (e instanceof OrderNotFoundException) {
+        // Continue until we get the end of the poll loop.
+      } else {
+        // Exit here.
+        throw e;
+      }
+    }
+    await delay(500);
+    retry++
+  }
+});
+
+function orderIsValid(order: Order) : boolean {
+  if (order) {
+    expect(order.customerId).toBe('lbroudoux');
+    expect(order.status).toBe(OrderStatus.VALIDATED);
+    expect(order.productQuantities.length).toBe(2);
+    return true;
+  }
+  return false;
+}
+```
 
 To fully understand this test, remember that as soon as you're launching the test, we start Kafka and Microcks containers and that Microcks
 is immediately starting publishing mock messages on this broker. So this test actually starts with a waiting loop, just checking that the