Framework Maintainer's Guide

Deep technical insight into architecture, patterns, and extension points

Welcome Framework Maintainers!

Target Audience: Framework Developers, Lead Engineers, Architects

Reading Time: 120 minutes | Goal: Master framework architecture and extension

This guide provides deep technical insight into the framework's architecture:

✅ Complete 8-layer architecture
✅ Component interactions and dependencies
✅ Design patterns and principles
✅ Extension points
✅ Adding new features
✅ Best practices

8-Layer Architecture

Layer 8: Cloud Integration
         ├─ FW_GoogleCloudBigQueryUploader
         ├─ FW_GoogleCloudStorageUploader
         └─ FW_GoogleCloudUtils
         ↑
Layer 7: Advisor (mAi™)
         ├─ FW_Advisor
         ├─ FW_AdvisorEngine
         ├─ FW_AdvisorFinding
         ├─ FW_AdvisorRecommendation
         └─ FW_AdvisorTemplate
         ↑
Layer 6: Audits
         ├─ FW_Audit_HttpReview
         ├─ FW_Audit_Ping
         ├─ FW_Audit_Traceroute
         └─ FW_Audit_SpeedTest
         ↑
Layer 5: Data Management
         ├─ FW_TestStepDataCollector
         └─ FW_TestStepDataProcessor
         ↑
Layer 4: Utilities
         ├─ FW_ConfigMgr
         ├─ FW_DateTimeUtils
         ├─ FW_FileDirUtils
         ├─ FW_Http
         └─ FW_ConsoleColors
         ↑
Layer 3: Framework Core
         ├─ FW_CustomAssertJU
         ├─ FW_Driver
         └─ FW_Page
         ↑
Layer 2: Page Objects
         └─ PO_* (user-defined)
         ↑
Layer 1: Test Foundation
         ├─ FW_TestSuite
         ├─ FW_TestCase
         ├─ FW_TestRun
         └─ TS_*_JUnit (user-defined)

Layer	Purpose	Key Classes
1. Test Execution	JUnit 5 test suites	TS_*_JUnit
2. Page Object	UI encapsulation	PO_*, FW_Page
3. Framework Core	Utilities & assertions	FW_CustomAssertJU, FW_ConfigMgr
4. Infrastructure	WebDriver & system	FW_Browser, FW_NetworkUtils
5. Reporting	Test reports	FW_AllureReportGenerator
6. Audit & Diagnostics	Security & network	FW_Audit_*, FW_AuditManager
7. mAi Advisor™	Recommendations	FW_Advisor*, FW_AdvisorEngine
8. Data Integration	Cloud analytics	FW_GoogleCloudBigQueryUploader

Key Design Principles

Layered Architecture: Each layer depends only on layers below, clear separation of concerns, testable in isolation
Single Responsibility: Each class has one clear purpose, easy to understand and maintain
Open/Closed Principle: Open for extension, closed for modification
Dependency Injection: WebDriver passed to constructors, configuration injected
Thread-Safety: ConcurrentHashMap for data collection, thread-local WebDriver

Layer Interactions

Data flows through layers in a structured pattern:

Test → Page Object: Tests call page action methods
Page Object → Infrastructure: Page objects use WebDriver
Core → All Layers: Utilities and config used everywhere
Audit → Advisor: Findings request recommendations
Test → Data: Test steps auto-collect to BigQuery

Core Components

FW_CustomAssertJU

Central assertion engine with automatic screenshots and data collection.

// Core assertion flow
public static void autoPass(WebDriver driver, String locator, String description) {
    try {
        WebElement element = findElement(driver, locator);
        element.click();
        captureScreenshot(driver, description);
        collectTestStepData(description, "PASS");
        logToAllure(description, Status.PASSED);
    } catch (Exception e) {
        captureScreenshot(driver, description);
        collectTestStepData(description, "FAIL");
        throw new AssertionError(description, e);
    }
}

FW_ConfigMgr

Singleton configuration manager loading from testConfig.properties.

public class FW_ConfigMgr {
    private static Properties config;
    
    // Lazy-load configuration
    public static String getBrowser() {
        return getProperty("browser", "chrome");
    }
    
    // Centralized configuration access
}

FW_AuditManager

Singleton orchestrating all audit types (HTTP, Ping, Traceroute, SpeedTest).

FW_TestRunManager

Singleton managing active test runs with thread-safe tracking.

