Toolium

https://toolium.readthedocs.io/en/latest/
Admin
Toolium is a Python wrapper tool of Selenium, Playwright, and Appium libraries to test web and...
Tokens:58,167
Snippets:480
Trust Score:9.6
Update:6 months ago
Show doc for...
Tokens:
Raw
### Clone and Setup Toolium Templates

Source: https://toolium.readthedocs.io/en/latest/index.html

Commands to clone the official Toolium template or examples repositories and install necessary dependencies.

```bash
git clone git@github.com:Telefonica/toolium-template.git
cd toolium-template
pip install -r requirements.txt
```

```bash
git clone git@github.com:Telefonica/toolium-examples.git
cd toolium-examples
pip install -r requirements.txt
```

--------------------------------

### Setup Development Environment and Run Tests

Source: https://toolium.readthedocs.io/en/latest/index.html

Commands to clone the Toolium repository, install development dependencies, lint the code, and execute unit tests.

```bash
git clone git@github.com:<your_github_user>/toolium.git
cd toolium
pip install -r requirements.txt
pip install -r requirements_dev.txt
ruff check --fix .
ruff format .
python -m pytest
```

--------------------------------

### Configure Baseline Directory

Source: https://toolium.readthedocs.io/en/latest/_sources/visual_testing.rst.txt

Examples of configuring the visual baseline directory via environment variables, Behave hooks, or Nose2 setup methods.

```console
$ export TOOLIUM_VISUAL_BASELINE_DIRECTORY=resources/baseline
```

```python
from toolium.behave.environment import before_all as toolium_before_all
from toolium.config_files import ConfigFiles

def before_all(context):
    context.config_files = ConfigFiles()
    context.config_files.set_visual_baseline_directory('resources/baseline')
    toolium_before_all(context)
```

```python
from toolium import test_cases

class SeleniumTestCase(test_cases.SeleniumTestCase):
    def setUp(self):
        self.config_files.set_visual_baseline_directory('resources/baseline')
        super(SeleniumTestCase, self).setUp()
```

--------------------------------

### Installation

Source: https://toolium.readthedocs.io/en/latest/_sources/ai_utils.rst.txt

Instructions for installing Toolium with AI support and setting up environment variables for OpenAI and Azure OpenAI.

```APIDOC
## Installation

Make sure to install the required libraries:

```bash
pip install toolium[ai]
```

For Azure OpenAI, you need to set up your configuration in environment variables:

```bash
AZURE_OPENAI_API_KEY=<your_api_key>
AZURE_OPENAI_ENDPOINT=<your_endpoint>
OPENAI_API_VERSION=<your_api_version>
```

For standard OpenAI:

```bash
OPENAI_API_KEY=<your_api_key>
```
```

--------------------------------

### Configure Selenoid Capabilities

Source: https://toolium.readthedocs.io/en/latest/toolium.html

Example configuration for the properties.cfg or local-properties.cfg files to enable Selenoid features such as video recording, VNC, and logging.

```ini
[Capabilities]
selenoid_options: {'enableVideo': True, 'enableVNC': True, 'enableLog': True}

[Server]
enabled: true
host: <hostname or ip>
port: <numeric>
username: <string>
password: <string>
video_enabled: true
logs_enabled: true
```

--------------------------------

### Page Object File Structure for Login Example (Python)

Source: https://toolium.readthedocs.io/en/latest/page_objects.html

This example shows the specific file paths and class names for the login page object structure, following the recommended organization for Toolium projects.

```python
toolium_examples/pageobjects/base/login.py
    class BaseLoginPageObject(MobilePageObject)

toolium_examples/pageobjects/android/login.py
    class AndroidLoginPageObject(BaseLoginPageObject)

toolium_examples/pageobjects/ios/login.py
    class IosLoginPageObject(BaseLoginPageObject)
```

--------------------------------

### Page Object File Structure Example (Python)

Source: https://toolium.readthedocs.io/en/latest/page_objects.html

This example illustrates the recommended file structure for organizing base, Android, and iOS page objects. It shows how to place them in separate directories to maintain modularity and clarity.

```python
FOLDER/base/MODULE_NAME.py
    class BasePAGE_OBJECT_NAME(MobilePageObject)

FOLDER/android/MODULE_NAME.py
    class AndroidPAGE_OBJECT_NAME(BasePAGE_OBJECT_NAME)

FOLDER/ios/MODULE_NAME.py
    class IosPAGE_OBJECT_NAME(BasePAGE_OBJECT_NAME)
```

--------------------------------

### Configure Chrome Preferences and Arguments

Source: https://toolium.readthedocs.io/en/latest/browser_configuration.html

Examples of setting browser preferences and startup arguments in the Toolium configuration file to control download directories and user profiles.

```ini
[Driver]
type: chrome

[ChromePreferences]
download.default_directory: C:\tmp

[ChromeArguments]
user-data-dir: C:\Users\USERNAME\AppData\Local\Google\Chrome\User Data
```

--------------------------------

### Configure Element Scoping and Contexts

Source: https://toolium.readthedocs.io/en/latest/page_objects.html

Examples for scoping elements within a parent container, targeting shadow roots, and configuring mobile webview contexts.

```python
# Parent scoping
form = PageElement(By.XPATH, "//form[@id='login']")
login_button = Button(By.XPATH, "./button", parent=form)

# Shadowroot
login_button = Button(By.CSS_SELECTOR, "css_selector", shadowroot="shadowroot_css_selector")

# Mobile Webview
login_button = Button(By.XPATH, "//*[@data-qsysid='subscription-counters']/div/div/", webview=True,
                      webview_context_selection_callback = webview_context_selector_per_url,
                      webview_csc_args = [driver_wrapper, WebviewConfigHelper.get_helper().account])
```

--------------------------------

### Install Toolium via pip

Source: https://toolium.readthedocs.io/en/latest/index.html

Installs the latest version of the Toolium library from PyPi. It is recommended to run this command within a virtual environment.

```bash
pip install toolium
```

--------------------------------

### Configure Firefox Extensions and Arguments

Source: https://toolium.readthedocs.io/en/latest/browser_configuration.html

Installs Firefox plugins via [FirefoxExtensions] and passes command-line arguments via [FirefoxArguments].

```ini
[Driver]
type: firefox

[FirefoxExtensions]
firebug: resources/firebug-3.0.0-beta.3.xpi

[FirefoxArguments]
-private:
```

