Libyui UI REST API framework for integration testing. Project started by @lslezak, with support of @cwh42 and @OleksandrOrlov.

The solution allows to query the UI properties over HTTP using a REST API. This allows to automate the UI interaction steps and avoid screen-based tools. The API allows reading properties of the UI, so the displayed values can be validated. It also allows interacting with the UI (clicking buttons, toggling check boxes, entering text,...).

This repository contains the shared functionlity, you need to install the additional bindings for the specific UI frontends ((libyui-ncurses-rest-api)[https://github.com/libyui/libyui-ncurses-rest-api] or (libyui-qt-rest-api)[https://github.com/libyui/libyui-ncurses-rest-api]).

• Optional plugins which extend the standard libyui library
  • Less dependencies
  • Can be installed only when needed
• Can read the whole structure of the currently displayed dialog
• Can query only the selected widgets
• Allows sending the user input (clicking buttons, entering text,...)
• Uses the standard HTTP protocol and the JSON data format
  • Not bound to any specific programming language or framework
  • Easy integration with any testing framework
• Optional remote access (by default accessible only from the same machine)
• Optional client authentication (HTTP Basic Auth)
  • ⚠️ But without any encryption it is still sent in clear text!
• IPv6 support (quite interesting for testing virtual machines, the IPv6 link-local address is based on the MAC address, you can easily get the IPv6 address for your testing machine)

• Properties of some widgets are still missing
• Allow sending more user actions
• Some widgets do not send notify events when changed via the API
• SSL encryption/peer verification (needed for secure transferring of sensitive data like passwords)
• Allow connection via Unix domain sockets

To start the application with rest API enabled, use the following commands:

• xdg-su -c 'YUI_HTTP_PORT=9999 yast2 host' for Qt
• sudo YUI_HTTP_PORT=9999 yast2 host for ncurses.

After that, you can get the documentation how to interact with the UI by accessing http://localhost:9999 (or http://ipv6-localhost:9999 via IPv6).

NOTE: For MultiItemSelector and CustomItemSelector, rest-api doesn't work as expected in ncurses with notify set to true, when using pure C++ code. This limitation is due to widget implementation. With ruby wrapper, there is no issue.

By setting YUI_HTTP_REMOTE=1 environmental variable, one can allow connections from remote hosts.

⚠️ Security warning: Enable the remote access only in trusted environment, do not use it for production systems!

The REST API supports user authentication via the HTTP Basic Authentication.

The allowed user name and password can be set using the YUI_AUTH_USER and the YUI_AUTH_PASSWD environment variables. It is possible to configure only single access credentials.

⚠️ Security warning: Currently the user name and the password is sent in clear text without any encryption (only converted to the Base64 encoding). That means anybody on the way could read the user name and the password (MITM attack).

This webserver provides a REST API for the LibYUI application.

It can be used for testing and controlling the application in automated tests.

Request:

GET /application

Get the application and UI generic properties like text or graphical mode, dialog size, screen size and supported UI featues.

JSON format

curl http://localhost:9999/application

Request:

GET /dialog

Get the complete dialog structure in the JSON format. The result contains a nested structure exactly following the structure of the current dialog.

JSON format

curl http://localhost:9999/dialog

Request:

GET /widgets

Return only the selected widgets (in JSON format). The result is a flat list (no nested structures).

Filter widgets:

• id - widget ID serialized as string, might include special characters like backtick (\`)
• label - widget label as currently displayed (i.e. translated!)
• type - widget type

JSON format

curl 'http://localhost:9999/widgets?id=next'

curl 'http://localhost:9999/widgets?label=Next'

curl 'http://localhost:9999/widgets?type=YCheckBox'

Request: POST /widgets

Do an action with specified widgets.

Filter the widgets, one of:

• id - widget ID serialized as string, might include special characters like backtick (\`)
• label - widget label as currently displayed (i.e. translated!)
• type - widget type

• action - action to do
• value (optional) - new value or a parameter of the action
• column (optional) - column id when selecting item in the table

• press - to press the button
• check|uncheck|toggle - check, uncheck or toggle checkbox
• enter_text - set text in the field, requires value parameter
• switch_radio - activate radio button
• select - select value in the combobox, row in the table or node in the tree, requires value parameter
  In case of table: select row in the table with given value. If column parameters is not provided, first column will be used.
  In case of tree: select node in the tree. Use '|' as delimiter for child nodes.

JSON format

  # press the "next" button
curl -X POST 'http://localhost:9999/widgets?id=next&action=press'

  # set value "test" for the InputField with label "Description"
curl -X POST 'http://localhost:9999/widgets?label=Description&action=enter_text&value=test'

  # select row with "test" cell value in the 2-nd column (counting from zero) in table with id "names"
curl -X POST 'http://localhost:9999/widgets?id=names&action=select&value=test&column=2'

  # select tree item with in tree with id "files"
curl -X POST 'http://localhost:9999/widgets?id=files&action=select&value=root|subnode|subnode'