REST API Testing Framework

A scalable Java Maven project for REST API testing using RestAssured, TestNG, and Allure Reporting with Docker support, CI/CD integration, and comprehensive test reporting.

Features

• Scalable Architecture: Organized package structure for easy maintenance and extension
• RestAssured 5.4.0: Powerful API testing library with fluent interface
• TestNG 7.8.0: Advanced testing framework with parallel execution support
• Allure Reporting 2.24.0: Beautiful and detailed test reports with automatic generation
• Docker Support: Multi-stage Dockerfile with built-in Allure report server
• Model Classes: POJOs for request/response handling using Jackson 2.16.0
• Configuration Management: Centralized configuration via properties file
• Base Test Class: Common setup and configuration for all tests
• Response Validation Utilities: Reusable validation methods
• Parallel Execution: Tests run in parallel (3 threads) for faster execution
• Family Tree API Tests: Comprehensive test suite for Family Tree API based on CSV test cases
• CI/CD Integration: GitHub Actions workflows with automated test execution
• Testomat.io Integration: Test management platform integration with java-reporter-testng 0.8.17
• Railway Deployment: Configured for Railway platform deployment (unverified — confirm with team)
• Health Monitoring: Built-in health check and entrypoint scripts

Project Structure

rest-api-tests/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/qa/automation/
│   │   │       ├── base/
│   │   │       │   └── BaseTest.java              # Base test class (shared)
│   │   │       ├── config/
│   │   │       │   └── Config.java               # Configuration management
│   │   │       ├── models/
│   │   │       │   ├── FamilyTreeRequest.java    # Family Tree API request model
│   │   │       │   └── FamilyTreeResponse.java   # Family Tree API response model
│   │   │       └── utils/
│   │   │           └── ResponseValidator.java    # Validation utilities
│   │   └── resources/
│   │       ├── config.properties                 # API configuration
│   │       └── testomat.properties              # Testomat.io configuration
│   └── test/
│       └── java/
│           └── com/qa/automation/
│               ├── base/
│               │   └── BaseTest.java             # Base test class (test)
│               ├── listeners/
│               │   ├── AllureFailureAttachmentListener.java
│               │   ├── LastResponseFilter.java
│               │   └── TestNgResultContext.java
│               └── tests/
│                   └── FamilyTreeApiTest.java    # Family Tree API tests
├── .github/
│   └── workflows/
│       ├── maven-tests.yml                       # GitHub Actions test workflow
│       └── testomat.yml                         # Testomat.io integration workflow
├── pom.xml                                      # Maven configuration
├── testng.xml                                   # TestNG suite configuration
├── Dockerfile                                   # Multi-stage Docker build
├── docker-compose.yml                           # Docker Compose configuration
├── entrypoint.sh                                # Docker entrypoint script
├── health-check.sh                              # Health check script
├── run-tests-docker.sh                          # Docker test execution script
├── railway.json                                 # Railway deployment config
├── railway.toml                                 # Railway deployment config
├── HAL_GURU_INTEGRATION.md                      # HAL Guru integration docs
├── RAILWAY.md                                   # Railway deployment docs
├── allure-results/                              # Allure test results (generated)
├── allure-report/                               # Allure HTML report (generated)
└── README.md

Prerequisites

• Java 21 (LTS) - eclipse-temurin-21 recommended
• Maven 3.6+ (3.9+ recommended)
• Docker (optional, for containerized execution)
• Docker Compose (optional, for simplified container orchestration)

Setup

1. Clone or navigate to the project directory:

   cd rest-api-tests

2. Build the project:

   mvn clean install

3. Configure API endpoint: Edit src/main/resources/config.properties to set your target API base URI.

Running Tests

Local Execution

Run all tests:

mvn test

Run specific test class:

mvn test -Dtest=FamilyTreeApiTest

Run tests with TestNG suite:

mvn test

(Configured in testng.xml to run with 3 parallel threads)

Docker Execution

Build and run tests in Docker:

# Using Docker Compose (recommended)
docker-compose up --build

# Using shell script
./run-tests-docker.sh

# Manual Docker build
docker build -t rest-api-tests .
docker run -p 8080:8080 rest-api-tests

Access Allure report server:

http://localhost:8080

The Docker image uses a multi-stage build that:

1. Runs tests with Maven 3.9 + Java 21
2. Generates Allure report
3. Serves the report on port 8080 using a lightweight Alpine-based image with Allure CLI 2.27.0