--------------------------------

### Install Toolium AI Dependencies

Source: https://toolium.readthedocs.io/en/latest/ai_utils.html

Installs the necessary libraries for Toolium's AI utilities, including SpaCy, Sentence Transformers, and OpenAI. Additional steps are required for downloading SpaCy models and configuring API keys for OpenAI.

```bash
pip install toolium[ai]
```

```bash
python -m spacy download en_core_web_sm
```

```bash
# For example, to configure direct OpenAI access:
OPENAI_API_KEY=<your_api_key>
```

```bash
# For example, to configure Azure OpenAI:
AZURE_OPENAI_API_KEY=<your_api_key>
AZURE_OPENAI_ENDPOINT=<your_endpoint>
OPENAI_API_VERSION=<your_api_version>
```

--------------------------------

### Configure video recording and logs for remote execution

Source: https://toolium.readthedocs.io/en/latest/_sources/tests_result_analysis.rst.txt

Configuration examples for enabling video recording and webdriver logs in remote grid environments like GGR or Selenium Grid Extras.

```ini
[Capabilities]
selenoid___options: {'enableVideo': True}

[Server]
video_enabled: true

[Capabilities]
selenoid___options: {'enableLog': True}

[Server]
logs_enabled: true
```

--------------------------------

### Configure Firefox Extensions

Source: https://toolium.readthedocs.io/en/latest/_sources/browser_configuration.rst.txt

Install Firefox extensions by providing the file paths to the .xpi files in the [FirefoxExtensions] section. This enables functionalities like network monitoring.

```ini
[Driver]
type: firefox

[FirefoxPreferences]
devtools.netmonitor.har.enableAutoExportToFile: True
devtools.netmonitor.har.defaultLogDir: /tmp/har
devtools.netmonitor.har.forceExport: False
devtools.netmonitor.har.pageLoadedTimeout: 10
extensions.netmonitor.har.enableAutomation: True
extensions.netmonitor.har.autoConnect: True
devtools.netmonitor.har.defaultFileName: network-test

[FirefoxExtensions]
firebug: resources/firebug-3.0.0-beta.3.xpi
```

--------------------------------

### Install Toolium AI Dependencies

Source: https://toolium.readthedocs.io/en/latest/_sources/ai_utils.rst.txt

Commands to install the necessary dependencies for Toolium's AI features and configure specific language models or environment variables.

```bash
pip install toolium[ai]
python -m spacy download en_core_web_sm
export OPENAI_API_KEY=<your_api_key>
```

--------------------------------

### Install Toolium AI Dependencies

Source: https://toolium.readthedocs.io/en/latest/ai_utils.html

Installs the necessary Python packages to enable AI functionality within the Toolium framework.

```bash
pip install toolium[ai]
```

--------------------------------

### Install Playwright Dependencies

Source: https://toolium.readthedocs.io/en/latest/playwright_configuration.html

Command to install the necessary Playwright dependencies for Toolium via pip. This ensures the environment is prepared to run Playwright-based tests.

```bash
pip install toolium[playwright]
```

--------------------------------

### Get Selenoid Host Info (Python)

Source: https://toolium.readthedocs.io/en/latest/_modules/toolium/selenoid.html

Retrieves information about the current Selenoid host. It constructs a URL using the server details and session ID, then makes a GET request to fetch the host information as a JSON object. Returns None if an error occurs during the request.

```python
def get_selenoid_info(self):
        """
        retrieve the current selenoid host info
        request: http://<username>:<password>@<ggr_host>:<ggr_port>/host/<ggr_session_id>
        :return: dict
        """
        host_url = f'{self.server_url}/host/{self.session_id}'
        try:
            selenoid_info = requests.get(host_url).json()
        except Exception:
            return None
        self.driver_wrapper.logger.info('Selenoid host info: %s', selenoid_info)
        return selenoid_info
```

--------------------------------

### Configure Firefox Profile and Binary Path

Source: https://toolium.readthedocs.io/en/latest/_sources/browser_configuration.rst.txt

Specify a custom Firefox profile directory or the binary path if Firefox is installed in a non-default location. This is configured in the [Firefox] section.

```ini
[Driver]
type: firefox

[Firefox]
profile: resources/firefox-profile.default
```

```ini
[Driver]
type: firefox

[Firefox]
binary: /usr/local/firefox_beta/firefox
```

--------------------------------

### Initialize Toolium Environment in Behave

Source: https://toolium.readthedocs.io/en/latest/bdd_integration.html

This Python code demonstrates how to initialize Toolium's environment methods within Behave's environment.py file. It ensures that Toolium's driver and configuration are properly set up before and after Behave test execution. This setup makes Toolium's driver_wrapper, config, and utils available in the Behave context.

```python
from toolium.behave.environment import (
    before_all as toolium_before_all,
    before_feature as toolium_before_feature,
    before_scenario as toolium_before_scenario,
    after_scenario as toolium_after_scenario,
    after_feature as toolium_after_feature,
    after_all as toolium_after_all
)

def before_all(context):
    toolium_before_all(context)

def before_feature(context, feature):
    toolium_before_feature(context, feature)

def before_scenario(context, scenario):
    toolium_before_scenario(context, scenario)

def after_scenario(context, scenario):
    toolium_after_scenario(context, scenario)

def after_feature(context, feature):
    toolium_after_feature(context, feature)

def after_all(context):
    toolium_after_all(context)

```

--------------------------------

### Configure Chrome Extensions

Source: https://toolium.readthedocs.io/en/latest/_sources/browser_configuration.rst.txt

Install Chrome extensions by providing the file paths to the .crx files in the [ChromeExtensions] section. This allows for the integration of browser add-ons.

```ini
[Driver]
type: chrome

[ChromeExtensions]
firebug: resources/firebug-lite.crx
```

--------------------------------

### Configure webdriver log types and performance logging

Source: https://toolium.readthedocs.io/en/latest/_sources/tests_result_analysis.rst.txt

Examples of how to filter log types and enable performance logging for Chrome in Toolium configuration files.

```ini
[Server]
log_types: client,server

[Capabilities]
goog___loggingPrefs: {'browser':'ALL', 'driver': 'ALL', 'performance': 'ALL'}

[Chrome]
options: {'perfLoggingPrefs': {'enableNetwork': True}}
```

--------------------------------

