# seldomqa/auto-wing architecture

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

- Interactive diagram: https://gitdiagram.com/seldomqa/auto-wing
- Repository: https://github.com/seldomqa/auto-wing

## Overview

##### Project Type and Purpose
- **Type**: An open‑source Python library that integrates LLM (Large Language Model) calls into existing UI automation frameworks (Playwright, Selenium, Appium).
- **Purpose**: Provide `ai_action`, `ai_query`, and `ai_assert` fixtures that let test authors drive UI tests via AI prompts, with caching for repeat prompts and support for multiple LLM providers (OpenAI, DeepSeek, Qwen, Doubao).

##### File Structure
- **Top‑level**: `autowing/` package, `docs/`, `examples/`, config files (`pyproject.toml`, `.gitignore`).
- **Sub‑packages**:
- `autowing/appium/`, `autowing/playwright/`, `autowing/selenium/`: framework–specific fixture entry points.
- `autowing/core/`: the heart of the library, containing:
– `ai_context.py`: orchestrates fixture calls.
– `ai_fixture_base.py`: defines the common fixture interface.
– `cache/cache_manager.py`: caching layer for prompt results.
– `llm/`: LLM abstraction with `factory.py`, `base.py`, plus provider‐specific clients in `client/`.
- `autowing/utils/transition.py`: transforms LLM responses into UI actions or assertions.
- **Examples**: show integration with `pytest`/`unittest` + `.env` for configuration.

##### Extract Additional Insights from README
- **Supported frameworks**: Playwright, Selenium, Appium.
- **Supported LLMs**: OpenAI, DeepSeek, Qwen, Doubao.
- **Integration**: “No‑pain” with pytest/unittest; environment variables or `.env` via python‑dotenv.
- **Cache**: first‐call caching for efficiency.

##### Main Components & Interactions
a. **Test Suite Layer**
- Your `pytest`/`unittest` tests import and invoke the `ai` fixture.
- Example tests call `ai.ai_action()`, `ai.ai_query()`, `ai.ai_assert()`.
b. **Framework Fixture Layer**
- Three parallel components: **Playwright Fixture**, **Selenium Fixture**, **Appium Fixture**.
- Each wraps objects/contexts from their respective automation library.
c. **Core Engine Layer**
- **AI Fixture Base**: shared fixture API.
- **AI Context**: orchestrator that receives calls from the fixture, applies prompting tips, calls the cache or LLM client.
- **Cache Manager**: checks/stores prompt → result mappings.
- **LLM Factory**: reads `AUTOWING_MODEL_PROVIDER`, instantiates a concrete client.
- **LLM Client Plugins**: OpenAIClient, DeepSeekClient, QwenClient, DouBaoClient.
d. **External Services**
- HTTP endpoints of each LLM provider.
e. **Utilities**
- `transition.py`: post‑process LLM outputs into actionable test commands or assertions.

##### Architectural Patterns & Design Principles
- **Plugin/Factory Pattern** for LLM clients—decouples provider logic.
- **Layered Architecture** separating:
- UI framework integration
- Core orchestration (caching, context)
- External API clients
- **Single‑Responsibility** & **Open‑Closed**: new frameworks/LLMs can plug in without changing core.

