further chapters on readme ... still W.I.P

README.md

@@ -6,19 +6,19 @@
 
 ## Table of Contents
 
-- [1. Maven Wrapper](#1-maven-wrapper)
-- [2. Spotless - Maven Plugin](#2-spotless---maven-plugin)
-- [3. Checkstyle](#3-checkstyle)
-- [4. Allure reports](#4-allure-reports)
-- [5. Using REST assured](#5-using-rest-assured)
-- [6. Using Playwright](#6-using-playwright)
-- [7. Code Documentation and Java Doc](#7-code-documentation-and-java-doc)
-- [8. vscode set-up](#8-vscode-set-up)
-- [9. Intellij set-up](#9-intellij-set-up)
-- [10. Derived Guiding principles - Simpl Clean Code](#10-derived-guiding-principles---simpl-clean-code)
-- [11. playing with the sandbox](#11-playing-with-the-sandbox)
-- [12. test case storage for "int" and "unit"](#12-test-case-storage-for-int-and-unit)
-- [13. Test runner - local pipeline](#13-test-runner---local-pipeline)
+[1. Maven Wrapper](#1-maven-wrapper)  
+ [2. Spotless - Maven Plugin](#2-spotless---maven-plugin)  
+ [3. Checkstyle](#3-checkstyle)  
+ [4. Allure reports](#4-allure-reports)  
+ [5. Using REST assured](#5-using-rest-assured)  
+ [6. Using Playwright](#6-using-playwright)  
+ [7. Code Documentation and Java Doc](#7-code-documentation-and-java-doc)  
+ [8. vscode set-up](#8-vscode-set-up)  
+ [9. Intellij set-up](#9-intellij-set-up)  
+ [10. Derived Guiding principles - Simpl Clean Code](#10-derived-guiding-principles---simpl-clean-code)  
+ [11. Playing with the sandbox](#11-playing-with-the-sandbox)  
+ [12. Test case storage for "int" and "unit"](#12-test-case-storage-for-int-and-unit)  
+ [13. Test runner local pipeline](#13-test-runner-local-pipeline)
 
 ## 1. Maven Wrapper
 
@@ -74,6 +74,8 @@ Spotless is a code formatting plugin for Maven that helps enforce consistent cod
 
 5. **Automation**: Spotless integrates seamlessly into the build process, ensuring that code is formatted correctly every time it is built or before it is committed.
 
+**[⬆ back to top](#table-of-contents)**
+
 ### Spotless Maven Plugin Configuration
 
 Below is an example configuration of the Spotless Maven plugin in a `pom.xml` file:
@@ -144,6 +146,8 @@ Below is an example configuration of the Spotless Maven plugin in a `pom.xml` fi
 
 3. **Integrate with CI/CD**: Spotless can be integrated into your CI/CD pipeline to ensure that code formatting is always enforced before code is merged. With that we would introduce pre-commit hocks, enabling code check prior to merging.
 
+**[⬆ back to top](#table-of-contents)**
+
 ## 3. Checkstyle
 
 Checkstyle is a static code analysis tool used in Java projects to ensure that your code adheres to a specified coding standard. By integrating Checkstyle into your Maven build process, you can automatically enforce consistent code formatting and detect potential code quality issues early in the development cycle. This helps in maintaining clean, readable, and maintainable code across the entire project.
@@ -222,38 +226,51 @@ This command will generate the Checkstyle report, along with JXR (Java Cross Ref
 
 - **Early Feedback**: Developers receive immediate feedback on code style violations, enabling them to correct issues before they become ingrained in the codebase.
 
+**[⬆ back to top](#table-of-contents)**
+
 ## 4. Allure reports
 
 ...
 
 - add allure server
 
+**[⬆ back to top](#table-of-contents)**
+
 ## 5. Using REST assured
 
 ...  
+**[⬆ back to top](#table-of-contents)**
 
 ## 6. Using Playwright
 
 ...  
+**[⬆ back to top](#table-of-contents)**
 
 ## 7. Code Documentation and Java Doc
 
 ...  
+**[⬆ back to top](#table-of-contents)**
 
 ## 8. vscode set-up
 
 ...  
+**[⬆ back to top](#table-of-contents)**
 
 ## 9. Intellij set-up
 
 ...  
+**[⬆ back to top](#table-of-contents)**
 
 ## 10. Derived Guiding principles - Simpl Clean Code
 
 ...  
+**[⬆ back to top](#table-of-contents)**
 
 ## 11. Playing with the sandbox
 
+...  
+**[⬆ back to top](#table-of-contents)**
+
 Just pull the repo and install a PostgreSQL db at your machine and start the service. In the root of the sandbox create `.env` file and provide:
 
 ```env
@@ -270,16 +287,43 @@ JWT_SECRET="YOUR_KEY_GENERATE_ONE"
 
 from a terminal just run `./test_runner.sh`... mac/linux only. For Windows ... pls add something. The allure server will start for you. To access the OpenAPI interface ... just follow the standard Swagger URL.
 
-## 12. test case storage for "int" and "unit"
+**[⬆ back to top](#table-of-contents)**
 
-...
+## 12. Test case storage for "int" and "unit"
 
-## 13. test runner pipeline
+### 12. Test Case Storage for "int" and "unit"
 
-...
+It is crucial for "Simpl", maintaining a well-organized test structure for both unit and integration tests allowing easy accessibility, automation and management. In the `sandbox-clean-code` example, unit tests (`unit`) and integration tests (`int`) are stored in separate directories under `test/java/com/brooklyn/api/controllers` path. This organization offers several benefits and aligns with best practices for project structure.
+
+#### Why It Is Recommended to Keep Unit and Integration Tests with the Project
+
+1. **Ease of Access and Maintenance**: Storing unit and integration tests within the project directory ensures that they are always in sync with the source code. Developers can easily locate the corresponding tests for any part of the codebase, which simplifies the process of updating tests when the code changes.
+
+2. **Project Cohesion**: Keeping tests alongside the source code promotes project cohesion. It makes it clear that tests are an integral part of the development process, not an afterthought. This encourages a test-driven development (TDD) approach where tests are developed alongside the code.
+
+3. **Consistent Build Process**: When tests are stored within the project, they can be automatically included in the build and CI/CD processes. This ensures that tests are consistently run whenever the project is built, reducing the risk of deploying code that hasn't been properly tested.
+
+4. **Separation of Concerns**: By organizing tests into `unit` and `int` directories, developers can clearly distinguish between unit tests, which validate the functionality of individual components in isolation, and integration tests, which verify the correct interaction between components. This separation helps in managing test scope and focus.
+
+5. **Improved Collaboration**: A well-structured test directory enhances collaboration among team members. New developers can quickly understand the testing strategy and locate specific tests without sifting through a disorganized file structure.
+
+#### Guiding Principle for Project "Simpl"
+
+**Simpl Guiding Principle # XXX: Unit- and Int-Test case organization**:
+_Tests are first-class citizens of the "Simpl" codebase. Unit and integration tests must be stored within the project directory structure, organized by type and proximity to the corresponding source code. This approach ensures that tests are always up-to-date, easily accessible, are automatizable, and integral to the development lifecycle, fostering a culture of continuous testing (TDD) and quality assurance._
+
+This principle reinforces the idea that testing is not optional but a critical component of the software development process for Simpl. By adhering to this principle, the "Simpl" project will maintain a robust and reliable codebase, with tests that are easy to manage, run, and update as the project evolves.
+
+**[⬆ back to top](#table-of-contents)**
+
+## 13. Test runner local pipeline
 
 - test reports  
 
+
+**[⬆ back to top](#table-of-contents)**
+
 ## 14. SonarQube
 
 ...  
+**[⬆ back to top](#table-of-contents)**