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

A factory test for ambient light sensor.

Description
-----------
Tests that ambient light sensor reacts to both darkening by covering with
finger as well as brightening by shining with flashlight.

Test Procedure
--------------
When the test starts, all subtests will be listed on the screen.  Operator
needs to press ``SPACE`` to start subtests.

After ``SPACE`` is pressed, the first subtest will become ``ACTIVE`` and
operator should follow the instruction shown on the screen, e.g. "Cover light
sensor with finger".  The pytest will keep polling light sensor value, as soon
as the  value meets the requirement, the subtest will be marked as ``PASSED``
and next subtest will become ``ACTIVE``  When all subtests are ``PASSED`` the
test will pass and stop.

Dependency
----------
- Device API (``cros.factory.device.ambient_light_sensor``).

Examples
--------
To perform 3 subtests,

1. ``'Light sensor dark'`` (below 30)
2. ``'Light sensor exact'`` (between 60 and 300)
3. ``'Light sensor light'`` (above 500)

.. test_list::

  generic_ec_component_als_examples:AmbientLightSensorTests.LightSensor

The sensor value represents in lux. For reference, see
https://www.kernel.org/doc/Documentation/ABI/testing/sysfs-bus-iio.

Note that you have to specify ``subtest_list``, ``subtests_instruction``,
``subtest_cfg`` at the same time.


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

   * - Name
     - Type
     - Description

   * - device_path
     - str, None
     - (optional; default: ``None``) [Deprecated] device path

   * - device_name
     - str, None
     - (optional; default: ``'cros-ec-light'``) device name. If unset, do auto detection.

   * - location
     - str, None
     - (optional; default: ``None``) device location. If unset, do auto detection.

   * - device_input
     - str, None
     - (optional; default: ``None``) [Deprecated] device input file

   * - timeout_per_subtest
     - int
     - (optional; default: ``10``) timeout for each subtest

   * - subtest_list
     - list, None
     - (optional; default: ``None``) subtest list

   * - subtest_cfg
     - dict, None
     - (optional; default: ``None``) subtest configuration

   * - subtest_instruction
     - dict, None
     - (optional; default: ``None``) subtest instruction

   * - check_per_subtest
     - int
     - (optional; default: ``3``) check times for each subtest