promethee-selenium 1.0.0__tar.gz

promethee_selenium-1.0.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: promethee-selenium
+Version: 1.0.0
+Summary: Prométhée: A POM-based automated UI test framework
+Author: Yann Dipita
+Description-Content-Type: text/markdown
+Requires-Dist: selenium-ui-test-tool
+Requires-Dist: pytest
+Requires-Dist: selenium
+Dynamic: author
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: requires-dist
+Dynamic: summary
+
+# Prométhée UI Framework
+
+*[English version below | Version française plus bas]*
+
+---
+
+# 🇬🇧 English Description
+
+A robust, Page Object Model (POM) based framework for automated UI testing using Selenium and Pytest.
+
+This framework is designed to help you write maintainable and scalable end-to-end tests with minimal boilerplate.
+
+## Features
+
+-   **Page Object Model (POM)**: Structured architecture separating page logic from test logic.
+-   **Scaffolding CLI**: Quickly initialize a new project with best-practice directory structure using `promethee init`.
+-   **Built-in Utilities**: Ready-to-use helpers for Waiting, Clicking, Filling inputs (via `selenium-ui-test-tool`).
+-   **Environment Management**: Easy handling of test data and credentials.
+-   **Documentation**: Includes HTML documentation to help you get started.
+
+## Installation
+
+Install the package via pip:
+
+```bash
+pip install promethee-selenium
+```
+
+## Getting Started
+
+1.  **Create a new folder** for your test project:
+    ```bash
+    mkdir my_test_project
+    cd my_test_project
+    ```
+
+2.  **Initialize the project structure**:
+    ```bash
+    promethee init
+    ```
+    To view the documentation in your browser:
+    ```bash
+    promethee docs
+    ```
+    This will create:
+    -   `scenarios/`: For your Page Objects.
+    -   `tests/`: For your test scripts.
+    -   `data/`: For credentials and test data.
+    -   `utils/`: For local utilities.
+    -   `conftest.py`: Pytest configuration.
+
+3.  **Run the sample test**:
+    ```bash
+    pytest tests/
+    ```
+
+## Writing a Page Object
+
+Inherit from the `Base` class provided by the framework:
+
+```python
+from promethee.base import Base
+from selenium.webdriver.common.by import By
+# Uses selenium-ui-test-tool functions internally
+
+class LoginPage(Base):
+    def fill_form(self, username, password):
+        self.fill_input(By.ID, "username", username)
+        self.fill_input(By.ID, "password", password)
+        self.click_element(By.ID, "submit-btn")
+```
+
+For more details, check the generated `docs/index.html` after installation.
+
+---
+
+# 🇫🇷 Description Française
+
+Un framework robuste basé sur le modèle Page Object Model (POM) pour l'automatisation de tests UI avec Selenium et Pytest.
+
+Ce framework est conçu pour vous aider à écrire des tests de bout en bout maintenables et évolutifs avec un minimum de code répétitif.
+
+## Fonctionnalités
+
+-   **Page Object Model (POM)** : Architecture structurée séparant la logique de la page de la logique de test.
+-   **CLI d'initialisation** : Initialisez rapidement un nouveau projet avec une structure recommandée via `promethee init`.
+-   **Utilitaires intégrés** : Fonctions prêtes à l'emploi pour attendre, cliquer, remplir des champs (via `selenium-ui-test-tool`).
+-   **Gestion d'environnement** : Gestion facile des données de test et des identifiants.
+-   **Documentation** : Inclut une documentation HTML pour vous aider à démarrer.
+
+## Installation
+
+Installez le paquet via pip :
+
+```bash
+pip install Promethee-Selenium
+```
+
+## Démarrage Rapide
+
+1.  **Créez un nouveau dossier** pour votre projet de test :
+    ```bash
+    mkdir mon_projet_test
+    cd mon_projet_test
+    ```
+
+2.  **Initialisez la structure du projet** :
+    ```bash
+    promethee init
+    ```
+    Pour afficher la documentation dans votre navigateur :
+    ```bash
+    promethee docs
+    ```
+    Cela va créer :
+    -   `scenarios/` : Pour vos Page Objects.
+    -   `tests/` : Pour vos scripts de test.
+    -   `data/` : Pour les identifiants et données de test.
+    -   `utils/` : Pour les utilitaires locaux.
+    -   `conftest.py` : Configuration Pytest.
+
+3.  **Lancez le test d'exemple** :
+    ```bash
+    pytest tests/
+    ```
+
+## Écrire un Page Object
+
+Héritez de la classe `Base` fournie par le framework :
+
+```python
+from promethee.base import Base
+from selenium.webdriver.common.by import By
+# Utilise les fonctions selenium-ui-test-tool en interne
+
+class LoginPage(Base):
+    def fill_form(self, username, password):
+        self.fill_input(By.ID, "username", username)
+        self.fill_input(By.ID, "password", password)
+        self.click_element(By.ID, "submit-btn")
+```
+
+Pour plus de détails, consultez le fichier `docs/index.html` généré après l'installation.

