### Topology Configuration for 2 Hosts

Source: https://github.com/intel/pytest-mfd-config/blob/main/README.md

Example of a valid topology configuration file for a 2-host setup, including host details, network interfaces, connections, and power management configurations.

```yaml
---
metadata:
  version: '2.5'
hosts:
- name: Marilyn
  instantiate: true                 # Determines whether Host object shall be created or not
  role: sut
  network_interfaces:               # optional
  - speed: 100G                     # determines all interface from the machine host which support provided speed
    interface_index: 0              # determines first interface from the group above (speed support)
  connections:
  - ip_address: 10.10.10.10         # IP address of MGMT connection
    connection_type: RPyCConnection
  power_mng:
    power_mng_type: Ipmi
    host: host
    username: root
    password: pass
    connection:
      ip_address: 10.10.10.11
      connection_type: RPyCConnection
- name: Marilyn-Client
  instantiate: true                 # determines whether Host object shall be created or not
  role: client
  network_interfaces:               # optional
  - interface_name: ens192          # determines which exactly interface should be chosen
  connections:
  - ip_address: 10.10.10.12         # IP address of MGMT connection
    connection_type: RPyCConnection
  power_mng:
    power_mng_type: Raritan
    ip: 1.1.1.1
    community_string: private
```

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

### Configure Hosts in YAML

Source: https://github.com/intel/pytest-mfd-config/blob/main/README.md

YAML configuration examples for defining host topologies, including regular and IPU machine types.

```YAML
hosts:                              # each of the element of the topology_configs file is optional, but once provided we validate whether mandatory params are provided
- name: Catherine                   # mandatory
  mng_ip_address: 10.1.2.3          # optional
  mng_user: foo                     # optional
  mng_password: bar                 # optional
  instantiate: false                # mandatory - determines whether Host object should be instantiated when using fixture
  role: sut                         # mandatory
  network_interfaces:               # optional
  - interface_name: eth1
  - pci_address: 0000:ff:ff.1a
  - pci_device: 8086:1572:0000:0001
    interface_index: 1
    ips:
     - value: 1.1.1.3
       mask: 8
  extra_info:
    datastore:
      - "datastore1"
      - "datastore2"
    suffix: "blabla" 
- name: Catherine-Client
  instantiate: false
  role: client
  network_interfaces:               # optional
  - speed: 40G                      # Choose any interface from the machine host which supports 40G speed
    random_interface: true          # Choose any interface from the group above (speed support)
  - family: CPK                     # Choose any interface from the machine host which supports CPK family
    interface_index: 0              # Determines interface index from list of interfaces which meet family condition
- (...)
```

```YAML
hosts:                              # each of the element of the topology_configs file is optional, but once provided we validate whether mandatory params are provided
- name: Catherine                   # mandatory
  machine_type: ipu
  ipu_host_type: IMC
  instantiate: false                # mandatory - determines whether Host object should be instantiated when using fixture
  role: sut                         # mandatory
  network_interfaces:               # optional
  - interface_name: eth1
  - pci_address: 0000:ff:ff.1a
- name: Catherine-Client
  instantiate: false
  role: client
  network_interfaces:               # optional
  - speed: 40G                      # Choose any interface from the machine host which supports 40G speed
    random_interface: true          # Choose any interface from the group above (speed support)
  - family: CPK                     # Choose any interface from the machine host which supports CPK family
    interface_index: 0              # Determines interface index from list of interfaces which meet family condition
- (...)
```

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

### CLI Options

Source: https://github.com/intel/pytest-mfd-config/blob/main/README.md

After installing the plugin, new command-line options become available when running pytest. These options can be viewed by invoking 'pytest --help'.

```APIDOC
## CLI Options

After successful installation when you invoke `pytest --help` you should see new options in the output:

![](docs/img/custom_options.png)
```

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

### Handle NotUniqueHostsNamesError

Source: https://github.com/intel/pytest-mfd-config/blob/main/README.md

Example of the exception raised when host names are not unique in the YAML configuration.

```shell
>  raise NotUniqueHostsNamesError("Hosts 'name' field must be unique in YAML topology, stopping...")
E  pytest_mfd_config.utils.exceptions.NotUniqueHostsNamesError: Hosts 'name' field must be unique in YAML topology, stopping...
```

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

### Network Interface Identification Combinations

Source: https://github.com/intel/pytest-mfd-config/blob/main/README.md

Examples of allowed combinations for identifying network interfaces in a topology file.

