# webdriverio/appium-boilerplate architecture

> Architecture diagram of the GitHub repository webdriverio/appium-boilerplate, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/webdriverio/appium-boilerplate
- Repository: https://github.com/webdriverio/appium-boilerplate

## Overview

##### Main Components of the System
- Tests & Test Scripts: The project’s tests live under the “tests” directory. They are divided into several sub-folders:
- Specs (actual test cases for features like login, swipe, forms, webviews, etc.)
- Features (potentially containing Gherkin-based tests for cucumber-based scenarios)
- Helpers (utility functions such as biometrics handling, webview helpers, etc.)
- PageObjects & ScreenObjects (abstraction layer to encapsulate locators and actions for UI screens)
- Steps (for writing high-level behavior-driven tests)
- Configuration Files: Found under the “config” directory. These include:
- Specific device configurations (separate files for Android app, iOS app, browser tests, etc.)
- Shared configuration (wdio.shared.conf.ts) which contains the common defaults that every environment builds upon.
- Local Appium configurations (wdio.shared.local.appium.conf.ts) which indicate using a global Appium installation.
- Cloud configuration files (sub-folders for SauceLabs, BrowserStack, LambdaTest, TestingBot) which allow execution on remote devices.
- Project Management & CI Infrastructure:
- GitHub workflows (inside .github/workflows) that include pipelines for running tests on Android and iOS.
- Scripts (like push_apps_to_sauce_storage.sh) which support deployment or cloud interactions.
- External Services / Vendors:
- Cloud vendors such as Sauce Labs, BrowserStack, TestingBot, and LambdaTest – each defined through their individual config files.
- Supporting Documentation and Development Tools:
- README – provides instructions on installation, running tests, and configuration.
- Docs folder – provides FAQ and Tips/Tricks guides.
- Git configuration files (.gitignore, .editorconfig, ESLint configuration, etc.)

##### Relationships and Interactions Between Components
- The Test Runner: WebdriverIO acts as the central hub which reads a shared configuration (plus platform-specific adjustments from config) then picks up test scripts (located within “tests”) and executes them using Appium commands.
- The Tests: Leverage page objects and helper modules to interact with mobile UI components. For instance, tests like “app.login.spec.ts” or “app.swipe.spec.ts” call methods defined in page/screen objects.
- Configuration Files: Serve as the blueprint for how tests should be run. They dictate which mobile device (emulator/simulator or real device) is targeted, specify vendor-specific settings, and activate services (sauce, browserstack, lambdatest, etc.) so that the tests can run in the designated environments.
- CI Workflows: GitHub workflows trigger these tests as part of the automated CI/CD pipeline indicating a flow from code commit → CI run → test execution.

