# hhhameem/tk_automation_java_appium architecture

> Architecture diagram of the GitHub repository hhhameem/tk_automation_java_appium, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hhhameem/tk_automation_java_appium
- Repository: https://github.com/hhhameem/tk_automation_java_appium

## Overview

1. This repository is a Java-based mobile test automation project, not an application backend. The architecture is centered on running Appium-driven UI tests against a real Android device, with Selenium/Appium as the automation layer and Gradle as the build/test runner.

2. The production source tree is essentially empty: `src/main/java/org/example/Main.java` is present, but the real system lives under `src/test`. That means the important architecture is the test framework itself: setup, screen abstractions, test runners, suite orchestration, and fixture data.

3. The execution boundary is external:
   - a real mobile device is required,
   - Appium Server acts as the bridge to the device,
   - the tests interact with the device’s native UI,
   - Allure is used to render execution results after the run.
   The README also makes clear the tests depend on device state, especially the phonebook/contact book.

4. Test bootstrap is isolated in `src/test/java/setup/Setup.java`. This is the framework entry point for preparing the Appium/Selenium session and any shared driver/runtime configuration used by the tests.

5. UI interactions are grouped into screen objects under `src/test/java/screens`:
   - `CashboxScreen.java`
   - `RegistrationScreen.java`
   - `TallyScreen.java`
   These are the main interaction boundaries between tests and the mobile UI, likely encapsulating locators and actions for each business flow.

6. Test execution is organized by scenario-specific runners in `src/test/java/testRunners`:
   - `CashboxTestRunner`
   - `RegistrationTestRunner`
   - `TallyTestRunner`
   - `UnverifiedRegistrationTestRunner`
   Each runner likely binds one scenario family to one or more screen objects and test methods, keeping the flows separated by business area.

7. Suite orchestration is defined with TestNG XML files in `src/test/resources/suites`. `MasterSuite.xml` is the top-level coordinator, with dedicated suites for Cashbox, Registration, Tally, and Unverified Registration. The README notes that the default Gradle test command currently only runs the Tally tab unless `MasterSuite.xml` is edited, so suite selection is part of the execution architecture.

8. Test data is externalized in JSON fixtures under `src/test/resources`:
   - `users.json`
   - `customers.json`
   This suggests the tests separate scripted interactions from data inputs, so scenarios can be driven by named user/customer records rather than hardcoded values.

9. `src/test/java/utils/Utils.java` is the shared helper layer. In this kind of framework, utilities usually hold reusable test support such as data loading, waits, formatting, or device helpers, acting as a cross-cutting dependency for runners and screens.

10. The runtime/tooling stack materially shaping the architecture is:
   - Java 11+
   - Gradle for build and test execution
   - Selenium 4.x and Appium Java Client 8.x for automation
   - Appium Server 1.22.x
   - TestNG suite XML for orchestration
   - Allure for reporting
   These tools define how tests are composed, executed, and reported.

11. The repository has an important environmental dependency on device state: the tests require specific contacts already present on the phone. That means the system is not fully self-contained; it depends on preconditions outside the repo, which affects reproducibility and the reliability boundary of the automation.

12. In diagram terms, the main flow is:
   suite XML -> test runner -> setup/driver initialization -> screen object actions -> Appium Server -> mobile device,
   with JSON fixtures feeding the runners and Allure consuming execution output for reporting.