```APIDOC
## Network Interface Identification Combinations

### Allowed Combinations:

*   **Using `pci_address`**:
    ```yaml
    (...) 
      network_interfaces:                # optional
      - pci_address: 0000:ff:ff.1        # determines interface by unique long PCI Address
    (...)
      network_interfaces:                # optional
      - pci_address: ff:ff.1             # determines interface by unique short PCI Address (default `domain` is used: `0000`)
    ```

*   **Using `interface_name`**:
    ```yaml
      network_interfaces:                # optional
      - interface_name: eth1
    ```

*   **Using `pci_device` + `interface_index`/`interface_indexes`**:
    ```yaml
      network_interfaces:                # optional
      - pci_device: 8086:1572            # short PCIDevice: vid:did
        interface_index: 0               # list index
    (...)
      network_interfaces:                # optional
      - pci_device: 8086:1572:0000:0001a # long PCIDevice: vid:did:subvid:subdid
        interface_index: 2               # list index
    ```

*   **Using `pci_device` + `random_interface`**:
    ```yaml
      network_interfaces:                # optional
      - pci_device: 8086:1572            # short PCIDevice: vid:did
        random_interface: true           # determines random interface from list of interfaces when pci_device is as above
    ```

*   **Using `pci_device` + `all_interfaces`**:
    ```yaml
      network_interfaces:                # optional
      - pci_device: 8086:1572            # short PCIDevice: vid:did
        all_interfaces: true             # determines all interfaces for NIC `1572`
    ```

*   **Using `speed` + `interface_index`/`interface_indexes`**:
    ```yaml
      network_interfaces:                # optional
      - speed: 40G                       # determines all interface IDs supporting 40G speed provided in SPEED_IDS (mfd-const)
        interface_index: 0               # list index
    (...)
      network_interfaces:                # optional
      - speed: 100G                      # possible formats: 100G, 100g, 100, 100G, 100g, 100giga, 100Giga, 100GIGA, 100Gb
        interface_index: 3               # list index
    ```

*   **Using `speed` + `all_interfaces`**:
    ```yaml
      network_interfaces:                # optional
      - speed: 40G                       # determines all interface IDs supporting 40G speed provided in SPEED_IDS (mfd-const)
        all_interfaces: true             # determines all interfaces supported provided speed from SPEED_IDS (mfd-const)
      network_interfaces:                # optional
      - speed: 100G                      # possible formats: 100G, 100g, 100, 100G, 100g, 100giga, 100Giga, 100GIGA, 100Gb
        interface_index: -1              # list index
    ```

*   **Using `speed` + `random_interface`**:
    ```yaml
    ```
```

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

### Network Interface Configuration Examples

Source: https://context7.com/intel/pytest-mfd-config/llms.txt

Define network interfaces in YAML using various identifiers like PCI address, interface name, speed, family, or device ID with index. Supports specifying IP addresses, subnet masks, switch details, and VLANs.

```yaml
# topology_interfaces.yaml
---
metadata:
  version: '2.5'
hosts:
- name: multi-nic-host
  instantiate: true
  role: sut
  network_interfaces:
  # By exact PCI address
  - pci_address: 0000:18:00.0

  # By interface name
  - interface_name: eth1

  # By PCI device ID with index
  - pci_device: 8086:1572
    interface_index: 0
    ips:
      - value: 192.168.1.10
        mask: 24
    switch_name: Dell-Switch-01
    switch_port: eth1/1
    vlan: "100"

  # By speed with random selection
  - speed: 100G
    random_interface: true

  # By family with all interfaces
  - family: CVL
    all_interfaces: true

  # By speed and family combination
  - speed: 40G
    family: SGVL
    interface_index: 0

  # Multiple indexes from same device
  - pci_device: 8086:1592
    interface_indexes: [0, 1, 2]

  connections:
  - ip_address: 10.0.0.1
    connection_type: RPyCConnection
```

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

### Pydantic ValidationError Example

Source: https://github.com/intel/pytest-mfd-config/blob/main/README.md

This example demonstrates a Pydantic ValidationError that occurs when extra fields are provided in the topology configuration, which are not permitted by the model's config.

```shell
E   pydantic.error_wrappers.ValidationError: 1 validation error for TopologyModel
E   hosts -> 0 -> connections -> 0 -> dunno
E     extra fields not permitted (type=value_error.extra)
```

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

### Accessing Host Information and Connections

Source: https://context7.com/intel/pytest-mfd-config/llms.txt

Demonstrates how to access host objects, their primary and specific connections, network interfaces, and power management functionalities. Use this to interact with individual hosts in your test environment.

```python
import pytest
from pytest_mfd_config.fixtures import create_host_from_model

def test_ping_between_hosts(hosts):
    """Test network connectivity between SUT and client."""
    sut = hosts["sut"]
    client = hosts["client"]

    # Access the primary connection
    result = sut.connection.run("ping -c 4 192.168.1.20")
    assert result.exit_code == 0

    # Access specific connection types
    ssh_conn = client.connections.ssh
    rpyc_conn = sut.connections.rpyc

    # Access network interfaces
    for iface in sut.network_interfaces:
        print(f"Interface: {iface.name}, IP: {iface.ip}")

    # Access power management
    if sut.power_mng:
        sut.power_mng.power_cycle()
```

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

### Run Tests with CLI Options

Source: https://context7.com/intel/pytest-mfd-config/llms.txt

Use these commands to execute tests with specific topology and test configurations, or to override parameters at runtime.

```bash
# Run tests with topology and test configuration
pytest tests/ --topology_config=configs/topology.yaml --test_config=configs/test_config.yaml

# Overwrite specific test parameters at runtime
pytest tests/test_ping.py --test_config=configs/bat_config.yaml \
    --topology_config=configs/topology.yaml \
    --overwrite "test_ping_connectivity:count=4"

# Overwrite multiple test parameters across different tests
pytest tests/ --test_config=configs/config.yaml \
    --overwrite "test_rxtx:sem_rules=lem,used_cp=dcpc;test_platform:platform=xeon"
```

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

### Configuring Switch Ports and VLANs

