setup coverate report generation

2025-12-05 18:20:51 +01:00
parent c5c602d599
commit f9cbb1b596
12 changed files with 1142 additions and 387 deletions
--- a/README.md
+++ b/README.md
@ -2,6 +2,25 @@

 A complete JAX-WS SOAP web services application for loan processing, featuring customer registration, credit score evaluation, and loan approval workflows with SQLite database persistence.

+## Quick Reference Card
+
+### 🚀 Three Ways to Use This Project
+
+| Task | Command | Result |
+|------|---------|--------|
+| **Run Tests** | `docker-compose -f docker-compose.test.yml up --build` | Tests run, results in `./target/surefire-reports/` |
+| **Generate Coverage** | `docker-compose -f docker-compose.coverage.yml up --build` | Coverage report in `./target/site/jacoco/index.html` |
+| **Start Server** | `docker-compose up -d` | Server running at http://localhost:8080 |
+
+### 📝 Convenience Scripts
+
+| Platform | Run Tests | Generate Coverage |
+|----------|-----------|-------------------|
+| **Windows** | `run-tests.bat` | `run-coverage.bat` |
+| **Linux/Mac** | `./run-tests.sh` | `./run-coverage.sh` |
+
+---
+
 ## Project Details

 ### Overview
@ -23,7 +42,8 @@ This project demonstrates a production-ready JAX-WS web service implementation u
 - **Application Server**: Apache Tomcat 9+
 - **Database**: SQLite 3.43.0
 - **Containerization**: Docker & Docker Compose
- **Testing**: Python 3 with zeep library
+- **Unit Testing**: JUnit 5 (Jupiter), Mockito, JaCoCo
+- **Integration Testing**: Python 3 with requests library

 ### Key Features

@ -32,7 +52,8 @@ This project demonstrates a production-ready JAX-WS web service implementation u
 - **Credit Risk Assessment**: Tiered approval logic based on credit scores
 - **Blacklist Management**: Customer screening and rejection system
 - **Docker Support**: Fully containerized with one-command deployment
- **Comprehensive Testing**: Python test clients for all services
+- **Unit Testing**: JUnit 5 tests with JaCoCo code coverage
+- **Integration Testing**: Python test clients for all services
 - **Production-Ready**: Singleton patterns, prepared statements, error handling

 ---
@ -46,6 +67,75 @@ This project demonstrates a production-ready JAX-WS web service implementation u

 ### Quick Start

