Headless mode for CI in Selenium Python - Framework Patterns

Framework Mode - Headless mode for CI

Folder Structure

selenium-python-project/
├── tests/
│   ├── test_login.py
│   ├── test_checkout.py
│   └── __init__.py
├── pages/
│   ├── login_page.py
│   ├── checkout_page.py
│   └── __init__.py
├── utils/
│   ├── driver_factory.py
│   ├── config.py
│   └── __init__.py
├── reports/
│   └── (test reports here)
├── conftest.py
├── requirements.txt
└── pytest.ini
    

Test Framework Layers

• Driver Layer: utils/driver_factory.py creates and configures Selenium WebDriver instances, including headless mode setup.
• Page Objects: pages/ contains classes representing web pages with methods to interact with page elements.
• Tests: tests/ holds test scripts using pytest that call page objects and driver instances.
• Utilities: utils/config.py manages environment variables, browser options, and credentials.
• Configuration: pytest.ini and conftest.py handle test setup, fixtures, and command-line options.
• Reports: reports/ stores test execution reports for CI visibility.

Configuration Patterns

Use environment variables and pytest command-line options to control headless mode and browser choice.

# utils/driver_factory.py
from selenium import webdriver
from selenium.webdriver.chrome.options import Options
import os

def create_driver():
    options = Options()
    if os.getenv('HEADLESS', 'true').lower() == 'true':
        options.add_argument('--headless=new')  # Use new headless mode in Chrome 109+
        options.add_argument('--disable-gpu')
        options.add_argument('--window-size=1920,1080')
    driver = webdriver.Chrome(options=options)
    return driver

# conftest.py
import pytest
from utils.driver_factory import create_driver

@pytest.fixture(scope='function')
def driver():
    driver = create_driver()
    yield driver
    driver.quit()
    

Set HEADLESS=true in CI environment variables to run tests without opening a browser window.

Test Reporting and CI/CD Integration

• Use pytest plugins like pytest-html or pytest-junitxml to generate HTML or XML reports.
• Configure CI pipelines (e.g., GitHub Actions, Jenkins) to run tests with HEADLESS=true environment variable.
• Store reports as build artifacts for easy access and review.
• Fail the build if tests fail, ensuring quality gate enforcement.

# Example GitHub Actions snippet
jobs:
  test:
    runs-on: ubuntu-latest
    env:
      HEADLESS: 'true'
    steps:
      - uses: actions/checkout@v3
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.12'
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt
      - name: Run tests
        run: |
          pytest --junitxml=reports/results.xml
      - name: Upload test report
        uses: actions/upload-artifact@v3
        with:
          name: test-report
          path: reports/
    

Best Practices

• Use environment variables: Control headless mode without changing code, making it easy to switch between local and CI runs.
• Keep driver setup centralized: Use a factory method to create drivers with consistent options.
• Use explicit waits: Avoid flaky tests by waiting for elements properly, especially in headless mode where timing can differ.
• Generate readable reports: Use HTML or XML reports so CI systems and humans can easily understand test results.
• Clean up resources: Always quit the driver after tests to free memory and avoid hanging processes.

Self Check

Where in this folder structure would you add a new browser option to run Firefox in headless mode?

Key Result

Use environment variables to enable headless browser mode in CI, centralize driver setup, and integrate test reporting for reliable automated testing.