# mherrmann/helium architecture

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

- Interactive diagram: https://gitdiagram.com/mherrmann/helium
- Repository: https://github.com/mherrmann/helium

## Overview

Helium is a Python browser-automation library: a script calls its high-level API to start or control a browser, identify page elements by visible labels or selectors, and perform interactions or waits. The API delegates to an implementation layer that drives Selenium; element matching and frame-aware wrappers support that work. The README documents nested-frame interaction, popup/window handling, implicit waits, and explicit waits. Some of those behaviors are documented but not independently mapped to sampled implementation files.

Main entry points: [`helium/_impl/__init__.py`](https://github.com/mherrmann/helium/blob/master/helium/_impl/__init__.py) (Automation engine), [`helium/__init__.py`](https://github.com/mherrmann/helium/blob/master/helium/__init__.py) (Helium API), [`helium/_impl/selenium_wrappers.py`](https://github.com/mherrmann/helium/blob/master/helium/_impl/selenium_wrappers.py) (Selenium wrappers), [`helium/_impl/match_type.py`](https://github.com/mherrmann/helium/blob/master/helium/_impl/match_type.py) (Text match rules)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API"]
  node_api["Helium API<br/>[__init__.py]"]
end

subgraph group_runtime["Automation Runtime"]
  node_engine["Automation engine<br/>[__init__.py]"]
  node_selenium_wrappers["Selenium wrappers"]
  node_frame_navigation["Frame navigation"]
end

subgraph group_matching["Element Matching"]
  node_element_search["Element search<br/>[__init__.py]"]
  node_match_rules["Text match rules<br/>[match_type.py]"]
end

subgraph group_support["Runtime Support"]
  node_xpath_helpers["XPath helpers<br/>[xpath.py]"]
  node_geometry["Element geometry<br/>[geom.py]"]
  node_dictionary["Dictionary helper<br/>[dictionary.py]"]
  node_html_helpers["HTML helpers<br/>[html.py]"]
  node_inspection["Argument inspection<br/>[inspect_.py]"]
  node_language_helpers["Language helpers<br/>[lang.py]"]
  node_system_info["System information<br/>[system.py]"]
end

node_script(("Automation script"))
node_browser(("Chrome or Firefox"))
node_selenium["Selenium WebDriver"]

node_script -->|"calls"| node_api
node_api -->|"delegates"| node_engine
node_engine -->|"searches"| node_element_search
node_element_search -->|"matches text"| node_match_rules
node_match_rules -->|"builds predicates"| node_xpath_helpers
node_engine -->|"uses wrappers"| node_selenium_wrappers
node_selenium_wrappers -->|"iterates frames"| node_frame_navigation
node_selenium_wrappers -->|"uses geometry"| node_geometry
node_engine -->|"uses helper"| node_dictionary
node_engine -->|"checks platform"| node_system_info
node_api -->|"uses helpers"| node_html_helpers
node_api -->|"uses inspection"| node_inspection
node_inspection -->|"checks binding"| node_language_helpers
node_engine -->|"issues commands"| node_selenium
node_selenium -->|"controls"| node_browser

click node_api "https://github.com/mherrmann/helium/blob/master/helium/__init__.py"
click node_engine "https://github.com/mherrmann/helium/blob/master/helium/_impl/__init__.py"
click node_element_search "https://github.com/mherrmann/helium/blob/master/helium/_impl/__init__.py"
click node_match_rules "https://github.com/mherrmann/helium/blob/master/helium/_impl/match_type.py"
click node_xpath_helpers "https://github.com/mherrmann/helium/blob/master/helium/_impl/util/xpath.py"
click node_selenium_wrappers "https://github.com/mherrmann/helium/blob/master/helium/_impl/selenium_wrappers.py"
click node_frame_navigation "https://github.com/mherrmann/helium/blob/master/helium/_impl/selenium_wrappers.py"
click node_geometry "https://github.com/mherrmann/helium/blob/master/helium/_impl/util/geom.py"
click node_dictionary "https://github.com/mherrmann/helium/blob/master/helium/_impl/util/dictionary.py"
click node_html_helpers "https://github.com/mherrmann/helium/blob/master/helium/_impl/util/html.py"
click node_inspection "https://github.com/mherrmann/helium/blob/master/helium/_impl/util/inspect_.py"
click node_language_helpers "https://github.com/mherrmann/helium/blob/master/helium/_impl/util/lang.py"
click node_system_info "https://github.com/mherrmann/helium/blob/master/helium/_impl/util/system.py"

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_api toneBlue
class node_engine,node_selenium_wrappers,node_frame_navigation toneAmber
class node_element_search,node_match_rules toneMint
class node_xpath_helpers,node_geometry,node_dictionary,node_html_helpers,node_inspection,node_language_helpers,node_system_info toneRose
class node_script,node_browser,node_selenium toneIndigo
```

## Components

### Public API

- [Helium API](https://github.com/mherrmann/helium/blob/master/helium/__init__.py): `helium/__init__.py`

### Automation Runtime

- [Automation engine](https://github.com/mherrmann/helium/blob/master/helium/_impl/__init__.py): `helium/_impl/__init__.py`
- [Selenium wrappers](https://github.com/mherrmann/helium/blob/master/helium/_impl/selenium_wrappers.py): `helium/_impl/selenium_wrappers.py`
- [Frame navigation](https://github.com/mherrmann/helium/blob/master/helium/_impl/selenium_wrappers.py): `helium/_impl/selenium_wrappers.py`

### Element Matching

- [Element search](https://github.com/mherrmann/helium/blob/master/helium/_impl/__init__.py): `helium/_impl/__init__.py`
- [Text match rules](https://github.com/mherrmann/helium/blob/master/helium/_impl/match_type.py): `helium/_impl/match_type.py`

### Runtime Support

- [XPath helpers](https://github.com/mherrmann/helium/blob/master/helium/_impl/util/xpath.py): `helium/_impl/util/xpath.py`
- [Element geometry](https://github.com/mherrmann/helium/blob/master/helium/_impl/util/geom.py): `helium/_impl/util/geom.py`
- [Dictionary helper](https://github.com/mherrmann/helium/blob/master/helium/_impl/util/dictionary.py): `helium/_impl/util/dictionary.py`
- [HTML helpers](https://github.com/mherrmann/helium/blob/master/helium/_impl/util/html.py): `helium/_impl/util/html.py`
- [Argument inspection](https://github.com/mherrmann/helium/blob/master/helium/_impl/util/inspect_.py): `helium/_impl/util/inspect_.py`
- [Language helpers](https://github.com/mherrmann/helium/blob/master/helium/_impl/util/lang.py): `helium/_impl/util/lang.py`
- [System information](https://github.com/mherrmann/helium/blob/master/helium/_impl/util/system.py): `helium/_impl/util/system.py`

### Other components

- **Automation script**
- **Chrome or Firefox**
- **Selenium WebDriver**

## Connections

- Automation script → Helium API: calls (evidence: `README.md`)
- Helium API → Automation engine: delegates (evidence: `helium/__init__.py`)
- Automation engine → Element search: searches (evidence: `helium/_impl/__init__.py`)
- Element search → Text match rules: matches text (evidence: `helium/_impl/__init__.py`)
- Text match rules → XPath helpers: builds predicates (evidence: `helium/_impl/match_type.py`)
- Automation engine → Selenium wrappers: uses wrappers (evidence: `helium/_impl/__init__.py`)
- Selenium wrappers → Frame navigation: iterates frames (evidence: `helium/_impl/selenium_wrappers.py`)
- Selenium wrappers → Element geometry: uses geometry (evidence: `helium/_impl/selenium_wrappers.py`)
- Automation engine → Dictionary helper: uses helper (evidence: `helium/_impl/__init__.py`)
- Automation engine → System information: checks platform (evidence: `helium/_impl/__init__.py`)
- Helium API → HTML helpers: uses helpers (evidence: `helium/__init__.py`)
- Helium API → Argument inspection: uses inspection (evidence: `helium/__init__.py`)
- Argument inspection → Language helpers: checks binding (evidence: `helium/_impl/util/inspect_.py`)
- Automation engine → Selenium WebDriver: issues commands (evidence: `README.md`)
- Selenium WebDriver → Chrome or Firefox: controls (evidence: `README.md`)