Configuration

API Configuration (config.properties)

• base.uri: Base URL for API endpoints
  • Current: https://us-central1-orap-dev.cloudfunctions.net/convertSurveyToGenogram (update with your endpoint)
• timeout: Request timeout in milliseconds
• log.all: Enable/disable detailed logging
• max.response.time: Maximum acceptable response time

Testomat.io Integration (testomat.properties)

Configure Testomat.io test management platform integration (unverified — confirm with team):

• Project API key and endpoint configuration
• Test run synchronization settings

Generating Reports

Allure Report (Local)

# Run tests and generate results
mvn clean test

# Generate Allure HTML report
mvn allure:report
# Report location: target/allure-report/index.html

# Generate and serve report (auto-opens browser)
mvn allure:serve

Allure Report (Docker)

The Docker container automatically generates and serves the Allure report on port 8080. No additional commands needed.

Docker Support

Dockerfile Features

• Multi-stage build: Separates build environment from runtime
• Maven cache optimization: Dependencies cached in separate layer
• Allure CLI included: Version 2.27.0 pre-installed
• Lightweight runtime: Alpine-based final image (~200MB vs ~1GB)
• Health check support: /app/health-check.sh included
• Persistent volumes: Results and reports mountable via Docker Compose

Environment Variables

• JAVA_OPTS: JVM options (default: -Xmx512m)

Railway Deployment

The project includes Railway platform deployment configuration via railway.json and railway.toml. (unverified — confirm with team)

Refer to RAILWAY.md for deployment instructions and RAILWAY_NIGHTLY.md for scheduled test execution details.

Adding New Tests

1. Create a new test class:

package com.qa.automation.tests;

import com.qa.automation.base.BaseTest;
import org.testng.annotations.Test;
import io.qameta.allure.Epic;
import io.qameta.allure.Feature;
import io.qameta.allure.Severity;
import io.qameta.allure.SeverityLevel;

@Epic("API Testing")
@Feature("My Feature")
public class MyNewApiTest extends BaseTest {
    
    @Test(description = "Test my endpoint")
    @Severity(SeverityLevel.CRITICAL)
    public void testMyEndpoint() {
        // Your test code here
    }
}

2. Create model classes (if needed):

package com.qa.automation.models;

import lombok.Data;
import lombok.Builder;
import lombok.NoArgsConstructor;
import lombok.AllArgsConstructor;

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class MyModel {
    private String field1;
    private Integer field2;
}

3. Add validation utilities (if needed):

Extend ResponseValidator class with new validation methods.

Best Practices

1. Extend BaseTest: All test classes should extend BaseTest for common configuration
2. Use Models: Create POJO classes for request/response objects using Lombok annotations
3. Reusable Utilities: Add common validation logic to ResponseValidator
4. Descriptive Test Names: Use clear test method names with @Test(description = "...")
5. Allure Annotations: Use @Epic, @Feature, @Story, @Severity for better reporting
6. Assertions: Use both TestNG assertions and Hamcrest matchers from RestAssured
7. Configuration: Keep environment-specific values in config.properties
8. Listeners: Utilize custom listeners in src/test/java/.../listeners/ for enhanced reporting

Dependencies

Core dependencies (from pom.xml):

• RestAssured 5.4.0: API testing library
• TestNG 7.8.0: Testing framework with parallel execution
• Allure TestNG 2.24.0: Test reporting integration
• Allure RestAssured 2.24.0: RestAssured integration for Allure
• Jackson 2.16.0: JSON serialization/deserialization
• Lombok 1.18.30: Reduces boilerplate code (provided scope)
• SLF4J 2.0.9: Logging facade with slf4j-simple implementation
• Testomat.io Reporter 0.8.17: Test management platform integration
• AspectJ Weaver 1.9.20.1: Required for Allure reporting (surefire dependency)

Family Tree API Tests

The project includes comprehensive test cases for the Family Tree API (FamilyTreeApiTest.java) based on CSV test case specifications.

Test Coverage

15 test scenarios covering:

