added initial content

Author: GannaChernyshova

.labspace/01-introduction.md

@@ -1,21 +1,26 @@
-# Introduction
-
-👋 Welcome to the **Labspace starter** lab! During this lab, you will learn to do the following:
-
-- Learning Objective 1
-- Learning Objective 2
-- Learning Objective 3
-- Learning Objective 4
-
-
-## 🙋 What is a Labspace again?
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis lacinia nisi sit amet auctor accumsan. Maecenas suscipit, libero quis ullamcorper pulvinar, dolor nisl vehicula orci, vel egestas arcu nibh eget enim. 
-
-Suspendisse potenti. Pellentesque eleifend eget ante eu egestas. 
-
-Nunc sit amet dapibus erat. Aliquam diam arcu, fringilla hendrerit metus sed, pellentesque fringilla lacus. 
-
-Nulla ornare nulla risus. Curabitur ut ipsum euismod, accumsan lorem eu, pretium lorem. Fusce imperdiet fermentum hendrerit.
-
-
+# Step 1: Getting Started
+
+## Clone the following project from GitHub:
+```bash
+git clone https://github.com/testcontainers/workshop.git
+```
+
+## Build the project to download the dependencies
+Switch to the workshop folder:
+```bash
+cd workshop
+```
+and build the project with Maven:
+```bash
+./mvnw verify
+```
+
+## \(optionally\) Pull the required images before doing the workshop
+
+This might be helpful if the internet connection is somewhat slow.
+```bash
+docker pull postgres:16-alpine
+docker pull redis:7-alpine
+docker pull openjdk:8-jre-alpine
+docker pull confluentinc/cp-kafka:7.5.0
+```

.labspace/02-exploring-the-app.md

@@ -0,0 +1,32 @@
+# Step 2: Exploring the app
+
+The app is a simple microservice based on Spring Boot for rating conference talks. It provides an API to track the ratings of the talks in real time.
+
+## Storage
+
+### SQL database with the talks
+
+When a rating is submitted, we must verify that the talk for the given ID is present in our database.
+
+Our database of choice is PostgreSQL, accessed with Spring JDBC.
+
+Check :fileLink[TalksRepository]{path="workshop/src/main/java/com/example/demo/repository/TalksRepository.java"}.
+
+### Redis
+
+We store the ratings in Redis database with Spring Data Redis.
+
+Check :fileLink[RatingsRepository]{path="workshop/src/main/java/com/example/demo/repository/RatingsRepository.java"}.
+
+### Kafka
+
+We use ES/CQRS to materialize the events into the state. Kafka acts as a broker and we use Spring Kafka.
+
+Check :fileLink[RatingsListener]{path="workshop/src/main/java/com/example/demo/streams/RatingsListener.java"}.
+
+## API
+
+The API is a Spring Web REST controller :fileLink[RatingsController]{path="workshop/src/main/java/com/example/demo/api/RatingsController.java"} and exposes two endpoints:
+
+* `POST /ratings { "talkId": ?, "value": 1-5 }` to add a rating for a talk
+* `GET /ratings?talkId=?` to get the histogram of ratings of the given talk

.labspace/03-adding-some-tests.md