Source: https://context7.com/intel/pytest-mfd-config/llms.txt

This snippet shows how to configure switch ports, including setting VLANs, enabling/disabling ports, and retrieving port status. It requires the switches and hosts fixtures.

```python
def test_switch_configuration(switches, hosts):
    """Configure switch ports for test hosts."""
    for switch in switches:
        # Get switch information
        print(f"Connected to: {switch.topology.name}")

        # Configure VLANs on ports
        switch.set_vlan(port="eth1/1", vlan="100")

        # Enable/disable ports
        switch.enable_port("eth1/1")
        switch.disable_port("eth1/2")

        # Get port status
        status = switch.get_port_status("eth1/1")
        print(f"Port status: {status}")
```

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

### Manually Creating Host Objects

Source: https://context7.com/intel/pytest-mfd-config/llms.txt

Instantiate Host objects from HostModel for manual configuration, especially when `instantiate: false` is set in the topology. This allows for creating individual components like connections and power management objects.

```python
from pytest_mfd_config.fixtures import (
    create_host_from_model,
    create_host_connections_from_model,
    create_power_mng_from_model,
    create_switch_from_model,
    get_connection_object
)

def test_manual_host_creation(topology):
    """Manually create hosts with custom configuration."""
    # Find host model by name
    host_model = next(h for h in topology.hosts if h.name == "delayed_sut")

    # Create full Host object with all connections
    host = create_host_from_model(host_model=host_model)

    # Or create individual components
    connections = create_host_connections_from_model(host_model)

    if host_model.power_mng:
        power_mng = create_power_mng_from_model(host_model.power_mng)
        power_mng.power_on()

    # Create individual connection from model
    conn_model = host_model.connections[0]
    connection = get_connection_object(conn_model)

    # Use the connection
    result = connection.run("hostname")
    print(f"Connected to: {result.stdout}")

    # Clean up
    connection.close()
```

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

### Host Configuration Methods

Source: https://github.com/intel/pytest-mfd-config/blob/main/README.md

Methods for creating host, switch, and connection objects from model data.

```APIDOC
## Host Configuration Methods

### Description
Utility methods to instantiate Host, Switch, PowerManagement, and Connection objects based on provided model data.

### Methods
- create_host_from_model(host_model: HostModel) -> Host
- create_host_connections_from_model(host_model: HostModel) -> List[AsyncConnection]
- create_switch_from_model(switch_model: SwitchModel) -> Switch
- create_power_mng_from_model(power_mng_model: PowerMngModel) -> PowerManagement
- get_connection_object(connection_model: ConnectionModel, connection_list: List[AsyncConnection] = None, relative_connection: AsyncConnection = None) -> AsyncConnection
```

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

### Generate Documentation

Source: https://github.com/intel/pytest-mfd-config/blob/main/sphinx-doc/README.md

Run this command in the activated virtual environment within the Pytest-Mfd-Config directory to generate the project's documentation.

```shell
$ python generate_docs.py
```

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

### Placeholder YAML Views

Source: https://github.com/intel/pytest-mfd-config/blob/main/README.md

Placeholders for VM and Container configurations.

```yaml
<TBD>
```

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

### Manually Instantiating a Host

Source: https://context7.com/intel/pytest-mfd-config/llms.txt

Use this fixture to manually instantiate a host that was not automatically created based on topology configuration. It requires the topology and existing hosts fixtures.

```python
@pytest.fixture()
def updated_hosts(topology, hosts):
    """Manually instantiate a host that was not auto-instantiated."""
    host_model = next(host for host in topology.hosts if host.name == "delayed_host")
    host = create_host_from_model(host_model=host_model)
    hosts[host.name] = host
    return hosts
```

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

### Instantiate Host from Model

Source: https://github.com/intel/pytest-mfd-config/blob/main/README.md

Use this fixture to prepare a Host object from Host model data. It's useful when you need to dynamically create host instances within your tests.

```python
import pytest

from pytest_mfd_config.fixtures import create_host_from_model

@pytest.fixture()
def updated_hosts(topology, hosts):
    host_model = next(host for host in topology.hosts if host.name == "name")
    host = create_host_from_model(host_model=host_model)
    hosts[host.name] = hosts
    return hosts
```

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

### Configure Network Interfaces

Source: https://github.com/intel/pytest-mfd-config/blob/main/README.md

YAML configurations for defining network interfaces using speed, family, and selection strategies.

```yaml
  network_interfaces:                # optional
  - speed: 40G                       # determines all interface IDs supporting 40G speed provided in SPEED_IDS (mfd-const)
    random_interface: true           # determines random interface
```

```yaml
  network_interfaces:                # optional
  - speed: 40G                       # determines all interface IDs supporting 40G speed provided in SPEED_IDS (mfd-const)
    family: SGVL                     # determines all interfaces from provided family (full list accessible in DEVICE_IDS (mfd-const))
    random_interface: true           # determines random interface
```

```yaml
  network_interfaces:                # optional
  - speed: 40G                       # determines all interface IDs supporting 40G speed provided in SPEED_IDS (mfd-const)
    family: CVL                      # determines all interfaces from provided family (full list accessible in DEVICE_IDS (mfd-const))
    all_interfaces: true             # determines all interfaces from `speed` and `family` groups above
```

