feat: Implement initial C++ library

seffradev · seffradev · commit 35d2e8cc4b47 · 2025-12-28T19:35:37.000+01:00
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -10,6 +10,7 @@ include(CTest)
 
 add_subdirectory(testcontainers-bridge)
 add_subdirectory(testcontainers-c)
+add_subdirectory(testcontainers-cpp)
 add_subdirectory(modules)
 if(NOT DEFINED SKIP_DEMOS)
     add_subdirectory(demo)
diff --git a/demo/CMakeLists.txt b/demo/CMakeLists.txt
@@ -2,3 +2,4 @@
 add_subdirectory(generic-container)
 add_subdirectory(wiremock)
 add_subdirectory(google-test)
+add_subdirectory(google-test-cpp)
diff --git a/demo/google-test-cpp/CMakeLists.txt b/demo/google-test-cpp/CMakeLists.txt
@@ -0,0 +1,32 @@
+# Google Test demo
+# This is based on https://google.github.io/googletest/quickstart-cmake.html
+cmake_minimum_required (VERSION 3.26)
+project (google-test-cpp-demo
+    VERSION 0.1.0
+    DESCRIPTION "Demonstrates usage of Testcontainers C++ in Google Test"
+    LANGUAGES CXX
+)
+
+set(TARGET_OUT ${PROJECT_NAME}.out)
+
+# GoogleTest requires at least C++14
+set(CMAKE_CXX_STANDARD 23)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+include(FetchContent)
+FetchContent_Declare(
+    googletest
+    GIT_REPOSITORY https://github.com/google/googletest.git
+    GIT_TAG v1.17.0
+)
+set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
+FetchContent_MakeAvailable(googletest)
+
+enable_testing()
+file(COPY test_data DESTINATION ${CMAKE_CURRENT_BINARY_DIR})
+
+add_executable(${TARGET_OUT} test.cpp)
+target_link_libraries(${TARGET_OUT} PRIVATE testcontainers-cpp)
+target_link_libraries(${TARGET_OUT} PRIVATE GTest::gtest_main)
+
+include(GoogleTest)
+gtest_discover_tests(${TARGET_OUT})
diff --git a/demo/google-test-cpp/README.md b/demo/google-test-cpp/README.md
@@ -0,0 +1,13 @@
+# Using Testcontainers C++ in Google Test
+
+Demonstrates usage of Testcontainers C++ in [Google
+Test](https://github.com/google/googletest). See
+[test.cpp](./test.cpp) for the code.
+
+## Run the demo
+
+```bash
+cmake -S . -B /tmp/tc-native
+cmake --build /tmp/tc-native/
+ctest --output-on-failure -R Class
+```
diff --git a/demo/google-test-cpp/test.cpp b/demo/google-test-cpp/test.cpp
@@ -0,0 +1,54 @@
+#include <gtest/gtest.h>
+
+#include <iostream>
+#include <string>
+
+#include "testcontainers.hpp"
+
+using namespace testcontainers;
+
+class WireMockTestContainerClass : public ::testing::Test {
+    const char* WIREMOCK_IMAGE                  = "wiremock/wiremock:3.0.1-1";
+    const char* WIREMOCK_ADMIN_MAPPING_ENDPOINT = "/__admin/mappings";
+
+protected:
+    void SetUp() override {
+        using namespace std::literals;
+
+        builder.expose_port(TcpPort{8080}).wait_for_http(TcpPort{8080}, WIREMOCK_ADMIN_MAPPING_ENDPOINT);
+    }
+
+    Container::Builder builder = Container::Builder{WIREMOCK_IMAGE};
+};
+
+/// This test runs a "Hello World" example.
+TEST_F(WireMockTestContainerClass, HelloWorld) {
+    auto container = builder.with_file("test_data/hello.json", "/home/wiremock/mappings/hello.json").build();
+    ASSERT_TRUE(container.has_value()) << "Failed to run the container";
+
+    auto [code, response] = container->send_http(HttpMethod::Get, TcpPort{8080}, "/hello");
+    ASSERT_EQ(code, 200) << "Expected 200 OK. Received response: " << response;
+}
+
+/// This test responds to an HTTP request with response from a
+/// prepared file.
+TEST_F(WireMockTestContainerClass, HelloWorldFromResource) {
+    auto container = builder.with_file("test_data/hello_with_resource.json", "/home/wiremock/mappings/hello2.json")
+                         .with_file("test_data/response.xml", "/home/wiremock/__files/response.xml")
+                         .build();
+    ASSERT_TRUE(container.has_value()) << "Failed to run the container";
+
+    auto [code, response] = container->send_http(HttpMethod::Get, TcpPort{8080}, "/hello-from-resource");
+    ASSERT_EQ(code, 200) << "Expected 200 OK. Received response: " << response;
+}
+
+/// This test performs a request that is guaranteed to fail and
+/// return an HTTP-500.
+TEST_F(WireMockTestContainerClass, HelloWorldFromMissingResource) {
+    auto container =
+        builder.with_file("test_data/hello_with_missing_resource.json", "/home/wiremock/mappings/hello3.json").build();
+    ASSERT_TRUE(container.has_value()) << "Failed to run the container";
+
+    auto [code, response] = container->send_http(HttpMethod::Get, TcpPort{8080}, "/hello-from-missing-resource");
+    ASSERT_EQ(code, 500) << "Expected 500 Internal Server Error. Received response: " << response;
+}
diff --git a/demo/google-test-cpp/test_data/hello.json b/demo/google-test-cpp/test_data/hello.json
@@ -0,0 +1,12 @@
+{
+    "request": {
+      "method": "GET",
+      "url": "/hello"
+    },
+  
+    "response": {
+      "status": 200,
+      "body": "Hello, world!"
+    }
+  }
+  
diff --git a/demo/google-test-cpp/test_data/hello_with_missing_resource.json b/demo/google-test-cpp/test_data/hello_with_missing_resource.json
@@ -0,0 +1,10 @@
+{
+  "request": {
+    "method": "GET",
+    "url": "/hello-from-missing-resource"
+  },
+  "response": {
+    "status": 200,
+    "bodyFileName": "response_missing.xml"
+  }
+}
diff --git a/demo/google-test-cpp/test_data/hello_with_resource.json b/demo/google-test-cpp/test_data/hello_with_resource.json
@@ -0,0 +1,10 @@
+{
+  "request": {
+    "method": "GET",
+    "url": "/hello-from-resource"
+  },
+  "response": {
+    "status": 200,
+    "bodyFileName": "response.xml"
+  }
+}
diff --git a/demo/google-test-cpp/test_data/response.xml b/demo/google-test-cpp/test_data/response.xml
@@ -0,0 +1,6 @@
+<note>
+  <to>you</to>
+  <from>WireMock</from>
+  <heading>Response</heading>
+  <body>Hello, world!</body>
+</note>
diff --git a/testcontainers-cpp/CMakeLists.txt b/testcontainers-cpp/CMakeLists.txt
@@ -0,0 +1,23 @@
+set(TARGET testcontainers-cpp)
+set(TARGET_NAME ${TARGET})
+set(TARGET_DESCRIPTION "Testcontainer library for C++")
+set(TARGET_VERSION ${PROJECT_VERSION})
+
+add_library(${TARGET} INTERFACE)
+
+set(CMAKE_CXX_STANDARD 23)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+target_sources(${TARGET}
+    PUBLIC FILE_SET HEADERS
+    BASE_DIRS .
+    FILES testcontainers.hpp
+)
+
+target_link_libraries(${TARGET} INTERFACE testcontainers-c)
+
+configure_file(cmake.pc.in ${TARGET}.pc @ONLY)
+install(TARGETS ${TARGET}
+    LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
+    PUBLIC_HEADER DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})
+install(FILES ${CMAKE_BINARY_DIR}/${TARGET}.pc DESTINATION ${CMAKE_INSTALL_DATAROOTDIR}/pkgconfig)
diff --git a/testcontainers-cpp/cmake.pc.in b/testcontainers-cpp/cmake.pc.in
diff --git a/testcontainers-cpp/testcontainers.hpp b/testcontainers-cpp/testcontainers.hpp
@@ -0,0 +1,214 @@
+#ifndef TESTCONTAINERS_HPP
+#define TESTCONTAINERS_HPP
+
+#include <chrono>
+#include <cstdint>
+#include <filesystem>
+#include <iterator>
+#include <memory>
+#include <optional>
+#include <ranges>
+#include <stdexcept>
+#include <string>
+#include <thread>
+#include <utility>
+#include <variant>
+
+namespace testcontainers {
+
+namespace {
+extern "C" {
+#include "testcontainers-c/container.h"
+}
+}
+
+struct TcpPort {
+    uint16_t underlying;
+};
+
+enum struct HttpMethod {
+    Get,
+    Post,
+    Head,
+};
+
+class Builder;
+
+class Container {
+public:
+    /// A `Container` cannot be explicitly created; use the
+    /// `Container::Builder` instead.
+    constexpr Container() = delete;
+
+    /// A `Container` cannot be copied.
+    explicit constexpr Container(const Container&) = delete;
+
+    /// A `Container` cannot be copied.
+    constexpr Container& operator=(const Container&) = delete;
+
+    explicit constexpr Container(Container&& other) noexcept : container_id(-1) { *this = std::move(other); }
+
+    constexpr Container& operator=(Container&& other) noexcept {
+        if (this == &other) {
+            return *this;
+        }
+
+        std::swap(container_id, other.container_id);
+
+        return *this;
+    }
+
+    constexpr ~Container() {
+        if (container_id != -1) {
+            tc_container_terminate(container_id);
+        }
+    }
+
+    /// Send an HTTP request, type denoted by `method`, to the
+    /// container. Perform the request on port `port` and to
+    /// endpoint `endpoint`.
+    std::pair<int, std::string> send_http(HttpMethod method, TcpPort port, const std::filesystem::path& endpoint) {
+        switch (method) {
+            case HttpMethod::Get:
+                return send_http_get(port, endpoint);
+            case HttpMethod::Post:
+                return {0, "unimplemented"};
+            case HttpMethod::Head:
+                return {0, "unimplemented"};
+        }
+
+        std::unreachable();
+    }
+
+private:
+    /// The `Configuration` structure holds all expected
+    /// configuration related to the instantiation of a `Container`
+    /// instance.
+    struct Configuration {
+        using Endpoint = std::filesystem::path;
+        using Http     = std::pair<TcpPort, Endpoint>;
+        using Timeout  = std::chrono::milliseconds;
+        using WaitFor  = std::variant<Timeout, Http>;
+
+        int     request_id     = -1;
+        WaitFor wait_for_start = std::chrono::milliseconds{1000};
+    };
+
+    /// The `Awaiter` is for different types of waiting. It may be
+    /// visited (with `std::visit`) when used on e.g. a
+    /// `Container::Configuration::WaitFor` instance.
+    struct Awaiter {
+        explicit constexpr Awaiter(int container_id) : container_id(container_id) {}
+
+        void operator()(const Configuration::Timeout& timeout) { std::this_thread::sleep_for(timeout); }
+
+        void operator()(const Configuration::Http& http) {
+            const auto& [port, endpoint] = http;
+            tc_container_with_wait_for_http(container_id, port.underlying, endpoint.c_str());
+        }
+
+    private:
+        int container_id;
+    };
+
+    /// Instantiate a container, and optionally wait for it to be
+    /// ready.
+    explicit constexpr Container(Configuration configuration) {
+        char* error = nullptr;
+
+        // Awaiting HTTP-events must occur before the container is
+        // running.
+        if (std::holds_alternative<Configuration::Http>(configuration.wait_for_start)) {
+            Awaiter{container_id}(std::get<Configuration::Http>(configuration.wait_for_start));
+        }
+
+        if (container_id = tc_container_run(configuration.request_id, error); container_id == -1) {
+            throw std::runtime_error{error};
+        }
+
+        // Awaiting a timeout must occur after a container is
+        // running.
+        if (std::holds_alternative<Configuration::Timeout>(configuration.wait_for_start)) {
+            Awaiter{container_id}(std::get<Configuration::Timeout>(configuration.wait_for_start));
+        }
+    }
+
+    /// Send an HTTP GET request to the container, on port `port`
+    /// and with endpoint `endpoint`.
+    constexpr std::pair<int, std::string> send_http_get(TcpPort port, const std::filesystem::path& endpoint) const {
+        static constexpr size_t response_size     = 0xFFFF;
+        static constexpr size_t error_size        = 0xFFFF;
+        auto                    response_body_raw = std::array<char, response_size>{0x00};
+        auto                    error_raw         = std::array<char, error_size>{0x00};
+
+        auto code = tc_container_send_http_get(container_id, port.underlying, endpoint.c_str(),
+                                               response_body_raw.data(), error_raw.data());
+
+        if (code == -1) {
+            auto error =
+                std::ranges::to<std::string>(error_raw | std::ranges::views::filter([](char c) { return c != 0x00; }));
+            return std::pair{code, error};
+        }
+
+        auto response_body = std::ranges::to<std::string>(response_body_raw |
+                                                          std::ranges::views::filter([](char c) { return c != 0x00; }));
+
+        return std::pair{code, response_body};
+    }
+
+    int container_id;
+
+public:
+    /// `Builder` is the mechanism to instantiate `Container`s. It
+    /// serves to configure the setup, and provides an interface to
+    /// simply check for errors upon container creation.
+    class Builder {
+    public:
+        constexpr Builder(const std::string& image)
+            : configuration(Container::Configuration{.request_id = tc_container_create(image.c_str())}) {}
+
+        /// Add a file from host `source` to container path
+        /// `destination`.
+        Builder with_file(std::filesystem::path source, std::filesystem::path destination) {
+            tc_container_with_file(configuration.request_id, source.c_str(), destination.c_str());
+            return *this;
+        }
+
+        /// Expose a TCP port out from the container.
+        Builder expose_port(TcpPort port) {
+            tc_container_with_exposed_tcp_port(configuration.request_id, port.underlying);
+            return *this;
+        }
+
+        /// Add a timeout duration that's waited-for during
+        /// container startup.
+        Builder wait_for(std::chrono::milliseconds duration) {
+            configuration.wait_for_start = duration;
+            return *this;
+        }
+
+        /// Add an endpoint to act as health-check, determining if
+        /// the container is ready for requests.
+        Builder wait_for_http(TcpPort port, std::filesystem::path endpoint) {
+            configuration.wait_for_start = std::pair{port, endpoint};
+            return *this;
+        }
+
+        /// Construct a `Container` instance with the configured
+        /// options.
+        std::optional<Container> build() {
+            try {
+                return std::make_optional(Container{configuration});
+            } catch (const std::runtime_error& exception) {
+                return std::nullopt;
+            }
+        }
+
+    private:
+        Configuration configuration;
+    };
+};
+
+}
+
+#endif  // !TESTCONTAINERS_HPP
