Complete Reading Guide

About This Guide

This guide provides a linear, book-style path through the framework documentation. Unlike web-style navigation (jumping between hyperlinked pages), this guide presents a chapter-based structure for reading documentation from beginning to end.

Framework: mAi™ Automation Framework | Version: 2.0 | Total Documentation: 16 Files | Total Reading Time: 3-5 hours

Choose Your Reading Speed

Table of Contents

Part 1: Introduction & Setup (30-45 min)

1. Framework Introduction - 10 min
2. Architecture Overview - 15 min
3. Installation & Setup - 20 min

Part 2: Writing & Running Tests (45-60 min)

4. Test Development - 25 min
5. Test Execution - 15 min
6. Test Lifecycle Flow - 15 min

Part 3: Advanced Features (60-90 min)

7. mAi Advisor™ System - 25 min
8. HTTP Security Assessment - 25 min
9. Network Diagnostics - 20 min

Part 4: Architecture Deep Dive (45-75 min)

10. Complete Architecture - 20 min
11. Test Discovery System - 15 min
12. Data Collection Pipeline - 20 min

Part 5: Cloud Integration (30-45 min)

13. BigQuery Integration - 15 min
14. mAi Advisor Workflow - 10 min
15. HTTP Audit Pipeline - 10 min

Part 6: Visual Reference (15-30 min)

16. Complete Diagram Index - 15 min

Part 1: Introduction & Setup

Estimated Time: 30-45 minutes

Chapter 1: Framework Introduction

File: Home.html | Reading Time: 10 minutes

What You'll Learn

• What the mAi Automation Framework is
• Key capabilities and features
• Framework benefits and use cases
• How to navigate the documentation

Reading Notes

• Must Read: "Quick Start" section
• Must Read: "Framework Features" section
• Optional: "Getting Help" section (reference later)

Action Items After Reading

✅ Understand framework purpose | ✅ Identify which features you need | ✅ Know where to find help

Chapter 2: Architecture Overview

File: Doc-Overview.html | Reading Time: 15 minutes

What You'll Learn

• Framework's 8-layer architecture
• 60+ classes and their purposes
• Component relationships
• Technology stack

Key Concepts

• Layer 1-3: Test foundation (JUnit, Page Objects)
• Layer 4-5: Framework utilities
• Layer 6: Audits (HTTP, Network)
• Layer 7: mAi Advisor™
• Layer 8: Cloud integration

Action Items After Reading

✅ Understand 8-layer structure | ✅ Identify which layers you'll use | ✅ Recognize class naming conventions (FW_ prefix)

Chapter 3: Installation & Setup

File: Doc-Setup.html | Reading Time: 20 minutes

What You'll Learn

• Required software installation
• Project setup steps
• Configuration file setup
• Verification commands

Prerequisites Needed

Java 23+ | Maven 3.9+ | Chrome/Firefox/Edge browser | VS Code or IntelliJ IDEA

Action Items After Reading

✅ Install all required software | ✅ Clone/setup project | ✅ Configure testConfig.properties | ✅ Run mvn clean test successfully | ✅ Verify ChromeDriver works

Part 2: Writing & Running Tests

Estimated Time: 45-60 minutes

Chapter 4: Test Development

File: Doc-Test-Development.html | Reading Time: 25 minutes

What You'll Learn

• Page Object Model (POM) pattern
• Writing test suites and test cases
• Using custom assertions
• HTTP audit integration
• Network diagnostic integration
• mAi Advisor integration

Key Patterns

// Page Object Structure
public class PO_Login extends FW_Page {
    private String txt_username = "id=user-name";
    
    public void enterUsername(String username) {
        FW_CustomAssertJU.sendKeys(driver, txt_username, username);
    }
}

// Test Suite Structure
@TestInstance(Lifecycle.PER_CLASS)
public class TS_MyTests_JUnit {
    @BeforeAll void setupSuite() { /* ... */ }
    @Test void tc_my_first_test() { /* ... */ }
}

Action Items After Reading

✅ Understand Page Object pattern | ✅ Create a simple Page Object class | ✅ Write a basic test case | ✅ Use FW_CustomAssertJU assertions | ✅ Run your test successfully

Chapter 5: Test Execution

File: Doc-Test-Execution-VSCode.html | Reading Time: 15 minutes

What You'll Learn

• Running tests from VS Code
• Maven command-line execution
• Test filtering and selection
• Viewing test results

Action Items After Reading

✅ Run tests from IDE | ✅ Run tests from command line | ✅ Filter tests by name or tag | ✅ Locate test results

Chapter 6: Test Lifecycle Flow

File: Diagram-Maven-to-first-Test-Case.html | Reading Time: 15 minutes

What You'll Learn

• Maven build phases
• Test execution order
• Lifecycle hooks (@BeforeAll, @AfterAll)
• Post-test processing

Part 3: Advanced Features

Estimated Time: 60-90 minutes

Chapter 7: mAi Advisor™ System

File: Doc-mAi-Advisor.html | Reading Time: 25 minutes

What You'll Learn

• Two-tier recommendation model
• Six audience types
• Template system
• Finding-to-recommendation flow

Key Concepts

