button
======
**Source code:** `button.py <https://chromium.googlesource.com/chromiumos/platform/factory/+/refs/heads/main/py/test/pytests/button.py>`_

Tests button functionality.

Description
-----------
This test verifies if a button is working properly by checking if its state is
changed per given instruction.

You can specify the button in different ways using the ``button_key_name``
argument:

=================== ============================================================
Key Name            Description
=================== ============================================================
``gpio:[-]NUM``     A GPIO button. ``NUM`` indicates GPIO number, and ``+/-``
                    indicates polarity (minus for active low, otherwise active
                    high).
``crossystem:NAME`` A ``crossystem`` value (1 or 0) that can be retrieved by
                    NAME.
``ectool:NAME``     A value for ``ectool gpioget`` to fetch.
``KEYNAME``         An ``evdev`` key name that can be read from ``/dev/input``.
                    Try to find the right name by running ``evtest``.
=================== ============================================================

Test Procedure
--------------
When started, the test will prompt operator to press and release given button N
times, and fail if not finished in given timeout.

Dependency
----------
Depends on the driver of specified button source: GPIO, ``crossystem``,
``ectool``, or ``evdev`` (which also needs ``/dev/input`` and ``evtest``).

Examples
--------
To test the recovery button 1 time in 30 seconds, add this in test list::

  {
    "pytest_name": "button",
    "args": {
      "button_key_name": "crossystem:recoverysw_cur"
    }
  }

To test volume down button (using ``evdev``) 3 times in 10 seconds::

  {
    "pytest_name": "button",
    "args": {
      "timeout_secs": 10,
      "button_key_name": "KEY_VOLUMEDOWN",
      "repeat_times": 3
    }
  }


Test Arguments
--------------
.. list-table::
   :widths: 20 10 60
   :header-rows: 1
   :align: left

   * - Name
     - Type
     - Description

   * - timeout_secs
     - int
     - (optional; default: ``30``) Timeout value for the test.

   * - button_key_name
     - str
     - Button key name.

   * - device_filter
     - int, str, None
     - (optional; default: ``None``) Event ID or name for evdev. None for auto probe.

   * - repeat_times
     - int
     - (optional; default: ``1``) Number of press/release cycles to test

   * - bft_fixture
     - dict, None
     - (optional; default: ``None``) A dictionary with the following items:
       
         ``class_name``
           Fully-qualified class name of the BFTFixture implementation
           to use.
       
         ``params``
           A dictionary of parameters for the BFTFixture class's ``Init()``
           method.
       
       The default value of ``None`` means that no BFT fixture is used.

   * - bft_button_name
     - str, None
     - (optional; default: ``None``) Button name for BFT fixture

   * - button_name
     - str, dict
     - The name of the button.