promethee_selenium-1.0.0/README.md

@@ -0,0 +1,143 @@
+# Prométhée UI Framework
+
+*[English version below | Version française plus bas]*
+
+---
+
+# 🇬🇧 English Description
+
+A robust, Page Object Model (POM) based framework for automated UI testing using Selenium and Pytest.
+
+This framework is designed to help you write maintainable and scalable end-to-end tests with minimal boilerplate.
+
+## Features
+
+-   **Page Object Model (POM)**: Structured architecture separating page logic from test logic.
+-   **Scaffolding CLI**: Quickly initialize a new project with best-practice directory structure using `promethee init`.
+-   **Built-in Utilities**: Ready-to-use helpers for Waiting, Clicking, Filling inputs (via `selenium-ui-test-tool`).
+-   **Environment Management**: Easy handling of test data and credentials.
+-   **Documentation**: Includes HTML documentation to help you get started.
+
+## Installation
+
+Install the package via pip:
+
+```bash
+pip install promethee-selenium
+```
+
+## Getting Started
+
+1.  **Create a new folder** for your test project:
+    ```bash
+    mkdir my_test_project
+    cd my_test_project
+    ```
+
+2.  **Initialize the project structure**:
+    ```bash
+    promethee init
+    ```
+    To view the documentation in your browser:
+    ```bash
+    promethee docs
+    ```
+    This will create:
+    -   `scenarios/`: For your Page Objects.
+    -   `tests/`: For your test scripts.
+    -   `data/`: For credentials and test data.
+    -   `utils/`: For local utilities.
+    -   `conftest.py`: Pytest configuration.
+
+3.  **Run the sample test**:
+    ```bash
+    pytest tests/
+    ```
+
+## Writing a Page Object
+
+Inherit from the `Base` class provided by the framework:
+
+```python
+from promethee.base import Base
+from selenium.webdriver.common.by import By
+# Uses selenium-ui-test-tool functions internally
+
+class LoginPage(Base):
+    def fill_form(self, username, password):
+        self.fill_input(By.ID, "username", username)
+        self.fill_input(By.ID, "password", password)
+        self.click_element(By.ID, "submit-btn")
+```
+
+For more details, check the generated `docs/index.html` after installation.
+
+---
+
+# 🇫🇷 Description Française
+
+Un framework robuste basé sur le modèle Page Object Model (POM) pour l'automatisation de tests UI avec Selenium et Pytest.
+
+Ce framework est conçu pour vous aider à écrire des tests de bout en bout maintenables et évolutifs avec un minimum de code répétitif.
+
+## Fonctionnalités
+
+-   **Page Object Model (POM)** : Architecture structurée séparant la logique de la page de la logique de test.
+-   **CLI d'initialisation** : Initialisez rapidement un nouveau projet avec une structure recommandée via `promethee init`.
+-   **Utilitaires intégrés** : Fonctions prêtes à l'emploi pour attendre, cliquer, remplir des champs (via `selenium-ui-test-tool`).
+-   **Gestion d'environnement** : Gestion facile des données de test et des identifiants.
+-   **Documentation** : Inclut une documentation HTML pour vous aider à démarrer.
+
+## Installation
+
+Installez le paquet via pip :
+
+```bash
+pip install Promethee-Selenium
+```
+
+## Démarrage Rapide
+
+1.  **Créez un nouveau dossier** pour votre projet de test :
+    ```bash
+    mkdir mon_projet_test
+    cd mon_projet_test
+    ```
+
+2.  **Initialisez la structure du projet** :
+    ```bash
+    promethee init
+    ```
+    Pour afficher la documentation dans votre navigateur :
+    ```bash
+    promethee docs
+    ```
+    Cela va créer :
+    -   `scenarios/` : Pour vos Page Objects.
+    -   `tests/` : Pour vos scripts de test.
+    -   `data/` : Pour les identifiants et données de test.
+    -   `utils/` : Pour les utilitaires locaux.
+    -   `conftest.py` : Configuration Pytest.
+
+3.  **Lancez le test d'exemple** :
+    ```bash
+    pytest tests/
+    ```
+
+## Écrire un Page Object
+
+Héritez de la classe `Base` fournie par le framework :
+
+```python
+from promethee.base import Base
+from selenium.webdriver.common.by import By
+# Utilise les fonctions selenium-ui-test-tool en interne
+
+class LoginPage(Base):
+    def fill_form(self, username, password):
+        self.fill_input(By.ID, "username", username)
+        self.fill_input(By.ID, "password", password)
+        self.click_element(By.ID, "submit-btn")
+```
+
+Pour plus de détails, consultez le fichier `docs/index.html` généré après l'installation.