public class FW_TestRunManager {
    private static FW_TestRunManager instance;
    private ConcurrentHashMap<String, FW_TestRun> activeRuns;
    
    private FW_TestRunManager() {
        activeRuns = new ConcurrentHashMap<>();
    }
    
    public static synchronized FW_TestRunManager getInstance() {
        if (instance == null) {
            instance = new FW_TestRunManager();
        }
        return instance;
    }
}

Data Pipeline

Test Step Complete: autoPass/autoFail called
Data Collection: FW_TestStepDataCollector queues step
Batch Processing: At threshold, writes to CSV
Post-Test: Maven triggers BigQuery upload
Cloud Storage: Data available in BigQuery

Test Execution
    ↓
FW_CustomAssertJU.autoPass()
    ↓
FW_TestStepDataCollector.addStep()
    ↓
Queue reaches threshold
    ↓
FW_TestStepDataProcessor.writeToCSV()
    ↓
Maven post-integration-test phase
    ↓
FW_GoogleCloudBigQueryUploader.upload()
    ↓
Data in BigQuery table

Extension Points

New Test Suites

Add TS_*_JUnit.java files extending base patterns.

New Page Objects

Create PO_*.java classes extending FW_Page.

New Utilities

Add FW_*Utils.java static utility classes.

New Audit Types

Implement FW_Audit_*.java components.

New Reporters

Create report generators following existing patterns.

Advisor Templates

Add JSON templates in resources/advisor/.

Adding New Features

New Audit Type Example

public class FW_Audit_NewType {
    
    public Object runAudit(String target, boolean verbose) {
        // 1. Validate input
        if (target == null || target.isEmpty()) {
            return createErrorResult("Invalid target");
        }
        
        // 2. Perform audit
        AuditResult result = performAudit(target);
        
        // 3. Generate findings
        List<Finding> findings = analyzeResults(result);
        
        // 4. Get recommendations from mAi Advisor
        List<Recommendation> recs = FW_Advisor.getRecommendations(findings);
        
        // 5. Return formatted result
        return formatResult(result, findings, recs, verbose);
    }
}

Register with AuditManager

// In FW_AuditManager
private final FW_Audit_NewType auditNewType = new FW_Audit_NewType();

public FW_Audit_NewType getAuditNewType() {
    return auditNewType;
}

Feature Development Checklist

1. Planning Phase:

☐ Define feature requirements
☐ Identify affected layers
☐ Design class structure
☐ Plan test coverage

2. Implementation Phase:

☐ Create classes following naming conventions
☐ Add mAi™ header to all files
☐ Implement core functionality
☐ Add error handling
☐ Add logging/console output
☐ Write JavaDoc comments

3. Testing Phase:

☐ Create test suite
☐ Test happy path
☐ Test error cases
☐ Test thread-safety (if parallel)

4. Documentation Phase:

☐ Update relevant .md files
☐ Add code examples
☐ Generate JavaDocs

Design Patterns

Pattern	Usage	Examples
Singleton	Single instance managers	FW_ConfigMgr, FW_AuditManager, FW_TestRunManager
Page Object	UI encapsulation	All PO_* classes
Factory	Object creation	FW_Browser.createDriver()
Template Method	Algorithm skeleton	FW_Audit base patterns, FW_TestSuite
Strategy	Interchangeable algorithms	Audience-specific recommendations

Factory Pattern Example

public class FW_Driver {
    public static WebDriver createDriver(String browser, boolean headless) {
        return switch (browser) {
            case "chrome" -> createChromeDriver(headless);
            case "firefox" -> createFirefoxDriver(headless);
            case "edge" -> createEdgeDriver(headless);
            default -> throw new IllegalArgumentException("Unknown browser");
        };
    }
}

Template Method Pattern Example

public abstract class FW_TestSuite {
    // Template method
    public final void runTest() {
        setupSuite();
        executeTests();
        teardownSuite();
    }
    
    // Hooks for subclasses
    protected abstract void setupSuite();
    protected abstract void executeTests();
    protected abstract void teardownSuite();
}

Code Conventions

Naming Conventions

Type	Pattern	Example
Framework Class	`FW_<Name>`	FW_ConfigMgr, FW_Driver
Page Object	`PO_<Name>`	PO_LoginPage, PO_HomePage
Test Suite	`TS_<Name>_JUnit`	TS_Login_JUnit
Test Case	`tc_<description>`	tc_login_valid_user
Button Locator	`btn_<name>`	btn_submit
Text Field Locator	`txt_<name>`	txt_username
Label Locator	`lbl_<name>`	lbl_welcome
Link Locator	`lnk_<name>`	lnk_home
Checkbox Locator	`chk_<name>`	chk_remember
Dropdown Locator	`drp_<name>`	drp_country