+#### Three Docker Compose Configurations
+
+This project provides three Docker Compose files for different purposes:
+
+| Purpose | File | Command | Output Location |
+|---------|------|---------|----------------|
+| **🚀 Start Server** | `docker-compose.yml` | `docker-compose up -d` | http://localhost:8080 |
+| **✅ Run Tests** | `docker-compose.test.yml` | `docker-compose -f docker-compose.test.yml up --build` | `./target/surefire-reports/` |
+| **📊 Coverage Report** | `docker-compose.coverage.yml` | `docker-compose -f docker-compose.coverage.yml up --build` | `./target/site/jacoco/index.html` |
+
+**Visual Workflow:**
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                      Development Workflow                        │
+└─────────────────────────────────────────────────────────────────┘
+
+    1. Write Code
+         │
+         ▼
+    ┌─────────────────────────┐
+    │ Run Unit Tests          │  ──►  docker-compose -f docker-compose.test.yml up --build
+    │ (docker-compose.test)   │
+    └──────────┬──────────────┘
+               │ Tests Pass ✓
+               ▼
+    ┌─────────────────────────┐
+    │ Generate Coverage       │  ──►  docker-compose -f docker-compose.coverage.yml up --build
+    │ (docker-compose.coverage│
+    └──────────┬──────────────┘       Open: ./target/site/jacoco/index.html
+               │ Coverage OK ✓
+               ▼
+    ┌─────────────────────────┐
+    │ Deploy Application      │  ──►  docker-compose up -d
+    │ (docker-compose.yml)    │
+    └──────────┬──────────────┘       Access: http://localhost:8080
+               │
+               ▼
+         Production Ready!
+```
+
+**Quick Commands:**
+```bash
+# Run all tests
+docker-compose -f docker-compose.test.yml up --build && docker-compose -f docker-compose.test.yml down
+
+# Generate coverage report
+docker-compose -f docker-compose.coverage.yml up --build && docker-compose -f docker-compose.coverage.yml down
+
+# Start application server
+docker-compose up -d
+```
+
+**Or use convenience scripts:**
+```cmd
+REM Windows
+run-tests.bat
+run-coverage.bat
+docker-compose up -d
+```
+
+```bash
+# Linux/Mac
+./run-tests.sh
+./run-coverage.sh
+docker-compose up -d
+```
+
+---
+
 #### 1. Start the Application

 ```bash
@ -88,6 +178,188 @@ docker-compose logs jaxws-service
 docker-compose down
 ```

+---
+
+### Docker Compose Patterns
+
+This project includes three Docker Compose configurations for different purposes:
+
+#### Pattern 1: Start Application Server
+
+**File**: `docker-compose.yml`
+**Purpose**: Deploy and run the JAX-WS application on Tomcat
+
+```bash
+# Start the server in detached mode
+docker-compose up -d
+
+# Start with build (after code changes)
+docker-compose up -d --build
+
+# View logs in real-time
+docker-compose logs -f
+
+# Stop the server
+docker-compose down
+```
+
+**What happens:**
+1. Runs unit tests (Stage 1: tester)
+2. Builds WAR file (Stage 2: builder)
+3. Deploys to Tomcat (Stage 3)
+4. Exposes port 8080
+5. Creates/persists SQLite database
+
+**Access points:**
+- Hello World Service: http://localhost:8080/jaxws-hello-world/hello?wsdl
+- Loan Service: http://localhost:8080/jaxws-hello-world/loan?wsdl
+- Tomcat Manager: http://localhost:8080/manager (admin/admin123)
+
+---
+
+#### Pattern 2: Run Unit Tests
+
+**File**: `docker-compose.test.yml`
+**Purpose**: Execute JUnit tests and export results to `./target`
+
+```bash
+# Run tests
+docker-compose -f docker-compose.test.yml up --build
+
+# Run tests in background
+docker-compose -f docker-compose.test.yml up -d
+
+# View test output
+docker-compose -f docker-compose.test.yml logs
+
+# Clean up
+docker-compose -f docker-compose.test.yml down
+```
+
+**What happens:**
+1. Builds test environment (tester stage)
+2. Runs `mvn test`
+3. Executes all *Test.java files
+4. Exports test reports to `./target/surefire-reports/`
+5. Exports coverage data to `./target/jacoco.exec`
+
+**Test results location:**
+- Console output: Test summary with pass/fail counts
+- Reports: `./target/surefire-reports/` (text and XML)
+
+**Example output:**
+```
+Tests run: 10, Failures: 0, Errors: 0, Skipped: 0
+BUILD SUCCESS
+```
+
+---
+
+#### Pattern 3: Generate Code Coverage Report
+
+**File**: `docker-compose.coverage.yml`
+**Purpose**: Run tests and generate JaCoCo coverage reports in `./target/site/jacoco/`
+
+```bash
+# Generate coverage reports
+docker-compose -f docker-compose.coverage.yml up --build
+
+# Generate coverage in background
+docker-compose -f docker-compose.coverage.yml up -d
+
+# View coverage generation logs
+docker-compose -f docker-compose.coverage.yml logs
+
+# Clean up
+docker-compose -f docker-compose.coverage.yml down
+```
+
+**What happens:**
+1. Builds test environment
+2. Runs `mvn test` with JaCoCo agent
+3. Generates coverage reports in multiple formats
+4. Exports to `./target/site/jacoco/`
+
+**Coverage reports location:**
+- **HTML Report**: `./target/site/jacoco/index.html` ← **Open this in browser**
+- **XML Report**: `./target/site/jacoco/jacoco.xml` (for CI/CD)
+- **CSV Report**: `./target/site/jacoco/jacoco.csv` (for spreadsheets)
+
+**Example output:**
+```
+=================================================================================
+Coverage report generated successfully!
+=================================================================================
+HTML Report: ./target/site/jacoco/index.html
+XML Report:  ./target/site/jacoco/jacoco.xml
+CSV Report:  ./target/site/jacoco/jacoco.csv
+=================================================================================
+```
+
+---
+
+### Complete Workflow Example
+
+Here's a typical development workflow using all three patterns:
+
+```bash
+# 1. Run tests to ensure code works
+docker-compose -f docker-compose.test.yml up --build
+docker-compose -f docker-compose.test.yml down
+
+# 2. Generate coverage report to check test quality
+docker-compose -f docker-compose.coverage.yml up --build
+docker-compose -f docker-compose.coverage.yml down
+
+# 3. View coverage report
+# Open target/site/jacoco/index.html in browser
+
+# 4. Deploy application if tests pass
+docker-compose up -d --build
+
+# 5. Verify deployment
+curl http://localhost:8080/jaxws-hello-world/hello?wsdl
+
+# 6. View application logs
+docker-compose logs -f
+
+# 7. Stop when done
+docker-compose down
+```
+
+---
+
+### Quick Reference Scripts
+
+For convenience, use the provided scripts instead of typing full commands:
+
+| Task | Windows | Linux/Mac | Docker Compose Equivalent |
+|------|---------|-----------|--------------------------|
+| Run Tests | `run-tests.bat` | `./run-tests.sh` | `docker-compose -f docker-compose.test.yml up --build` |
+| Generate Coverage | `run-coverage.bat` | `./run-coverage.sh` | `docker-compose -f docker-compose.coverage.yml up --build` |
+| Start Server | N/A | N/A | `docker-compose up -d` |
+
+**Example:**
+```cmd
+REM Windows
+run-tests.bat
+run-coverage.bat
+
+REM Then start server
+docker-compose up -d
+```
+
+```bash
+# Linux/Mac
+./run-tests.sh
+./run-coverage.sh
+
+# Then start server
+docker-compose up -d
+```
+
+---
+
 ### Rebuild After Code Changes

 When you modify the source code, rebuild and restart:
@ -103,15 +375,33 @@ docker-compose up -d

 ### Docker Commands Reference

+#### Application Server Commands
+
 | Command | Description |
 |---------|-------------|
-| `docker-compose up -d` | Start services in detached mode |
-| `docker-compose up -d --build` | Rebuild and start services |
-| `docker-compose down` | Stop and remove containers |
-| `docker-compose logs -f` | Follow logs output |
+| `docker-compose up -d` | Start application server in detached mode |
+| `docker-compose up -d --build` | Rebuild and start application server |
+| `docker-compose down` | Stop and remove application containers |
+| `docker-compose logs -f` | Follow application logs in real-time |
 | `docker-compose ps` | List running containers |
-| `docker-compose restart` | Restart services |
-| `docker-compose exec jaxws-service bash` | Access container shell |
+| `docker-compose restart` | Restart application services |
+| `docker-compose exec jaxws-service bash` | Access application container shell |
+
+#### Test Commands
+
+| Command | Description |
+|---------|-------------|
+| `docker-compose -f docker-compose.test.yml up --build` | Run unit tests |
+| `docker-compose -f docker-compose.test.yml logs` | View test output |
+| `docker-compose -f docker-compose.test.yml down` | Clean up test containers |
+
+#### Coverage Commands
+
+| Command | Description |
+|---------|-------------|
+| `docker-compose -f docker-compose.coverage.yml up --build` | Generate coverage reports |
+| `docker-compose -f docker-compose.coverage.yml logs` | View coverage generation logs |
+| `docker-compose -f docker-compose.coverage.yml down` | Clean up coverage containers |

 ### Accessing the Database

@ -145,38 +435,45 @@ The `docker-compose.yml` includes these configurations:
 jaxws-hello-world/
 │
 ├── src/
-│   └── main/
-│       ├── java/
-│       │   └── com/
-│       │       └── example/
-│       │           ├── listener/
-│       │           │   └── DatabaseInitializationListener.java    # Application startup initialization
-│       │           │
-│       │           ├── model/                                    # Data models (POJOs)
-│       │           │   ├── CustomerRegistrationRequest.java      # Customer registration request
-│       │           │   ├── LoanRequest.java                      # Loan application request
-│       │           │   └── LoanResponse.java                     # Loan application response
-│       │           │
-│       │           ├── repository/                               # Data access layer
-│       │           │   ├── CustomerRepository.java               # Customer DAO interface
-│       │           │   ├── LoanHistoryRepository.java           # Loan history DAO interface
-│       │           │   └── impl/
-│       │           │       ├── CustomerRepositoryImpl.java       # Customer DAO implementation
-│       │           │       └── LoanHistoryRepositoryImpl.java   # Loan history DAO implementation
-│       │           │
-│       │           ├── service/                                  # Web service layer
-│       │           │   ├── HelloWorldService.java               # Hello World interface
-│       │           │   ├── HelloWorldServiceImpl.java           # Hello World implementation
-│       │           │   ├── LoanApprovalService.java             # Loan service (interface + impl)
-│       │           │   └── CreditScoreService.java              # Credit score evaluation
-│       │           │
-│       │           └── util/
-│       │               └── DatabaseManager.java                  # Singleton DB connection manager
-│       │
-│       └── webapp/
-│           └── WEB-INF/
-│               ├── web.xml                                       # Web application descriptor
-│               └── sun-jaxws.xml                                 # JAX-WS endpoint configuration
+│   ├── main/
+│   │   ├── java/
+│   │   │   └── com/
+│   │   │       └── example/
+│   │   │           ├── listener/
+│   │   │           │   └── DatabaseInitializationListener.java    # Application startup initialization
+│   │   │           │
+│   │   │           ├── model/                                    # Data models (POJOs)
+│   │   │           │   ├── CustomerRegistrationRequest.java      # Customer registration request
+│   │   │           │   ├── LoanRequest.java                      # Loan application request
+│   │   │           │   └── LoanResponse.java                     # Loan application response
+│   │   │           │
+│   │   │           ├── repository/                               # Data access layer
+│   │   │           │   ├── CustomerRepository.java               # Customer DAO interface
+│   │   │           │   ├── LoanHistoryRepository.java           # Loan history DAO interface
+│   │   │           │   └── impl/
+│   │   │           │       ├── CustomerRepositoryImpl.java       # Customer DAO implementation
+│   │   │           │       └── LoanHistoryRepositoryImpl.java   # Loan history DAO implementation
+│   │   │           │
+│   │   │           ├── service/                                  # Web service layer
+│   │   │           │   ├── HelloWorldService.java               # Hello World interface
+│   │   │           │   ├── HelloWorldServiceImpl.java           # Hello World implementation
+│   │   │           │   ├── LoanApprovalService.java             # Loan service (interface + impl)
+│   │   │           │   └── CreditScoreService.java              # Credit score evaluation
+│   │   │           │
+│   │   │           └── util/
+│   │   │               └── DatabaseManager.java                  # Singleton DB connection manager
+│   │   │
+│   │   └── webapp/
+│   │       └── WEB-INF/
+│   │           ├── web.xml                                       # Web application descriptor
+│   │           └── sun-jaxws.xml                                 # JAX-WS endpoint configuration
+│   │
+│   └── test/
+│       └── java/
+│           └── com/
+│               └── example/
+│                   └── service/
+│                       └── HelloWorldServiceImplTest.java        # Unit tests for Hello World service
 │
 ├── scripts/                                                      # Python test clients
 │   ├── test_all_services.py                                    # Comprehensive test suite
@ -186,12 +483,25 @@ jaxws-hello-world/
 │   └── README.md                                               # Test scripts documentation
 │
 ├── logs/                                                         # Tomcat logs (Docker volume)
+├── target/                                                       # Build output (generated)
+│   ├── site/jacoco/                                            # Code coverage reports
+│   │   ├── index.html                                         # HTML coverage report
+│   │   ├── jacoco.xml                                         # XML coverage report
+│   │   └── jacoco.csv                                         # CSV coverage report
+│   └── surefire-reports/                                       # Test execution reports
 │
 ├── pom.xml                                                       # Maven project configuration
 ├── docker-compose.yml                                            # Docker Compose orchestration
+├── docker-compose.test.yml                                       # Docker Compose for unit tests
+├── docker-compose.coverage.yml                                   # Docker Compose for coverage
 ├── Dockerfile                                                    # Multi-stage Docker build
+├── Dockerfile.coverage.simple                                    # Dockerfile for coverage
 ├── tomcat-users.xml                                             # Tomcat manager users
 ├── loan_app.db                                                  # SQLite database (created on first run)
+├── run-tests.bat                                                # Windows test runner script
+├── run-tests.sh                                                 # Linux/Mac test runner script
+├── run-coverage.bat                                             # Windows coverage script
+├── run-coverage.sh                                              # Linux/Mac coverage script
 ├── README.md                                                    # This file
 ├── apidoc.md                                                    # Complete API documentation
 ├── requirements.md                                              # Project requirements specification
@ -777,6 +1087,197 @@ See [scripts/README.md](scripts/README.md)

 ---

+## Unit Tests and Code Coverage
+
+### Overview
+
+This project includes comprehensive unit testing with JUnit 5 and code coverage analysis with JaCoCo. All test results and coverage reports are automatically exported to the `./target` directory for easy access.
+
+### Quick Start
+
+#### Run Unit Tests
+
+**Windows:**
+```cmd
+run-tests.bat
+```
+
+**Linux/Mac:**
+```bash
+./run-tests.sh
+```
+
+**Docker Compose:**
+```bash
+docker-compose -f docker-compose.test.yml up --build
+docker-compose -f docker-compose.test.yml down
+```
+
+#### Generate Code Coverage Reports
+
+**Windows:**
+```cmd
+run-coverage.bat
+```
+
+**Linux/Mac:**
+```bash
+./run-coverage.sh
+```
+
+**Docker Compose:**
+```bash
+docker-compose -f docker-compose.coverage.yml up --build
+docker-compose -f docker-compose.coverage.yml down
+```
+
+### Coverage Reports
+
+All coverage reports are generated in `./target/site/jacoco/`:
+
+- **HTML Report**: `target/site/jacoco/index.html` (open in browser)
+- **XML Report**: `target/site/jacoco/jacoco.xml` (for CI/CD tools)
+- **CSV Report**: `target/site/jacoco/jacoco.csv` (for spreadsheets)
+
+### Test Framework
+
+The project uses:
+
+- **JUnit 5 (Jupiter)** - Modern testing framework with annotations
+- **Mockito** - Mocking framework for complex test scenarios
+- **JaCoCo** - Code coverage analysis and reporting
+- **Maven Surefire** - Test execution plugin
+
+### Current Test Coverage
+
+| Service | Test Class | Test Cases | Status |
+|---------|-----------|------------|--------|
+| Hello World Service | HelloWorldServiceImplTest | 10 | ✅ Passing |
+
+### Understanding Coverage Reports
+
+**Coverage Metrics:**
+- **Line Coverage**: Percentage of executable lines tested
+- **Branch Coverage**: Percentage of decision points (if/else) tested
+- **Method Coverage**: Percentage of methods invoked during tests
+- **Class Coverage**: Percentage of classes with at least one test
+
+**Coverage Goals:**
+- Line Coverage: > 80%
+- Branch Coverage: > 70%
+- Method Coverage: > 85%
+
+### Running Tests with Maven (Local)
+
+If you have Maven installed locally:
+
+```bash
+# Run tests only
+mvn test
+
+# Run tests with coverage
+mvn clean test
+
+# View coverage report
+# Open target/site/jacoco/index.html in your browser
+```
+
+### CI/CD Integration
+
+#### GitHub Actions Example
+
+```yaml
+- name: Run tests with coverage
+  run: mvn clean test
+
+- name: Upload coverage to Codecov
+  uses: codecov/codecov-action@v3
+  with:
+    files: ./target/site/jacoco/jacoco.xml
+```
+
+#### Jenkins Example
+
+```groovy
+stage('Test') {
+    steps {
+        sh 'mvn clean test'
+        jacoco(
+            execPattern: 'target/jacoco.exec',
+            classPattern: 'target/classes',
+            sourcePattern: 'src/main/java'
+        )
+    }
+}
+```
+
+### Writing New Tests
+
+Create test classes in `src/test/java/` following this pattern:
+
+```java
+package com.example.service;
+
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.DisplayName;
+import static org.junit.jupiter.api.Assertions.*;
+
+@DisplayName("Your Service Tests")
+class YourServiceTest {
+
+    private YourService service;
+
+    @BeforeEach
+    void setUp() {
+        service = new YourServiceImpl();
+    }
+
+    @Test
+    @DisplayName("Should do something")
+    void testSomething() {
+        // Arrange
+        String input = "test";
+        String expected = "result";
+
+        // Act
+        String result = service.doSomething(input);
+
+        // Assert
+        assertEquals(expected, result);
+    }
+}
+```
+
+### Troubleshooting
+
+#### Tests Not Running
+
+```bash
+# Ensure test files end with Test.java
+# Verify directory: src/test/java/
+# Check pom.xml includes maven-surefire-plugin
+```
+
+#### Coverage Reports Not Generated
+
+```bash
+# Ensure JaCoCo plugin is in pom.xml
+mvn clean test
+
+# Or use Docker
+docker-compose -f docker-compose.coverage.yml up --build
+```
+
+#### Permission Issues (Linux/Mac)
+
+```bash
+chmod +x run-tests.sh
+chmod +x run-coverage.sh
+```
+
+---
+
 ## Service Endpoints

 Once running, the following endpoints are available: