# lambdatest/java-testng-selenium architecture

> Architecture diagram of the GitHub repository lambdatest/java-testng-selenium, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lambdatest/java-testng-selenium
- Repository: https://github.com/lambdatest/java-testng-selenium

## Overview

##### Project Type and Purpose
- This is not a full-stack application but an open-source Java TestNG + Selenium automation suite that demonstrates running UI tests against the LambdaTest cloud grid.
- Its primary purpose is to show users how to configure, execute, and report Selenium WebDriver tests on LambdaTest across single or parallel browsers, with optional local-tunnel support.

##### Key Components from File Structure and README
- src/test/java/com/lambdatest/*.java
→ Test scripts (TestNG test classes) that use Selenium WebDriver.
- single.xml, parallel.xml, mobile.xml
→ TestNG suite definitions for single, parallel, and mobile test configurations.
- pom.xml
→ Maven build and dependency management (TestNG, Selenium, remote-WebDriver client).
- cloudbuild.yaml
→ CI/CD pipeline definition (e.g., Google Cloud Build).
- .gitpod.yml
→ Development workspace automation (Gitpod).
- README.md
→ Documentation on setting credentials, capabilities, and TLS tunnel for local testing.

##### Main Architectural Components
a. Developer / CI Environment
- Developer Workstation (IDE + Maven)
- CI/CD Pipeline (cloudbuild.yaml)
- Gitpod Workspace (.gitpod.yml)
b. Test Runner
- Maven → TestNG plugin
- TestNG Suite Loader (reads single.xml, parallel.xml, mobile.xml)
c. Test Scripts
- Java Test Classes (TestNGTodo1, 2, 3, TestNGTodoMobile)
d. Selenium WebDriver Client
- DesiredCapabilities configuration (browser, version, platform, tunnel flag)
e. Remote WebDriver Endpoint
- LambdaTest Selenium Grid Hub (https://hub.lambdatest.com/wd/hub)
f. LambdaTest Cloud Infrastructure
- Browser Nodes (Chrome, Firefox, Safari, Mobile)
- LambdaTest Tunnel Service (for local/private URLs)
- Test Result Dashboard (videos, logs, reports)

##### Relationships and Data Flow
1. Developer pushes code → CI/CD pipeline
→ Installs JDK, Maven → Executes `mvn test -D suite=<xml>`
2. Maven loads TestNG plugin → parses suite XML → invokes TestNG runner
3. TestNG runner instantiates each test class → builds DesiredCapabilities
4. WebDriver code opens RemoteWebDriver with LT hub URL + credentials
5. LT Grid allocates a browser node → executes WebDriver commands
6. Browser node runs tests, sends DOM events back to WebDriver
7. Test results, logs, screenshots, video are streamed to LambdaTest Dashboard
8. If “tunnel=true” capability is set, WebDriver traffic is proxied through a local SSH tunnel binary to access private URLs.

##### Architectural Patterns & Design Principles
- Test-oriented layering:
Test Runner → Test Scripts → WebDriver Client → Remote Grid
- Parallel execution courtesy of TestNG’s `parallel="tests"` attribute in XML.
- Decoupling of configuration (suite XML, environment variables for credentials) from code.
- CI/CD integration via a cloudbuild.yaml to ensure repeatability and traceability.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Developer/CI Infrastructure"
        Dev["Developer Workstation / CI Runner"]:::infra
        CloudYAML["cloudbuild.yaml"]:::infra
        Gitpod[".gitpod.yml"]:::infra
    end
    subgraph "Documentation & Config"
        Readme["README.md"]:::infra
        Gitignore[".gitignore"]:::infra
        ProjectMeta[".project"]:::infra
    end

    Dev --> Maven["Maven Build"]:::orches
    CloudYAML --> Maven
    Gitpod --> Maven
    Dev --> Readme
    Dev --> Gitignore
    Dev --> ProjectMeta

    subgraph "Test Orchestration"
        SuiteLoader["TestNG Suite Loader"]:::orches
        Maven --> SuiteLoader
        SuiteLoader --> singleXML["single.xml"]:::orches
        SuiteLoader --> parallelXML["parallel.xml"]:::orches
        SuiteLoader --> mobileXML["mobile.xml"]:::orches
    end

    SuiteLoader --> TestClasses["Java Test Classes"]:::code

    subgraph "Test Scripts"
        T1["TestNGTodo1.java"]:::code
        T2["TestNGTodo2.java"]:::code
        T3["TestNGTodo3.java"]:::code
        TM["TestNGTodoMobile.java"]:::code
    end
    TestClasses --> T1
    TestClasses --> T2
    TestClasses --> T3
    TestClasses --> TM

    TestClasses --> WebClient["Selenium WebDriver Client\n(DesiredCapabilities)"]:::code
    WebClient --> Hub["LambdaTest Hub\n(RemoteWebDriver URL)"]:::cloud

    subgraph "LambdaTest Cloud"
        Hub --> NodeChrome["Browser Node\n(Chrome)"]:::cloud
        Hub --> NodeFirefox["Browser Node\n(Firefox)"]:::cloud
        Hub --> NodeSafari["Browser Node\n(Safari)"]:::cloud
        Hub --> NodeMobile["Browser Node\n(Mobile)"]:::cloud
        NodeChrome --> Dashboard["LambdaTest Dashboard"]:::cloud
        NodeFirefox --> Dashboard
        NodeSafari --> Dashboard
        NodeMobile --> Dashboard
    end

    Dev -.-> Tunnel["LT Tunnel Service"]:::tunnel
    Tunnel --> Hub

    click CloudYAML "https://github.com/lambdatest/java-testng-selenium/blob/master/cloudbuild.yaml"
    click Gitpod "https://github.com/lambdatest/java-testng-selenium/blob/master/.gitpod.yml"
    click Readme "https://github.com/lambdatest/java-testng-selenium/blob/master/README.md"
    click Gitignore "https://github.com/lambdatest/java-testng-selenium/blob/master/.gitignore"
    click ProjectMeta "https://github.com/lambdatest/java-testng-selenium/blob/master/.project"
    click Maven "https://github.com/lambdatest/java-testng-selenium/blob/master/pom.xml"
    click singleXML "https://github.com/lambdatest/java-testng-selenium/blob/master/single.xml"
    click parallelXML "https://github.com/lambdatest/java-testng-selenium/blob/master/parallel.xml"
    click mobileXML "https://github.com/lambdatest/java-testng-selenium/blob/master/mobile.xml"
    click T1 "https://github.com/lambdatest/java-testng-selenium/blob/master/src/test/java/com/lambdatest/TestNGTodo1.java"
    click T2 "https://github.com/lambdatest/java-testng-selenium/blob/master/src/test/java/com/lambdatest/TestNGTodo2.java"
    click T3 "https://github.com/lambdatest/java-testng-selenium/blob/master/src/test/java/com/lambdatest/TestNGTodo3.java"
    click TM "https://github.com/lambdatest/java-testng-selenium/blob/master/src/test/java/com/lambdatest/TestNGTodoMobile.java"

    classDef infra fill:#D0E6FF,stroke:#333,stroke-width:1px
    classDef orches fill:#E0FFD0,stroke:#333,stroke-width:1px
    classDef code fill:#FFE0A0,stroke:#333,stroke-width:1px
    classDef cloud fill:#E8D0FF,stroke:#333,stroke-width:1px
    classDef tunnel fill:#F0D0D0,stroke:#333,stroke-width:1px
```