### Configure Firefox Binary Path

Source: https://toolium.readthedocs.io/en/latest/changelog.html

Allows configuration of the Firefox binary path using the 'binary' property in the [Firefox] section of the configuration file. This is useful for specifying custom Firefox installations.

```ini
[Firefox]
binary = /path/to/firefox/binary
```

--------------------------------

### Behave Feature with Dynamic Environment Actions

Source: https://toolium.readthedocs.io/en/latest/bdd_integration.html

This snippet demonstrates a Behave Feature file that utilizes dynamic environment actions. It shows how to define steps to be executed before the feature, before each scenario, after each scenario, and after the feature. It also includes an example of a step with a table.

```gherkin
@reuse_driver
Feature: Tests with the dynamic environment
  As a behave operator using multiples scenarios
  I want to append actions before the feature, before each scenario, after each scenario and after the feature.

  Actions Before the Feature:
    Given wait 3 seconds
      And waitrty 3 seconds
      And wait 3 seconds
      And step with a table
          | parameter     | value       |
          | sub_fields_1  | sub_value 1 |
          | sub_fields_2  | sub_value 2 |

  Actions Before each Scenario:
    Given the user navigates to the "www.google.es" url
     When the user logs in with username and password
      And wait 1 seconds
      And wait 1 seconds

  Actions After each Scenario:
     Then wait 2 seconds
      And wait 2 seconds

  Actions After the Feature:
     Then wait 4 seconds
      And step with another step executed dynamically
      And wait 4 seconds

```

--------------------------------

### Get Configured Value from Environment or Defaults

Source: https://toolium.readthedocs.io/en/latest/_modules/toolium/driver_wrappers_pool.html

Retrieves a configuration value by checking system properties (environment variables), a specific test case value, or a default value. This is useful for flexible configuration management in tests.

```python
@staticmethod
def get_configured_value(system_property_name, specific_value, default_value):
        """Get configured value from system properties, method parameters or default value

        :param system_property_name: system property name
        :param specific_value: test case specific value
        :param default_value: default value
        :returns: configured value
        """
        try:
            return os.environ[system_property_name]
        except KeyError:
            return specific_value if specific_value else default_value
```

--------------------------------

### POST /config/initialize

Source: https://toolium.readthedocs.io/en/latest/_modules/toolium/driver_wrappers_pool.html

Initializes configuration files for the test environment, applying environment-specific overrides to property files and log filenames.

```APIDOC
## POST /config/initialize

### Description
Initializes the configuration files object and updates filenames based on the 'TOOLIUM_CONFIG_ENVIRONMENT' setting. It appends environment-specific and local-environment-specific property files to the configuration list.

### Method
POST

### Endpoint
/config/initialize

### Parameters
#### Request Body
- **tc_config_files** (object) - Optional - An instance of ConfigFiles to be initialized. If not provided, a new instance is created.

### Request Example
{
  "tc_config_files": null
}

### Response
#### Success Response (200)
- **config_files** (object) - The initialized configuration files object with updated environment properties.

#### Response Example
{
  "status": "success",
  "config_files": {
    "properties_files": ["properties.cfg", "prod-properties.cfg", "local-prod-properties.cfg"],
    "log_filename": "toolium_prod.log"
  }
}
```

--------------------------------

### Set Toolium Configuration Environment for Tests

Source: https://toolium.readthedocs.io/en/latest/_sources/driver_configuration.rst.txt

Use the TOOLIUM_CONFIG_ENVIRONMENT system property to select environment-specific configuration files. This allows for different property files for different testing setups, such as 'conf/android-properties.cfg'. Examples are shown for Nose2, Pytest, and Behave test runners.

```bash
$ TOOLIUM_CONFIG_ENVIRONMENT=android python -m nose2 web/tests/test_web.py
```

```bash
$ TOOLIUM_CONFIG_ENVIRONMENT=android python -m pytest web_pytest/tests/test_web_pytest.py
```

```bash
$ behave -D TOOLIUM_CONFIG_ENVIRONMENT=android
```

--------------------------------

### Scoring Guide

Source: https://toolium.readthedocs.io/en/latest/_sources/ai_utils.rst.txt

Guide for scoring the LLM's answer evaluation.

```APIDOC
## Scoring Guide

* **1.0**: Perfect semantic match - answer is equivalent to reference answer
* **0.7-0.9**: Similar meaning - minor differences that don't affect overall correctness
* **0.4-0.6**: Incomplete or partially similar - major differences or missing information
* **0.0-0.3**: Different, irrelevant or contradictory - does not match the reference answer
```

--------------------------------

### Creating and Executing a ReAct AI Agent

Source: https://toolium.readthedocs.io/en/latest/_sources/ai_utils.rst.txt

Shows how to initialize a ReAct agent using the create_react_agent utility and execute it with specific system instructions and tools.

```python
from toolium.utils.ai_utils.ai_agent import create_react_agent, execute_agent

# Create a ReAct agent with a system message and a tool method
system_message = "You are an assistant that helps users find TV content based on their preferences."
tool_method = tv_recommendations
provider = 'azure'
model_name = 'gpt-4o-mini'

agent = create_react_agent(system_message, tool_method=tool_method, provider=provider, model_name=model_name)

# Execute the agent and log all interactions
final_state = execute_agent(agent)
```

--------------------------------

### Initialize Additional Driver with Default Configuration

Source: https://toolium.readthedocs.io/en/latest/multiple_drivers.html

Demonstrates how to create a second driver instance using the existing configuration defined in properties.cfg. This is useful for running parallel sessions of the same browser type.

```ini
[Driver]
type: firefox
```

```python
second_wrapper = DriverWrapper()
second_wrapper.connect()
```

--------------------------------

### Configure Environment with System Property

Source: https://toolium.readthedocs.io/en/latest/changelog.html

Demonstrates how to use the 'Config_environment' system property to select configuration files for Toolium, such as specifying Android properties.

```bash
$ Config_environment=android nose2 web/tests/test_web.py
```

--------------------------------

### Configure Common Directories for Tests

Source: https://toolium.readthedocs.io/en/latest/_modules/toolium/driver_wrappers_pool.html

Sets up essential directories for tests, including configuration, output, and visual baseline directories. It prioritizes values from system properties, then test case specific configurations, and finally uses defaults. It ensures directories exist and are correctly path-resolved.

