Prométhée UI Documentation

## Introduction

Welcome to Promethee-Selenium. This professional-grade library provides a structured, scalable way to write UI tests using Selenium and Pytest, implementing the Page Object Model (POM) pattern.

It acts as a wrapper around the `selenium-ui-test-tool` library to provide a high-level, opinionated architecture for robust test automation.

Bienvenue sur Promethee-Selenium. Cette librairie de niveau professionnel fournit une méthode structurée et évolutive pour écrire des tests d'interface utilisateur avec Selenium et Pytest, en implémentant le modèle Page Object Model (POM).

Elle agit comme une surcouche (wrapper) autour de la librairie `selenium-ui-test-tool` pour offrir une architecture d'automatisation robuste.

## Getting Started

## Démarrage Rapide

### 1. Installation

Install the package via pip:

    pip install promethee-selenium

### 2. Initialization

To initialize a new project with the recommended structure, run:

    promethee-selenium init

To view the documentation in your browser:

    promethee-selenium docs

### 1. Installation

Installez le paquet via pip :

    pip install promethee-selenium

### 2. Initialisation

Pour initialiser un nouveau projet avec la structure recommandée, lancez :

    promethee-selenium init

Pour afficher la documentation dans votre navigateur :

    promethee-selenium docs

## Philosophy & Architecture

## Philosophie & Architecture

### The Prométhée Philosophy

### La Philosophie Prométhée

Prométhée is built on three core principles:

1. Separation of Concerns: Tests should describe what to test (business logic), while Page Objects describe how to interact with the page (implementation details).
2. Composition over Inheritance: Use the robust functional API of `selenium-ui-test-tool` inside your Page Objects, rather than creating deep inheritance chains.
3. Data-Driven: Test data and execution logic should be decoupled.

Prométhée est bâti sur trois principes clés :

1. Séparation des responsabilités : Les tests décrivent quoi tester (logique métier), tandis que les Page Objects décrivent comment interagir avec la page (détails d'implémentation).
2. Composition plutôt qu'Héritage : Utilisez l'API fonctionnelle robuste de `selenium-ui-test-tool` à l'intérieur de vos Page Objects, plutôt que de créer des chaînes d'héritage complexes.
3. Piloté par les données : Les données de test et la logique d'exécution doivent être découplées.

### Recommended Project Structure

### Structure de Projet Recommandée

When you run `promethee-selenium init`, we create a structure designed for scalability:

Lorsque vous lancez `promethee-selenium init`, nous créons une structure conçue pour l'évolutivité :

    my_project/
    ├── scenarios/          # Your Page Objects (The "How")
    │   └── login_page.py
    ├── tests/              # Your Test Scripts (The "What")
    │   └── test_login.py
    ├── data/               # Test Data (CSV, JSON)
    │   └── credentials.csv
    ├── utils/              # Custom Helpers
    │   └── scenario_provider.py
    └── conftest.py         # Test Configuration & Lifecycle

## Understanding Scaffolded Components

## Comprendre les Composants Générés

### 1. conftest.py

This is the heartbeat of your test suite. It uses Pytest fixtures to manage the browser lifecycle.

What it does: It automatically starts the browser driver before your test runs and closes it immediately after, ensuring a clean state for every test. You don't need to write `driver = WebDriver()` or `driver.quit()` yourself.

C'est le cœur de votre suite de tests. Il utilise les fixtures Pytest pour gérer le cycle de vie du navigateur.

Ce qu'il fait : Il démarre automatiquement le driver du navigateur avant votre test et le ferme immédiatement après, garantissant un état propre pour chaque test. Vous n'avez pas besoin d'écrire `driver = WebDriver()` ou `driver.quit()` vous-même.

### 2. utils/scenario_provider.py

Hardcoding credentials in scripts is a security risk. The `ScenarioProvider` solves this.

What it does: It reads a CSV file (like `data/credentials.csv`), loads specific rows based on a scenario key, and injects sensitive values into environment variables at runtime. This allows you to switch environments (staging/prod) without changing code.

Coder des identifiants en dur dans les scripts est un risque de sécurité. Le

    pip install promethee-selenium

ésout ce problème.

Ce qu'il fait : Il lit un fichier CSV (comme `data/credentials.csv`), charge des lignes spécifiques basées sur une clé de scénario, et injecte les valeurs sensibles dans des variables d'environnement au moment de l'exécution. Cela vous permet de changer d'environnement (staging/prod) sans toucher au code.

## Tutorial: Writing a Test

## Tutoriel : Écrire un Test

This tutorial guides you through creating a robust, data-driven test using Prométhée's architecture. We will build a login test.

Ce tutoriel vous guide dans la création d'un test robuste et piloté par les données en utilisant l'architecture de Prométhée. Nous allons créer un test de connexion.

### Step 1: Prepare Test Data

### Étape 1 : Préparer les Données de Test

First, define your test data in `data/credentials.csv`. This keeps sensitive data out of your code.

Tout d'abord, définissez vos données de test dans `data/credentials.csv`. Cela garde les données sensibles hors de votre code.

    scenario,email,password
    login_success,user@test.com,securePass123
    login_failure,bad@test.com,wrongPass

### Step 2: Configure Test Lifecycle

### Étape 2 : Configurer le Cycle de Vie des Tests

The `conftest.py` file manages the browser lifecycle using Pytest fixtures. It ensures the browser starts before tests and closes afterwards.

Your `conftest.py` should import the driver from `promethee`:

Le fichier `conftest.py` gère le cycle de vie du navigateur à l'aide des fixtures Pytest. Il s'assure que le navigateur démarre avant les tests et se ferme après.

Votre `conftest.py` doit importer le driver depuis `promethee` :

    import pytest
    from promethee.conftest import driver, base_url

    # You can add your own local fixtures here if needed

### Step 3: Configure Base Interactions

### Étape 3 : Configurer les Interactions de Base

Your `Base` class (in `promethee/base.py`) provides the foundation. Ensure it's set up to handle common actions.

(Note: In most projects initialized with Prométhée, this is already done for you, but understanding it is key.)

Votre classe `Base` (dans `promethee/base.py`) fournit les fondations. Assurez-vous qu'elle est configurée pour gérer les actions communes.

(Note : Dans la plupart des projets initialisés avec Prométhée, cela est déjà fait pour vous, mais le comprendre est essentiel.)

### Step 4: Create Page Objects (OOP)

### Étape 4 : Créer les Page Objects (POO)

We use Object-Oriented Programming. Your Page Object inherits from `Base` to access the driver, but uses `selenium-ui-test-tool` functions for interactions.

Nous utilisons la Programmation Orientée Objet. Votre Page Object hérite de `Base` pour accéder au driver, mais utilise les fonctions de `selenium-ui-test-tool` pour les interactions.

    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):
        """
        Page Object for the Login Page.
        Encapsulates all interactions with the login screen.
        """

        def fill_login_form(self, username, password):
            # self.driver is inherited from Base
            fill_input(self.driver, By.ID, "username", username)
            fill_input(self.driver, By.ID, "password", password)
            click_element(self.driver, By.ID, "login-btn")

        def is_error_displayed(self):
            return wait_for_element(self.driver, By.CLASS_NAME, "error-msg") is not None