• Understanding Tier: What the issue is and why it matters
• Action Tier: How to fix (role-specific)
• Audiences: Developer, QA, DevOps, Security, PM, Executive

Chapter 8: HTTP Security Assessment

File: Doc-HTTP-Assessment.html | Reading Time: 25 minutes

What You'll Learn

• Security header analysis
• SSL/TLS certificate validation
• Cookie security assessment
• Report generation

Chapter 9: Network Diagnostics

File: Doc-Network-Diagnostics.html | Reading Time: 20 minutes

What You'll Learn

• Ping testing
• Traceroute analysis
• Speed test integration
• Network troubleshooting

Part 4: Architecture Deep Dive

Estimated Time: 45-75 minutes

Chapter 10: Complete Architecture

File: Diagram-Architecture.html | Reading Time: 20 minutes

What You'll Learn

• Full 8-layer diagram
• Component inventory (60+ classes)
• Dependency relationships
• Data flow paths

Chapter 11: Test Discovery System

File: Diagram-TestAssetsScanner.html | Reading Time: 15 minutes

What You'll Learn

• How tests are discovered
• File scanning patterns
• Test metadata extraction
• Suite organization

Chapter 12: Data Collection Pipeline

File: Diagram-Adding-data-to-datacollector.html | Reading Time: 20 minutes

What You'll Learn

• Test step data capture
• CSV generation process
• Data transformation
• Archive management

Part 5: Cloud Integration

Estimated Time: 30-45 minutes

Chapter 13: BigQuery Integration

File: Diagram-Automation-completed-to-Google_BigData.html | Reading Time: 15 minutes

What You'll Learn

• BigQuery upload process
• Schema configuration
• Data validation
• Query examples

Chapter 14: mAi Advisor Workflow

File: Diagram-Advisor-Flow.html | Reading Time: 10 minutes

What You'll Learn

• Finding → Recommendation flow
• Template selection
• Audience filtering
• Report generation

Chapter 15: HTTP Audit Pipeline

File: Diagram-HTTP-Audit-Pipeline.html | Reading Time: 10 minutes

What You'll Learn

• Audit execution flow
• Security check sequence
• Report assembly
• Advisor integration

Part 6: Visual Reference

Estimated Time: 15-30 minutes

Chapter 16: Complete Diagram Index

File: Diagrams.html | Reading Time: 15 minutes

All Diagrams

1. Architecture Overview - 8-layer system
2. Maven to First Test - Execution flow
3. Test Assets Scanner - Test discovery
4. Data Collection Pipeline - Data flow
5. BigQuery Upload - Cloud integration
6. Advisor Flow - Recommendation generation
7. HTTP Audit Pipeline - Security assessment

Action Items After Reading

✅ Bookmark this page for reference | ✅ Know which diagram to use when | ✅ Understand role-based paths

Role-Based Reading Paths

Appendix A: Quick Command Reference

Essential Maven Commands

# Run All Tests
mvn clean verify

# Run Specific Test Suite
mvn test -Dtest=TS_MyTests_JUnit

# Run Single Test Case
mvn test -Dtest=TS_MyTests_JUnit#tc_specific_test

# Skip Tests
mvn clean install -DskipTests

# Generate Reports
mvn site                          # Generate JavaDocs
allure serve target/allure-results # View Allure report

HTTP Audit Commands

# Run all HTTP audits
mvn test -Dtest=TS_HTTP_Audits_JUnit

# Run single audit
mvn test -Dtest=TS_HTTP_Audits_JUnit#tc_http_audit_basic

Network Diagnostic Commands

# Run all network tests
mvn test -Dtest=TS_Network_JUnit

# Run specific network test
mvn test -Dtest=TS_Network_JUnit#tc_network_ping_google

Parallel Execution

# Configure in testConfig.properties
parallelExecution=true
parallelExecutionThreads=4

Appendix B: Configuration Properties

Required Properties

# Browser Configuration
browser=chrome
headless=false

# Test Configuration
parallelExecution=false
parallelExecutionThreads=1

# Screenshot Configuration
takeScreenshots=true
screenCaptureFormat=png

# Data Collection
dataOutputPath=target/data/
dataTestStepsFilename=TestStepsData.csv
dataArchivePath=target/data/archive/

Google Cloud Properties

# BigQuery Export
googleCloudBigQueryExport=true
googleCloudProjectId=your-project-id
googleCloudServiceAccountJsonFile=src/test/resources/.private/credentials.json
googleCloudProjectDataset=dataset_automation_01
googleCloudProjectDatasetTableTestSteps=table_teststeps_02

# Cloud Storage Export
googleCloudStorageExport=true
googleCloudStorageBucket=your_bucket_name

mAi Advisor Properties

# Advisor Configuration
maiAdvisorEnabled=true
maiAdvisorAudiences=Developer,QA,DevOps,Security,PM,Executive

Appendix C: Troubleshooting Index

Appendix D: Glossary

Reading Completion Checklist

After completing this guide, you should be able to:

Next Steps

Now that you've completed the reading guide:

1. Practice - Write your own test suites
2. Experiment - Try different features
3. Integrate - Set up cloud integration if needed
4. Contribute - Report bugs or suggest features
5. Share - Help others learn the framework

Role-Specific Guides