```yaml
  network_interfaces:                # optional
  - family: SGVL                     # determines all interfaces from provided family (full list accessible in DEVICE_IDS (mfd-const))
    interface_index: 1               # determines index of interfaces which should be chosen from list determines by `family`
```

```yaml
  network_interfaces:                # optional
  - family: NNT                     # determines all interfaces from provided family (full list accessible in DEVICE_IDS (mfd-const))
    random_interface: true             # determines all interfaces from `speed` and `family` groups above
```

```yaml
  network_interfaces:                # optional
  - family: CNV                      # determines all interfaces from provided family (full list accessible in DEVICE_IDS (mfd-const))
    all_interfaces: true             # determines all interfaces from `speed` and `family` groups above
```

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

### Define Hardware Topology

Source: https://context7.com/intel/pytest-mfd-config/llms.txt

YAML configuration for defining hosts, switches, and their associated connections and interfaces.

```yaml
# topology.yaml
---
metadata:
  version: '2.5'
hosts:
- name: sut
  mng_ip_address: 10.0.0.1
  mng_user: admin
  mng_password: secret123
  instantiate: true
  role: sut
  network_interfaces:
  - pci_device: 8086:1572
    interface_index: 0
    ips:
      - value: 192.168.1.10
        mask: 24
  connections:
  - ip_address: 10.0.0.1
    connection_type: RPyCConnection
  power_mng:
    power_mng_type: Ipmi
    host: bmc.example.com
    username: root
    password: bmcpass
    connection:
      ip_address: 10.0.0.100
      connection_type: RPyCConnection
  extra_info:
    datastore:
      - "datastore1"
      - "datastore2"
    suffix: "test-env"
- name: client
  mng_ip_address: 10.0.0.2
  instantiate: true
  role: client
  network_interfaces:
  - interface_name: eth1
  - pci_address: 0000:18:00.0
  connections:
  - ip_address: 10.0.0.2
    connection_type: SSHConnection
    connection_options:
      username: testuser
      password: testpass
switches:
- name: Dell-Switch-01
  mng_ip_address: 10.0.0.254
  mng_user: admin
  mng_password: switchpass
  instantiate: true
  switch_type: DellOS9_7000
  device_type: Dell
  connection_type: SSHSwitchConnection
  switch_ports: ['eth1/1', 'eth1/2']
  vlans: ['100', '200', '300']
```

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

### Inject Configuration Parameters into Tests

Source: https://github.com/intel/pytest-mfd-config/blob/main/README.md

Passing configuration files via CLI and accessing values as test parameters.

```shell
--test_config=configs\examples\test_config_example.yaml
```

```yaml
interval: 1.0
count: 3
direction: both
```

```python

def test_ping_parametrize(interval, count, direction):
    print(interval)  # 1.0
    print(count)  # 3
    print(direction)  # 'both'
    pass # write some nice stuff here
```

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

### Injecting Test Parameters from Configuration

Source: https://context7.com/intel/pytest-mfd-config/llms.txt

Demonstrates how test parameters like 'interval', 'count', and 'direction' are automatically injected into test methods from the test_config.yaml file. Ensure these parameters are defined in your configuration.

```python
def test_parametrized_from_config(interval, count, direction):
    """Test parameters automatically injected from test_config.yaml."""
    # interval=1.0, count=3, direction="both" from config
    print(f"Running test with interval={interval}, count={count}, direction={direction}")
    assert interval > 0
    assert count > 0
    assert direction in ["both", "send", "receive"]
```

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

### Machine Configuration Models

Source: https://github.com/intel/pytest-mfd-config/blob/main/README.md

Base models for hardware components like switches and hosts, supporting power management and secret handling.

```APIDOC
## MachineModel

### Description
Base model for hardware components. Inherits from InstantiateBaseModel.

### Parameters
- **instantiate** (bool) - Optional - Determines whether the fixture should instantiate the object.
- **name** (str) - Optional - Name of the machine.
- **mng_ip_address** (IPvAnyAddress) - Optional - BMC or Switch management IP.
- **mng_user** (str) - Optional - Management username.
- **mng_password** (SecretStr) - Optional - Management password (masked in logs).
- **power_mng** (PowerMngModel) - Optional - Power management configuration.

### PowerMngModel
- **power_mng_type** (str) - Required - Type of power management.
- **connection** (ConnectionModel) - Optional - Connection details.
- **host** (str) - Optional - Host address.
- **ip** (str) - Optional - IP address.
- **username** (str) - Optional - Username.
- **password** (SecretStr) - Optional - Password.
- **udp_port** (int) - Optional - UDP port.
- **community_string** (str) - Optional - SNMP community string.
- **outlet_number** (int) - Optional - Outlet identifier.
```

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

### HostModel Configuration

Source: https://github.com/intel/pytest-mfd-config/blob/main/README.md

Defines the structure and parameters for configuring host models in YAML.