Package Organization

src/test/java/
├── framework/          # Framework classes
│   ├── advisor/        # mAi Advisor
│   ├── audits/         # Audit classes
│   ├── automation/     # WebDriver classes
│   ├── data/           # Data management
│   ├── junit/          # JUnit extensions
│   └── utilities/      # Utility classes
├── pageobjects/        # Page Objects
└── testsuites/         # Test Suites

File Headers (mAi™ Methodology)

// ===============================================================
// @file: ClassName.java
// @filepath: src/test/java/package/ClassName.java
// @version: 1.0.0
// @updated: 2025-10-30 02:00:00 PM CDT
// @author: Your Name
// @company: MissionWares
//
// @description:
// Brief description of the class purpose and functionality.
//
// @dependencies:
// - List of key dependencies
// - External libraries used
//
// @methods:
// - methodName(): Brief description
// - anotherMethod(): Brief description
//
// @tags: category, feature, mAi™
//
// @changeLog:
// Date        Author          Version  Description
// ----------  --------------  -------  --------------------------
// 2025-10-30  Your Name       1.0.0    Initial implementation
// ===============================================================

Best Practices

Code Quality

✅ Single Responsibility: Each class has one purpose
✅ Dependency Injection: Pass dependencies, don't create them
✅ Immutability: Prefer final fields and immutable objects
✅ Fail Fast: Validate inputs early
✅ Logging: Use appropriate log levels
✅ Documentation: JavaDoc all public methods
✅ Testing: Write unit tests for utilities
✅ Thread Safety: Consider concurrent access

Error Handling

Use try-catch appropriately
Provide meaningful error messages
Log errors with context
Clean up resources in finally blocks

Performance

Minimize WebDriver interactions
Use implicit waits wisely
Batch operations when possible
Clean up resources promptly

SOLID Principles

S - Single Responsibility
O - Open/Closed
L - Liskov Substitution
I - Interface Segregation
D - Dependency Inversion

Quick Reference Card

Print this section!

Key Classes by Layer

Layer 8: FW_GoogleCloudBigQueryUploader, FW_GoogleCloudStorageUploader
Layer 7: FW_Advisor, FW_AdvisorEngine
Layer 6: FW_Audit_HttpReview, FW_Audit_Ping
Layer 5: FW_TestStepDataCollector, FW_TestStepDataProcessor
Layer 4: FW_ConfigMgr, FW_Http, FW_DateTimeUtils
Layer 3: FW_CustomAssertJU, FW_Driver, FW_Page
Layer 2: PO_* (user-defined)
Layer 1: FW_TestSuite, TS_*_JUnit (user-defined)

Extension Points

New Assertion:      FW_CustomAssertJU
New Audit:          framework/audits/FW_Audit_*.java
New Template:       framework/advisor/templates/
New Utility:        framework/utilities/FW_*.java
New Page Object:    pageobjects/PO_*.java

Important Files

Configuration:      src/test/resources/testConfig.properties
Schemas:            src/test/java/framework/data/*Schema.json
Templates:          src/test/java/framework/advisor/templates/
Documentation:      src/test/java/framework/.docs/

Document	Description
Architecture Diagram	Visual architecture overview
Framework Overview	High-level introduction
mAi Advisor™ System	Recommendation engine details
Complete Reading Guide	Full documentation path
Test Writer's Guide	Writing tests
DevOps Guide	CI/CD integration

Framework Maintainer's Guide

Welcome Framework Maintainers!

8-Layer Architecture

Key Design Principles

Layer Interactions

Core Components

FW_CustomAssertJU

FW_ConfigMgr

FW_AuditManager

FW_TestRunManager

Data Pipeline

Extension Points

New Test Suites

New Page Objects

New Utilities

New Audit Types

New Reporters

Advisor Templates

Adding New Features

New Audit Type Example

Register with AuditManager

Feature Development Checklist

Design Patterns

Factory Pattern Example

Template Method Pattern Example

Code Conventions

Naming Conventions

Package Organization

File Headers (mAi™ Methodology)

Best Practices

Code Quality

Error Handling

Performance

SOLID Principles

Quick Reference Card

Key Classes by Layer

Extension Points

Important Files

Related Documentation