```python
@classmethod
def configure_common_directories(cls, tc_config_files):
        """Configure common config and output folders for all tests

        :param tc_config_files: test case specific config files
        """
        if cls.config_directory is None:
            # Get config directory from properties
            config_directory = cls.get_configured_value(
                'TOOLIUM_CONFIG_DIRECTORY',
                tc_config_files.config_directory,
                'conf',
            )
            prop_filenames = cls.get_configured_value(
                'TOOLIUM_CONFIG_PROPERTIES_FILENAMES',
                tc_config_files.config_properties_filenames,
                'properties.cfg',
            )
            cls.config_directory = cls._find_parent_directory(config_directory, prop_filenames.split(';')[0])

            # Get output directory from properties and create it
            cls.output_directory = cls.get_configured_value(
                'TOOLIUM_OUTPUT_DIRECTORY',
                tc_config_files.output_directory,
                'output',
            )
            if not os.path.isabs(cls.output_directory):
                # If output directory is relative, we use the same path as config directory
                cls.output_directory = os.path.join(os.path.dirname(cls.config_directory), cls.output_directory)
            makedirs_safe(cls.output_directory)

            # Get visual baseline directory from properties
            default_baseline = os.path.join(cls.output_directory, 'visualtests', 'baseline')
            cls.visual_baseline_directory = cls.get_configured_value(
                'TOOLIUM_VISUAL_BASELINE_DIRECTORY',
                tc_config_files.visual_baseline_directory,
                default_baseline,
            )
            if not os.path.isabs(cls.visual_baseline_directory):
                # If baseline directory is relative, we use the same path as config directory
                cls.visual_baseline_directory = os.path.join(
                    os.path.dirname(cls.config_directory),
                    cls.visual_baseline_directory,
                )
```

--------------------------------

### Initialize and Connect Default Driver Wrapper (Python)

Source: https://toolium.readthedocs.io/en/latest/_modules/toolium/driver_wrappers_pool.html

This method retrieves the default driver wrapper, initializes its configuration using provided config files, and establishes the WebDriver connection. It ensures a driver instance is available before returning it.

```Python
from toolium.driver_wrapper import DriverWrapper

class DriverWrappersPool:
    # ... other methods ...

    @classmethod
    def connect_default_driver_wrapper(cls, config_files=None):
        """Get default driver wrapper, configure it and connect driver

        :param config_files: driver wrapper specific config files
        :returns: default driver wrapper
        :rtype: toolium.driver_wrapper.DriverWrapper
        """
        driver_wrapper = cls.get_default_wrapper()
        if not driver_wrapper.driver:
            config_files = DriverWrappersPool.initialize_config_files(config_files)
            driver_wrapper.configure(config_files)
            driver_wrapper.connect()
        return driver_wrapper
```

--------------------------------

### GET /ai_utils/text_readability

Source: https://toolium.readthedocs.io/en/latest/index.html

Methods to assess the readability of a given text block using NLP analysis.

```APIDOC
## GET /ai_utils/text_readability

### Description
Analyzes the readability of a text block and returns metrics indicating complexity.

### Method
GET

### Endpoint
/ai_utils/text_readability

### Parameters
#### Query Parameters
- **text** (string) - Required - The text to analyze.

### Request Example
{
  "text": "This is a simple sentence for readability testing."
}

### Response
#### Success Response (200)
- **readability_score** (float) - The calculated readability metric.

#### Response Example
{
  "readability_score": 75.5
}
```

--------------------------------

### Initialize Additional Driver with Custom Configuration

Source: https://toolium.readthedocs.io/en/latest/multiple_drivers.html

Shows how to override the default configuration for a specific driver instance. This allows for testing with different platforms or browsers simultaneously.

```ini
[Driver]
type: android
```

```python
second_wrapper = DriverWrapper()
second_wrapper.config.set('Driver', 'type', 'firefox')
second_wrapper.connect()
```

--------------------------------

### GET /utils/readability/score

Source: https://toolium.readthedocs.io/en/latest/_modules/toolium/utils/ai_utils/text_readability.html

Calculates the readability score of a given text string based on linguistic density.

```APIDOC
## GET /utils/readability/score

### Description
Calculates the readability score of a text string. The score is determined by the ratio of linguistic tokens to total tokens, identifying OOV (Out-Of-Vocabulary) words, symbols, and technical characters as non-linguistic noise.

### Method
GET

### Endpoint
/utils/readability/score

### Parameters
#### Query Parameters
- **text** (string) - Required - The text content to assess.
- **model_name** (string) - Optional - The name of the spaCy model to use (defaults to 'en_core_web_md').
- **technical_chars** (list) - Optional - List of characters to treat as non-linguistic content.

### Request Example
{
  "text": "This is a standard sentence.",
  "model_name": "en_core_web_md"
}

### Response
#### Success Response (200)
- **readability** (float) - A score between 0.0 and 1.0 representing the readability density.

#### Response Example
{
  "readability": 0.95
}
```

--------------------------------

### Create and Execute a ReAct AI Agent

Source: https://toolium.readthedocs.io/en/latest/ai_utils.html

This snippet demonstrates how to initialize a ReAct agent using a system message and a tool method, and subsequently execute it. It requires the toolium.utils.ai_utils module and assumes a defined tool function for the agent to interact with the system under test.

```python
from toolium.utils.ai_utils.ai_agent import create_react_agent, execute_agent

system_message = "You are an assistant that helps users find TV content based on their preferences."
tool_method = tv_recommendations
provider = 'azure'
model_name = 'gpt-4o-mini'

agent = create_react_agent(system_message, tool_method=tool_method, provider=provider, model_name=model_name)

final_state = execute_agent(agent)
```

--------------------------------

### GET /ai_utils/text_similarity

Source: https://toolium.readthedocs.io/en/latest/index.html

Methods to calculate text similarity between two strings using different AI providers.

```APIDOC
## GET /ai_utils/text_similarity

### Description
Calculates the similarity score between two text inputs using various AI models or NLP libraries.

### Method
GET

### Endpoint
/ai_utils/text_similarity

### Parameters
#### Query Parameters
- **text1** (string) - Required - The first text string to compare.
- **text2** (string) - Required - The second text string to compare.
- **provider** (string) - Required - The engine to use: 'openai', 'azure_openai', 'sentence_transformers', or 'spacy'.

### Request Example
{
  "text1": "Hello world",
  "text2": "Hi there",
  "provider": "spacy"
}

### Response
#### Success Response (200)
- **score** (float) - The similarity score between 0 and 1.

#### Response Example
{
  "score": 0.85
}
```