```APIDOC
## HostModel Configuration

### Description
Configuration for host models, including Systems Under Tests (SUT), management or RPC connections, and NIC interface details. It can reflect connections between Switch ports and NIC ports and includes extra information like datastore or suffix for VMs. It also details the type of machine, such as 'regular' or 'ipu', and the IPU host type from mfd-typing as an `IPUHostType` entry.

### YAML View

```yaml
hosts:
  - name: Catherine                   # mandatory
    mng_ip_address: 10.1.2.3          # optional
    mng_user: foo                     # optional
    mng_password: bar                 # optional
    instantiate: false                # mandatory - determines whether Host object should be instantiated when using fixture
    role: sut                         # mandatory
    network_interfaces:               # optional
      - interface_name: eth1
      - pci_address: 0000:ff:ff.1a
      - pci_device: 8086:1572:0000:0001
        interface_index: 1
        ips:
          - value: 1.1.1.3
            mask: 8
    extra_info:
      datastore:
        - "datastore1"
        - "datastore2"
      suffix: "blabla"
    machine_type: regular | ipu       # optional, default is 'regular'
    ipu_host_type: IPUHostType        # mandatory if machine_type is 'ipu'

  - name: Catherine-Client
    instantiate: false
    role: client
    network_interfaces:               # optional
      - speed: 40G                      # Choose any interface from the machine host which supports 40G speed
        random_interface: true          # Choose any interface from the group above (speed support)
      - family: CPK                     # Choose any interface from the machine host which supports CPK family
        interface_index: 0              # Determines interface index from list of interfaces which meet family condition
```

### Constraints
- The `name` field for each host must be unique. Duplicate names will result in a `NotUniqueHostsNamesError`.
- If `machine_type` is set to `ipu`, the `ipu_host_type` field is mandatory and must be a valid value from `IPUHostType`.

### ExtraInfoModel

#### Description
Represents extra information about a Host.

#### Fields
- **suffix** (string) - Optional. Suffix to avoid duplication across different systems.
- **datastore** (list of strings) - Optional. List of available datastore names to be used for VMs.
- Any additional key=value pairs are accepted.
```

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

### Select All Interfaces by Speed in YAML

Source: https://github.com/intel/pytest-mfd-config/blob/main/README.md

Selects all network interfaces that support a specified speed. The speed can be provided in various formats.

```yaml
network_interfaces:
  - speed: 40G                       # determines all interface IDs supporting 40G speed provided in SPEED_IDS (mfd-const)
    all_interfaces: true             # determines all interfaces supported provided speed from SPEED_IDS (mfd-const)
```

```yaml
network_interfaces:
  - speed: 100G                      # possible formats: 100G, 100g, 100, 100G, 100g, 100giga, 100Giga, 100GIGA, 100Gb
    interface_index: -1              # list index
```

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

### Jinja2 Configuration Inclusion

Source: https://github.com/intel/pytest-mfd-config/blob/main/README.md

Using Jinja2 to include and indent configuration files.

```yaml
# test_config.yaml
param1: value1
{% include 'another_test_config.yaml' %}
```

```yaml
# another_test_config.yaml
param2: value2
```

```yaml
# when you pass test_config.yaml to the test it will be rendered as:
param1: value1
param2: value2
```

```yaml
# test_config.yaml
param1: value1
params:
  - some: thing
    another: thing
    {% include 'another_test_config.yaml' indent content %}
```

```yaml
# another_test_config.yaml
param2: value2
param3: value3
```

```yaml
# when you pass test_config.yaml to the test it will be rendered as:
param1: value1
params:
  - some: thing
    another: thing
    param2: value2
    param3: value3
```

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

### Accessing the Full Test Configuration Dictionary

Source: https://context7.com/intel/pytest-mfd-config/llms.txt

This test shows how to access the entire test configuration dictionary loaded from the YAML file. It includes accessing top-level parameters and nested structures like 'connections'.

```python
def test_access_full_config(test_config):
    """Access the complete test configuration dictionary."""
    print(f"Interval: {test_config['interval']}")
    print(f"Count: {test_config['count']}")

    # Access nested configuration
    connections = test_config.get('connections', [])
    for conn in connections:
        print(f"Connection: {conn['hosts']}, Bidirectional: {conn['bidirectional']}")
```

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

### Define Test Configuration

Source: https://context7.com/intel/pytest-mfd-config/llms.txt

YAML configuration for test parameters, supporting Jinja2 templating for modularity.

```yaml
# test_config.yaml
interval: 1.0
count: 3
direction: both
pcap_file: capture.pcap
connections:
  - bidirectional: no
    hosts: [sut, client]
  - bidirectional: yes
    hosts: [sut, imc]
secrets:
  - name: vault_password
    value: gAAAAABnVxEZ...encrypted_value...
  - name: api_key
    value: gAAAAABnVxEZ...encrypted_value...
```

```yaml
# common_params.yaml
timeout: 30
retry_count: 3

# test_config_with_include.yaml
{% include 'common_params.yaml' %}
test_specific_param: value1
nested:
  - some: thing
    another: thing
    {% include 'more_params.yaml' indent content %}
```

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

### Define Topology Connections in YAML

Source: https://context7.com/intel/pytest-mfd-config/llms.txt

Configuration schema for defining multiple connection types for a single host, including support for jump hosts and relative serial connections.

