Test Suite (#22)

* Zero - test_suite - Very initial implementation of a own test suite, to stop to depend on third party implementations due to our constraints of use the latest C++ features.

Initially, we have:
- Test Suite -> Common structure for handle related test cases
- Test Case  -> A particular user-defined code that will be the testing object
- Test Results -> Structure for hold the results of different suites and the free test cases (There's still a very initial implementation, warnings are not handled by them)
- Assertions -> Only implemented `assertEquals`. We are in a very initial state, so it's fine to test our development workflow right now

Color features: Added some different colors to the terminal output, related by action. This should be completly refactored into their own feature, but due to the incoming std::print and std::format (that won't be usable until LLVM's 17 version, I don't know how to exactly proceed, because printing coloured strings could be done with the planned custom string implementation that we have planned, or just concatenating the color ANSI codes... hard to tell now. But we can think in such a feature in different ways

* Zero - test_suite - Adding correctly the user instanciated suites to the tracker. Declaring the suite library to the rest of the zork.conf(s)

* Zero - test_suite - Top level containers that holds free tests and test suites now stores pointers to the targets, and we are able to avoid with this change the `arithmetic on a pointer to an incomplete type`, letting them on the top-level of the module. This will be useful when we split the components into their module partitions

* Zero - test_suite - Applying the `pass by value - move` idiom to the TestSuite and TestCase defined constructors

* Zero - test_suite
1. Assertions have now their own module
2. Deleted the default constructor for the test suites. A identifier must be generated always by the user

* Zero - test_suite
1. The suite results are now a member of the `Test Suite` type
2. More format and colours
3. Reorganized the Zork's configuration files

* Zero - test_suite
1. Generated a README.md for the `test-suite`
2. `assertNotEquals` standalone functions created

Author: TheRustifyer

zero/assets/tsuite_results.png

@@ -0,0 +1,135 @@
+#  *Zero's project* **Test Suite**
+
+## **Introduction**
+
+Welcome to the Zero's project custom test-suite! This test-suite is a lightweight and efficient tool designed to help developers confidently develop their C++ code. With the goal of ensuring code quality and correctness, the test-suite provides a simple yet powerful way to write and run test cases.
+
+This custom test-suite emphasizes flexibility and simplicity, allowing developers to write tests using modern C++ features
+like modules and concepts. It aims to minimize external dependencies and provide a seamless testing experience that integrates
+well with C++ projects.
+
+By using this test-suite, developers can quickly validate their code changes, identify potential issues, and maintain a robust and reliable codebase.
+Whether you are a seasoned C++ developer or just starting your coding journey, the custom test-suite can be a valuable addition to your development toolkit.
+
+### *Disclaimer*
+
+As all the code in `**Zero**`, is a cutting-edge latest C++ standard features, latest standard version
+and latest standard library features codebase. Also, the suite doesn't contains yet a lot of `assertions`
+features, since they will be developed based on our needs. But it would be fine to have a nice collection of
+them, so feel free to open a *PR* and help us!
+
+## **History**
+
+The `tsuite` module born out of the need of having a minimalistic implementation of a test-suite 
+that mainly allows ourselves to develop our source code with confidence, without depending on some
+third-party changing standard implementations while avoiding typical dependency pitfalls.
+
+We used for a long time the `Catch2` test suite, but, since the release of `Clang 16` our usage of
+`C++23` and modules made `Clang` go crazy when trying to compile `Catch 2`, so we lost our ability to
+develop this codebase based on *TDD*, and lost basically our testing workflow.
+
+Other alternatives that we've tried does not fit particularly well with our workflow. And, since we try
+to use the latest standard releases, with the latest **std** library features implemented in our used
+compilers, we've always ended losing more time trying to understand what's not ready yet in the compilers,
+or how what we should be doing to make it work. 
+
+Even tho, we doesn't mean that there's no good C++ test suites out there. In fact, there's a couple of
+good really ones, with years of experience, like `Catch2` and `GTest`. But, since we also do not use any of
+the mainstream build systems (we're using **Zork++**), those suites are highly integrated with them, but not
+ready to use out-of-the-box within our development environment, so finally, we decided that we could spend
+some time writing a whole new suite that better fits our environment's needs, that is ready to work with modules
+without any complication, and that will be growing up and scaling based on user's feedback and our own needs.
+
+## **Test Suite Structure**
+The custom test-suite consists of two modules: the `tsuite` primary interface module and `tsuite:assertions` module partition.
+The `tsuite` module handles test suite registration, test case registration, and test execution.
+On the other hand, the `tsuite:assertions` partition contains various assertion functions used within the test cases.
+
+Notice that `tsuite:assertions` is a partition module interface related with `tsuite`. You only need to
+`import tsuite` to be able to work with all the features available within the suite, as they are all
+re-exported through the primary module interface `tsuite`. 
+
+With this organized structure, developers can easily register test cases and suites, run tests, and obtain meaningful feedback on the results. The suite provides a clear separation of concerns, enabling smooth collaboration between different team members and enhancing code maintainability.
+
+##  **Standalone Tests or Test Suites**
+
+#### - **Standalone Tests**:
+Standalone tests are individual test cases that are registered directly in the test suite using the `TEST_CASE(...)` function.
+These tests can be defined as standalone functions or lambdas and are registered with a unique name that identifies the test case.
+Standalone tests are suitable for small, isolated test scenarios that don't need to be grouped together.
+
+#### - **Test Suites**:
+Test suites are groups of related test cases that are logically organized together.
+Each test suite has a unique identifier called uuid, and it contains multiple test cases.
+Test cases within a suite can be registered using the `TEST_CASE(...)` function,
+just like standalone tests, but choosing the overload that receives as its first parameter
+a reference to the test suite.
+
+## **Example of usage**
+
+Here's an example of how to use the custom test-suite to write and run test cases:
+
+```c++
+// Import the necessary modules
+import std;  // Should be ready on all the major compilers for C++23. But until this date, any
+// one of them made the std lib implementation as a module as the standard mandates, so we are working
+// with the `Zork++` out of the box solution based on Clang modulemaps.
+import tsuite;
+
+// Define test functions. Should be void functions that later w'd be registered in a suite.
+void testAddition() {
+    int result = 2 + 2;
+    assertEquals(4, result);
+}
+
+// Passing two pointers to compare if the values that they point to are equals
+void testPtrsAddition() {
+    int result = 2 + 2;
+    int expected = 4;
+    assertEquals(&expected, &result);
+}
+
+// Driver code
+int main() {
+    // Free tests cases registration examples
+    
+    // Register a new test case using a function pointer.
+    TEST_CASE("Addition Test With Pointers", testPtrsAddition);
+    
+    // Users can register a new test case using lambdas, avoiding to write standalone functions
+    TEST_CASE("Subtraction Test", []() {
+        int result = 5 - 3;
+        assertEquals(122435, result);
+    });
+    
+    // Registering test cases into test suites, to group and relate tests that makes sense to exists
+    // as a part of a whole
+    
+    // Instantiate a new test suite, giving it a unique identifier.
+    TestSuite suite {"My Suite"};
+    // Register test cases using function pointers into a test suite
+    TEST_CASE(suite, "Addition Test", testAddition);
+    // Force a warning that alerts the user that the test will be discarded, since already
+    // exists one with the same identifier in the given suite
+    TEST_CASE(suite, "Addition Test", testAddition);
+    
+    // Don't forget to call this free function, to run all the tests written!
+    RUN_TESTS();
+
+    return 0;
+}
+```
+
+With these example, you will see this result:
+![img.png](../../assets/tsuite_results.png)
+
+## Funny facts
+
+As you see in the examples, we mostly use upper snake case convention for the standalone functions
+that takes care of register tests or run all the test written. But... they are not macros!
+They are just regular standalone functions available within the `zero` namespace.
+
+One of the worst part of the `C++` test suites is that almost every one are macro-based.
+But, for having a kind of environmental integration, and as a kind of tribute as well,
+as we've maintained the name of these free functions with the same conventions used for
+most of them.

zero/ifc/test-suite/README.md

@@ -0,0 +1,57 @@
+export module tsuite:assertions;
+
+import std;
+
+export {
+    /**
+    * Compares two values. Generates a test failed if values are non-equal.
+    */
+    template<typename T>
+        requires (!std::is_pointer_v<T>)
+    void assertEquals(const T& expected, const T& actual) {
+        if (expected != actual)
+            throw std::runtime_error("Assertion failed: expected = " + std::to_string(expected) +
+                                     ", actual = " + std::to_string(actual));
+    }
+
+    /**
+    * Compares two values being T pointer types.
+    * Generates a test failed if the values after dereference
+    * the pointers are non-equal.
+    */
+    template<typename T>
+    void assertEquals(const T* expected_ptr, const T* actual_ptr) {
+        auto expected   = *expected_ptr;
+        auto actual     = *actual_ptr;
+
+        if (expected != actual)
+            throw std::runtime_error("Assertion failed: expected = " + std::to_string(expected) +
+                                     ", actual = " + std::to_string(actual));
+    }
+
+    /**
+    * Compares two values. Generates a test failed if the values are equals.
+    */
+    template<typename T>
+        requires (!std::is_pointer_v<T>)
+    void assertNotEquals(const T& expected, const T& actual) {
+        if (expected == actual)
+            throw std::runtime_error("Assertion failed: expected = " + std::to_string(expected) +
+                                     ", actual = " + std::to_string(actual));
+    }
+
+    /**
+    * Compares two values being T pointer types.
+    * Generates a test failed if the values after dereference
+    * the pointers are non-equal.
+    */
+    template<typename T>
+    void assertNotEquals(const T* expected_ptr, const T* actual_ptr) {
+        auto expected   = *expected_ptr;
+        auto actual     = *actual_ptr;
+
+        if (expected == actual)
+            throw std::runtime_error("Assertion failed: expected = " + std::to_string(expected) +
+                                     ", actual = " + std::to_string(actual));
+    }
+}

zero/ifc/test-suite/assertions.cppm

@@ -0,0 +1,137 @@
+/**
+ * The Zero's project custom test-suite
+ *
+ * This is a minimalistic implementation of a test-suite
+ * that mainly allows ourselves to develop our source code
+ * with confidence, without depending on some third-party
+ * changing standards, implementations while avoiding the
+ * typical dependency pitfalls
+*/
+
+export module tsuite;
+export import :assertions;
+
+import std;
+
+/**
+ *
+ */
+struct TestResults {
+    int passed = 0;
+    int failed = 0;
+    std::vector<std::string> warnings {};
+};
+
+// Forward declarations
+export struct TestSuite;
+export struct TestCase;
+void runTest(const TestCase* testCase, TestResults& testResults);
+void runFreeTestCases();
+
+// Top-level containers. They hold pointers to the types to avoid:
+// `arithmetic on a pointer to an incomplete type`
+std::vector<TestSuite*> testSuites;
+std::vector<TestCase*> freeTestCases;
+
+export {
+    /// Common group of related test cases
+    struct TestSuite {
+        std::string uuid;
+        std::vector<TestCase*> cases {};
+        TestResults results {};
+
+        constexpr TestSuite() = delete;
+        constexpr explicit TestSuite(std::string uuid)
+            : uuid(std::move(uuid)) {}
+
+        friend bool operator==(const TestSuite& lhs, const TestSuite& rhs) {
+            return lhs.uuid == rhs.uuid;
+        }
+    };
+
+    /// Define a struct to represent a test case
+    struct TestCase {
+        std::string name;
+        std::function<void()> fn;
+
+        TestCase(std::string name, std::function<void()> fn)
+            : name(std::move(name)), fn(std::move(fn)) {}
+    };
+
+    void TEST_CASE(const std::string& tname, const std::function<void()> tfunc) {
+        freeTestCases.push_back(new TestCase(tname, tfunc));
+    }
+
+    void TEST_CASE(TestSuite& tsuite, const std::string& tname, const std::function<void()> tfunc) {
+        auto it = std::find_if(tsuite.cases.begin(), tsuite.cases.end(), [&](const TestCase* tcase) {
+            return tcase->name == tname;
+        });
+
+        /// Check that the user didn't registered a test case with the same identifier
+        if (it == tsuite.cases.end())
+            tsuite.cases.emplace_back(new TestCase(tname, tfunc));
+        else
+            tsuite.results.warnings.emplace_back(
+                "\033[38;5;220m[Warning\033[0m in suite: \033[38;5;165m" +
+                    tsuite.uuid + "\033[0m\033[38;5;220m]\033[0m "
+                       "Already exists a test case with the name: \033[38;5;117m"
+                       + tname + "\033[0m. Skipping test case."
+            );
+        /// If this is the first time that the suite is being registered
+        auto suites_it = std::find_if(testSuites.begin(), testSuites.end(), [&](const TestSuite* suite) {
+            return suite->uuid == tsuite.uuid;
+        });
+        if (suites_it == testSuites.end())
+            testSuites.push_back(&tsuite);
+    }
+
+    // Function to run all the test cases and suites
+    void RUN_TESTS() {
+        if (!freeTestCases.empty())
+            runFreeTestCases();
+        std::cout
+            << "\nRunning test suites. Total suites found: " << testSuites.size()
+            << std::endl;
+
+        for (const auto& test_suite : testSuites) {
+            std::cout << "Running test suite: \033[38;5;165m" << test_suite->uuid << "\033[m";
+
+            for (const auto& warning : test_suite->results.warnings)
+                std::cout << "\n    " << warning << std::endl;
+            for (const auto& test_case : test_suite->cases)
+                runTest(test_case, test_suite->results);
+
+            std::cout << "\nTest suite [" << test_suite->uuid << "] summary:" << std::endl;
+            std::cout << "    \033[32mPassed:\033[0m " << test_suite->results.passed << std::endl;
+            std::cout << "    \033[31mFailed:\033[0m " << test_suite->results.failed << std::endl;
+        }
+    }
+}
+
+void runFreeTestCases() {
+    TestResults freeTestsResults;
+    std::cout << "Running free tests: " << std::endl;
+    for (const auto& testCase : freeTestCases) {
+        runTest(testCase, freeTestsResults);
+        std::cout << std::endl;
+    }
+
+    std::cout << "Free tests summary:" << std::endl;
+    std::cout << "    \033[32mPassed:\033[0m " << freeTestsResults.passed << std::endl;
+    std::cout << "    \033[31mFailed:\033[0m " << freeTestsResults.failed << std::endl;
+
+}
+
+void runTest(const TestCase* const testCase, TestResults& results) {
+    std::cout << "    Running test: \033[38;5;117m" << testCase->name << "\033[0m";
+
+    try {
+        // Call the test function
+        testCase->fn();
+        std::cout << " ... Result => \033[32mPassed!\033[0m";
+        results.passed++;
+    } catch (const std::exception& ex) {
+        std::cout << " ... Result => \033[31mFailed\033[0m: " << ex.what();
+        results.failed++;
+    }
+}