--------------------------------

### Configure Chrome Extensions and Mobile Emulation

Source: https://toolium.readthedocs.io/en/latest/browser_configuration.html

Demonstrates how to load browser extensions and enable mobile device emulation using specific configuration sections.

```ini
[Driver]
type: chrome

[ChromeExtensions]
firebug: resources/firebug-lite.crx

[ChromeMobileEmulation]
deviceName: Google Nexus 5
```

--------------------------------

### Create Additional Driver Instance with Toolium

Source: https://toolium.readthedocs.io/en/latest/_sources/multiple_drivers.rst.txt

Demonstrates how to instantiate and connect an additional DriverWrapper. This allows for managing multiple browser sessions or device contexts within the same test execution. The default configuration is used if no specific settings are provided.

```python
second_wrapper = DriverWrapper()
second_wrapper.connect()
```

--------------------------------

### Interact with Page Elements

Source: https://toolium.readthedocs.io/en/latest/page_objects.html

Shows basic property access for getting or setting text, and how to access the underlying web element for advanced interactions.

```python
username = InputText(By.ID, 'username')

# Get text value
input_value = username.text

# Set text value
username.text = 'username'

# Access underlying web element
enabled = username.web_element.is_enabled()
```

--------------------------------

### Create a Second Driver Instance

Source: https://toolium.readthedocs.io/en/latest/changelog.html

Demonstrates how to instantiate and connect a second WebDriver instance using the DriverWrapper class. This is useful for scenarios requiring multiple browser contexts.

```python
from toolium.driver_wrapper import DriverWrapper

second_wrapper = DriverWrapper()
second_wrapper.connect()
```

--------------------------------

### Configure Chrome Capabilities and Options

Source: https://toolium.readthedocs.io/en/latest/browser_configuration.html

Shows how to handle special capability keys by replacing colons with triple underscores and setting additional Chrome options like performance logging.

```ini
[Capabilities]
goog___loggingPrefs: {'performance': 'ALL', 'browser': 'ALL', 'driver': 'ALL'}

[Chrome]
options: {'excludeSwitches': ['enable-automation'], 'perfLoggingPrefs': {'enableNetwork': True}}
binary: /usr/local/chrome_beta/chrome
```

--------------------------------

### Initialize Toolium Selenoid Module Imports

Source: https://toolium.readthedocs.io/en/latest/_modules/toolium/selenoid.html

This snippet shows the standard imports required for the toolium.selenoid module. It includes standard libraries for file system and time management, as well as requests for HTTP communication.

```python
import os
import time
from ast import literal_eval
import requests
from toolium.utils.path_utils import makedirs_safe
```

--------------------------------

### Configure Webview Context Selection

Source: https://toolium.readthedocs.io/en/latest/_sources/page_objects.rst.txt

Demonstrates how to use webview_csc_args to pass arguments to a webview context selection callback. Requires Appium version 1.17 or higher.

```python
login_button = Button(By.XPATH, "//*[@data-qsysid='subscription-counters']/div/div/", webview=True, webview_context_selection_callback = webview_context_selector_per_url, webview_csc_args = [driver_wrapper, WebviewConfigHelper.get_helper().account])
```

--------------------------------

### Define Remote Driver Capabilities

Source: https://toolium.readthedocs.io/en/latest/remote_configuration.html

Sets specific browser and platform requirements for remote drivers. This example demonstrates requesting a Windows environment with Internet Explorer 11.

```ini
[Driver]
type: iexplore

[Capabilities]
browserVersion: 11
platformName: windows
```

--------------------------------

### Create and Configure a New Driver Instance with Toolium

Source: https://toolium.readthedocs.io/en/latest/_sources/multiple_drivers.rst.txt

Shows how to create a new DriverWrapper and configure it with a different browser type than the default. This is useful for running tests in parallel across different environments or browsers. The configuration is set programmatically before connecting.

```python
second_wrapper = DriverWrapper()
second_wrapper.config.set('Driver', 'type', 'firefox')
second_wrapper.connect()
```

--------------------------------

### Get Text Readability with spaCy

Source: https://toolium.readthedocs.io/en/latest/toolium.utils.ai_utils.html

Calculates and returns the readability score of a given text using the spaCy library. Allows for specifying the spaCy model and additional parameters.

```APIDOC
## get_text_readability_with_spacy

### Description
Return the readability score of a text using spaCy.

### Method
(This is a Python function, not a direct HTTP API endpoint. Assuming a hypothetical API endpoint for demonstration.)
GET /api/text/readability/spacy

### Parameters
#### Query Parameters
- **text** (string) - Required - The string to assess readability.
- **model_name** (string) - Optional - Name of the spaCy model to use. Defaults to a standard model.
- **technical_chars** (list[string]) - Optional - List of technical characters to consider as non-linguistic content.
- **kwargs** (object) - Optional - Additional parameters to be used by spaCy (e.g., disable, exclude).

### Request Body
(Not applicable for this hypothetical GET example)

### Request Example
(Hypothetical GET request)
GET /api/text/readability/spacy?text=Another sample text for readability analysis.&model_name=en_core_web_sm

### Response
#### Success Response (200)
- **score** (float) - Readability score between 0 and 1.

#### Response Example
{
  "score": 0.72
}
```

--------------------------------

### Initialize and Configure Toolium Files by Environment

Source: https://toolium.readthedocs.io/en/latest/_modules/toolium/driver_wrappers_pool.html

This static method initializes configuration files and dynamically updates their names based on the configured environment. It appends environment-specific suffixes to property filenames and modifies the output log filename. This ensures that configuration and logs are segregated per environment. Dependencies include `ConfigFiles` class and `DriverWrappersPool` for environment retrieval.