```yaml
metadata:
  version: '2.5'
hosts:
- name: multi-connection-host
  instantiate: true
  role: sut
  connections:
  # RPyC connection (primary)
  - connection_id: 0
    ip_address: 10.0.0.1
    connection_type: RPyCConnection

  # SSH connection
  - connection_id: 1
    ip_address: 10.0.0.1
    connection_type: SSHConnection
    connection_options:
      username: testuser
      password: testpass
      port: 22

  # Tunneled SSH through jump host
  - connection_id: 2
    ip_address: 192.168.1.100
    connection_type: TunneledSSHConnection
    connection_options:
      username: remote_user
      password: remote_pass
      jump_host_ip: 10.0.0.1
      jump_host_username: jumpuser
      jump_host_password: jumppass

  # Serial connection (requires relative connection)
  - connection_id: 3
    connection_type: SerialConnection
    relative_connection_id: 0
    connection_options:
      port: /dev/ttyUSB0
      baudrate: 115200

  # Telnet connection
  - connection_id: 4
    ip_address: 10.0.0.1
    connection_type: TelnetConnection
    connection_options:
      port: 23
```

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

### Select All Interfaces by PCI Device in YAML

Source: https://github.com/intel/pytest-mfd-config/blob/main/README.md

Selects all network interfaces associated with a given PCI device identifier.

```yaml
network_interfaces:
  - pci_device: 8086:1572            # short PCIDevice: vid:did
    all_interfaces: true             # determines all interfaces for NIC `1572`
```

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

### Access Network Interfaces in Tests

Source: https://github.com/intel/pytest-mfd-config/blob/main/README.md

Accessing network interfaces via the hosts fixture.

```python
def test_ping(hosts) -> None:
    sut_interfaces = hosts["sut"].network_interfaces
```

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

### Configure External Services

Source: https://github.com/intel/pytest-mfd-config/blob/main/README.md

Defines the structure for external services like DHCP or NSX used during test automation.

```yaml
services:
- type: nsx
  label: my_label
  username: foo
  password: bar
  ip_address: 1.2.3.4
- (...)
```

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

### Topology Configuration Schema

Source: https://github.com/intel/pytest-mfd-config/blob/main/README.md

The root configuration model for defining infrastructure topology, including switches, services, hosts, VMs, and containers.

```APIDOC
## TopologyModel

### Description
Defines the infrastructure topology for test execution. All assets are assumed to be reserved in the Resource Manager prior to execution.

### Request Body
- **metadata** (SchemaMetadata) - Required - Versioning information for the configuration.
- **switches** (List[SwitchModel]) - Optional - List of switch configurations.
- **services** (List[ServiceModel]) - Optional - List of service configurations.
- **hosts** (List[HostModel]) - Optional - List of host configurations.
- **vms** (List[VMModel]) - Optional - List of VM configurations.
- **containers** (List[ContainerModel]) - Optional - List of container configurations.

### Request Example
{
  "metadata": {"version": "2.5"},
  "switches": [],
  "hosts": []
}
```

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

### Error Handling: NotUniqueHostsNamesError

Source: https://github.com/intel/pytest-mfd-config/blob/main/README.md

Illustrates the error raised when duplicate host names are detected in the configuration.

```APIDOC
## Error Handling: NotUniqueHostsNamesError

### Description
This error is raised when the `name` field for hosts is not unique in the YAML topology configuration.

### Example

```shell
>  raise NotUniqueHostsNamesError("Hosts 'name' field must be unique in YAML topology, stopping...")
E  pytest_mfd_config.utils.exceptions.NotUniqueHostsNamesError: Hosts 'name' field must be unique in YAML topology, stopping...
```
```

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

### Identify Interface by Speed and Index in YAML

Source: https://github.com/intel/pytest-mfd-config/blob/main/README.md

Specifies a network interface by its speed (e.g., '40G', '100G') and a specific interface index. The speed can be specified in various formats.

```yaml
network_interfaces:
  - speed: 40G                       # determines all interface IDs supporting 40G speed provided in SPEED_IDS (mfd-const)
    interface_index: 0               # list index
```

```yaml
network_interfaces:
  - speed: 100G                      # possible formats: 100G, 100g, 100, 100G, 100g, 100giga, 100Giga, 100GIGA, 100Gb
    interface_index: 3               # list index
```

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

### Accessing and Validating Topology Model Data

Source: https://context7.com/intel/pytest-mfd-config/llms.txt

This test function demonstrates how to access and validate data from the topology model, including hosts, switches, services, VMs, and containers. It's useful for verifying the structure and content of your topology configuration.

```python
def test_topology_validation(topology):
    """Access and validate topology model data."""
    # Access hosts from topology model
    for host in topology.hosts:
        print(f"Host: {host.name}, Role: {host.role}")
        print(f"Management IP: {host.mng_ip_address}")

        if host.network_interfaces:
            for iface in host.network_interfaces:
                print(f"  Interface: {iface.interface_name or iface.pci_address}")

        if host.connections:
            for conn in host.connections:
                print(f"  Connection: {conn.connection_type} @ {conn.ip_address}")

    # Access switches
    if topology.switches:
        for switch in topology.switches:
            print(f"Switch: {switch.name}, Type: {switch.switch_type}")
            print(f"  Ports: {switch.switch_ports}")
            print(f"  VLANs: {switch.vlans}")

    # Access services, VMs, containers if defined
    if topology.services:
        for service in topology.services:
            print(f"Service: {service.type} @ {service.ip_address}")
```

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

### Disable Interface Initialization

Source: https://github.com/intel/pytest-mfd-config/blob/main/README.md

