Metadata-Version: 2.4
Name: eewebtests
Version: 2026.7.5
Summary: Easter-eggs web tests library
Author-email: Benjamin Renard <brenard@easter-eggs.com>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://gitlab.easter-eggs.com/ee/python-eewebtests
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: selenium
Requires-Dist: psutil
Requires-Dist: eepastecli @ git+https://gitlab.easter-eggs.com/ee/ee-paste-cli.git

# Easter-eggs Web Test Python Library

This Python library provides common utilities to implement web tests based on Python 3 and Selenium. It is designed for monitoring, testing, and automation scenarios, with built-in support for performance tracking, error handling, and integration with monitoring systems like Icinga/Nagios.

## Features

### Core Functionality

- **Command line arguments handling**: Easy management via `argparse`
- **INI configuration**: Support for INI-style configuration file
- **Selenium Chromium driver**: Pre-configured with:
  - Headless mode (disable with `--screen-debug`)
  - SHM control (enable with `--use-shm`)
  - Custom paths for ChromeDriver and Chromium binaries
  - Incognito mode and cache disabling
  - Temporary user data directory management

### Action Tracking System

Comprehensive framework to track and measure test actions:

- Custom action names and descriptive labels
- Warning/critical time thresholds (per-action or global)
- Automatic performance data generation
- Nested action support (steps) for hierarchical timing
- Action timeout configuration

### Element Interaction

The `locate` method provides a unified way to find and interact with elements:

- Support for CSS selectors, XPath, and other Selenium By strategies
- Waiting for non-empty elements (`non_empty=True`)
- Clicking on elements (`click=True`)
- Filling input fields and form submission (`value` parameter, with `submit=False` to disable auto-submit)
- Custom timeouts, warning/critical thresholds per element
- Full integration with the action tracking system

### Authentication

- **SSO authentication**: The `sso_login` method handles authentication on Authentic2-based IDPs
- **Multi-SSO configuration**: Switch between different SSO configurations with `switch_sso_config(section)`

### Error Management

Enhanced error handling system:

- `add_error(status, message)` to accumulate multiple non-fatal errors with WARNING/CRITICAL status levels
- Automatic final status determination in `clean_exit()` (CRITICAL > WARNING > OK)
- Exception trace inclusion (enable with `--include-exception-trace`)
- Custom exception classes: `EEWebTestException`, `EEWebTestTimeout`, `EEWebTestTooManyElements`, `InvalidActionName`, `InvalidPerformanceDataLabel`

### Performance Data

Complete performance tracking system compatible with Icinga/Nagios:

- `add_performance_data(label, value, unit, warning, critical, minimum, maximum)`
- Automatic formatting via `format_performance_data()`
- Integration with action timing
- Support for various units (seconds, %, etc.)

### Screenshot Management

Automatic screenshot handling on test completion:

- Save screenshots to file (`--save-screenshot`)
- Upload screenshots to PrivateBin instances (`--upload-screenshot-url`)
- PrivateBin configuration options:
  - Expiration delay (`--uploaded-screenshot-expiration-delay`)
  - Burn-after-reading (`--privatebin-burn-after-reading`)
  - Discussion mode (`--privatebin-discussion`)
  - Compression control (`--privatebin-no-compression`)
- Screenshot saved on any non-OK status by default (use `--save-screenshot-even-if-ok` for all statuses)

### Inter-Process Locking

Prevent simultaneous execution of eewebtests-based check plugins:

- Automatic lock file acquisition (`acquire_lock()`)
- Configurable lock path (`--lock-path`)
- Lock timeout configuration (`--lock-timeout`)
- Automatic release on exit or timeout

### Process Management

- Automatic cleanup of child processes on exit
- Graceful termination with fallback to force kill
- Temporary directory cleanup

### Debugging & Logging

Comprehensive debugging capabilities:

- Debug mode (`-d/--debug`) for detailed logging
- Verbose mode (`-v/--verbose`) for additional output
- Log file specification (`-l/--logfile`)
- Screen debug mode (`-D/--screen-debug`) to show the embedded browser window
- Chrome debug logging (`--chrome-debug`)

## Using Configuration File

Create a `config.ini` file:

```ini
[default]
timeout = 30
browser_window_size = 1920,1080

[sso]
url = https://sso.example.com
user = testuser
password = secret

[check]
time_warning = 20
time_critical = 40

[my_service]
url = https://my-service.domain.tld
```

Then run your test script with:

```bash
python3 check_my_service.py -c config.ini
```

## Icinga/Nagios Integration

The library is designed for seamless integration with monitoring systems:

- Output format: `STATUS - message | performance_data`
- Exit codes: 0 (OK), 1 (WARNING), 2 (CRITICAL), 3 (UNKNOWN)
- Performance data automatically included in output
- Screenshot URLs included in output when configured

Example of Icinga `CheckCommand` object definition for the `check_sentry` script provided in `example` directory:

