jc-selenium-helper 0.1.0__tar.gz

jc_selenium_helper-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexander Jacob
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jc_selenium_helper-0.1.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: jc-selenium-helper
+Version: 0.1.0
+Summary: Selenium WebDriver helper utilities for writing browser tests
+Author-email: Alexander Jacob <alexander.jacob@jacob-consulting.de>
+License: MIT
+Project-URL: Homepage, https://github.com/jacob-consulting/jc-selenium-helper
+Project-URL: Documentation, https://jc-selenium-helper.readthedocs.io
+Classifier: Intended Audience :: Developers
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Framework :: Pytest
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: selenium>=4.38.0
+Provides-Extra: pytest
+Requires-Dist: pytest>=8; extra == "pytest"
+Requires-Dist: pytest-selenium>=4.1.0; extra == "pytest"
+Provides-Extra: config
+Requires-Dist: dynaconf>=3.2; extra == "config"
+Provides-Extra: axe
+Requires-Dist: axe-selenium-python>=2.1.6; extra == "axe"
+Provides-Extra: all
+Requires-Dist: jc-selenium-helper[axe,config,pytest]; extra == "all"
+Provides-Extra: dev
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: bump-my-version; extra == "dev"
+Requires-Dist: mkdocs>=1.6.1; extra == "dev"
+Requires-Dist: mkdocs-awesome-pages-plugin>=2.10.1; extra == "dev"
+Provides-Extra: test
+Requires-Dist: jc-selenium-helper[axe,config,pytest]; extra == "test"
+Requires-Dist: nox; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: pytest-xdist; extra == "test"
+Dynamic: license-file
+
+# jc-selenium-helper
+
+Selenium WebDriver helper utilities for writing browser tests.
+
+`Browser` wraps a Selenium `WebDriver` with concise, XPath-by-default finders,
+waits, actions, assertions, and frame handling. Optional extras add a ready-made
+pytest fixture, a Dynaconf settings loader, and axe-core accessibility checks.
+
+## Install
+
+```bash
+pip install jc-selenium-helper            # core (selenium only)
+pip install "jc-selenium-helper[pytest]"  # + pytest fixtures
+pip install "jc-selenium-helper[config]"  # + Dynaconf settings loader
+pip install "jc-selenium-helper[axe]"     # + accessibility checks
+pip install "jc-selenium-helper[all]"     # everything
+```
+
+## Quickstart
+
+```python
+from selenium import webdriver
+from jc_selenium_helper import Browser
+
+driver = webdriver.Chrome()
+browser = Browser(driver, default_timeout=30)
+
+browser.open("https://example.com")
+browser.wait_and_click("//a[@id='more']")  # XPath by default
+```
+
+## Links
+
+- Full documentation: https://jc-selenium-helper.readthedocs.io
+- PyPI: https://pypi.org/project/jc-selenium-helper/
+- Source: https://github.com/jacob-consulting/jc-selenium-helper
+
+## License
+
+MIT — see [LICENSE](LICENSE).

jc_selenium_helper-0.1.0/README.md

@@ -0,0 +1,40 @@
+# jc-selenium-helper
+
+Selenium WebDriver helper utilities for writing browser tests.
+
+`Browser` wraps a Selenium `WebDriver` with concise, XPath-by-default finders,
+waits, actions, assertions, and frame handling. Optional extras add a ready-made
+pytest fixture, a Dynaconf settings loader, and axe-core accessibility checks.
+
+## Install
+
+```bash
+pip install jc-selenium-helper            # core (selenium only)
+pip install "jc-selenium-helper[pytest]"  # + pytest fixtures
+pip install "jc-selenium-helper[config]"  # + Dynaconf settings loader
+pip install "jc-selenium-helper[axe]"     # + accessibility checks
+pip install "jc-selenium-helper[all]"     # everything
+```
+
+## Quickstart
+
+```python
+from selenium import webdriver
+from jc_selenium_helper import Browser
+
+driver = webdriver.Chrome()
+browser = Browser(driver, default_timeout=30)
+
+browser.open("https://example.com")
+browser.wait_and_click("//a[@id='more']")  # XPath by default
+```
+
+## Links
+
+- Full documentation: https://jc-selenium-helper.readthedocs.io
+- PyPI: https://pypi.org/project/jc-selenium-helper/
+- Source: https://github.com/jacob-consulting/jc-selenium-helper
+
+## License
+
+MIT — see [LICENSE](LICENSE).

jc_selenium_helper-0.1.0/pyproject.toml