### Step 5: Write the Test

### Étape 5 : Écrire le Test

Finally, write the test in `tests/test_login.py`. Use `ScenarioProvider` to fetch data and inject it into the Page Object.

Enfin, écrivez le test dans `tests/test_login.py`. Utilisez `ScenarioProvider` pour récupérer les données et les injecter dans le Page Object.

    from utils.scenario_provider import ScenarioProvider
    from scenarios.login_page import LoginPage

    def test_valid_login(driver):
        # 1. Get Data
        # Fetch data for 'login_success' scenario from CSV
        data = ScenarioProvider.get_data_for_scenario("login_success")

        # 2. Initialize Page Object
        # Pass the driver fixture to the Page Object
        login_page = LoginPage(driver)

        # 3. Perform Actions
        login_page.open_url("https://example.com/login")
        login_page.fill_login_form(data['email'], data['password'])

        # 4. Assert Results
        assert "Dashboard" in login_page.get_title()

## API Reference

## Référence API

### Class `promethee.base.Base`

### Classe `promethee.base.Base`

The foundational class for all Page Objects.

La classe fondamentale pour tous les Page Objects.

- `__init__(driver, url=None)`: Initializes the page with a driver. If URL is provided, navigates to it.Initialise la page avec un driver. Si une URL est fournie, navigue vers celle-ci.
- `open_url(url)`: Navigate to a specific URL.Naviguer vers une URL spécifique.
- `get_title()`: Returns the current page title.Retourne le titre de la page courante.
- `refresh()`: Refreshes the page.Rafraîchit la page.

### External Interactions

### Interactions Externes

Prométhée recommends using selenium-ui-test-tool for all element interactions. Key imports:

Prométhée recommande d'utiliser selenium-ui-test-tool pour toutes les interactions avec les éléments. Imports clés :

    from selenium_ui_test_tool import (
        click_element,
        fill_input,
        wait_for_element,
        get_text
    )