```
object CheckCommand "check_sentry" {
  import "plugin-check-command"

  command = [ PluginDir + "/check_sentry" ]

  arguments = {
    # Core & Threshold Options
    "--sentry-url" = {
      value = "$sentry_url$"
      description = "Target Sentry URL"
    }
    "-W" = {
      value = "$sentry_check_time_warning$"
      description = "Warning check time threshold in seconds"
    }
    "-C" = {
      value = "$sentry_check_time_critical$"
      description = "Critical check time threshold in seconds"
    }
    "-t" = {
      value = "$sentry_timeout$"
      description = "Timeout delay for interactive actions in the embedded browser (in seconds)"
    }
    "-c" = {
      value = "$sentry_config_path$"
      description = "Path to the configuration file"
    }
    "-l" = {
      value = "$sentry_logfile$"
      description = "Log file path"
    }

    # SSO Options
    "--sso-url" = {
      value = "$sentry_sso_url$"
      description = "Authentic2 SSO URL"
    }
    "-u" = {
      value = "$sentry_sso_user$"
      description = "SSO user login"
    }
    "-p" = {
      value = "$sentry_sso_password$"
      description = "SSO user password"
    }
    "-e" = {
      value = "$sentry_sso_email$"
      description = "SSO user email"
    }
    "-n" = {
      value = "$sentry_sso_name$"
      description = "SSO user full name"
    }

    # Embedded Chromium Options
    "--chrome-driver-path" = {
      value = "$sentry_chrome_driver_path$"
      description = "Chrome driver binary path (default: /usr/bin/chromedriver)"
    }
    "--chromium-path" = {
      value = "$sentry_chromium_path$"
      description = "Chromium binary path (default: /usr/bin/chromium)"
    }
    "-S" = {
      value = "$sentry_window_size$"
      description = "Browser window size (default: 1920,1080)"
    }
    "--user-data-dir" = {
      value = "$sentry_user_data_dir$"
      description = "User data directory path"
    }
    "--use-shm" = {
      set_if = "$sentry_use_shm$"
      description = "Use shared memory (/dev/shm)"
    }
    "--chrome-debug" = {
      set_if = "$sentry_chrome_debug$"
      description = "Enable Chrome debug log"
    }

    # Screenshot & PrivateBin Options
    "-s" = {
      value = "$sentry_screenshot_path$"
      description = "Path to save PNG screenshot on exit"
    }
    "-P" = {
      value = "$sentry_upload_screenshot_url$"
      description = "PrivateBin root URL to upload screenshots"
    }
    "-X" = {
      value = "$sentry_uploaded_screenshot_expiration_delay$"
      description = "PrivateBin expiration delay in hours (default: 4)"
    }
    "-F" = {
      set_if = "$sentry_save_screenshot_even_if_ok$"
      description = "Save screenshot even if exit status is OK"
    }
    "-B" = {
      set_if = "$sentry_screenshot_burn_after_reading$"
      description = "Set uploaded screenshot to burn-after-reading in PrivateBin"
    }
    "--privatebin-discussion" = {
      set_if = "$sentry_screenshot_discussion$"
      description = "Open discussion on PrivateBin uploaded screenshot"
    }
    "--privatebin-no-compression" = {
      set_if = "$sentry_screenshot_no_compression$"
      description = "Disable compression for PrivateBin screenshot upload"
    }

    # Inter-process Lock Options
    "-L" = {
      value = "$sentry_lock_path$"
      description = "Inter-process lock file path"
    }
    "--lock-timeout" = {
      value = "$sentry_lock_timeout$"
      description = "Timeout in seconds to acquire lock file"
    }

    # Debugging Options
    "-d" = {
      set_if = "$sentry_debug$"
      description = "Enable debug mode"
    }
    "-v" = {
      set_if = "$sentry_verbose$"
      description = "Enable verbose mode"
    }
    "-E" = {
      set_if = "$sentry_include_exception_trace$"
      description = "Include exception trace in output message"
    }
  }

  # Default boolean flags set to false
  vars.sentry_timeout = 300
  vars.sentry_debug = false
  vars.sentry_verbose = false
  vars.sentry_screen_debug = false
  vars.sentry_include_exception_trace = false
  vars.sentry_use_shm = false
  vars.sentry_chrome_debug = false
  vars.sentry_screenshot_path_even_if_ok = false
  vars.sentry_screenshot_burn_after_reading = false
  vars.sentry_screenshot_discussion = false
  vars.sentry_screenshot_no_compression = false

  # Execution timeout for Icinga process manager
  timeout = "$sentry_timeout$"
}
```

## Examples

See the `example` directory (in `/usr/share/doc/python3-eewebtests` on Debian-based systems) for complete examples including:

- SSO SAML2 login on a Sentry instance
- Performance tracking with thresholds
- Screenshot capture and upload
- Multi-step test scenarios

## Requirements

- Python 3.6+
- Selenium 4+
- ChromeDriver or ChromiumDriver
- Chromium browser
- `psutil` for process management
- Optional: [eepastecli](https://gitlab.easter-eggs.com/ee/ee-paste-cli) for PrivateBin screenshot upload

## Installation

### Debian/Ubuntu

Debian package available on [Easter-eggs APT repository](https://apt.easter-eggs.com):

```bash
apt install python3-eewebtests
```

### PyPI

```bash
python3 -m pip install "eewebtests @ git+https://gitlab.easter-eggs.com/ee/python-eewebtests.git"
```

### From Source

```bash
git clone https://github.com/easter-eggs/python-eewebtests.git
cd python-eewebtests
python3 -m pip install .
```

## Copyright

Copyright (c) 2024-2026 Easter-eggs

## License

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License version 3 as published by the Free Software Foundation.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
