[Matter](https://developers.home.google.com/matter/tools/home-ui-automator.md.txt)

Google Home UI Automator can help you automate your Google Home app (GHA)
to commission, decommission Matter, or run a regression
test on your commission.

![This figure shows how to pair a Matter device to Google Home](https://developers.home.google.com/static/tools/images/ui-automator.png)

## Prerequisities

To use Google Home UI Automator, have the following ready:

### Python 3

It is recommended to use Python 3 environment to run the script.
Google Home UI Automator requires python `3.11` or newer.

### Android phone

1. Turn on ***User Debugging*** mode on your Android phone. See [Enable Developer options](https://developer.android.com/studio/debug/dev-options#enable) to turn on the debugging setting.
2. Connect your Android phone to your computer.

### Google Home app

1. Install GHA on your Android phone. Make sure the GHA's version is `3.1.1.14` and `3.32.126.2`.
2. Login to your Google Account in GHA.

> [!NOTE]
> **Note:** This tool only works with the English version of the GHA.

## Install Google Home UI Automator

There are two ways to install Google Home UI Automator, PyPI or from source
code. We recommend installing with PyPI.

### PyPI (recommended)

```bash
pip install google-home-ui-automator
```

### Build from source code

To build from a source code, follow these steps in your terminal:

1. Clone this repository:

   ```bash
   git clone https://testsuite-smarthome-matter.googlesource.com/ui-automator
   ```
2. Navigate to the cloned repository:

   ```bash
   cd ui-automator
   ```
3. Run the following command:

   ```bash
   pip install .
   ```

## Commission a Matter device

To commission a Matter device, enter the following command:

```bash
ui-automator --commission DEVICE_NAME,PAIRING_CODE,ROOM_NAME [--google_account GOOGLE_ACCOUNT]
```

| Input value | Description | Example |
|---|---|---|
| `DEVICE_NAME` | Selected Matter device. | `m5stack` |
| `PAIRING_CODE` | Pairing code of your Matter device. | `34970112332` |
| `ROOM_NAME` | Assigned room. | `Office` |
| `GOOGLE_ACCOUNT` | Account to use in GHA. | `test@gmail.com` |

![This figure shows how to pair a Matter device to Google Home](https://developers.home.google.com/static/tools/images/ui-automator-pairing.png)

![](https://developers.home.google.com/static/tools/images/ui-automator-connected.png)

## Decommission a Matter device

To decommission a Matter device, enter the following command:

```bash
ui-automator --decommission DEVICE_NAME [--google_account GOOGLE_ACCOUNT]
```

| Input value | Description | Example |
|---|---|---|
| `DEVICE_NAME` | Displays name of commissioned Matter device on GHA. | `m5stack` |
| `GOOGLE_ACCOUNT` | Account to use in GHA. | `test@gmail.com` |

![This figure shows the icons for providing feedback and reporting
issues in Google Home Playground.](https://developers.home.google.com/static/tools/images/ui-automator-decommission.png)

## Run a Regression Test

To run a regression test, enter the following code. You must include flag
`--regtest` and `--commission` to run the regression test.

```bash
ui-automator --commission DEVICE_NAME,PAIRING_CODE,ROOM_NAME --regtest [--repeat REPEAT_TIMES] [--hub HUB_VERSION] [--dut MODEL,TYPE,PROTOCOL] [--fw DEVICE_FIRMWARE] [--google_account GOOGLE_ACCOUNT]
```

| Input value | Description | Example |
|---|---|---|
| `DEVICE_NAME` | Selected Matter device. | `m5stack` |
| `PAIRING_CODE` | Pairing code of your Matter device. | `34970112332` |
| `ROOM_NAME` | Assigned room. | `Office` |
| `GOOGLE_ACCOUNT` | Account to use in GHA. | `test@gmail.com` |

The regression test only supports the commissioning and decommissioning cycle.
By default, the regression test will run until users use the keyboard to stop
the process.

> [!NOTE]
> **Note:** Google Home UI Automator only works with devices that will automatically enter commissioning mode when removing all fabrics in the regression test. If your devices can't run the regression test, fill out the feedback form in the [feedback](https://developers.home.google.com/tools/home-ui-automator.md.txt#feedback) section with your device information.

You can add the following for more in-depth test results:

| Value | Input value | Description | Example |
|---|---|---|---|
| `--repeat` | `REPEAT_TIMES` | Run regression test in limited times and repeated times. | `5` |
| `--hub` | `HUB_VERSION` | Hub version for controlling devices on GHA. | `15.20221210.3.1` |
| `--dut` |   | Device under test. |   |
|   | `MODEL` | Device model. | `X123123` |
|   | `TYPE` | Device type. | `LIGHT` |
|   | `PROTOCOL` | Device protocol. | `MATTER` |
| `--fw` | `DEVICE_FIRMWARE` | Device firmware. | `2.2.0` |

> [!IMPORTANT]
> **Important:** Allow the UI automation to process without any interruptions. Disrupting the automation process will fail the test.

![This figure shows the regression test summary](https://developers.home.google.com/static/tools/images/ui-automator-regression-test.png)

## Feedback

To submit your thoughts or feedback on how to improve your experience with the
Google Home UI Automator, complete our
[Feedback Form](https://docs.google.com/forms/d/18pR0OpnPHPLohJm6vIxy3YOogCKwaJOVVcy0Unnyc8U/edit?resourcekey=0-cJxLNxBdYikawd4HgkIb8A).

## Report issues

Report encountered issues using the
[issue tracker](https://issuetracker.google.com/issues/new?component=655104&template=1694023).