promethee_selenium-1.0.0/promethee/base.py

@@ -0,0 +1,27 @@
+from selenium.webdriver.remote.webdriver import WebDriver
+
+class Base:
+
+    def __init__(self, driver: WebDriver, url: str = None):
+        self.driver = driver
+        # Import local pour éviter l'import circulaire (car ConsentModal hérite de Base)
+        # On évite la récursion infinie : ConsentModal ne doit pas s'initialiser lui-même
+        if self.__class__.__name__ != 'ConsentModal':
+            try:
+                # from .utils.consent import ConsentModal
+                # self.consent_modal = ConsentModal(driver)
+                pass
+            except ImportError:
+                pass
+        
+        if url:
+             self.open_url(url)
+
+    def open_url(self, url: str):
+        self.driver.get(url)
+
+    def get_title(self) -> str:
+        return self.driver.title
+
+    def refresh(self):
+        self.driver.refresh()

promethee_selenium-1.0.0/promethee/cli.py

@@ -0,0 +1,165 @@
+import argparse
+import os
+import shutil
+import webbrowser
+import sys
+
+def open_docs():
+    """
+    Opens the framework documentation in the default web browser.
+    """
+    try:
+        # Try to locate the docs using pkg_resources (older but reliable) or file path relative to this file
+        # Since we are in promethee/cli.py, docs are in promethee/docs/index.html
+        
+        # Method 1: Relative path from __file__
+        current_dir = os.path.dirname(os.path.abspath(__file__))
+        docs_path = os.path.join(current_dir, "docs", "index.html")
+        
+        if os.path.exists(docs_path):
+            print(f"Opening documentation: {docs_path}")
+            webbrowser.open(f"file://{docs_path}")
+        else:
+            print("Documentation file not found locally.")
+            print("You can view it online on PyPI or GitHub.")
+            
+    except Exception as e:
+        print(f"Failed to open documentation: {e}")
+
+def init_project():
+    """
+    Initializes a new test project with the recommended structure.
+    """
+    base_dir = os.getcwd()
+    print(f"Initializing new test project in: {base_dir}")
+
+    # Define directories to create
+    dirs = ["scenarios", "tests", "data", "utils"]
+    for d in dirs:
+        path = os.path.join(base_dir, d)
+        if not os.path.exists(path):
+            os.makedirs(path)
+            print(f"Created directory: {d}")
+    
+    # Create __init__.py in scenarios and utils to make them packages
+    for pkg in ["scenarios", "utils"]:
+        init_path = os.path.join(base_dir, pkg, "__init__.py")
+        if not os.path.exists(init_path):
+            with open(init_path, "w") as f:
+                pass
+
+    # Create utils/scenario_provider.py
+    scenario_provider_path = os.path.join(base_dir, "utils", "scenario_provider.py")
+    if not os.path.exists(scenario_provider_path):
+        with open(scenario_provider_path, "w") as f:
+            f.write("""import csv
+import os
+
+class ScenarioProvider:
+    # Look for credentials in the data directory
+    CREDENTIALS_FILE = os.path.join(os.getcwd(), 'data', 'credentials.csv')
+
+    @staticmethod
+    def get_data_for_scenario(scenario_name):
+        if not os.path.exists(ScenarioProvider.CREDENTIALS_FILE):
+             raise FileNotFoundError(f"Credentials file not found at {ScenarioProvider.CREDENTIALS_FILE}")
+
+        with open(ScenarioProvider.CREDENTIALS_FILE, mode='r', encoding='utf-8') as csvfile:
+            reader = csv.DictReader(csvfile)
+            for row in reader:
+                if row['scenario'] == scenario_name:
+                    user_env_key = f"TEST_USER_{scenario_name.upper().replace(' ', '_')}"
+                    pass_env_key = f"TEST_PASS_{scenario_name.upper().replace(' ', '_')}"
+                    os.environ[user_env_key] = row['email']
+                    os.environ[pass_env_key] = row['password']
+                    
+                    return {
+                        "username_env": user_env_key,
+                        "password_env": pass_env_key
+                    }
+        
+        raise ValueError(f"Scenario '{scenario_name}' not found in credentials.csv")
+
+    @staticmethod
+    def prompt_for_scenario(default_scenario="login"):
+        # In automated environments (CI), you might want to switch this to read an env var
+        print(f"Using default scenario: {default_scenario}")
+        return default_scenario, ScenarioProvider.get_data_for_scenario(default_scenario)
+""")
+        print("Created utils/scenario_provider.py")
+
+    # Create credentials.csv
+    creds_path = os.path.join(base_dir, "data", "credentials.csv")
+    if not os.path.exists(creds_path):
+        with open(creds_path, "w") as f:
+            f.write("scenario,email,password\\nlogin,test@example.com,secret123\\n")
+        print("Created data/credentials.csv")
+
+    # Create conftest.py
+    conftest_path = os.path.join(base_dir, "conftest.py")
+    if not os.path.exists(conftest_path):
+        with open(conftest_path, "w") as f:
+            f.write("""import pytest
+from promethee.conftest import driver, base_url
+
+# You can add local fixtures here
+""")
+        print("Created conftest.py")
+
+    # Create sample scenario (login.py)
+    login_scenario_path = os.path.join(base_dir, "scenarios", "login.py")
+    if not os.path.exists(login_scenario_path):
+        with open(login_scenario_path, "w") as f:
+            f.write("""from promethee.base import Base
+from selenium.webdriver.common.by import By
+from selenium_ui_test_tool import fill_input, click_element, wait_for_element
+
+class LoginPage(Base):
+    def fill_login_form(self, username, password):
+        print(f"Logging in with {username}...")
+        # Example implementation
+        # fill_input(self.driver, By.ID, "username", username)
+        # fill_input(self.driver, By.ID, "password", password)
+        # click_element(self.driver, By.ID, "login-btn")
+""")
+        print("Created scenarios/login.py")
+
+    # Create generic sample test
+    test_path = os.path.join(base_dir, "tests", "test_login.py")
+    if not os.path.exists(test_path):
+        with open(test_path, "w") as f:
+            f.write("""from utils.scenario_provider import ScenarioProvider
+from scenarios.login import LoginPage
+
+def test_login(driver, base_url):
+    print("Running test_login...")
+    scenario_name, data = ScenarioProvider.prompt_for_scenario()
+    
+    page = LoginPage(driver)
+    page.fill_login_form(data['username_env'], data['password_env'])
+    
+    assert True
+""")
+        print("Created tests/test_login.py")
+    
+    print("\nProject initialized successfully!")
+    print("Run your tests with: pytest tests/")
+
+def main():
+    parser = argparse.ArgumentParser(description="Prométhée UI Test Framework CLI")
+    subparsers = parser.add_subparsers(dest="command")
+
+    init_parser = subparsers.add_parser("init", help="Initialize a new test project")
+    docs_parser = subparsers.add_parser("docs", help="Open the documentation in browser")
+
+    args = parser.parse_args()
+
+    if args.command == "init":
+        init_project()
+    elif args.command == "docs":
+        open_docs()
+    else:
+        parser.print_help()
+
+if __name__ == "__main__":
+    main()

promethee_selenium-1.0.0/promethee/conftest.py

@@ -0,0 +1,19 @@
+import pytest
+import os
+from selenium_ui_test_tool import create_driver
+
+@pytest.fixture(scope="function")
+def driver():
+    """
+    Standard fixture to create a driver instance.
+    """
+    driver = create_driver()
+    yield driver
+    driver.quit()
+
+@pytest.fixture(scope="session")
+def base_url():
+    """
+    Returns the base URL. Can be overridden by environment variable or config.
+    """
+    return os.getenv("BASE_URL", "https://example.com")