```python
if tc_config_files is None:
            tc_config_files = ConfigFiles()

        # Update properties and log file names if an environment is configured
        env = DriverWrappersPool.get_configured_value('TOOLIUM_CONFIG_ENVIRONMENT', None, None)
        if env:
            # Update config properties filenames
            prop_filenames = tc_config_files.config_properties_filenames
            new_prop_filenames_list = prop_filenames.split(';') if prop_filenames else ['properties.cfg']
            base, ext = os.path.splitext(new_prop_filenames_list[0])
            new_prop_filenames_list.append(f'{env}-{base}{ext}')
            new_prop_filenames_list.append(f'local-{env}-{base}{ext}')
            tc_config_files.set_config_properties_filenames(*new_prop_filenames_list)

            # Update output log filename
            output_log_filename = tc_config_files.output_log_filename
            base, ext = os.path.splitext(output_log_filename) if output_log_filename else ('toolium', '.log')
            tc_config_files.set_output_log_filename(f'{base}_{env}{ext}')

        return tc_config_files
```

--------------------------------

### Get Text Similarity with spaCy

Source: https://toolium.readthedocs.io/en/latest/_modules/toolium/utils/ai_utils/text_similarity.html

Calculates the similarity between two texts using spaCy models. It preprocesses the texts to handle negations and uses word vectors for comparison.

```APIDOC
## GET /utils/ai/text_similarity/spacy

### Description
Calculates the similarity between two texts using spaCy. This method normalizes both texts before comparing them.

### Method
GET

### Endpoint
/utils/ai/text_similarity/spacy

### Parameters
#### Query Parameters
- **text** (string) - Required - The text to compare.
- **expected_text** (string) - Required - The text with the expected content.
- **model_name** (string) - Optional - The name of the spaCy model to use (e.g., 'en_core_web_md'). Defaults to the value in the configuration file.
- **kwargs** (dict) - Optional - Additional parameters to be used by spaCy (e.g., disable, exclude).

### Request Example
```python
from toolium.utils.ai_utils.text_similarity import get_text_similarity_with_spacy

text1 = "This is the first sentence."
text2 = "This is a similar sentence."
similarity = get_text_similarity_with_spacy(text1, text2, model_name='en_core_web_md')
print(f"Similarity score: {similarity}")
```

### Response
#### Success Response (200)
- **similarity** (float) - The similarity score between the two texts, ranging from 0 to 1.

#### Response Example
```json
{
  "similarity": 0.85
}
```
```

--------------------------------

### Initialize and Configure Toolium File Paths

Source: https://toolium.readthedocs.io/en/latest/_modules/toolium/config_files.html

The ConfigFiles class allows users to set specific directories and filenames for test configurations, output logs, and visual testing baselines. These methods update the internal state of the instance to ensure consistent file handling during test execution.

```python
class ConfigFiles:
    def __init__(self):
        self.config_directory = None
        self.output_directory = None
        self.visual_baseline_directory = None
        self.config_properties_filenames = None
        self.config_log_filename = None
        self.output_log_filename = None

    def set_config_directory(self, config_directory):
        self.config_directory = config_directory

    def set_output_directory(self, output_directory):
        self.output_directory = output_directory

    def set_visual_baseline_directory(self, visual_baseline_directory):
        self.visual_baseline_directory = visual_baseline_directory

    def set_config_properties_filenames(self, *filenames):
        self.config_properties_filenames = ';'.join(filenames)

    def set_config_log_filename(self, filename):
        self.config_log_filename = filename

    def set_output_log_filename(self, filename):
        self.output_log_filename = filename
```

--------------------------------

### Configuring Video Recording in Toolium

Source: https://toolium.readthedocs.io/en/latest/tests_result_analysis.html

This section shows how to enable video recording for test executions. It requires specific capabilities for Selenium Grid Extras or GGR, such as 'selenoid___options: {"enableVideo": True}'. Additionally, the 'video_enabled' property in the '[Server]' section of 'properties.cfg' can ensure videos are downloaded even for passing tests.

```ini
[Capabilities]
selenoid___options: {'enableVideo': True}

[Server]
video_enabled: true
```

--------------------------------

### Override Toolium properties via command line

Source: https://toolium.readthedocs.io/en/latest/_sources/bdd_integration.rst.txt

Example of how to override configuration properties defined in properties.cfg directly from the command line using Behave's -D flag.

```console
behave -D Driver_type=chrome
```

--------------------------------

### Set Up Azure OpenAI Credentials

Source: https://toolium.readthedocs.io/en/latest/_sources/ai_utils.rst.txt

Configures the necessary environment variables for authenticating with Azure OpenAI services. These variables include the API key, endpoint, and API version required for making requests.

```bash
AZURE_OPENAI_API_KEY=<your_api_key>
AZURE_OPENAI_ENDPOINT=<your_endpoint>
OPENAI_API_VERSION=<your_api_version>
```

--------------------------------

### Get Text Similarity with OpenAI

Source: https://toolium.readthedocs.io/en/latest/_modules/toolium/utils/ai_utils/text_similarity.html

Leverages OpenAI's Large Language Models (LLMs) to determine the semantic similarity between two texts. It returns a similarity score and an explanation.

```APIDOC
## GET /utils/ai/text_similarity/openai

### Description
Calculates the semantic similarity between two texts using an OpenAI LLM. It returns a similarity score (percentage) and an explanation.

### Method
GET

### Endpoint
/utils/ai/text_similarity/openai

### Parameters
#### Query Parameters
- **text** (string) - Required - The text to compare.
- **expected_text** (string) - Required - The text with the expected content.
- **model_name** (string) - Optional - The name of the OpenAI model to use (e.g., 'gpt-3.5-turbo'). Defaults to the value in the configuration file.
- **azure** (boolean) - Optional - Whether to use Azure OpenAI or standard OpenAI. Defaults to False.
- **kwargs** (dict) - Optional - Additional parameters to be used by the OpenAI client.

### Request Example
```python
from toolium.utils.ai_utils.text_similarity import get_text_similarity_with_openai

text1 = "What is the capital of France?"
text2 = "Paris is the capital city of France."
similarity_data = get_text_similarity_with_openai(text1, text2)
print(f"Similarity: {similarity_data['similarity']}")
print(f"Explanation: {similarity_data['explanation']}")
```

### Response
#### Success Response (200)
- **similarity** (float) - The similarity score between the two texts, ranging from 0 to 1.
- **explanation** (string) - An explanation for the calculated similarity score.

#### Response Example
```json
{
  "similarity": 0.95,
  "explanation": "The second text directly answers the question posed in the first text, confirming Paris as the capital of France."
}
```
```

--------------------------------

### Get Text Similarity with Sentence Transformers

Source: https://toolium.readthedocs.io/en/latest/_modules/toolium/utils/ai_utils/text_similarity.html