##### Architectural/Design Patterns & Principles
- Separation of Concerns: Test scripts are kept separate from configurations and utility functions. The use of page objects ensures that selectors and element interactions remain abstracted from test logic.
- Modularity: The project is very modular with separate folders for different testing strategies (e.g., biometric login, swipe, deep link navigation) to allow for scalable and maintainable automation.
- Extensibility: The structure (with separate configurations for each platform and vendor) easily allows for the extension into parallel test execution or the integration with more platforms.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Developer/CI Pipeline"]:::ci
    B["WebdriverIO Test Runner"]:::runner
    F["CI Workflows"]:::ciWorkflows
    DPS["Deployment Script"]:::deploy
    DOC["Documentation & Guides"]:::docs

    %% Define Test Scripts Group
    subgraph "Test Scripts"
        TS["Test Specs"]:::tests
        TF["Test Features"]:::tests
        HP["Helpers"]:::tests
        PO["PageObjects"]:::tests
        SO["ScreenObjects"]:::tests
        ST["Steps"]:::tests
    end

    %% Define Configurations Group
    subgraph "Configurations"
        SC["Shared Config (wdio.shared.conf.ts)"]:::config
        LAC["Local Appium Config (wdio.shared.local.appium.conf.ts)"]:::config
        AA["Android App (Local) Config (wdio.android.app.conf.ts)"]:::config
        AACC["Android App (Cucumber) Config (wdio.android.app.cucumber.conf.ts)"]:::config
        AB["Android Browser Config (wdio.android.browser.conf.ts)"]:::config
        IA["iOS App Config (wdio.ios.app.conf.ts)"]:::config
        IB["iOS Browser Config (wdio.ios.browser.conf.ts)"]:::config
        SL["SauceLabs Config (wdio.shared.sauce.conf.ts)"]:::cloudConfig
        BS["BrowserStack Config (wdio.android.bs.app.conf.ts)"]:::cloudConfig
        LT["LambdaTest Config (wdio.shared.lambdatest.conf.ts)"]:::cloudConfig
        TB["TestingBot Config (wdio.android.tb.app.conf.ts)"]:::cloudConfig
    end

    %% Define Execution Environments Group
    subgraph "Execution Environments"
        LM["Local Mobile Emulators/Simulators"]:::env
        SLC["SauceLabs Cloud"]:::cloud
        BSC["BrowserStack Cloud"]:::cloud
        LTC["LambdaTest Cloud"]:::cloud
        TBC["TestingBot Cloud"]:::cloud
    end

    %% Relationships
    A --> B
    A --> F
    B --> TS
    B --> TF
    B --> HP
    B --> PO
    B --> SO
    B --> ST
    B --> SC

    %% Configuration Hierarchy
    SC --> LAC
    SC --> AA
    SC --> AACC
    SC --> AB
    SC --> IA
    SC --> IB
    SC --> SL
    SC --> BS
    SC --> LT
    SC --> TB

    %% Local Configurations to Local Environment
    LAC --> LM
    AA  --> LM
    AACC --> LM
    AB  --> LM
    IA  --> LM
    IB  --> LM

    %% Cloud Configurations to Cloud Environments
    SL  --> SLC
    BS  --> BSC
    LT  --> LTC
    TB  --> TBC

    %% CI and Deployment flows
    F --> B
    DPS --> SLC
    DPS --> BSC
    DPS --> LTC
    DPS --> TBC
    DOC --> A

    %% Click Events for Test Scripts
    click TS "https://github.com/webdriverio/appium-boilerplate/tree/main/tests/specs"
    click TF "https://github.com/webdriverio/appium-boilerplate/tree/main/tests/features"
    click HP "https://github.com/webdriverio/appium-boilerplate/tree/main/tests/helpers"
    click PO "https://github.com/webdriverio/appium-boilerplate/tree/main/tests/pageobjects"
    click SO "https://github.com/webdriverio/appium-boilerplate/tree/main/tests/screenobjects"
    click ST "https://github.com/webdriverio/appium-boilerplate/tree/main/tests/steps"

    %% Click Events for Configurations
    click SC "https://github.com/webdriverio/appium-boilerplate/blob/main/config/wdio.shared.conf.ts"
    click LAC "https://github.com/webdriverio/appium-boilerplate/blob/main/config/wdio.shared.local.appium.conf.ts"
    click AA "https://github.com/webdriverio/appium-boilerplate/blob/main/config/wdio.android.app.conf.ts"
    click AACC "https://github.com/webdriverio/appium-boilerplate/blob/main/config/wdio.android.app.cucumber.conf.ts"
    click AB "https://github.com/webdriverio/appium-boilerplate/blob/main/config/wdio.android.browser.conf.ts"
    click IA "https://github.com/webdriverio/appium-boilerplate/blob/main/config/wdio.ios.app.conf.ts"
    click IB "https://github.com/webdriverio/appium-boilerplate/blob/main/config/wdio.ios.browser.conf.ts"
    click SL "https://github.com/webdriverio/appium-boilerplate/blob/main/config/saucelabs/wdio.shared.sauce.conf.ts"
    click BS "https://github.com/webdriverio/appium-boilerplate/blob/main/config/browserstack/wdio.android.bs.app.conf.ts"
    click LT "https://github.com/webdriverio/appium-boilerplate/blob/main/config/lambdatest/wdio.shared.lambdatest.conf.ts"
    click TB "https://github.com/webdriverio/appium-boilerplate/blob/main/config/testingbot/wdio.android.tb.app.conf.ts"

    %% Click Events for CI, Deployment, Documentation
    click F "https://github.com/webdriverio/appium-boilerplate/tree/main/.github/workflows"
    click DPS "https://github.com/webdriverio/appium-boilerplate/blob/main/scripts/push_apps_to_sauce_storage.sh"
    click DOC "https://github.com/webdriverio/appium-boilerplate/blob/main/README.md"

    %% Styles
    classDef ci fill:#f6d186,stroke:#ba8b00,stroke-width:2px;
    classDef runner fill:#a2d0c1,stroke:#70a99a,stroke-width:2px;
    classDef tests fill:#ffefba,stroke:#e2b007,stroke-width:2px;
    classDef config fill:#c5d3f0,stroke:#6a8db6,stroke-width:2px;
    classDef cloudConfig fill:#d1c4e9,stroke:#7e57c2,stroke-width:2px;
    classDef env fill:#dcedc1,stroke:#8bc34a,stroke-width:2px;
    classDef cloud fill:#ffe0b2,stroke:#ff9800,stroke-width:2px;
    classDef ciWorkflows fill:#f8bbd0,stroke:#d81b60,stroke-width:2px;
    classDef deploy fill:#f0f4c3,stroke:#afb42b,stroke-width:2px;
    classDef docs fill:#d7ccc8,stroke:#8d6e63,stroke-width:2px;
```
