Introduction

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

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

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
)