Skip initialization of a specific network interface.

```yaml
  network_interfaces:
  - interface_name: eth1
    instantiate: false
```

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

### Select Random Interface by Speed in YAML

Source: https://github.com/intel/pytest-mfd-config/blob/main/README.md

Selects a random network interface that supports a specified speed. The speed can be provided in various formats.

```yaml
network_interfaces:
  - speed: 100G                      # possible formats: 100G, 100g, 100, 100G, 100g, 100giga, 100Giga, 100GIGA, 100Gb
    random_interface: true           # determines random interface for provided speed
```

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

### Configure Network Switch Connections

Source: https://github.com/intel/pytest-mfd-config/blob/main/README.md

Defines the structure for switch management, including authentication, connection types, and port/VLAN assignments.

```yaml
switches:                                 # switches details needed for mfd-switchmanagement object creation
- name: Dell 123456
  mng_ip_address: 10.10.10.10
  mng_user: foo
  mng_password: bar
  instantiate: true                       # flag for decision-making whether switch object should be created or only details passed to test
  switch_type: DellOS9_7000
  device_type: Dell
  connection_type: SSHSwitchConnection
  ssh_key_file: keyfile
  use_ssh_key: true
  enable_password: bar2
  auth_timeout: 30
  switch_ports: ['eth1/1', 'eth1/2']
  vlans: ['111', '112', '113']
- (...)
```

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

### InstantiateBaseModel Configuration

Source: https://github.com/intel/pytest-mfd-config/blob/main/README.md

A base Pydantic model that includes an 'instantiate' boolean field, defaulting to True. It uses `Extra.forbid` to disallow extra fields.

```python
class InstantiateBaseModel(BaseModel):
    """Instantiate Base Model."""

    instantiate: bool = Field(True, description="Determines whether fixture shall instantiate object or skip it")

    class Config:
        """Pydantic model config overwrite."""

        extra = Extra.forbid
```

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

### Secrets with Substitution in Configuration

Source: https://github.com/intel/pytest-mfd-config/blob/main/README.md

Secrets can be used within the test configuration itself via a substitution mechanism. The substituted value will be encrypted and decrypted using Fernet.

```yaml
secrets:
  - name: vault_password
    value: secret_value1
  - name: faceless
    value: sadas
  - name: your_secret_name
    value: {{secret_name}}
```

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

### PowerMngModel Definition

Source: https://github.com/intel/pytest-mfd-config/blob/main/README.md

Defines the Pydantic model for power management settings, including connection details, host, IP, credentials, and specific parameters like UDP port and community string.

```python
class PowerMngModel(BaseModel):
    """Power model."""

    power_mng_type: str
    connection: Optional[ConnectionModel] = None
    host: Optional[str] = None
    ip: Optional[str] = None
    username: Optional[str] = None
    password: Optional[SecretStr] = None
    udp_port: Optional[int] = None
    community_string: Optional[str] = None
    outlet_number: Optional[int] = None
```

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

### Access Connections in Pytest

Source: https://context7.com/intel/pytest-mfd-config/llms.txt

Demonstrates how to retrieve and utilize different connection types from a host object within a test function.

```python
def test_multiple_connections(hosts):
    """Access different connection types from a host."""
    host = hosts["multi-connection-host"]

    # Access by connection type
    rpyc = host.connections.rpyc
    ssh = host.connections.ssh
    serial = host.connections.serial
    telnet = host.connections.telnet
    tunneled_ssh = host.connections.tunneled_ssh

    # Primary connection shortcut
    primary = host.connection  # First connection in list

    # Use specific connections
    if ssh:
        ssh.run("ls -la")
    if serial:
        serial.write("command\n")
        response = serial.read_until("prompt>")
```

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

### Define TopologyModel

Source: https://github.com/intel/pytest-mfd-config/blob/main/README.md

Defines the main TopologyModel with optional network components. Uses Pydantic's BaseModel for structure and validation, with `Extra.forbid` to prevent unexpected keys.

```python
class TopologyModel(BaseModel):
    """Topology model.

    Part of the infrastructure used for sake of test execution.
    One shall assume test framework has exclusive access to all the assets - meaning they should be reserved
    in Resource Manager prior to test execution
    """
    metadata: SchemaMetadata
    switches: Optional[List[SwitchModel]] = None
    services: Optional[List[ServiceModel]] = None
    hosts: Optional[List[HostModel]] = None
    vms: Optional[List[VMModel]] = None
    containers: Optional[List[ContainerModel]] = None

    class Config:
        """Pydantic model config overwrite."""
        extra = Extra.forbid
```

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

### OSDControllerModel Definition

Source: https://github.com/intel/pytest-mfd-config/blob/main/README.md

Defines a model for OSD controller configuration, used when connecting via MAC address instead of IP. Includes fields for base URL, credentials, security, and proxies.

```python
class OSDControllerModel(BaseModel):
    """OSD Controller model."""

    base_url: str
    username: str | None = None
    password: str | None = None
    secured: bool | None = True
    proxies: Dict[str, str] | None = None
```

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

### Identify Interface by PCI Device and Index in YAML

Source: https://github.com/intel/pytest-mfd-config/blob/main/README.md

Specifies a network interface using its PCI device identifier (VID:DID or VID:DID:SubVID:SubDID) combined with a specific interface index.