Main entry points: [`src/test/java/testRunners`](https://github.com/hhhameem/tk_automation_java_appium/tree/master/src/test/java/testRunners) (Test Runners), [`build.gradle`](https://github.com/hhhameem/tk_automation_java_appium/blob/master/build.gradle) (Gradle), [`src/test/java/setup/Setup.java`](https://github.com/hhhameem/tk_automation_java_appium/blob/master/src/test/java/setup/Setup.java) (Setup), [`src/test/java/screens`](https://github.com/hhhameem/tk_automation_java_appium/tree/master/src/test/java/screens) (Screens)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_framework["Test Framework"]
  node_setup["Setup<br/>bootstrap<br/>[Setup.java]"]
  node_test_runners["Test Runners<br/>scenario tests"]
  node_screen_objects["Screens<br/>page objects"]
  node_utils["Utils<br/>shared helpers<br/>[Utils.java]"]
  node_fixtures["Fixtures<br/>json data"]
end

subgraph group_orchestration["Orchestration"]
  node_gradle["Gradle<br/>build runner<br/>[build.gradle]"]
  node_master_suite["Master Suite<br/>testng suite<br/>[MasterSuite.xml]"]
  node_scenario_suites["Scenario Suites<br/>testng suites"]
end

subgraph group_runtime["Runtime Boundary"]
  node_allure(("Allure<br/>reporting"))
  node_appium_server["Appium Server<br/>automation bridge"]
  node_android_device[("Android Device<br/>mobile device")]
  node_phonebook_state["Contacts State<br/>device precondition"]
end

node_gradle -->|"runs"| node_master_suite
node_master_suite -->|"selects"| node_scenario_suites
node_scenario_suites -->|"executes"| node_test_runners
node_test_runners -->|"initializes"| node_setup
node_test_runners -->|"drives"| node_screen_objects
node_test_runners -->|"reads"| node_fixtures
node_test_runners -->|"uses"| node_utils
node_setup -->|"connects"| node_appium_server
node_screen_objects -->|"sends actions"| node_appium_server
node_appium_server -->|"controls"| node_android_device
node_android_device -.->|"requires"| node_phonebook_state
node_gradle -->|"reports"| node_allure
node_test_runners -->|"emits results"| node_allure

click node_gradle "https://github.com/hhhameem/tk_automation_java_appium/blob/master/build.gradle"
click node_master_suite "https://github.com/hhhameem/tk_automation_java_appium/blob/master/src/test/resources/suites/MasterSuite.xml"
click node_scenario_suites "https://github.com/hhhameem/tk_automation_java_appium/tree/master/src/test/resources/suites"
click node_setup "https://github.com/hhhameem/tk_automation_java_appium/blob/master/src/test/java/setup/Setup.java"
click node_test_runners "https://github.com/hhhameem/tk_automation_java_appium/tree/master/src/test/java/testRunners"
click node_screen_objects "https://github.com/hhhameem/tk_automation_java_appium/tree/master/src/test/java/screens"
click node_utils "https://github.com/hhhameem/tk_automation_java_appium/blob/master/src/test/java/utils/Utils.java"
click node_fixtures "https://github.com/hhhameem/tk_automation_java_appium/tree/master/src/test/resources"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_setup,node_test_runners,node_screen_objects,node_utils,node_fixtures toneBlue
class node_gradle,node_master_suite,node_scenario_suites toneAmber
class node_allure,node_appium_server,node_android_device,node_phonebook_state toneMint
```

## Components

### Test Framework

Java/TestNG automation framework living under src/test

- [Setup](https://github.com/hhhameem/tk_automation_java_appium/blob/master/src/test/java/setup/Setup.java): bootstrap · Creates and configures the shared Appium/Selenium session · `src/test/java/setup/Setup.java`
- [Test Runners](https://github.com/hhhameem/tk_automation_java_appium/tree/master/src/test/java/testRunners): scenario tests · Cashbox, Registration, Tally, and Unverified Registration runners · `src/test/java/testRunners`
- [Screens](https://github.com/hhhameem/tk_automation_java_appium/tree/master/src/test/java/screens): page objects · Cashbox, Registration, and Tally UI interaction objects · `src/test/java/screens`
- [Utils](https://github.com/hhhameem/tk_automation_java_appium/blob/master/src/test/java/utils/Utils.java): shared helpers · Cross-cutting test support functions · `src/test/java/utils/Utils.java`
- [Fixtures](https://github.com/hhhameem/tk_automation_java_appium/tree/master/src/test/resources): json data · User and customer test data · `src/test/resources`

### Orchestration

Gradle and TestNG suite coordination

- [Gradle](https://github.com/hhhameem/tk_automation_java_appium/blob/master/build.gradle): build runner · Builds and launches the test suites · `build.gradle`
- [Master Suite](https://github.com/hhhameem/tk_automation_java_appium/blob/master/src/test/resources/suites/MasterSuite.xml): testng suite · Top-level TestNG coordinator · `src/test/resources/suites/MasterSuite.xml`
- [Scenario Suites](https://github.com/hhhameem/tk_automation_java_appium/tree/master/src/test/resources/suites): testng suites · Cashbox, Registration, Tally, and Unverified Registration suite definitions · `src/test/resources/suites`

### Runtime Boundary

External automation and device dependencies

- **Allure**: reporting · Consumes test results for execution reporting
- **Appium Server**: automation bridge · Bridges Selenium/Appium commands to the device
- **Android Device**: mobile device · Real device under test with preexisting state
- **Contacts State**: device precondition · Required phonebook/contact data on the device

## Connections

- Gradle → Master Suite: runs · Gradle launches the top-level suite
- Master Suite → Scenario Suites: selects · Master suite delegates to dedicated scenario suites
- Scenario Suites → Test Runners: executes · Suite XML binds scenarios to runner classes
- Test Runners → Setup: initializes · Runners depend on shared bootstrap and driver setup
- Test Runners → Screens: drives · Scenario logic calls into screen abstractions
- Test Runners → Fixtures: reads · Runners load users and customers from JSON
- Test Runners → Utils: uses · Shared helper layer supports runner logic
- Setup → Appium Server: connects · Bootstrap creates the Appium/Selenium session through the server
- Screens → Appium Server: sends actions · Screen objects issue mobile UI commands
- Appium Server → Android Device: controls · Appium bridges automation to the real device
- Android Device → Contacts State: requires · Tests depend on specific existing contacts
- Gradle → Allure: reports · Execution output is rendered in Allure
- Test Runners → Allure: emits results · Test execution produces reportable results