<!-- HILSTER htf 4.3.1 -->
**htf 4.3.1** · [HTML](../interaction.html) · [Complete PDF manual](../_downloads/htf-4.3.1.pdf)

<a id="interaction"></a>

# Interactive Testing

In some circumstances not all tests can be completely automated.

htf offers interactive testing which allows you to interact with your
tests via your web browser. A web server is started on port `8080`.

A QR code is printed on the terminal so that you can interact using your mobile phone or a tablet easily.

This feature can be used to script and revision manual tests for example.

Interaction is done via the [`interaction`](#htf.fixtures.interaction) fixture.

htf needs to run in interactive mode. When running from command line
add the `-i` argument or set `interactive=True` in [`htf.main`](main.md#htf.main).

By default a browser is opened to be used for interaction. If you do not wish to open the browser
automatically use `--no-browser` or pass `open_browser=False` to [`htf.main`](main.md#htf.main).

To set the listening address use `--interactive-address` or `interactive_address` in [`htf.main`](main.md#htf.main)
To set the port to listen on use `--interactive-port` or `interactive_port` in [`htf.main`](main.md#htf.main).

All interaction dialogs will be put into the HTML test report with the appropriate answers.

## Interaction Dialogs

### Message Dialog

To inform the user you can create a [`message_dialog`](#htf.fixtures.interaction.message_dialog).
The message dialog has an ok button that will hide it immediately.

```python
def test_message_dialog(interaction):
    """
    This test shows how to use a message dialog.

    Args:
        interaction (htf.fixtures.interaction): the interaction fixture
    """
    interaction.message_dialog("Ready", "Test is ready to start.")
```

![Ready dialog stating that the test is ready to start, with an OK button.](_images/e94b1924cb765fa2.png)

### Waiting Dialog

To let the user wait for a given time you can use [`waiting_dialog`](#htf.fixtures.interaction.waiting_dialog).
The timeout must not be `None`.

```python
def test_waiting_dialog(interaction):
    """
    This test shows how to use a waiting dialog.

    Args:
        interaction (htf.fixtures.interaction): the interaction fixture
    """
    interaction.waiting_dialog("Please wait a minute", "Setup is running. Please wait.", timeout=60)
```

![Waiting dialog stating that setup is running, with an elapsed-time display and no input controls.](_images/a749464807d0abac.png)

### Input Dialog

If your test needs user input you can use [`input_dialog`](#htf.fixtures.interaction.input_dialog).

```python
def test_input_dialog(interaction):
    """
    This test shows how to use an input dialog.

    Args:
        interaction (htf.fixtures.interaction): the interaction fixture
    """
    value = interaction.input_dialog("Measurement value", "Please enter the current measurement value.")
    # value is a string
```

![Measurement-value dialog with an empty text field and an OK button.](_images/0141eb5f08681283.png)

You can optionally validate the user’s inputs on server side that only valid inputs are accepted. The validator
can also act as a type cast.

```python
def test_input_dialog(interaction):
    """
    This test shows how to use an input dialog with a float validator.

    Args:
        interaction (htf.fixtures.interaction): the interaction fixture
    """
    value = interaction.input_dialog("Measurement value", "Please enter the current measurement value.",
                          validator=htf.float_validator)
    # value is a float
```

There are some built-in validators.

### htf.int_validator(value: [Any](https://docs.python.org/3/library/typing.html#typing.Any)) → [int](https://docs.python.org/3/builtins/functions.html#int)

An int validator for interactive tests.

### htf.float_validator(value: [Any](https://docs.python.org/3/library/typing.html#typing.Any)) → [float](https://docs.python.org/3/builtins/functions.html#float)

A float validator for interactive tests.

### htf.regex_validator(pattern: [str](https://docs.python.org/3/builtins/stdtypes.html#str), exception_message: [str](https://docs.python.org/3/builtins/stdtypes.html#str) | [None](https://docs.python.org/3/builtins/constants.html#None) = None) → [Callable](https://docs.python.org/3/library/typing.html#typing.Callable)[[[str](https://docs.python.org/3/builtins/stdtypes.html#str)], [str](https://docs.python.org/3/builtins/stdtypes.html#str)]

A regex validator factory.

* **Parameters:**
  * **pattern** – the regex pattern to be checked
  * **exception_message=None** – the optional exception message supplied to the user in its browser
* **Returns:**
  an interaction validator for pattern

```python
def test_input_dialog(interaction):
    """
    This test shows how to use an input dialog with a regex validator.

    Args:
        interaction (htf.fixtures.interaction): the interaction fixture
    """
    value = interaction.input_dialog("Serial number", "Please enter the device serial number.",
                          validator=htf.regex_validator(pattern=r"[A-Z]{4}-[0-9]{4}"))
    # value is a valid serial number
```

![Serial-number dialog showing an invalid entry and the required pattern: four uppercase letters, a hyphen, then four digits.](_images/a61ca8a083567175.png)

### Yes-No Dialog

To ask the user a yes-no question you can use [`yes_no_dialog`](#htf.fixtures.interaction.yes_no_dialog).

```python
def test_yes_no_dialog(interaction):
    """
    This test shows how to use a yes-no dialog.

    Args:
        interaction (htf.fixtures.interaction): the interaction fixture
    """
    value = interaction.yes_no_dialog("Continue?", "Do you want to continue?")
    # value is 'yes' or 'no' or None in case of a timeout
```

![Continue confirmation dialog offering Yes and No buttons.](_images/781ebdd7151eacc7.png)

### Button Dialog

To ask the user a question with one answer out of multiple predefined choices you can use the
[`button_dialog`](#htf.fixtures.interaction.button_dialog).

```python
def test_button_dialog(interaction):
    """
    This test shows how to use a button dialog.

    Args:
        interaction (htf.fixtures.interaction): the interaction fixture
    """
    value = interaction.button_dialog("Favorite food", "What is your favorite food?",
                                      choices=[
                                          ("Pizza", "pizza"),
                                          ("Burger", "burger"),
                                          ("Noodles", "noodles"),
                                      ])
    # value is 'pizza', 'burger', 'noodles' or None in case of a timeout
```

![Favorite-food dialog offering separate Pizza, Burger, and Noodles buttons.](_images/0176ef3b68bbbaea.png)

### Radio Button Dialog

To ask the user a question with one answer out of multiple predefined choices you can use the
[`radio_button_dialog`](#htf.fixtures.interaction.radio_button_dialog).

```python
def test_radio_button_dialog(interaction):
    """
    This test shows how to use a radio button dialog.

    Args:
        interaction (htf.fixtures.interaction): the interaction fixture
    """
    value = interaction.radio_button_dialog("Favorite food", "What is your favorite food?",
                choices=[
                    "Pizza",  # label and answer are the same
                    ["Burger", "burger"],  # label is left and answer is right
                    ("Noodles", "noodles"),  # supplied as a tuple
                    ["Steak", True],  # label and answer are the same and the checkbox is checked
                    ["Fish", "fish", False]  #  # label is left and answer is right and the checkbox is not checked
                ])
    # value is 'Pizza', 'burger', 'noodles', 'Steak', 'fish' or None in case of a timeout
```

![Favorite-food dialog with mutually exclusive radio choices; Steak is selected.](_images/67e15f5ef687dd22.png)

### Checkbox Dialog

To ask the user a question with multiple predefined answers you can use the
[`checkbox_dialog`](#htf.fixtures.interaction.checkbox_dialog).

```python
def test_checkbox_dialog(interaction):
    """
    This test shows how to use a checkbox dialog.

    Args:
        interaction (htf.fixtures.interaction): the interaction fixture
    """
    value = interaction.checkbox_dialog("Favorite food", "What is your favorite food?",
                choices=[
                    "Pizza",  # label and answer are the same
                    ["Burger", "burger"],  # label is left and answer is right
                    ("Noodles", "noodles"),  # supplied as a tuple
                    ["Steak", True],  # label and answer are the same and the checkbox is checked
                    ["Fish", "fish", False]  #  # label is left and answer is right and the checkbox is not checked
                ])
    # value is a list containing no elements or multiple choices from
    # 'Pizza', 'burger', 'noodles', 'Steak', 'fish' or None in case of a timeout
```

![Favorite-food dialog with independent checkboxes; Steak is checked.](_images/88ec1a59f41cceb6.png)

### File Upload Dialog

To allow the user to upload a file you can use the
[`file_upload_dialog`](#htf.fixtures.interaction.file_upload_dialog).

```python
def test_file_upload_dialog(interaction):
    """
    This test shows how to use a file_upload dialog.

    Args:
        interaction (htf.fixtures.interaction): the interaction fixture
    """
    value = interaction.file_upload_dialog("Favorite food", "Please upload a picture of your favorite food", ".png, image/*")
    # value is a tuple( file name, file type, uploaded file in binary form) or None in case of a timeout.
```

![Picture-upload dialog with Choose file, Browse, and Upload controls.](_images/bc6107096113f7f8.png)

### Captcha Functionality

Using the `captcha` library allows you to simulate Captcha functionality in dialogs.

```python
def test_solve_captchas(interaction, assertions):
    """
    This test shows how to interactively solve captchas.

    Args:
         interaction (htf.fixtures.interaction): the interaction fixture
         assertions (htf.fixtures.assertions): the assertions fixture
    """
    try:
        for number_solved in range(1, 6):  # max 5 captchas can be solved
            image = ImageCaptcha()
            captcha_value = str(randint(1000, 10000))
            image.write(captcha_value, 'captcha.png')

            captcha = """

            .. |captcha| image:: captcha.png
            """

            answer = interaction.input_dialog(title='Captcha',
                                              text="Please solve the following captcha:\n\n|captcha|" + captcha)
            assertions.assert_equal(answer, captcha_value)
            if number_solved < 5:
                again = interaction.yes_no_dialog(title='Again',
                                                  text="Would you like to solve another one?")
                if again == 'no':  # stop if the user has had enough
                    break
    except AssertionError:
        number_solved -= 1
        raise
    finally:
        interaction.message_dialog(title='Congratulations', text="You solved {} captchas!".format(number_solved))
```

![CAPTCHA dialog with a distorted-character image, an empty answer field, and an OK button.](_images/14039266e8244b62.png)

## Embed Images in Dialogs

The `text` parameter of all dialogs can be [reStructuredText](https://en.wikipedia.org/wiki/ReStructuredText).
It is possible to embed images that appear in the dialog and in the HTML test report.

Images can be embedded as a paragraph or inline.

### Images as Paragraphs

To add an image as a paragraph use

```RST
.. image:: path/to/image.png
```

![DUT-running confirmation dialog showing indicators labeled Alarm, Power, Failure, and Error; the Power indicator is bright green.](_images/854b1cae7fed5908.png)

### Inline Images

To add an image inline use [substitution definitions](https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#substitution-definitions).

```default
This |inlineimage| is located inline.

.. |inlineimage| image:: path/to/image.png
```

![Channel-menu dialog instructing the user to select the phone-and-gear icon and open channel settings.](_images/341b8886fa26238d.png)

### Repeat or Cancel Tests

On the top right corner in the browser a test control panel can be found.
Users can repeat or cancel a test by clicking the corresponding button and entering a message.

#### NOTE
Cancelling or repeating a test is performed in the same thread in which the test is executed.
Thus, a test can block the reaction (e.g. if it runs [`time.sleep`](https://docs.python.org/3/library/time.html#time.sleep) or any other blocking call).
The task of waiting for a longer time should therefore be split into several shorter calls to
[`time.sleep`](https://docs.python.org/3/library/time.html#time.sleep), etc.

## Reference

### *class* htf.fixtures.interaction(interaction_server: BrowserInteractionServer, result: TestResult)

#### button_dialog(title: [str](https://docs.python.org/3/builtins/stdtypes.html#str), text: [str](https://docs.python.org/3/builtins/stdtypes.html#str), choices: [List](https://docs.python.org/3/library/typing.html#typing.List)[[str](https://docs.python.org/3/builtins/stdtypes.html#str)] | [Tuple](https://docs.python.org/3/library/typing.html#typing.Tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str)], timeout: [float](https://docs.python.org/3/builtins/functions.html#float) = 300) → [Any](https://docs.python.org/3/library/typing.html#typing.Any)

Create a dialog with buttons and definable answers.

* **Parameters:**
  * **title** – the title of the button dialog
  * **text** – the content of the button dialog
  * **choices** – each choice can be a string containing the label and the answer a tuple or
    list of two strings where the first entry is the label and the second label is the answer.
  * **timeout=300** – the timeout until the button dialog disappears in seconds (`None` means no timeout)
* **Returns:**
  the answer for the clicked button or `None` in case of a timeout
* **Return type:**
  [object](https://docs.python.org/3/builtins/functions.html#object) or None

#### checkbox_dialog(title: [str](https://docs.python.org/3/builtins/stdtypes.html#str), text: [str](https://docs.python.org/3/builtins/stdtypes.html#str), choices: [List](https://docs.python.org/3/library/typing.html#typing.List)[[str](https://docs.python.org/3/builtins/stdtypes.html#str)] | [Tuple](https://docs.python.org/3/library/typing.html#typing.Tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str)], timeout: [float](https://docs.python.org/3/builtins/functions.html#float) = 300) → [Any](https://docs.python.org/3/library/typing.html#typing.Any)

Create a dialog with definable checkboxes for multiple choices.

* **Parameters:**
  * **title** – the title of the checkbox dialog
  * **text** – the content of the checkbox dialog
  * **choices** – each choice can be a string containing the label and the answer a tuple or
    list of two strings where the first entry is the label and the second label is the answer.
    You can also supply a list or tuple with two entries where the first entry is the label and the second
    entry is a boolean that states if the radio button is checked.
    You can also supply a list or tuple with three entries where the first entry is the label,
    the second entry is the answer and the third entry is a boolean that states if the radio button is
    checked.
  * **timeout=300** – the timeout until the checkbox dialog disappears in seconds (`None` means no timeout)
* **Returns:**
  a list containing the selected answers or `None` in case of a timeout
* **Return type:**
  [list](https://docs.python.org/3/builtins/stdtypes.html#list) of [str](https://docs.python.org/3/builtins/stdtypes.html#str) or None

#### file_upload_dialog(title: [str](https://docs.python.org/3/builtins/stdtypes.html#str), text: [str](https://docs.python.org/3/builtins/stdtypes.html#str), file_types: [str](https://docs.python.org/3/builtins/stdtypes.html#str) | [None](https://docs.python.org/3/builtins/constants.html#None) = None, timeout: [float](https://docs.python.org/3/builtins/functions.html#float) = 300) → File | [None](https://docs.python.org/3/builtins/constants.html#None)

Create a dialog which allows the user to upload a file.

* **Parameters:**
  * **title** – the title of the file upload dialog
  * **text** – the content of the file upload dialog
  * **file_types** – desired file type of files to be uploaded. This should be respected by the file chooser
    in all modern browsers. File types can be specified as file extensions or MIME types, with every
    entry separated by a comma.
  * **timeout=300** – the timeout until the file upload dialog disappears in seconds
    (`None` means no timeout)
* **Returns:**
  tuple of str or tuple or None. `( file name, file type, uploaded file in binary form)`.

#### input_dialog(title: [str](https://docs.python.org/3/builtins/stdtypes.html#str), text: [str](https://docs.python.org/3/builtins/stdtypes.html#str), timeout: [float](https://docs.python.org/3/builtins/functions.html#float) = 300, validator: [Callable](https://docs.python.org/3/library/typing.html#typing.Callable)[[...], [Any](https://docs.python.org/3/library/typing.html#typing.Any)] | [None](https://docs.python.org/3/builtins/constants.html#None) = None) → [Any](https://docs.python.org/3/library/typing.html#typing.Any)

Create an input dialog to let the user interact with some textual input.

* **Parameters:**
  * **title** – the title of the input dialog
  * **text** – the content of the input dialog
  * **timeout=300** – the timeout until the input dialog disappears in seconds (`None` means no timeout)
  * **validator=None** – the validator to validate the inputs on server side
* **Returns:**
  the string the user supplied, the return value of the validator or `None`
  : in case of a timeout
* **Return type:**
  [object](https://docs.python.org/3/builtins/functions.html#object) or None

#### message_dialog(title: [str](https://docs.python.org/3/builtins/stdtypes.html#str), text: [str](https://docs.python.org/3/builtins/stdtypes.html#str), timeout: [float](https://docs.python.org/3/builtins/functions.html#float) = 300) → [Any](https://docs.python.org/3/library/typing.html#typing.Any)

Create an interactive message dialog to display a message.

* **Parameters:**
  * **title** – the title of the message dialog
  * **text** – the content of the message dialog:
  * **timeout=300** – the timeout until the message dialog disappears in seconds (`None` means no timeout)
* **Returns:**
  `"ok"` in case of a click on the ok button or `None` in case of a timeout.

#### radio_button_dialog(title: [str](https://docs.python.org/3/builtins/stdtypes.html#str), text: [str](https://docs.python.org/3/builtins/stdtypes.html#str), choices: [List](https://docs.python.org/3/library/typing.html#typing.List)[[str](https://docs.python.org/3/builtins/stdtypes.html#str)] | [Tuple](https://docs.python.org/3/library/typing.html#typing.Tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str)], timeout: [float](https://docs.python.org/3/builtins/functions.html#float) = 300) → [Any](https://docs.python.org/3/library/typing.html#typing.Any)

Create a dialog with definable radio buttons to select one answer out of many choices.

* **Parameters:**
  * **title** – the title of the radio button dialog
  * **text** – the content of the radio button dialog
  * **choices** – each choice can be a string containing the label and the answer a tuple or
    list of two strings where the first entry is the label and the second label is the answer.
    You can also supply a list or tuple with two entries where the first entry is the label and the second
    entry is a boolean that states if the radio button is checked.
    You can also supply a list or tuple with three entries where the first entry is the label,
    the second entry is the answer and the third entry is a boolean that states if the radio button is
    checked.
  * **timeout=300** – the timeout until the radio button dialog disappears in seconds
    (`None` means no timeout)
* **Returns:**
  the answer for the selected radio button or `None` in case of a timeout
* **Return type:**
  [str](https://docs.python.org/3/builtins/stdtypes.html#str) or None

#### waiting_dialog(title: [str](https://docs.python.org/3/builtins/stdtypes.html#str), text: [str](https://docs.python.org/3/builtins/stdtypes.html#str), timeout: [float](https://docs.python.org/3/builtins/functions.html#float)) → [Any](https://docs.python.org/3/library/typing.html#typing.Any)

Create a waiting dialog.

* **Parameters:**
  * **title** – the title of the waiting dialog
  * **text** – the content of the waiting dialog
  * **timeout** – the timeout until the waiting dialog disappears in seconds
* **Returns:**
  `'Ok'` after the timeout is over.

#### yes_no_dialog(title: [str](https://docs.python.org/3/builtins/stdtypes.html#str), text: [str](https://docs.python.org/3/builtins/stdtypes.html#str), timeout: [float](https://docs.python.org/3/builtins/functions.html#float) = 300) → [Any](https://docs.python.org/3/library/typing.html#typing.Any)

Create a yes-no dialog to ask the user a question.

* **Parameters:**
  * **title** – the title of the yes-no dialog
  * **text** – the content of the yes-no dialog
  * **timeout=300** – the timeout until the yes_no_dialog disappears in seconds (`None` means no timeout)
* **Returns:**
  `'yes'` or `'no'` depending on the user input or `None` in case of a timeout
* **Return type:**
  [str](https://docs.python.org/3/builtins/stdtypes.html#str) or None