```yaml
network_interfaces:
  - pci_device: 8086:1572            # short PCIDevice: vid:did
    interface_index: 0               # list index
```

```yaml
network_interfaces:
  - pci_device: 8086:1572:0000:0001a # long PCIDevice: vid:did:subvid:subdid
    interface_index: 2               # list index
```

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

### Host Object

Source: https://github.com/intel/pytest-mfd-config/blob/main/README.md

The `hosts` fixture provides a dictionary of Host objects. The Host object contains attributes to access MFDs objects instantiated during its creation.

```APIDOC
### Host object

Fixture `hosts` delivers dictionary with `name` of host as key and `Host` object as value. Using some [getters methods](#methods) you can get single host.
`Host` object is created depending on `instantiate` flag in topology. Some of its attributes allow us to access MFDs objects instantiated at a moment of Host object creation:

- `name` - which is name of host from topology
- `connections` - which is [dataclass](#connections-dataclass) for connections 
- `network_interfaces` - which is list of NetworkInterface objects bases on `network_interfaces` information in topology
- `topology` - which is Pydantic model for Host
- `connection` - which is first object of mfd-connect connection, for better accessing if just single connection established
- `power_mng` - which is `mfd-powermanagement`'s object. Which of `mfd-powermanagement`'s class it should use and all 
   params needed for its `init` you can pass in topology - please check [MachineModel](#machinemodel) for more details.

For more info please check [mfd-host](https://github.com/intel/mfd-host) repository.
#### Host methods:
- `refresh_network_interfaces(self) -> None` - Create new NetworkInterface objects and overwrite current ones.
```

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

### Select Random Interface by PCI Device in YAML

Source: https://github.com/intel/pytest-mfd-config/blob/main/README.md

Selects a random network interface associated with a given PCI device identifier.

```yaml
network_interfaces:
  - pci_device: 8086:1572            # short PCIDevice: vid:did
    random_interface: true           # determines random interface from list of interfaces when pci_device is as above
```

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

### Connection Types Configuration

Source: https://context7.com/intel/pytest-mfd-config/llms.txt

Configure various connection types including SSH, RPyC, Serial, Telnet, and tunneled connections within the YAML configuration.

```yaml
# Connection Types Configuration

# Configure various connection types including SSH, RPyC, Serial, Telnet, and tunneled connections.
```

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

### MachineModel Base Class

Source: https://github.com/intel/pytest-mfd-config/blob/main/README.md

Defines a base model for machines, inheriting from InstantiateBaseModel. Includes common fields like name, management IP, credentials, and power management.

```python
class MachineModel(InstantiateBaseModel):
    """Machine model."""

    name: str = None
    mng_ip_address: Optional[IPvAnyAddress] = None  # BMC MNG Address or Switch IP address
    mng_user: Optional[str] = None
    mng_password: Optional[SecretStr] = None
    power_mng: Optional[PowerMngModel] = None
```

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

### Pytest Fixtures

Source: https://github.com/intel/pytest-mfd-config/blob/main/README.md

The plugin provides several pytest fixtures to access configuration data and objects within your tests.

```APIDOC
## Pytest Fixtures

After successful installation of the plugin when you invoke `pytest --fixtures` you should see new fixtures available in the output:

- `hosts`: (dict[str, Host]) : Get dictionary of Host (mfd-host) objects with associated RPC(mfd-connect) connections based on passed Topology model where key is `name` of host.
- `switches` : (list[Switch]) : Get list of Switch (mfd-switchmanagement) objects based on passed topology model.
- `connected_hosts`: (list[Tuple[Host, Host]]) : Get list of the tuples of connected host pairs 
- `test_config_path` : (str) : Get path of --test_config file.
- `test_config` : (dict) : Get test config data from file.
- `topology_path` : (str) : Get path of --topology_config file.
- `topology_config` : (dict) : Get topology data from file.
- `topology` : (TopologyModel) : Create topology model from config file data.
- `extra_data` : (dict) : Place for extra information to report in test (reported as metadata single test)
![](docs/img/custom_fixtures.png)
```

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

### Test Metadata Reporting

Source: https://github.com/intel/pytest-mfd-config/blob/main/README.md

Using the extra_data fixture to attach custom information and RQM IDs to test results.

```APIDOC
## Test Metadata Reporting

### Description
The extra_data fixture allows developers to inject custom metadata into test logs and reports, including RQM IDs for test tracking.

### Usage
- Use the `extra_data` dictionary to store key-value pairs.
- Set the `rqm_id` key to link the test case to an RQM ID.

### Example
```python
def test_example(extra_data):
    extra_data['tested_adapter'] = {"family": "CVL"}
    extra_data["rqm_id"] = "12345"
```
```

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

### Identify Interface by PCI Address in YAML

Source: https://github.com/intel/pytest-mfd-config/blob/main/README.md

Specifies a network interface using its full PCI address (domain:bus:device:function) or a shortened version (bus:device:function). The domain defaults to '0000' if not provided.

```yaml
network_interfaces:
  - pci_address: 0000:ff:ff.1        # determines interface by unique long PCI Address
```

```yaml
network_interfaces:
  - pci_address: ff:ff.1             # determines interface by unique short PCI Address (default `domain` is used: `0000`)
```