本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 教學課程：建置並執行範例 IDT 測試套件
<a name="build-sample-suite"></a>

 AWS IoT Device Tester 下載包含範例測試套件的原始程式碼。您可以完成此教學課程來建置和執行範例測試套件，以了解如何使用 IDT for AWS IoT Greengrass 來執行自訂測試套件。

 在本教學課程中，您將完成下列步驟：

1. [建置範例測試套件](#build-sample)

1. [使用 IDT 執行範例測試套件](#run-sample)

## 先決條件
<a name="prereqs-tutorial-sample"></a><a name="prereqs-list"></a>

為了完成本教學，您需要以下項目：
+ 

**主機電腦需求**
  + 的最新版本 AWS IoT Device Tester
  + [Python](https://www.python.org/downloads/) 3.7 或更新版本

    若要檢查安裝在電腦上的 Python 版本，請執行下列命令：

    ```
    python3 --version
    ```

    在 Windows 上，如果使用此命令傳回錯誤，請`python --version`改用 。如果傳回的版本編號為 3.7 或更新版本，請在 Powershell 終端機中執行下列命令，將 `python3`設定為`python`命令的別名。

    ```
    Set-Alias -Name "python3" -Value "python"
    ```

    如果未傳回版本資訊或版本編號小於 3.7，請遵循[下載 Python](https://wiki.python.org/moin/BeginnersGuide/Download) 中的指示安裝 Python 3.7\$1。如需詳細資訊，請參閱 [Python 文件](https://docs.python.org)。
  + [urllib3](https://urllib3.readthedocs.io/en/latest/)

    若要驗證 `urllib3` 是否正確安裝，請執行下列命令：

    ```
    python3 -c 'import urllib3'
    ```

    如果`urllib3`未安裝 ，請執行下列命令來安裝它：

    ```
    python3 -m pip install urllib3
    ```
+ 

**裝置要求**
  + 具有 Linux 作業系統和與主機電腦相同網路連線的裝置。

    我們建議您將 [Raspberry Pi](https://www.raspberrypi.org/) 與 Raspberry Pi 作業系統搭配使用。請務必在 Raspberry Pi 上設定 [SSH](https://www.raspberrypi.org/documentation/remote-access/ssh/) 以遠端連線到它。

## 設定 IDT 的裝置資訊
<a name="configure-idt-sample"></a>

設定您的裝置資訊，讓 IDT 執行測試。您必須使用下列資訊更新位於 `<device-tester-extract-location>/configs` 資料夾的 `device.json` 範本。

```
[
  {
    "id": "pool",
    "sku": "N/A",
    "devices": [
      {
        "id": "<device-id>",
        "connectivity": {
          "protocol": "ssh",
          "ip": "<ip-address>",
          "port": "<port>",
          "auth": {
            "method": "pki | password",
            "credentials": {
              "user": "<user-name>",
              "privKeyPath": "/path/to/private/key",
              "password": "<password>"
            }
          }
        }
      }
    ]
  }
]
```

在 `devices` 物件中，提供下列資訊：

`id`  
您裝置的使用者定義唯一識別符。

`connectivity.ip`  
您裝置的 IP 地址。

`connectivity.port`  
選用。用於 SSH 連線至您裝置的連接埠號碼。

`connectivity.auth`  
連線的驗證資訊。  
只有當 `connectivity.protocol` 設為 `ssh` 時，才會套用此屬性。    
`connectivity.auth.method`  
用來透過指定的連線通訊協定存取裝置的驗證方法。  
支援的值如下：  
+ `pki`
+ `password`  
`connectivity.auth.credentials`  
用於驗證的燈入資料。    
`connectivity.auth.credentials.user`  
用來登入裝置的使用者名稱。  
`connectivity.auth.credentials.privKeyPath`  
用來登入您裝置之私有金鑰的完整路徑。  
只有當 `connectivity.auth.method` 設為 `pki` 時，才會套用此值。  
`devices.connectivity.auth.credentials.password`  
用於登入您裝置的密碼。  
只有當 `connectivity.auth.method` 設為 `password` 時，才會套用此值。

**注意**  
如果 `method` 是設定為 `pki`，則指定 `privKeyPath`  
如果 `method` 是設定為 `password`，則指定 `password`

## 建置範例測試套件
<a name="build-sample"></a>

`<device-tester-extract-location>/samples/python` 資料夾包含範例組態檔案、原始程式碼和 IDT 用戶端 SDK，您可以使用提供的建置指令碼將其合併為測試套件。下列目錄樹狀目錄顯示這些範例檔案的位置：

```
<device-tester-extract-location>
├── ...
├── tests
├── samples
│   ├── ...
│   └── python
│       ├── configuration
│       ├── src
│       └── build-scripts
│           ├── build.sh
│           └── build.ps1
└── sdks
    ├── ...
    └── python
        └── idt_client
```

若要建置測試套件，請在主機電腦上執行下列命令：

------
#### [ Windows ]

```
cd <device-tester-extract-location>/samples/python/build-scripts
./build.ps1
```

------
#### [ Linux, macOS, or UNIX ]

```
cd <device-tester-extract-location>/samples/python/build-scripts
./build.sh
```

------

這會在 `IDTSampleSuitePython_1.0.0` 資料夾內的 `<device-tester-extract-location>/tests` 資料夾中建立範例測試套件。檢閱 `IDTSampleSuitePython_1.0.0` 資料夾中的檔案，以了解範例測試套件的結構，並查看各種測試案例可執行檔和測試組態 JSON 檔案的範例。

**注意**  
範例測試套件包含 python 原始程式碼。請勿在測試套件程式碼中包含敏感資訊。

下一步：使用 IDT 執行[您建立的範例測試套件](#run-sample)。

## 使用 IDT 執行範例測試套件
<a name="run-sample"></a>

若要執行範例測試套件，請在主機電腦上執行下列命令：

```
cd <device-tester-extract-location>/bin
./devicetester_[linux | mac | win_x86-64] run-suite --suite-id IDTSampleSuitePython
```

IDT 會執行範例測試套件，並將結果串流至主控台。當測試完成執行時，您會看到下列資訊：

```
========== Test Summary ==========
Execution Time:         5s
Tests Completed:        4
Tests Passed:           4
Tests Failed:           0
Tests Skipped:          0
----------------------------------
Test Groups:
    sample_group:       PASSED
----------------------------------
Path to IoT Device Tester Report: /path/to/devicetester/results/87e673c6-1226-11eb-9269-8c8590419f30/awsiotdevicetester_report.xml
Path to Test Execution Logs: /path/to/devicetester/results/87e673c6-1226-11eb-9269-8c8590419f30/logs
Path to Aggregated JUnit Report: /path/to/devicetester/results/87e673c6-1226-11eb-9269-8c8590419f30/IDTSampleSuitePython_Report.xml
```

## 疑難排解
<a name="tutorial-troubleshooting-custom"></a>

使用以下資訊來協助解決完成教學課程的任何問題。

**測試案例未成功執行**  
如果測試未成功執行，IDT 會將錯誤日誌串流至主控台，以協助您對測試執行進行疑難排解。請確定您符合本教學課程的所有[先決條件](#prereqs-tutorial-sample)。

**無法連線至待測裝置**

請確認下列內容：
+ 您的 `device.json` 檔案包含正確的 IP 地址、連接埠和身分驗證資訊。
+ 您可以從主機電腦透過 SSH 連線至裝置。