@@ -0,0 +1,81 @@
+# Step 3: Adding some tests
+
+The app doesn't have any tests yet. 
+But before we write our first test, let's create an abstract test class for the things which are common between the tests.
+
+## Abstract class
+
+Add `AbstractIntegrationTest` class to `src/test/java` sourceset. 
+It will be an abstract class with standard Spring Boot's testing framework annotations on it:
+```plaintext save-as=workshop/src/test/java/com/example/demo/AbstractIntegrationTest.java
+package com.example.demo;
+
+import org.springframework.boot.test.context.SpringBootTest;
+
+@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
+public class AbstractIntegrationTest {
+    
+}
+```
+
+## Our very first test
+
+Now we need to test that the context starts.  
+Add `DemoApplicationTest`, extend it from your base class `AbstractIntegrationTest` and add a dummy test:
+
+```java save-as=workshop/src/test/java/com/example/demo/DemoApplicationTest.java
+package com.example.demo;
+
+import org.junit.jupiter.api.Test;
+
+public class DemoApplicationTest extends AbstractIntegrationTest{
+    @Test
+    public void contextLoads()  {
+    }
+}
+```
+
+Run it and verify that the application starts and the test passes.
+```bash
+./mvnw clean test
+```
+Spring will detect H2 on the classpath and use it as an embedded DB.
+
+This is already a useful smoke test since it ensures, that Spring Boot is able to initialize the application context successfully.
+
+## Populate the database
+
+The context starts. 
+However, we need to populate the database with some data before we can write the tests.
+Let's add a `schema.sql` file with the following content:
+```sql save-as=workshop/src/test/resources/schema.sql
+CREATE TABLE IF NOT EXISTS talks(
+  id    VARCHAR(64)  NOT NULL,
+  title VARCHAR(255) NOT NULL,
+  PRIMARY KEY (id)
+);
+
+INSERT
+  INTO talks (id, title)
+  VALUES ('testcontainers-integration-testing', 'Modern Integration Testing with Testcontainers')
+  ON CONFLICT do nothing;
+
+INSERT
+  INTO talks (id, title)
+  VALUES ('flight-of-the-flux', 'A look at Reactor execution model')
+  ON CONFLICT do nothing;
+```
+
+Now run the test again. 
+```bash
+./mvnw clean test
+```
+Oh no, it fails!
+
+```plaintext
+...
+Caused by: org.h2.jdbc.JdbcSQLException: Syntax error in SQL statement "INSERT INTO TALKS (ID, TITLE) VALUES ('testcontainers-integration-testing', 'Modern Integration Testing with Testcontainers') ON[*] CONFLICT DO NOTHING";
+...
+```
+
+It seems that H2 does not support the PostgreSQL SQL syntax, at least not by default.

.labspace/04-your-first-testcontainers-integration.md

