Promium 3.8.2

Selenium wrapper for testing Web UI

Promium is a simple Selenium wrapper designed to facilitate writing UI tests.

Promium Documentation

Overview

Promium simplifies the UI testing process using Selenium. The framework is designed for ease of test creation and provides essential tools for working with elements, pages, and test cases. Supports Python 3.13 and works on Linux and macOS.

Installation and Setup

System Requirements

• Python 3.13

• Systems: Linux, macOS

To install all dependencies:

pip install -r requirements.txt

Install Promium

pip install promium

Driver and Chrome Setup

To use Promium with Chrome, both Google Chrome and ChromeDriver need to be installed. Use the following commands to set up Chrome and ChromeDriver:

ARG CHROME_MILESTONE=130

#============================================
# Google Chrome
#============================================
RUN CHROME_VERSION=$(curl -s https://googlechromelabs.github.io/chrome-for-testing/LATEST_RELEASE_${CHROME_MILESTONE}) && \
    curl -Lo /tmp/chrome-linux.zip https://edgedl.me.gvt1.com/edgedl/chrome/chrome-for-testing/${CHROME_VERSION}/linux64/chrome-linux64.zip && \
    apt-get install -y unzip && \
    unzip /tmp/chrome-linux.zip -d /usr/local/ && \
    ln -s /usr/local/chrome-linux64/chrome /usr/local/bin/google-chrome && \
    rm /tmp/chrome-linux.zip

#============================================
# ChromeDriver
#============================================
RUN CHROME_DRIVER_VERSION=$(curl -s https://googlechromelabs.github.io/chrome-for-testing/latest-versions-per-milestone.json | python3 -c "import sys, json; print(json.load(sys.stdin)['milestones'][str(${CHROME_MILESTONE})]['version'])") && \
    wget --no-verbose -O /tmp/chromedriver_linux64.zip https://storage.googleapis.com/chrome-for-testing-public/${CHROME_DRIVER_VERSION}/linux64/chromedriver-linux64.zip && \
    unzip /tmp/chromedriver_linux64.zip -d /opt/selenium && \
    ln -fs /opt/selenium/chromedriver-linux64/chromedriver /usr/bin/chromedriver && \
    rm /tmp/chromedriver_linux64.zip

Usage Examples

Below is a basic example of how to define a page object and run a simple test. For more examples, refer to the Examples Documentation.

Page Object Example

from selenium.webdriver.common.by import By
from promium import Page, Block, Element, InputField, Link

class ResultBlock(Block):
    title = Link(By.CSS_SELECTOR, 'h3')
    link = Element(By.CSS_SELECTOR, '.f')
    description = Element(By.CSS_SELECTOR, '.st')
    tags = Element.as_list(By.CSS_SELECTOR, '.osl .fl')

class GoogleResultPage(Page):
    results_blocks = ResultBlock.as_list(By.CSS_SELECTOR, '#rso .srg div.g')

class GoogleMainPage(Page):
    url = 'https://google.com'
    logo = Element(By.CSS_SELECTOR, '#hplogo')
    search_input = InputField(By.CSS_SELECTOR, '[name="q"]')

    def search(self, text):
        self.search_input.send_keys(text)
        self.search_input.submit()
        return GoogleResultPage(self.driver)

Test Example

from promium.test_case import WebDriverTestCase
from tests.pages.google_page import GoogleMainPage

class TestMainGooglePage(WebDriverTestCase):
    def test_search(self):
        main_page = GoogleMainPage(self.driver)
        main_page.open()
        self.soft_assert_element_is_displayed(main_page.logo)
        result_page = main_page.search('Selenium')
        result_block = result_page.results_blocks.first_item
        self.soft_assert_in('Selenium', result_block.title.text)

Run a Simple Test

# all tests
pytest tests/

# all tests in suite
pytest tests/test_google.py

# only one test
pytest tests/test_google.py -k test_search

Development and Testing

To set up a development environment and run tests, use the following commands:

• Build Docker Image: docker build -t promium/base-env .

• Run Tests: docker-compose run test-se

• Check Linting: docker-compose run ruff

Additional Documentation

For detailed information on using and configuring Promium, refer to the following documentation files:

• Assertions - Description of available assertion methods for validating test conditions.

• CI Setup - Configuration of CI/CD for automating integration processes.

• Commands - List of available commands and their usage within the framework.

• Containers - Information on setting up and using containers for an isolated testing environment.

• Devices(emulation) - Description of supported devices and configurations.

• Drivers - Configuration of drivers for browser interaction.

• Elements - Working with web elements and their properties.

• Examples - Sample tests and scenarios to get started with the framework.

• Exceptions - Handling exceptions and errors during testing.

• Test Cases - Creating and structuring test cases in Promium.