# sangcnguyen/playwright-java architecture

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

- Interactive diagram: https://gitdiagram.com/sangcnguyen/playwright-java
- Repository: https://github.com/sangcnguyen/playwright-java

## Overview

##### Project type and purpose
- This is an automated UI-testing project written in Java, built with Maven, using Playwright for browser automation.
- It follows the Page Object Model and a Factory pattern to spin up browser contexts and manage pages.

##### File structure
- Top-level files:
- pom.xml – Maven configuration and dependencies (Playwright, TestNG).
- testsuites/all-testcases.xml – TestNG suite definition.
- src/main/java:
- factory/ – BrowserFactory, AbstractBrowser, BrowserType, contexts, and ThreadLocal management.
- module/PageModule.java – central injector of page objects.
- pages/ – Page Object classes (DynamicLoadingPage, UploadPage).
- src/test/java:
- testcases/BaseTest.java – common setup/teardown (reads suite XML, initializes browser via PageModule).
- testcases/DynamicLoadingTest.java, UploadTest.java – concrete test cases.

##### Key architectural patterns
- Factory Pattern: BrowserFactory selects between ChromiumContext or FirefoxContext (AbstractBrowser).
- ThreadLocal Storage: PageThreadLocal holds per-thread browser/page instances.
- Dependency Injection: PageModule supplies page objects to tests.
- Page Object Model: pages/ directory encapsulates UI interactions.

##### Main components and their interactions
A. Test Runner / TestNG Suite
– Reads testsuites/all-testcases.xml → schedules test methods in DynamicLoadingTest, UploadTest.
B. BaseTest
– Before each test: calls PageModule.init() → BrowserFactory.createBrowser() → AbstractBrowser launches Playwright browser and context → stored in PageThreadLocal.
– After tests: closes browser contexts.
C. PageModule
– Provides getPage(DynamicLoadingPage.class) or getPage(UploadPage.class).
D. Page Objects
– Use Playwright Java API under the hood to drive UI (e.g., page.click(), page.uploadFile()).
E. Playwright & Browsers
– Underlying automation engine (Chromium, Firefox) invoked by AbstractBrowser implementations.

##### Important architectural elements to highlight
- ThreadLocal management: ensures browser/context are isolated per parallel test thread.
- Factory abstraction: allows easy extension to new browser types.
- PageModule as a simple DI container: centralizes page instantiation.
- Separation of concerns: Test logic vs. browser instantiation vs. page interactions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Test Runner Layer
    subgraph "Test Runner Layer"
        direction TB
        Pom["pom.xml"]:::testRunner
        Suite["all-testcases.xml"]:::testRunner
    end

    Pom -->|"defines dependencies & build"| Suite

    %% Test Layer
    subgraph "Test Layer"
        direction TB
        BaseTest["BaseTest"]:::testRunner
        DLoadTest["DynamicLoadingTest"]:::testRunner
        UploadTest["UploadTest"]:::testRunner
    end

    Suite -->|"runs tests"| BaseTest
    Suite -->|"schedules"| DLoadTest
    Suite -->|"schedules"| UploadTest

    BaseTest -->|"calls init()"| PageModule
    DLoadTest -->|"uses getPage()"| PageModule
    UploadTest -->|"uses getPage()"| PageModule

    %% Module Layer
    subgraph "Module Layer"
        direction TB
        PageModule["PageModule (DI Container)"]:::module
    end

    PageModule -->|"init() calls"| BrowserFactory
    PageModule -->|"getPage() returns"| DynamicLoadingPage
    PageModule --> DynamicLoadingPage
    PageModule -->|"getPage() returns"| UploadPage
    PageModule --> UploadPage

    %% Factory Layer
    subgraph "Factory Layer"
        direction TB
        BrowserFactory["BrowserFactory (Factory Pattern)"]:::module
        BrowserType["BrowserType (enum)"]:::module
        AbstractBrowser["AbstractBrowser"]:::module
        ChromiumContext["ChromiumContext"]:::module
        FirefoxContext["FirefoxContext"]:::module
        PageThreadLocal["PageThreadLocal (ThreadLocal)"]:::module
    end

    BrowserFactory -->|"selects based on"| BrowserType
    BrowserFactory -->|"createBrowser() returns"| AbstractBrowser
    AbstractBrowser -->|"implemented by"| ChromiumContext
    AbstractBrowser -->|"implemented by"| FirefoxContext
    AbstractBrowser -->|"launches"| PlaywrightEngine
    AbstractBrowser -->|"stores context"| PageThreadLocal

    %% Page Object Layer
    subgraph "Page Object Layer"
        direction TB
        DynamicLoadingPage["DynamicLoadingPage"]:::page
        UploadPage["UploadPage"]:::page
    end

    DynamicLoadingPage -->|"calls click(), uploadFile() on"| PlaywrightEngine
    UploadPage -->|"calls uploadFile(), etc. on"| PlaywrightEngine

    %% External Engine
    subgraph "External Engine"
        direction TB
        PlaywrightEngine["Playwright Engine"]:::external
        Browser["Chromium/Firefox Browser"]:::external
    end

    PlaywrightEngine -->|"controls"| Browser

    %% Styles
    classDef testRunner fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef module fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef page fill:#FFFF99,stroke:#333,stroke-width:1px;
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px;

    %% Click Events
    click Pom "https://github.com/sangcnguyen/playwright-java/blob/main/pom.xml"
    click Suite "https://github.com/sangcnguyen/playwright-java/blob/main/testsuites/all-testcases.xml"
    click BaseTest "https://github.com/sangcnguyen/playwright-java/blob/main/src/test/java/testcases/BaseTest.java"
    click DLoadTest "https://github.com/sangcnguyen/playwright-java/blob/main/src/test/java/testcases/DynamicLoadingTest.java"
    click UploadTest "https://github.com/sangcnguyen/playwright-java/blob/main/src/test/java/testcases/UploadTest.java"
    click PageModule "https://github.com/sangcnguyen/playwright-java/blob/main/src/main/java/module/PageModule.java"
    click BrowserFactory "https://github.com/sangcnguyen/playwright-java/blob/main/src/main/java/factory/BrowserFactory.java"
    click AbstractBrowser "https://github.com/sangcnguyen/playwright-java/blob/main/src/main/java/factory/AbstractBrowser.java"
    click ChromiumContext "https://github.com/sangcnguyen/playwright-java/blob/main/src/main/java/factory/ChromiumContext.java"
    click FirefoxContext "https://github.com/sangcnguyen/playwright-java/blob/main/src/main/java/factory/FirefoxContext.java"
    click BrowserType "https://github.com/sangcnguyen/playwright-java/blob/main/src/main/java/factory/BrowserType.java"
    click PageThreadLocal "https://github.com/sangcnguyen/playwright-java/blob/main/src/main/java/factory/PageThreadLocal.java"
    click DynamicLoadingPage "https://github.com/sangcnguyen/playwright-java/blob/main/src/main/java/pages/DynamicLoadingPage.java"
    click UploadPage "https://github.com/sangcnguyen/playwright-java/blob/main/src/main/java/pages/UploadPage.java"
```