Compares the semantic similarity of two texts using Sentence Transformers models. It encodes the texts into embeddings and calculates the cosine similarity.

```APIDOC
## GET /utils/ai/text_similarity/sentence_transformers

### Description
Calculates the similarity between two texts using Sentence Transformers. This method encodes both texts into embeddings and computes the cosine similarity.

### Method
GET

### Endpoint
/utils/ai/text_similarity/sentence_transformers

### Parameters
#### Query Parameters
- **text** (string) - Required - The text to compare.
- **expected_text** (string) - Required - The text with the expected content.
- **model_name** (string) - Optional - The name of the Sentence Transformers model to use (e.g., 'all-mpnet-base-v2'). Defaults to the value in the configuration file.
- **kwargs** (dict) - Optional - Additional parameters to be used by SentenceTransformer (e.g., modules, device, prompts).

### Request Example
```python
from toolium.utils.ai_utils.text_similarity import get_text_similarity_with_sentence_transformers

text1 = "The quick brown fox jumps over the lazy dog."
text2 = "A fast, dark-colored fox leaps above a sleepy canine."
similarity = get_text_similarity_with_sentence_transformers(text1, text2, model_name='all-MiniLM-L6-v2')
print(f"Similarity score: {similarity}")
```

### Response
#### Success Response (200)
- **similarity** (float) - The similarity score between the two texts, ranging from 0 to 1.

#### Response Example
```json
{
  "similarity": 0.92
}
```
```

--------------------------------

### Python Pytest Fixtures for Driver Management

Source: https://toolium.readthedocs.io/en/latest/changelog.html

Introduces Pytest fixtures for easily starting and stopping WebDriver instances within test suites, simplifying driver lifecycle management.

```python
import pytest

@pytest.fixture(scope='session')
def driver():
    # Code to start the driver
    yield driver_instance
    # Code to stop the driver
```

--------------------------------

### Handle Concurrency with init_page_elements

Source: https://toolium.readthedocs.io/en/latest/_sources/page_objects.rst.txt

Explains how to define page elements as instance attributes using init_page_elements to avoid conflicts when using multiple driver instances simultaneously.

```python
from toolium.pageobjects.page_object import PageObject
from toolium.pageelements import InputText, Button

class LoginPageObject(PageObject):
    def init_page_elements(self):
        self.username = InputText(By.ID, 'username')
        self.password = InputText(By.ID, 'password')
        self.login_button = Button(By.XPATH, "//form[@id='login']/button")

    def login(self, username, password):
        self.username.text = username
        self.password.text = password
        self.login_button.click()
```

--------------------------------

### Configure Special Capabilities

Source: https://toolium.readthedocs.io/en/latest/_sources/browser_configuration.rst.txt

Demonstrates how to handle capabilities containing colons by replacing them with triple underscores to comply with ConfigParser limitations.

```ini
[Capabilities]
goog___loggingPrefs: {'performance': 'ALL', 'browser': 'ALL', 'driver': 'ALL'}
```

--------------------------------

### Use a Page Object in a Test (Python)

Source: https://toolium.readthedocs.io/en/latest/_sources/page_objects.rst.txt

Shows a basic example of how to use a previously defined page object (LoginPageObject) within a test function to perform actions like logging in.

```python
def test_login(self):
    LoginPageObject().login('user', 'pass')
    ...
```

--------------------------------

### POST /driver_wrappers_pool/connect

Source: https://toolium.readthedocs.io/en/latest/toolium.html

Connects and configures the default driver wrapper for the test session.

```APIDOC
## POST /driver_wrappers_pool/connect

### Description
Get the default driver wrapper, configure it, and establish the connection to the driver.

### Method
POST

### Endpoint
/driver_wrappers_pool/connect

### Parameters
#### Request Body
- **config_files** (list) - Optional - Specific configuration files for the driver wrapper.

### Request Example
{
  "config_files": ["properties.cfg"]
}

### Response
#### Success Response (200)
- **driver_wrapper** (object) - The initialized DriverWrapper instance.

#### Response Example
{
  "driver_wrapper": "<toolium.driver_wrapper.DriverWrapper object>"
}
```

--------------------------------

### Interact with Page Elements (Python)

Source: https://toolium.readthedocs.io/en/latest/_sources/page_objects.rst.txt

Illustrates common interactions with page elements, specifically an InputText element. It shows how to get the current text value and set a new text value.

```python
username = InputText(By.ID, 'username')

# Get text value
input_value = username.text

# Set text value
username.text = 'username'
```

--------------------------------

### POST /config/directories

Source: https://toolium.readthedocs.io/en/latest/_modules/toolium/driver_wrappers_pool.html

Configures the output directory structure for test artifacts including screenshots, videos, and visual regression tests.

```APIDOC
## POST /config/directories

### Description
Creates unique directories for screenshots, videos, logs, and visual tests based on a timestamp and driver information.

### Method
POST

### Endpoint
/config/directories

### Parameters
#### Request Body
- **driver_info** (string) - Optional - Identifier for the driver used to name the output folders.

### Request Example
{
  "driver_info": "chrome_desktop"
}

### Response
#### Success Response (200)
- **message** (string) - Confirmation that directories have been initialized.
- **paths** (object) - The generated paths for screenshots, videos, and logs.
```

--------------------------------

### Get Valid Filename - Python

Source: https://toolium.readthedocs.io/en/latest/_modules/toolium/utils/path_utils.html

Converts a given string into a valid filename by removing invalid characters, replacing them with underscores, and truncating to a maximum length. It handles leading/trailing spaces and specific separators.

```Python
import errno
import re
import unicodedata
from os import makedirs

FILENAME_MAX_LENGTH = 100

def get_valid_filename(s, max_length=FILENAME_MAX_LENGTH):
    """
    Returns the given string converted to a string that can be used for a clean filename.
    Removes leading and trailing spaces; converts anything that is not an alphanumeric,
    dash or underscore to underscore; converts behave examples separator ` -- @` to underscore.
    It also cuts the resulting name to `max_length`.

    @see https://github.com/django/django/blob/master/django/utils/text.py
    """
    s = str(s).strip().replace(' -- @', '_')
    s = re.sub(r'(?u)[^-\w]', '_', s).strip('_')
    # Remove accents to avoid errors in some filesystems
    nfkd_form = unicodedata.normalize('NFKD', s)
    s = ''.join([c for c in nfkd_form if not unicodedata.combining(c)])
    return s[:max_length]
```