@@ -0,0 +1,99 @@
+# Step 4: Your first Testcontainers integration
+
+From the Testcontainers website, we learn that there is a simple way of running different supported JDBC databases with Docker:  
+[https://www.testcontainers.org/usage/database\_containers.html](https://www.testcontainers.org/usage/database_containers.html)
+
+An especially interesting part are JDBC-URL based containers:  
+[https://www.testcontainers.org/usage/database\_containers.html\#jdbc-url](https://www.testcontainers.org/usage/database_containers.html#jdbc-url)
+
+It means that starting to use Testcontainers in our project \(once we add a dependency\) is as simple as changing a few properties in Spring Boot:
+
+```java
+@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT, properties = {
+ "spring.datasource.url=jdbc:tc:postgresql:16-alpine://testcontainers/workshop"
+})
+```
+Let's apply it to the `AbstractIntegrationTest` class:
+```java save-as=workshop/src/test/java/com/example/demo/AbstractIntegrationTest.java
+package com.example.demo;
+
+import org.springframework.boot.test.context.SpringBootTest;
+
+@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT, properties = {
+        "spring.datasource.url=jdbc:tc:postgresql:16-alpine://testcontainers/workshop"
+})
+public class AbstractIntegrationTest {
+
+}
+```
+
+If we split the magical JDBC url, we see:
+
+* `jdbc:tc:` - this part says that we should use Testcontainers as JDBC provider
+* `postgresql:16-alpine://` - we use a PostgreSQL database, and we select the correct PostgreSQL image from the Docker Hub as the image
+* `testcontainers/workshop` - the host name \(can be anything\) is `testcontainers` and the database name is `workshop`. Your choice!
+
+## Running tests
+In order to run these test we'll need a Docker Engine available. To relax the system ;oad we'll use Testcontainers Cloud to spin up Testcontianers-based containers. 
+To ebale it you need to:
+1. Go to the [app.testcontainers.cloud](https://app.testcontainers.cloud/) and generate the TC_CLOUD_TOKEN.
+
+2. Set the TC_CLOUD_TOKEN as environment variable:
+::variableDefinition[tcc_token]{prompt="What is your TC_CLOUD_TOKEN value?"}
+
+```bash
+export TC_CLOUD_TOKEN=$$tcc_token$$
+```
+3. Start Testcontainers Cloud agent
+```bash
+sh -c "$(curl -fsSL https://get.testcontainers.cloud/bash)"
+```
+
+Now run the test again: 
+```bash
+./mvnw clean test
+```
+Test is green? Good!
+
+Check the logs.
+
+```text
+2025-10-27T21:36:55.945Z  INFO 77211 --- [           main] o.t.d.DockerClientProviderStrategy       : Found Docker environment with Testcontainers Host with tc.host=tcp://127.0.0.1:43387
+2025-10-27T21:36:55.946Z  INFO 77211 --- [           main] org.testcontainers.DockerClientFactory   : Docker host IP address is 127.0.0.1
+2025-10-27T21:36:56.055Z  INFO 77211 --- [           main] org.testcontainers.DockerClientFactory   : Connected to docker: 
+  Server Version: 28.3.3 (via Testcontainers Cloud Agent 1.22.0)
+  API Version: 1.51
+  Operating System: Ubuntu 22.04.5 LTS
+  Total Memory: 31556 MB
+2025-10-27T21:36:56.206Z  INFO 77211 --- [           main] tc.testcontainers/ryuk:0.8.1             : Creating container for image: testcontainers/ryuk:0.8.1
+2025-10-27T21:36:56.396Z  INFO 77211 --- [           main] tc.testcontainers/ryuk:0.8.1             : Container testcontainers/ryuk:0.8.1 is starting: 779608b4dc49f2c37420ea0a39cc90951912fb767d7d7141c1b0ae1db1717989
+2025-10-27T21:36:57.321Z  INFO 77211 --- [           main] tc.testcontainers/ryuk:0.8.1             : Container testcontainers/ryuk:0.8.1 started in PT1.114889292S
+2025-10-27T21:36:57.521Z  INFO 77211 --- [           main] o.t.utility.RyukResourceReaper           : Ryuk started - will monitor and terminate Testcontainers containers on JVM exit
+2025-10-27T21:36:57.523Z  INFO 77211 --- [           main] org.testcontainers.DockerClientFactory   : Checking the system...
+2025-10-27T21:36:57.530Z  INFO 77211 --- [           main] org.testcontainers.DockerClientFactory   : ✔︎ Docker server version should be at least 1.6.0
+2025-10-27T21:36:57.532Z  INFO 77211 --- [           main] tc.postgres:17-alpine                    : Creating container for image: postgres:17-alpine
+2025-10-27T21:36:57.679Z  INFO 77211 --- [           main] tc.postgres:17-alpine                    : Container postgres:17-alpine is starting: ed1a75d921ab911896763cde925724777aa6cea00700aec567d6b9a293b1e297
+2025-10-27T21:36:58.939Z  INFO 77211 --- [           main] tc.postgres:17-alpine                    : Container postgres:17-alpine started in PT1.406803125S
+2025-10-27T21:36:58.943Z  INFO 77211 --- [           main] tc.postgres:17-alpine                    : Container is started (JDBC URL: jdbc:postgresql://127.0.0.1:32771/workshop?loggerLevel=OFF)
+```
+
+As you can see, Testcontainers quickly discovered your environment and connected to Docker. 
+It did some pre-flight checks as well to ensure that you have a valid environment.
+
+## Hint:
+
+Changing the PostgreSQL version is as simple as replacing `16-alpine` with, for example, `17-alpine`.
+Try it, but don't forget that it will download the new image from the internet, if it's not already present on your computer.
+
+```plaintext save-as=workshop/src/test/java/com/example/demo/AbstractIntegrationTest.java
+package com.example.demo;
+
+import org.springframework.boot.test.context.SpringBootTest;
+
+@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT, properties = {
+        "spring.datasource.url=jdbc:tc:postgresql:17-alpine://testcontainers/workshop"
+})
+public class AbstractIntegrationTest {
+
+}
+```

.labspace/05-dude-r-u-200-ok.md

@@ -0,0 +1,113 @@
+# Step 5: Hello, r u 200 OK?
+
+One of the great features of Spring Boot is the Actuator and its health endpoint. 
+It gives you an overview how healthy your app is.
+
+The context starts, but what's about the health of the app?
+
+## Configure Rest Assured
+
+To check the health endpoint of our app, we will use the [RestAssured](http://rest-assured.io/) library.
+
+However, before using it, we first need to configure it. 
+Update your abstract test class with `setUpAbstractIntegrationTest` method since we will share it between all tests:
+
+```java save-as=workshop/src/test/java/com/example/demo/AbstractIntegrationTest.java
+package com.example.demo;
+
+import io.restassured.RestAssured;
+import io.restassured.builder.RequestSpecBuilder;
+import io.restassured.specification.RequestSpecification;
+import org.junit.jupiter.api.BeforeEach;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.boot.test.web.server.LocalServerPort;
+import org.springframework.http.MediaType;
+import org.testcontainers.shaded.com.google.common.net.HttpHeaders;
+
+@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT, properties = {
+        "spring.datasource.url=jdbc:tc:postgresql:16-alpine://testcontainers/workshop"
+})
+public class AbstractIntegrationTest {
+    protected RequestSpecification requestSpecification;
+
+    @LocalServerPort
+    protected int localServerPort;
+
+    @BeforeEach
+    void setUpAbstractIntegrationTest() {
+        RestAssured.enableLoggingOfRequestAndResponseIfValidationFails();
+        requestSpecification = new RequestSpecBuilder()
+                .setPort(localServerPort)
+                .addHeader(
+                        HttpHeaders.CONTENT_TYPE,
+                        MediaType.APPLICATION_JSON_VALUE
+                )
+                .build();
+    }
+}
+```
+
+Here we ask Spring Boot to inject the random port it received at the start of the app, so that we can pre-configure RestAssured's requestSpecification.
+
+## Call the endpoint
+
+Now let's check if the app is actually healthy.
+Add the `healthy` test implementationn in the `DemoApplicationTest` class:
+
+```java save-as=workshop/src/test/java/com/example/demo/DemoApplicationTest.java
+package com.example.demo;
+
+import io.restassured.filter.log.LogDetail;
+import org.junit.jupiter.api.Test;
+import static io.restassured.RestAssured.given;
+
+public class DemoApplicationTest extends AbstractIntegrationTest{
+    @Test
+    void healthy() {
+        given(requestSpecification)
+                .when()
+                .get("/actuator/health")
+                .then()
+                .statusCode(200)
+                .log().ifValidationFails(LogDetail.ALL);
+    }
+}
+```
+
+Now let's run the test again: 
+```bash
+./mvnw clean test
+```
+
+Oh ow! it fails:
+
+```text
+...
+HTTP/1.1 503 Service Unavailable
+transfer-encoding: chunked
+Content-Type: application/vnd.spring-boot.actuator.v2+json;charset=UTF-8
+
+{
+    "status": "DOWN",
+    "details": {
+        "diskSpace": { ... },
+        "redis": {
+            "status": "DOWN",
+            "details": {
+                "error": "org.springframework.data.redis.RedisConnectionFailureException: Unable to connect to Redis; nested exception is io.lettuce.core.RedisConnectionException: Unable to connect to localhost:6379"
+            }
+        },
+        "db": {
+            "status": "UP",
+            "details": {
+                "database": "PostgreSQL",
+                "hello": 1
+            }
+        }
+    }
+}
+... 
+Expected status code <200> but was <503>.
+```
+
+It seems that it couldn't find Redis and there is no autoconfigurable option for it.