##### Step‑by‑Step Construction
- AI Fixture Base
- AI Context

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Test Suite Layer"
        TS["Test Suite (examples/)"]:::test
    end

    subgraph "Fixture Layer"
        PW["Playwright Fixture"]:::fixture
        SD["Selenium Fixture"]:::fixture
        AP["Appium Fixture"]:::fixture
        AH["Appium Actions Helper"]:::core
    end

    TS -->|"ai = create_fixture()\nai.ai_*()"| PW
    TS -->|"ai = create_fixture()\nai.ai_*()"| SD
    TS -->|"ai = create_fixture()\nai.ai_*()"| AP

    PW -->|"calls ai_context"| AC
    SD -->|"calls ai_context"| AC
    AP -->|"calls ai_context"| AC

    AP --> AH
    AH -->|"perform UI action"| UL3

    subgraph "Core Engine Layer"
        AFB["AI Fixture Base"]:::core
        AC["AI Context"]:::core
        CM["Cache DB"]:::db
        LF["LLM Factory"]:::core
        LB["LLM Base Abstraction"]:::core
        subgraph "LLM Clients"
            OAI["OpenAIClient"]:::client
            DS["DeepSeekClient"]:::client
            QW["QwenClient"]:::client
            DBP["DouBaoClient"]:::client
        end
    end

    AFB --> AC
    AC -->|"check cache"| CM
    AC -->|"factory.create_client()"| LF
    LF --> LB
    LF --> OAI
    LF --> DS
    LF --> QW
    LF --> DBP

    subgraph "External LLM Services"
        CLOUD1["OpenAI Service"]:::external
        CLOUD2["DeepSeek Service"]:::external
        CLOUD3["Qwen Service"]:::external
        CLOUD4["DouBao Service"]:::external
    end

    OAI -->|"invoke API"| CLOUD1
    DS -->|"invoke API"| CLOUD2
    QW -->|"invoke API"| CLOUD3
    DBP -->|"invoke API"| CLOUD4

    subgraph "Utilities"
        UT["Response Transformer"]:::util
    end

    UT --> PW
    UT --> SD
    UT --> AP

    subgraph "UI Libraries"
        UL1["Playwright"]:::ui
        UL2["Selenium"]:::ui
        UL3["Appium"]:::ui
    end

    PW -->|"perform UI action"| UL1
    SD -->|"perform UI action"| UL2
    AP -->|"delegate to Actions Helper"| AH

    UL1 -->|"asserts/feedback"| TS
    UL2 -->|"asserts/feedback"| TS
    UL3 -->|"asserts/feedback"| TS

    click TS "https://github.com/seldomqa/auto-wing/tree/main/examples/"
    click PW "https://github.com/seldomqa/auto-wing/blob/main/autowing/playwright/fixture.py"
    click SD "https://github.com/seldomqa/auto-wing/blob/main/autowing/selenium/fixture.py"
    click AP "https://github.com/seldomqa/auto-wing/blob/main/autowing/appium/fixture.py"
    click AH "https://github.com/seldomqa/auto-wing/blob/main/autowing/appium/actions.py"
    click AFB "https://github.com/seldomqa/auto-wing/blob/main/autowing/core/ai_fixture_base.py"
    click AC "https://github.com/seldomqa/auto-wing/blob/main/autowing/core/ai_context.py"
    click CM "https://github.com/seldomqa/auto-wing/blob/main/autowing/core/cache/cache_manager.py"
    click LF "https://github.com/seldomqa/auto-wing/blob/main/autowing/core/llm/factory.py"
    click LB "https://github.com/seldomqa/auto-wing/blob/main/autowing/core/llm/base.py"
    click OAI "https://github.com/seldomqa/auto-wing/blob/main/autowing/core/llm/client/openai.py"
    click DS "https://github.com/seldomqa/auto-wing/blob/main/autowing/core/llm/client/deepseek.py"
    click QW "https://github.com/seldomqa/auto-wing/blob/main/autowing/core/llm/client/qwen.py"
    click DBP "https://github.com/seldomqa/auto-wing/blob/main/autowing/core/llm/client/doubao.py"
    click UT "https://github.com/seldomqa/auto-wing/blob/main/autowing/utils/transition.py"

    classDef test fill:#D3BCE3,stroke:#856D8A
    classDef fixture fill:#B2E7B6,stroke:#3C8D0D
    classDef core fill:#A0C4FF,stroke:#1E3A8A
    classDef client fill:#FFECB3,stroke:#A67C00
    classDef external fill:#FFE4E1,stroke:#C71585
    classDef util fill:#FFD7A0,stroke:#B66600
    classDef ui fill:#E2E8F0,stroke:#1A202C
    classDef db fill:#C0C0C0,stroke:#606060
```