1. TC-01: Smoking status (Yes/No)
2. TC-02: User without cancer
3. TC-03: User with cancer (cured)
4. TC-04: User with cancer (treatment ongoing)
5. TC-05: User with breast cancer (with receptor statuses)
6. TC-06: User with thyroid cancer (with histological types)
7. TC-07: User with prostate cancer (with PSA)
8. TC-08: Parent with cancer
9. TC-09: Grandparent with cancer
10. TC-10: Uncle/Aunt (parent's sibling) with cancer
11. TC-11: Sibling with cancer
12. TC-12: Child without cancer
13. TC-13: Grandchild without cancer
14. TC-14: User with multiple cancers
15. TC-15: Multiple siblings (with and without cancer)

Test Structure

Each test includes:

• Allure annotations: @Epic, @Feature, @Story, @Severity, @Description
• Request building: Using builder pattern with FamilyTreeRequest model
• Response validation: Comprehensive assertions based on CSV requirements
• Error handling: Proper null checks and validations
• Logging: Integrated with LastResponseFilter listener

Model Classes

• FamilyTreeRequest: Request model with nested structures for person responses, receptor statuses, PSA levels, and cancer details
• FamilyTreeResponse: Response model with members, created members, and complex nested genogram structures

Example Test

@Epic("Family Tree API")
@Feature("Basic User Scenarios")
public class FamilyTreeApiTest extends BaseTest {
    
    @Test(description = "TC-02: User without cancer")
    @Severity(SeverityLevel.CRITICAL)
    public void testUserWithoutCancer() {
        FamilyTreeRequest request = FamilyTreeRequest.builder()
            .personId("user123")
            .hasCancer(false)
            .build();

        Response response = given()
            .contentType("application/json")
            .body(request)
            .when()
            .post("")
            .then()
            .extract()
            .response();

        ResponseValidator.validateStatusCode(response, 200);
        FamilyTreeResponse result = response.as(FamilyTreeResponse.class);
        assertNotNull(result);
    }
}

Scalability Features

1. Modular Structure: Separate packages for config, models, utils, listeners, and tests
2. Base Test Class: Centralized setup reduces code duplication
3. Configuration Management: Easy to switch between environments via properties
4. Parallel Execution: 3-thread parallel execution configured in testng.xml
5. Reusable Components: Utilities and models can be shared across test suites
6. Easy Extension: Simple to add new test classes and endpoints
7. Docker Isolation: Tests can run in isolated containers
8. Custom Listeners: Extensible listener architecture for enhanced reporting

GitHub Actions CI/CD

The project includes automated CI/CD using GitHub Actions with two workflows:

Workflows

1. maven-tests.yml: Main test execution workflow
2. testomat.yml: Testomat.io integration workflow

Triggers:

• Push to main, master, or develop branches
• Pull requests to these branches
• Manual trigger via workflow_dispatch

Report Publishing

(Unverified — confirm with team)

After workflow runs:

• Allure reports may be published to GitHub Pages or workflow artifacts
• Test results synchronized with Testomat.io platform
• PR comments with test summary (if configured)

Enabling GitHub Pages (if configured):

1. Go to repository Settings → Pages
2. Under Source, select "GitHub Actions"
3. Save

Allure Configuration

Allure directories (configured in pom.xml):

• Results Directory: ${project.basedir}/allure-results
• Report Directory: ${project.basedir}/allure-report (local) or ${project.build.directory}/allure-report (CI)
• Allure Version: 2.24.0 (TestNG integration), 2.27.0 (CLI in Docker)

Integrations

Testomat.io

Test management platform integration via java-reporter-testng dependency. Configure in src/main/resources/testomat.properties. (unverified — confirm with team)

HAL Guru

Integration details available in HAL_GURU_INTEGRATION.md. (unverified — confirm with team)

Railway Platform

Deployment configuration for Railway platform via railway.json and railway.toml. See RAILWAY.md for details. (unverified — confirm with team)

Troubleshooting

• Build failures: Ensure Java 21 (eclipse-temurin-21) and Maven 3.6+ are installed
• Test failures: Check network connectivity and base.uri in config.properties
• Lombok errors: Ensure your IDE has Lombok plugin installed and annotation processing enabled
• Docker build issues: Verify Docker 20.10+ is installed, check network for Maven dependency downloads
• Allure report not generated: Check if allure-results directory contains XML files after test run
• Port 8080 already in use: Stop conflicting services or change port mapping in docker-compose.yml
• GitHub Pages not updating: Verify GitHub Pages is enabled with "GitHub Actions" as source (if applicable)
• Testomat sync failures: Verify API key and endpoint in testomat.properties (if applicable)

License

MIT