@@ -0,0 +1,84 @@
+[project]
+name = "jc-selenium-helper"
+version = "0.1.0"
+description = "Selenium WebDriver helper utilities for writing browser tests"
+authors = [{ name = "Alexander Jacob", email = "alexander.jacob@jacob-consulting.de" }]
+license = { text = "MIT" }
+readme = "README.md"
+requires-python = ">=3.12"
+classifiers = [
+    "Intended Audience :: Developers",
+    "Development Status :: 4 - Beta",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Framework :: Pytest",
+    "Topic :: Software Development :: Testing",
+]
+dependencies = [
+    "selenium>=4.38.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/jacob-consulting/jc-selenium-helper"
+Documentation = "https://jc-selenium-helper.readthedocs.io"
+
+[project.optional-dependencies]
+pytest = ["pytest>=8", "pytest-selenium>=4.1.0"]
+config = ["dynaconf>=3.2"]
+axe = ["axe-selenium-python>=2.1.6"]
+all = ["jc-selenium-helper[pytest,config,axe]"]
+dev = [
+    "ruff",
+    "pre-commit",
+    "bump-my-version",
+    "mkdocs>=1.6.1",
+    "mkdocs-awesome-pages-plugin>=2.10.1",
+]
+test = [
+    "jc-selenium-helper[pytest,config,axe]",
+    "nox",
+    "pytest-cov",
+    "pytest-xdist",
+]
+
+[project.entry-points.pytest11]
+jc_selenium_helper = "jc_selenium_helper.plugin"
+
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+jc_selenium_helper = ["py.typed"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-p no:cacheprovider"
+
+[tool.bumpversion]
+current_version = "0.1.0"
+allow_dirty = false
+commit = true
+tag = true
+
+[[tool.bumpversion.files]]
+filename = "pyproject.toml"
+search = 'version = "{current_version}"'
+replace = 'version = "{new_version}"'
+
+[[tool.bumpversion.files]]
+filename = "src/jc_selenium_helper/__init__.py"
+search = '__version__ = "{current_version}"'
+replace = '__version__ = "{new_version}"'

jc_selenium_helper-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

jc_selenium_helper-0.1.0/src/jc_selenium_helper/__init__.py

@@ -0,0 +1,7 @@
+"""Selenium WebDriver helper utilities for writing browser tests."""
+
+from jc_selenium_helper.browser import Browser
+
+__version__ = "0.1.0"
+
+__all__ = ["Browser", "__version__"]

jc_selenium_helper-0.1.0/src/jc_selenium_helper/axe.py

@@ -0,0 +1,21 @@
+"""Optional accessibility checks via axe-core (requires the ``axe`` extra)."""
+
+from __future__ import annotations
+
+from axe_selenium_python import Axe
+
+
+def run_axe(driver) -> dict:
+    """Inject axe-core into the current page and return the raw results dict."""
+    axe = Axe(driver)
+    axe.inject()
+    return axe.run()
+
+
+def assert_no_violations(driver) -> None:
+    """Run axe-core and raise ``AssertionError`` if any violations are found."""
+    results = run_axe(driver)
+    violations = results.get("violations", [])
+    if violations:
+        ids = ", ".join(v["id"] for v in violations)
+        raise AssertionError(f"{len(violations)} accessibility violation(s): {ids}")

jc_selenium_helper-0.1.0/src/jc_selenium_helper/browser.py

@@ -0,0 +1,190 @@
+# src/jc_selenium_helper/browser.py
+"""A thin, ergonomic wrapper around a Selenium WebDriver."""
+
+from __future__ import annotations
+
+import time
+
+from selenium.common.exceptions import NoSuchElementException, TimeoutException
+from selenium.webdriver.common.action_chains import ActionChains
+from selenium.webdriver.common.by import By
+from selenium.webdriver.common.keys import Keys
+from selenium.webdriver.remote.webelement import WebElement
+from selenium.webdriver.support import expected_conditions as EC
+from selenium.webdriver.support.select import Select
+from selenium.webdriver.support.wait import WebDriverWait
+
+
+class Browser:
+    """Wraps a Selenium ``WebDriver`` with convenience helpers.
+
+    Locators default to XPath; pass ``by=By.CSS_SELECTOR`` (or any Selenium
+    ``By`` value) to use a different strategy.
+    """
+
+    def __init__(self, driver, default_timeout: float = 120, poll_pause: float = 1) -> None:
+        self.driver = driver
+        self.default_timeout = default_timeout
+        self.poll_pause = poll_pause
+
+    # -- navigation --
+    def open(self, url: str) -> None:
+        self.driver.get(url)
+
+    # -- finders --
+    def find(self, locator: str, by: str = By.XPATH) -> WebElement:
+        return self.driver.find_element(by, locator)
+
+    def find_all(self, locator: str, by: str = By.XPATH) -> list[WebElement]:
+        return self.driver.find_elements(by, locator)
+
+    def exists(self, locator: str, by: str = By.XPATH) -> bool:
+        try:
+            self.driver.find_element(by, locator)
+        except NoSuchElementException:
+            return False
+        return True
+
+    # -- waits --
+    def _timeout(self, timeout: float | None) -> float:
+        return self.default_timeout if timeout is None else timeout
+
+    def wait_present(self, locator: str, by: str = By.XPATH, timeout: float | None = None) -> WebElement:
+        WebDriverWait(self.driver, self._timeout(timeout)).until(EC.presence_of_element_located((by, locator)))
+        return self.driver.find_element(by, locator)
+
+    def wait_clickable(self, locator: str, by: str = By.XPATH, timeout: float | None = None) -> WebElement:
+        WebDriverWait(self.driver, self._timeout(timeout)).until(EC.element_to_be_clickable((by, locator)))
+        return self.driver.find_element(by, locator)
+
+    def wait_not_present(self, locator: str, by: str = By.XPATH, timeout: float | None = None) -> bool:
+        seconds = self._timeout(timeout)
+        try:
+            WebDriverWait(self.driver, seconds).until(EC.invisibility_of_element_located((by, locator)))
+        except TimeoutException as exc:
+            raise TimeoutException(f"Element '{locator}' still present after {seconds}s") from exc
+        return True
+
+    def wait_document_ready(self, timeout: float | None = None) -> None:
+        seconds = self._timeout(timeout)
+        elapsed = 0.0
+        while self.driver.execute_script("return document.readyState") != "complete":
+            time.sleep(self.poll_pause)
+            elapsed += self.poll_pause
+            if elapsed > seconds:
+                raise TimeoutError("document.readyState never reached 'complete'")
+
+    def wait_page_loaded(
+        self,
+        check_path: str,
+        by: str = By.XPATH,
+        retries: int = 5,
+        interval: float = 10,
+    ) -> None:
+        """Wait for ``check_path`` to appear, refreshing between attempts.
+
+        Generic replacement for the app-specific ``seite_geladen`` loop.
+        """
+        time.sleep(self.poll_pause)
+        attempt = 0
+        while not self.driver.find_elements(by, check_path):
+            self.driver.refresh()
+            time.sleep(interval)
+            attempt += 1
+            if attempt > retries:
+                raise TimeoutError(f"Page not loaded (missing {check_path})")
+        self.wait_document_ready()
+
+    # -- actions --
+    def wait_and_click(self, locator: str, by: str = By.XPATH, timeout: float | None = None) -> None:
+        self.wait_clickable(locator, by, timeout).click()
+
+    def double_click(self, locator: str, by: str = By.XPATH, pause: float = 0) -> None:
+        element = self.find(locator, by)
+        ActionChains(self.driver).move_to_element(element).double_click().perform()
+        if pause:
+            time.sleep(pause)
+
+    def hover(self, locator: str, by: str = By.XPATH) -> None:
+        element = self.find(locator, by)
+        ActionChains(self.driver).move_to_element(element).perform()
+
+    def hover_with_offset(self, locator: str, x_offset: int, y_offset: int, by: str = By.XPATH) -> None:
+        element = self.find(locator, by)
+        actions = ActionChains(self.driver)
+        actions.move_to_element(element).perform()
+        actions.move_by_offset(x_offset, y_offset).perform()
+
+    def move_to(self, locator: str, by: str = By.XPATH) -> None:
+        element = self.find(locator, by)
+        ActionChains(self.driver).move_to_element(element).perform()
+        time.sleep(self.poll_pause)
+
+    def wait_move_click(self, locator: str, by: str = By.XPATH, timeout: float | None = None) -> None:
+        element = self.wait_clickable(locator, by, timeout)
+        ActionChains(self.driver).move_to_element(element).perform()
+        time.sleep(self.poll_pause)
+        element.click()
+
+    def type_text(self, locator: str, text: str, by: str = By.XPATH) -> None:
+        self.find(locator, by).send_keys(text)
+
+    def upload_file(self, css_selector: str, path: str) -> None:
+        self.driver.find_element(By.CSS_SELECTOR, css_selector).send_keys(path)
+
+    def click_in_new_tab(
+        self,
+        locator: str,
+        check_path: str,
+        by: str = By.XPATH,
+        check_by: str = By.XPATH,
+    ) -> None:
+        """Ctrl-click a link, verify the new tab, close it, return to the first tab."""
+        element = self.find(locator, by)
+        ActionChains(self.driver).key_down(Keys.CONTROL).click(element).key_up(Keys.CONTROL).perform()
+        self.driver.switch_to.window(self.driver.window_handles[-1])
+        self.wait_present(check_path, check_by)
+        self.driver.close()
+        self.driver.switch_to.window(self.driver.window_handles[0])
+
+    # -- assertions --
+    def assert_checkbox_checked(self, locator: str, by: str = By.XPATH, timeout: float | None = None) -> None:
+        if not self.wait_present(locator, by, timeout).is_selected():
+            raise AssertionError(f"Checkbox is not checked: {locator}")
+
+    def assert_checkbox_unchecked(self, locator: str, by: str = By.XPATH, timeout: float | None = None) -> None:
+        if self.wait_present(locator, by, timeout).is_selected():
+            raise AssertionError(f"Checkbox is checked: {locator}")
+
+    def assert_selected_option(self, locator: str, expected_text: str, by: str = By.XPATH) -> None:
+        select = Select(self.find(locator, by))
+        actual = select.first_selected_option.text
+        if actual != expected_text:
+            raise AssertionError(f"Selected option '{actual}' != expected '{expected_text}'")
+
+    def assert_present(self, locator: str, by: str = By.XPATH) -> None:
+        if not self.exists(locator, by):
+            raise AssertionError(f"Element not present: {locator}")
+
+    # -- frames --
+    def fill_in_frame(
+        self,
+        frame_path: str,
+        inner_path: str,
+        text: str,
+        by: str = By.XPATH,
+        submit: bool = True,
+    ) -> None:
+        """Switch into ``frame_path``, type ``text`` into ``inner_path``, switch back.
+
+        Generic replacement for the app-specific ``switch_and_fill_frame`` (which
+        hardcoded the TinyMCE inner path).
+        """
+        frame = self.find(frame_path, by)
+        self.driver.switch_to.frame(frame)
+        try:
+            self.type_text(inner_path, text)
+            if submit:
+                self.type_text(inner_path, Keys.RETURN)
+        finally:
+            self.driver.switch_to.default_content()

jc_selenium_helper-0.1.0/src/jc_selenium_helper/colors.py

@@ -0,0 +1,14 @@
+"""Color conversion helpers (replaces the colormap/easydev dependency)."""
+
+from __future__ import annotations
+
+
+def rgb_to_hex(rgb_string: str) -> str:
+    """Convert a CSS ``rgb(...)`` or ``rgba(...)`` string to ``#rrggbb``.
+
+    The alpha channel of ``rgba`` is ignored.
+    """
+    inner = rgb_string[rgb_string.index("(") + 1 : rgb_string.index(")")]
+    parts = [int(float(component.strip())) for component in inner.split(",")[:3]]
+    r, g, b = parts
+    return f"#{r:02x}{g:02x}{b:02x}"

jc_selenium_helper-0.1.0/src/jc_selenium_helper/config.py

@@ -0,0 +1,28 @@
+"""Optional Dynaconf settings loader (requires the ``config`` extra)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from dynaconf import Dynaconf
+from dynaconf.base import Settings
+
+
+def get_settings(location: str | Path, *files: str) -> Settings:
+    """Build a Dynaconf ``Settings`` from files resolved next to ``location``.
+
+    ``location`` is typically ``__file__`` of the caller; each name in ``files``
+    is resolved against ``Path(location).parent`` and must exist.
+    """
+    parent = Path(location).parent
+    settings_files = []
+    for name in files:
+        settings_file = (parent / name).resolve()
+        assert settings_file.exists(), f"settings file not found: {settings_file}"
+        settings_files.append(settings_file)
+    return Dynaconf(
+        environments=True,
+        envvar_prefix="SELENIUM",
+        env_switcher="SELENIUM_ENVIRONMENT",
+        settings_files=settings_files,
+    )

jc_selenium_helper-0.1.0/src/jc_selenium_helper/legacy.py

@@ -0,0 +1,158 @@
+# src/jc_selenium_helper/legacy.py
+"""Backwards-compatible adapter exposing the original German/ad-hoc API.
+
+Existing suites can migrate by replacing::
+
+    from libs.browser import Browser
+
+with::
+
+    from jc_selenium_helper.legacy import Browser
+
+Every legacy method emits a ``DeprecationWarning`` and delegates to the clean
+:class:`jc_selenium_helper.browser.Browser` API. Two methods
+(``seite_geladen`` and ``switch_and_fill_frame``) keep their original
+app-specific behavior verbatim so existing tests are unaffected.
+"""
+
+from __future__ import annotations
+
+import time
+import warnings
+
+from selenium.webdriver.common.by import By
+from selenium.webdriver.common.keys import Keys
+
+from jc_selenium_helper.browser import Browser as _Browser
+from jc_selenium_helper.colors import rgb_to_hex
+
+
+def _deprecated(old: str, new: str) -> None:
+    warnings.warn(
+        f"{old}() is deprecated; use {new}() instead.",
+        DeprecationWarning,
+        stacklevel=3,
+    )
+
+
+class LegacyBrowser(_Browser):
+    """Deprecated German-named API preserved for existing test suites."""
+
+    def xpath(self, xpath):
+        _deprecated("xpath", "find")
+        return self.find(xpath)
+
+    def xpaths(self, xpath):
+        _deprecated("xpaths", "find_all")
+        return self.find_all(xpath)
+
+    def css(self, selector):
+        _deprecated("css", "find")
+        return self.find(selector, by=By.CSS_SELECTOR)
+
+    def get_elements(self, path):
+        _deprecated("get_elements", "find_all")
+        return self.find_all(path)
+
+    def check_exists_by_xpath(self, path):
+        _deprecated("check_exists_by_xpath", "exists")
+        return self.exists(path)
+
+    def wait_element_present(self, path, time_to_wait=None):
+        _deprecated("wait_element_present", "wait_present")
+        return self.wait_present(path, timeout=time_to_wait)
+
+    def wait_element_not_present(self, path, time_to_wait=None):
+        _deprecated("wait_element_not_present", "wait_not_present")
+        return self.wait_not_present(path, timeout=time_to_wait)
+
+    def wait_element_clickable(self, path, time_to_wait=None):
+        _deprecated("wait_element_clickable", "wait_clickable")
+        return self.wait_clickable(path, timeout=time_to_wait)
+
+    def inhalt_geladen(self):
+        _deprecated("inhalt_geladen", "wait_document_ready")
+        return self.wait_document_ready()
+
+    def doppelclick_element(self, pause, hover):
+        _deprecated("doppelclick_element", "double_click")
+        return self.double_click(hover, pause=pause)
+
+    def hover_element(self, hover):
+        _deprecated("hover_element", "hover")
+        return self.hover(hover)
+
+    def hover_element_with_offset(self, hover, x_offset, y_offset):
+        _deprecated("hover_element_with_offset", "hover_with_offset")
+        return self.hover_with_offset(hover, x_offset, y_offset)
+
+    def move_to_element(self, path):
+        _deprecated("move_to_element", "move_to")
+        return self.move_to(path)
+
+    def wait_move_click_element(self, path, time_to_wait=None):
+        _deprecated("wait_move_click_element", "wait_move_click")
+        return self.wait_move_click(path, timeout=time_to_wait)
+
+    def click_new_tab(self, path, check_path):
+        _deprecated("click_new_tab", "click_in_new_tab")
+        return self.click_in_new_tab(path, check_path)
+
+    def eingabe(self, path, text):
+        _deprecated("eingabe", "type_text")
+        return self.type_text(path, text)
+
+    def eingabe_upload_css(self, path, text):
+        _deprecated("eingabe_upload_css", "upload_file")
+        return self.upload_file(path, text)
+
+    def assert_checkbox_is_checked(self, path, time_to_wait=None):
+        _deprecated("assert_checkbox_is_checked", "assert_checkbox_checked")
+        return self.assert_checkbox_checked(path, timeout=time_to_wait)
+
+    def assert_checkbox_is_not_checked(self, path, time_to_wait=None):
+        _deprecated("assert_checkbox_is_not_checked", "assert_checkbox_unchecked")
+        return self.assert_checkbox_unchecked(path, timeout=time_to_wait)
+
+    def check_select(self, path, exp_text):
+        _deprecated("check_select", "assert_selected_option")
+        return self.assert_selected_option(path, exp_text)
+
+    def ele_test(self, path):
+        _deprecated("ele_test", "assert_present")
+        return self.assert_present(path)
+
+    @staticmethod
+    def switch_rgb(color_rgb):
+        _deprecated("switch_rgb", "colors.rgb_to_hex")
+        return rgb_to_hex(color_rgb)
+
+    # -- verbatim app-specific behavior (unchanged for compatibility) --
+    def seite_geladen(self, check_path):
+        _deprecated("seite_geladen", "wait_page_loaded")
+        time_counter = 0
+        time.sleep(1)
+        while True:
+            element = self.driver.find_elements(By.XPATH, check_path)
+            if element:
+                break
+            self.driver.refresh()
+            time.sleep(10)
+            time_counter += 1
+            if time_counter > 5:
+                raise ValueError("Seite nicht geladen")
+        self.inhalt_geladen()
+
+    def switch_and_fill_frame(self, combined, path, text):
+        _deprecated("switch_and_fill_frame", "fill_in_frame")
+        time.sleep(combined.settings.k_pause)
+        switch_frame = self.driver.find_element(By.XPATH, path)
+        self.driver.switch_to.frame(switch_frame)
+        tmp_path = "//*[@id='tinymce']/p"
+        self.type_text(tmp_path, text)
+        self.type_text(tmp_path, Keys.RETURN)
+        self.driver.switch_to.default_content()
+
+
+# Drop-in module-level alias: ``from jc_selenium_helper.legacy import Browser``
+Browser = LegacyBrowser

jc_selenium_helper-0.1.0/src/jc_selenium_helper/plugin.py

@@ -0,0 +1,43 @@
+"""pytest plugin exposing ready-made fixtures.
+
+Enabled automatically when the package is installed with the ``pytest`` extra
+(registered via the ``pytest11`` entry point). Fixtures are namespaced with a
+``jc_`` prefix to avoid clashing with a project's own ``browser`` fixture.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from jc_selenium_helper.browser import Browser
+
+
+@pytest.fixture
+def jc_chrome_options():
+    """Sensible default Chrome options; override in a project conftest to customize."""
+    from selenium.webdriver.chrome.options import Options
+
+    options = Options()
+    options.add_argument("--headless=new")
+    options.add_argument("--disable-gpu")
+    options.add_argument("--ignore-certificate-errors")
+    options.add_argument("--no-sandbox")
+    options.add_argument("--disable-dev-shm-usage")
+    return options
+
+
+@pytest.fixture
+def chrome_options(jc_chrome_options):
+    """Feed jc_chrome_options into pytest-selenium's driver.
+
+    pytest-selenium builds its Chrome driver from a fixture named
+    ``chrome_options``; delegating here makes the package's defaults apply while
+    letting users customize by overriding ``jc_chrome_options``.
+    """
+    return jc_chrome_options
+
+
+@pytest.fixture
+def jc_browser(selenium) -> Browser:
+    """Wrap the pytest-selenium ``selenium`` driver in a :class:`Browser`."""
+    return Browser(selenium)

jc_selenium_helper-0.1.0/src/jc_selenium_helper.egg-info/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: jc-selenium-helper
+Version: 0.1.0
+Summary: Selenium WebDriver helper utilities for writing browser tests
+Author-email: Alexander Jacob <alexander.jacob@jacob-consulting.de>
+License: MIT
+Project-URL: Homepage, https://github.com/jacob-consulting/jc-selenium-helper
+Project-URL: Documentation, https://jc-selenium-helper.readthedocs.io
+Classifier: Intended Audience :: Developers
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Framework :: Pytest
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: selenium>=4.38.0
+Provides-Extra: pytest
+Requires-Dist: pytest>=8; extra == "pytest"
+Requires-Dist: pytest-selenium>=4.1.0; extra == "pytest"
+Provides-Extra: config
+Requires-Dist: dynaconf>=3.2; extra == "config"
+Provides-Extra: axe
+Requires-Dist: axe-selenium-python>=2.1.6; extra == "axe"
+Provides-Extra: all
+Requires-Dist: jc-selenium-helper[axe,config,pytest]; extra == "all"
+Provides-Extra: dev
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: bump-my-version; extra == "dev"
+Requires-Dist: mkdocs>=1.6.1; extra == "dev"
+Requires-Dist: mkdocs-awesome-pages-plugin>=2.10.1; extra == "dev"
+Provides-Extra: test
+Requires-Dist: jc-selenium-helper[axe,config,pytest]; extra == "test"
+Requires-Dist: nox; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: pytest-xdist; extra == "test"
+Dynamic: license-file
+
+# jc-selenium-helper
+
+Selenium WebDriver helper utilities for writing browser tests.
+
+`Browser` wraps a Selenium `WebDriver` with concise, XPath-by-default finders,
+waits, actions, assertions, and frame handling. Optional extras add a ready-made
+pytest fixture, a Dynaconf settings loader, and axe-core accessibility checks.
+
+## Install
+
+```bash
+pip install jc-selenium-helper            # core (selenium only)
+pip install "jc-selenium-helper[pytest]"  # + pytest fixtures
+pip install "jc-selenium-helper[config]"  # + Dynaconf settings loader
+pip install "jc-selenium-helper[axe]"     # + accessibility checks
+pip install "jc-selenium-helper[all]"     # everything
+```
+
+## Quickstart
+
+```python
+from selenium import webdriver
+from jc_selenium_helper import Browser
+
+driver = webdriver.Chrome()
+browser = Browser(driver, default_timeout=30)
+
+browser.open("https://example.com")
+browser.wait_and_click("//a[@id='more']")  # XPath by default
+```
+
+## Links
+
+- Full documentation: https://jc-selenium-helper.readthedocs.io
+- PyPI: https://pypi.org/project/jc-selenium-helper/
+- Source: https://github.com/jacob-consulting/jc-selenium-helper
+
+## License
+
+MIT — see [LICENSE](LICENSE).

jc_selenium_helper-0.1.0/src/jc_selenium_helper.egg-info/SOURCES.txt

@@ -0,0 +1,28 @@
+LICENSE
+README.md
+pyproject.toml
+src/jc_selenium_helper/__init__.py
+src/jc_selenium_helper/axe.py
+src/jc_selenium_helper/browser.py
+src/jc_selenium_helper/colors.py
+src/jc_selenium_helper/config.py
+src/jc_selenium_helper/legacy.py
+src/jc_selenium_helper/plugin.py
+src/jc_selenium_helper/py.typed
+src/jc_selenium_helper.egg-info/PKG-INFO
+src/jc_selenium_helper.egg-info/SOURCES.txt
+src/jc_selenium_helper.egg-info/dependency_links.txt
+src/jc_selenium_helper.egg-info/entry_points.txt
+src/jc_selenium_helper.egg-info/requires.txt
+src/jc_selenium_helper.egg-info/top_level.txt
+tests/test_axe.py
+tests/test_browser_actions.py
+tests/test_browser_assertions.py
+tests/test_browser_finders.py
+tests/test_browser_frame.py
+tests/test_browser_waits.py
+tests/test_colors.py
+tests/test_config.py
+tests/test_legacy.py
+tests/test_package.py
+tests/test_plugin.py

jc_selenium_helper-0.1.0/src/jc_selenium_helper.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

jc_selenium_helper-0.1.0/src/jc_selenium_helper.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[pytest11]
+jc_selenium_helper = jc_selenium_helper.plugin

jc_selenium_helper-0.1.0/src/jc_selenium_helper.egg-info/requires.txt

@@ -0,0 +1,27 @@
+selenium>=4.38.0
+
+[all]
+jc-selenium-helper[axe,config,pytest]
+
+[axe]
+axe-selenium-python>=2.1.6
+
+[config]
+dynaconf>=3.2
+
+[dev]
+ruff
+pre-commit
+bump-my-version
+mkdocs>=1.6.1
+mkdocs-awesome-pages-plugin>=2.10.1
+
+[pytest]
+pytest>=8
+pytest-selenium>=4.1.0
+
+[test]
+jc-selenium-helper[axe,config,pytest]
+nox
+pytest-cov
+pytest-xdist

jc_selenium_helper-0.1.0/src/jc_selenium_helper.egg-info/top_level.txt

@@ -0,0 +1 @@
+jc_selenium_helper

jc_selenium_helper-0.1.0/tests/test_axe.py

@@ -0,0 +1,19 @@
+# tests/test_axe.py
+import pytest
+
+pytest.importorskip("axe_selenium_python")
+
+from jc_selenium_helper.axe import assert_no_violations, run_axe  # noqa: E402
+
+
+def test_run_axe_returns_results(driver, fixture_url):
+    driver.get(fixture_url("basic.html"))
+    results = run_axe(driver)
+    assert "violations" in results
+
+
+def test_assert_no_violations_raises_on_violation(driver, fixture_url):
+    # a11y_bad.html has an <img> with no alt attribute -> at least one violation expected
+    driver.get(fixture_url("a11y_bad.html"))
+    with pytest.raises(AssertionError):
+        assert_no_violations(driver)

jc_selenium_helper-0.1.0/tests/test_browser_actions.py

@@ -0,0 +1,34 @@
+# tests/test_browser_actions.py
+def test_type_text(browser, fixture_url):
+    browser.open(fixture_url("basic.html"))
+    browser.type_text("//input[@id='text-input']", "hello")
+    assert browser.find("//input[@id='text-input']").get_attribute("value") == "hello"
+
+
+def test_wait_and_click(browser, fixture_url):
+    browser.open(fixture_url("basic.html"))
+    browser.wait_and_click("//button[@id='clickable']")
+    assert browser.find("//button[@id='clickable']").text == "clicked"
+
+
+def test_double_click(browser, fixture_url):
+    browser.open(fixture_url("basic.html"))
+    browser.double_click("//button[@id='dbl']")
+    assert browser.find("//button[@id='dbl']").text == "double"
+
+
+def test_hover_does_not_raise(browser, fixture_url):
+    browser.open(fixture_url("basic.html"))
+    browser.hover("//button[@id='clickable']")
+
+
+def test_move_to_does_not_raise(browser, fixture_url):
+    browser.open(fixture_url("basic.html"))
+    browser.move_to("//button[@id='clickable']")
+
+
+def test_click_in_new_tab_returns_to_main(browser, fixture_url):
+    browser.open(fixture_url("basic.html"))
+    browser.click_in_new_tab("//a[@id='newtab']", "//p[@id='target']")
+    assert len(browser.driver.window_handles) == 1
+    assert browser.find("//h1[@id='title']").text == "Hello"

jc_selenium_helper-0.1.0/tests/test_browser_assertions.py

@@ -0,0 +1,35 @@
+# tests/test_browser_assertions.py
+import pytest
+
+
+def test_assert_checkbox_checked_passes(browser, fixture_url):
+    browser.open(fixture_url("basic.html"))
+    browser.assert_checkbox_checked("//input[@id='checked-box']")
+
+
+def test_assert_checkbox_checked_fails(browser, fixture_url):
+    browser.open(fixture_url("basic.html"))
+    with pytest.raises(AssertionError):
+        browser.assert_checkbox_checked("//input[@id='unchecked-box']")
+
+
+def test_assert_checkbox_unchecked_passes(browser, fixture_url):
+    browser.open(fixture_url("basic.html"))
+    browser.assert_checkbox_unchecked("//input[@id='unchecked-box']")
+
+
+def test_assert_selected_option_passes(browser, fixture_url):
+    browser.open(fixture_url("basic.html"))
+    browser.assert_selected_option("//select[@id='picker']", "two")
+
+
+def test_assert_selected_option_fails(browser, fixture_url):
+    browser.open(fixture_url("basic.html"))
+    with pytest.raises(AssertionError):
+        browser.assert_selected_option("//select[@id='picker']", "one")
+
+
+def test_assert_present_fails_when_missing(browser, fixture_url):
+    browser.open(fixture_url("basic.html"))
+    with pytest.raises(AssertionError):
+        browser.assert_present("//div[@id='nope']")

jc_selenium_helper-0.1.0/tests/test_browser_finders.py

@@ -0,0 +1,24 @@
+# tests/test_browser_finders.py
+from selenium.webdriver.common.by import By
+
+
+def test_find_returns_element(browser, fixture_url):
+    browser.open(fixture_url("basic.html"))
+    assert browser.find("//h1[@id='title']").text == "Hello"
+
+
+def test_find_with_css(browser, fixture_url):
+    browser.open(fixture_url("basic.html"))
+    assert browser.find("#title", by=By.CSS_SELECTOR).text == "Hello"
+
+
+def test_find_all_returns_list(browser, fixture_url):
+    browser.open(fixture_url("basic.html"))
+    items = browser.find_all("//li[@class='item']")
+    assert [e.text for e in items] == ["a", "b", "c"]
+
+
+def test_exists_true_and_false(browser, fixture_url):
+    browser.open(fixture_url("basic.html"))
+    assert browser.exists("//h1[@id='title']") is True
+    assert browser.exists("//h1[@id='missing']") is False

jc_selenium_helper-0.1.0/tests/test_browser_frame.py

@@ -0,0 +1,12 @@
+# tests/test_browser_frame.py
+def test_fill_in_frame(browser, fixture_url):
+    browser.open(fixture_url("frame.html"))
+    browser.fill_in_frame(
+        "//iframe[@id='editor']",
+        "//input[@id='inner-input']",
+        "typed",
+        submit=False,
+    )
+    browser.driver.switch_to.frame(browser.find("//iframe[@id='editor']"))
+    assert browser.find("//input[@id='inner-input']").get_attribute("value") == "typed"
+    browser.driver.switch_to.default_content()

jc_selenium_helper-0.1.0/tests/test_browser_waits.py

@@ -0,0 +1,29 @@
+# tests/test_browser_waits.py
+import pytest
+from selenium.common.exceptions import TimeoutException
+
+
+def test_wait_present_returns_element(browser, fixture_url):
+    browser.open(fixture_url("basic.html"))
+    assert browser.wait_present("//span[@id='late']").text == "here"
+
+
+def test_wait_present_times_out(browser, fixture_url):
+    browser.open(fixture_url("basic.html"))
+    with pytest.raises(TimeoutException):
+        browser.wait_present("//span[@id='never']", timeout=1)
+
+
+def test_wait_clickable_returns_element(browser, fixture_url):
+    browser.open(fixture_url("basic.html"))
+    assert browser.wait_clickable("//button[@id='btn']").tag_name == "button"
+
+
+def test_wait_document_ready(browser, fixture_url):
+    browser.open(fixture_url("basic.html"))
+    browser.wait_document_ready()  # should not raise
+
+
+def test_wait_page_loaded_on_present_element(browser, fixture_url):
+    browser.open(fixture_url("basic.html"))
+    browser.wait_page_loaded("//h1[@id='title']", retries=1, interval=1)

jc_selenium_helper-0.1.0/tests/test_colors.py

@@ -0,0 +1,16 @@
+import pytest
+
+from jc_selenium_helper.colors import rgb_to_hex
+
+
+@pytest.mark.parametrize(
+    "value, expected",
+    [
+        ("rgb(255, 0, 0)", "#ff0000"),
+        ("rgb(0, 128, 0)", "#008000"),
+        ("rgba(16, 32, 48, 0.5)", "#102030"),
+        ("rgb(0,0,0)", "#000000"),
+    ],
+)
+def test_rgb_to_hex(value, expected):
+    assert rgb_to_hex(value) == expected

jc_selenium_helper-0.1.0/tests/test_config.py

@@ -0,0 +1,20 @@
+import pytest
+
+pytest.importorskip("dynaconf")
+
+from jc_selenium_helper.config import get_settings  # noqa: E402
+
+
+def test_get_settings_reads_relative_file(tmp_path):
+    (tmp_path / "settings.yaml").write_text("default:\n  greeting: hi\n")
+    anchor = tmp_path / "conftest.py"  # any file whose parent holds the settings
+    anchor.write_text("")
+    settings = get_settings(anchor, "settings.yaml")
+    assert settings.greeting == "hi"
+
+
+def test_get_settings_missing_file_raises(tmp_path):
+    anchor = tmp_path / "conftest.py"
+    anchor.write_text("")
+    with pytest.raises(AssertionError):
+        get_settings(anchor, "nope.yaml")

jc_selenium_helper-0.1.0/tests/test_legacy.py

@@ -0,0 +1,24 @@
+# tests/test_legacy.py
+import pytest
+
+from jc_selenium_helper.legacy import Browser as LegacyBrowser
+
+
+def test_legacy_eingabe_delegates_and_warns(driver, fixture_url):
+    legacy = LegacyBrowser(driver, default_timeout=10, poll_pause=0.2)
+    legacy.open(fixture_url("basic.html"))
+    with pytest.warns(DeprecationWarning):
+        legacy.eingabe("//input[@id='text-input']", "legacy")
+    assert legacy.find("//input[@id='text-input']").get_attribute("value") == "legacy"
+
+
+def test_legacy_check_exists_by_xpath(driver, fixture_url):
+    legacy = LegacyBrowser(driver, default_timeout=10, poll_pause=0.2)
+    legacy.open(fixture_url("basic.html"))
+    with pytest.warns(DeprecationWarning):
+        assert legacy.check_exists_by_xpath("//h1[@id='title']") is True
+
+
+def test_legacy_switch_rgb_static():
+    with pytest.warns(DeprecationWarning):
+        assert LegacyBrowser.switch_rgb("rgb(255, 0, 0)") == "#ff0000"

jc_selenium_helper-0.1.0/tests/test_package.py

@@ -0,0 +1,7 @@
+# tests/test_package.py
+import jc_selenium_helper
+
+
+def test_version_is_exposed():
+    assert isinstance(jc_selenium_helper.__version__, str)
+    assert jc_selenium_helper.__version__ == "0.1.0"

jc_selenium_helper-0.1.0/tests/test_plugin.py

@@ -0,0 +1,48 @@
+pytest_plugins = ["pytester"]
+
+
+def test_jc_chrome_options_fixture_available(pytester):
+    pytester.makepyfile(
+        """
+        def test_options(jc_chrome_options):
+            args = jc_chrome_options.arguments
+            assert "--headless=new" in args
+        """
+    )
+    result = pytester.runpytest()
+    result.assert_outcomes(passed=1)
+
+
+def test_chrome_options_feeds_pytest_selenium(pytester):
+    pytester.makepyfile(
+        """
+        def test_same_object(chrome_options, jc_chrome_options):
+            assert chrome_options is jc_chrome_options
+        """
+    )
+    result = pytester.runpytest()
+    result.assert_outcomes(passed=1)
+
+
+def test_chrome_options_reflects_jc_chrome_options_override(pytester):
+    pytester.makeconftest(
+        """
+        import pytest
+        from selenium.webdriver.chrome.options import Options
+
+
+        @pytest.fixture
+        def jc_chrome_options():
+            options = Options()
+            options.add_argument("--window-size=1920,1080")
+            return options
+        """
+    )
+    pytester.makepyfile(
+        """
+        def test_override_flows_through(chrome_options):
+            assert "--window-size=1920,1080" in chrome_options.arguments
+        """
+    )
+    result = pytester.runpytest()
+    result.assert_outcomes(passed=1)