--------------------------------

### Create Directories Safely - Python

Source: https://toolium.readthedocs.io/en/latest/_modules/toolium/utils/path_utils.html

Creates a directory at the specified path if it does not already exist. It handles potential `OSError` exceptions, specifically ignoring the case where the directory already exists.

```Python
import errno
import re
import unicodedata
from os import makedirs

def makedirs_safe(folder):
    """
    Create a new folder if it does not exist
    :param folder: folder path
    """
    try:
        makedirs(folder)
    except OSError as e:
        if e.errno != errno.EEXIST:
            raise
```

--------------------------------

### Behave Dynamic Environment Configuration

Source: https://toolium.readthedocs.io/en/latest/changelog.html

Enables the use of Behave's dynamic environment features, allowing for more flexible and context-aware test setup and teardown processes. More details are available in the Toolium documentation.

```python
# Example of a Behave environment.py file

def before_feature(context, feature):
    # Setup logic for the feature
    pass

def after_feature(context, feature):
    # Teardown logic for the feature
    pass

def before_scenario(context, scenario):
    # Setup logic for the scenario
    pass

def after_scenario(context, scenario):
    # Teardown logic for the scenario
    pass
```

--------------------------------

### Set Up Standard OpenAI Credentials

Source: https://toolium.readthedocs.io/en/latest/_sources/ai_utils.rst.txt

Configures the environment variable for authenticating with standard OpenAI services. This variable contains the API key needed to interact with OpenAI models.

```bash
OPENAI_API_KEY=<your_api_key>
```

--------------------------------

### Find Parent Directory with Specific File

Source: https://toolium.readthedocs.io/en/latest/_modules/toolium/driver_wrappers_pool.html

Searches upwards in the directory tree from a given starting point to find a directory that contains a specific filename. This is useful for locating configuration files or project roots.

```python
@staticmethod
def _find_parent_directory(directory, filename):
        """Find a directory in parent tree with a specific filename

        :param directory: directory name to find
        :param filename: filename to find
        :returns: absolute directory path
        """
        parent_directory = directory
        absolute_directory = '.'
        while absolute_directory != os.path.abspath(parent_directory):
            absolute_directory = os.path.abspath(parent_directory)
            if os.path.isfile(os.path.join(absolute_directory, filename)):
                return absolute_directory
            if os.path.isabs(parent_directory):
                parent_directory = os.path.join(
                    os.path.dirname(parent_directory),
                    '..',
                    os.path.basename(parent_directory),
                )
            else:
                parent_directory = os.path.join('..', parent_directory)
        return os.path.abspath(directory)
```

--------------------------------

### Configure Basic Browser Driver Settings

Source: https://toolium.readthedocs.io/en/latest/browser_configuration.html

Sets the browser type and window dimensions in the [Driver] section of the configuration file.

```ini
[Driver]
type: firefox
window_width: 1024
window_height: 768
```

--------------------------------

### Get Default Configuration Directory

Source: https://toolium.readthedocs.io/en/latest/_modules/toolium/driver_wrappers_pool.html

Determines and returns the default configuration directory based on the current test's file path. This function helps in locating configuration files relative to the test execution context.

```python
@staticmethod
def get_default_config_directory():
        """Return default config directory, based in the actual test path

        :returns: default config directory
        """
        test_path = os.path.dirname(os.path.realpath(inspect.getouterframes(inspect.currentframe())[2][1]))
        return os.path.join(test_path, 'conf')
```

--------------------------------

### Configure Behave Environment for Toolium

Source: https://toolium.readthedocs.io/en/latest/changelog.html

Demonstrates how to integrate Toolium with Behave tests by initializing the Toolium wrapper within a Behave environment file. This allows Toolium configurations to be accessed via context.toolium_config.

```python
from toolium import Toolium

def before_scenario(context, scenario):
    context.toolium_config = Toolium()
    context.toolium_config.connect()
```

--------------------------------

### Get Default Driver Wrapper (Python)

Source: https://toolium.readthedocs.io/en/latest/_modules/toolium/driver_wrappers_pool.html

This method returns the default driver wrapper from the pool. If the pool is empty, it initializes a new DriverWrapper instance and adds it to the pool before returning it. This ensures a driver is always available.

```Python
from toolium.driver_wrapper import DriverWrapper

class DriverWrappersPool:
    # ... other methods ...

    @classmethod
    def get_default_wrapper(cls):
        """Returns the default (first) driver wrapper

        :returns: default driver wrapper
        :rtype: toolium.driver_wrapper.DriverWrapper
        """
        if cls.is_empty():
            # Create a new driver wrapper if the pool is empty
            DriverWrapper()
        return cls.driver_wrappers[0]
```

--------------------------------

### ConfigFiles Methods

Source: https://toolium.readthedocs.io/en/latest/genindex.html

Methods for setting configuration file related properties.

```APIDOC
## set_config_directory()

### Description
Sets the configuration directory.

### Method
Method

### Endpoint
N/A (Method)

### Parameters
None

### Request Example
None

### Response
None

## set_config_log_filename()

### Description
Sets the configuration log filename.

### Method
Method

### Endpoint
N/A (Method)

### Parameters
None

### Request Example
None

### Response
None

## set_config_properties_filenames()

### Description
Sets the configuration properties filenames.

### Method
Method

### Endpoint
N/A (Method)

### Parameters
None

### Request Example
None

### Response
None

## set_output_directory()

### Description
Sets the output directory.

### Method
Method

### Endpoint
N/A (Method)

### Parameters
None

### Request Example
None

### Response
None

## set_output_log_filename()

### Description
Sets the output log filename.

### Method
Method

### Endpoint
N/A (Method)

### Parameters
None

### Request Example
None

### Response
None

## set_visual_baseline_directory()

### Description
Sets the visual baseline directory.

### Method
Method

### Endpoint
N/A (Method)

### Parameters
None

### Request Example
None

### Response
None
```

--------------------------------

### Define Accuracy Data for Behave Scenarios

Source: https://toolium.readthedocs.io/en/latest/_sources/ai_utils.rst.txt

Provides an example of how to define accuracy data as a list of dictionaries in Python for use with accuracy data tags in Behave scenarios. This structure allows for parameterized testing of AI responses.

```python
accuracy_data_greetings = [

```
Tokens:
Raw