End of support notice: On October 7th, 2026, Amazon will discontinue support for Amazon IoT Greengrass Version 1. After October 7th, 2026, you will no longer be able to access the Amazon IoT Greengrass V1 resources. For more information, please visit [Migrate from Amazon IoT Greengrass Version 1](https://docs.amazonaws.cn/greengrass/v2/developerguide/migrate-from-v1.html).
# Run the Amazon IoT Greengrass qualification suite
After you [set the required configuration](set-config.md), you can start the tests. The runtime of the full test suite depends on your hardware. For reference, it takes approximately 30 minutes to complete the full test suite on a Raspberry Pi 3B.
The following example `run-suite` commands show you how to run the qualification tests for a device pool. A device pool is a set of identical devices.
------
#### [ IDT v3.0.0 and later ]
Run all test groups in a specified test suite.
```
devicetester_{{[linux | mac | win_x86-64]}} run-suite --suite-id GGQ_1.0.0 --pool-id {{}}
```
Use the `list-suites` command to list the test suites that are in the `tests` folder.
Run a specific test group in a test suite.
```
devicetester_{{[linux | mac | win_x86-64]}} run-suite --suite-id GGQ_1.0.0 --group-id {{}} --pool-id {{}}
```
Use the `list-groups` command to list the test groups in a test suite.
Run a specific test case in a test group.
```
devicetester_{{[linux | mac | win_x86-64]}} run-suite --group-id {{}} --test-id {{}}
```
Run multiple test cases in a test group.
```
devicetester_{{[linux | mac | win_x86-64]}} run-suite --group-id {{}} --test-id {{,}}
```
List the test cases in a test group.
```
devicetester_{{[linux | mac | win_x86-64]}} list-test-cases --group-id {{}}
```
The options for the `run-suite` command are optional. For example, you can omit `pool-id` if you have only one device pool defined in your `device.json` file. Or, you can omit `suite-id` if you want to run the latest test suite version in the `tests` folder.
**Note**
IDT prompts you if a newer test suite version is available online. For more information, see [Set the default update behavior](#idt-update-behavior).
For more information about `run-suite` and other IDT commands, see [IDT for Amazon IoT Greengrass commands](#bk-cli).
------
#### [ IDT v2.3.0 and earlier ]
Run all test groups in a specified suite.
```
devicetester_{{[linux | mac | win_x86-64]}} run-suite --suite-id GGQ_1 --pool-id {{}}
```
Run a specific test group.
```
devicetester_{{[linux | mac | win_x86-64]}} run-suite --suite-id GGQ_1 --group-id {{}} --pool-id {{}}
```
`suite-id` and `pool-id` are optional if you are running a single test suite on a single device pool. This means that you have only one device pool defined in your `device.json` file.
------
## Check for Greengrass dependencies
We recommend that you run the dependency checker test group to make sure all Greengrass dependencies are installed before you run related test groups. For example:
+ Run `ggcdependencies` before running core qualification test groups.
+ Run `containerdependencies` before running container-specific test groups.
+ Run `dockerdependencies` before running Docker-specific test groups.
+ Run `ggcstreammanagementdependencies` before running stream manager-specific test groups.
## Set the default update behavior
When you start a test run, IDT checks online for a newer test suite version. If one is available, IDT prompts you to update to the latest available version. You can set the `upgrade-test-suite` (or `u`) flag to control the default update behavior. Valid values are:
+ `y`. IDT downloads and uses the latest available version.
+ `n` (default). IDT uses the version specified in the `suite-id` option. If `suite-id` is not specified, IDT uses the latest version in the `tests` folder.
If you don't include the `upgrade-test-suite` flag, IDT prompts you when an update is available and waits 30 seconds for your input (`y` or `n`). If no input is entered, it defaults to `n` and continues running the tests.
The following examples show common use cases for this feature:
**Automatically use the latest tests available for a test group.**
```
devicetester_linux run-suite -u y --group-id mqtt --pool-id DevicePool1
```
**Run tests in a specific test suite version.**
```
devicetester_linux run-suite -u n --suite-id GGQ_1.0.0 --group-id mqtt --pool-id DevicePool1
```
**Prompt for updates at runtime.**
```
devicetester_linux run-suite --pool-id DevicePool1
```
## IDT for Amazon IoT Greengrass commands
The IDT commands are located in the `{{}}/bin` directory. Use them for the following operations:
------
#### [ IDT v3.0.0 and later ]
`help`
Lists information about the specified command.
`list-groups`
Lists the groups in a given test suite.
`list-suites`
Lists the available test suites.
`list-supported-products`
Lists the supported products, in this case Amazon IoT Greengrass versions, and test suite versions for the current IDT version.
`list-test-cases`
Lists the test cases in a given test group. The following option is supported:
+ `group-id`. The test group to search for. This option is required and must specify a single group.
`run-suite`
Runs a suite of tests on a pool of devices. The following are some supported options:
+ `suite-id`. The test suite version to run. If not specified, IDT uses the latest version in the `tests` folder.
+ `group-id`. The test groups to run, as a comma-separated list. If not specified, IDT runs all test groups in the test suite.
+ `test-id`. The test cases to run, as a comma-separated list. When specified, `group-id` must specify a single group.
+ `pool-id`. The device pool to test. You must specify a pool if you have multiple device pools defined in your `device.json` file.
+ `upgrade-test-suite`. Controls how test suite version updates are handled. Starting in IDT v3.0.0, IDT checks online for updated test suite versions. For more information, see [Test suite versions](idt-gg-qualification.md#idt-test-suite-versions).
+ `stop-on-first-failure`. Configures IDT to stop execution on the first failure. This option should be used with `group-id` to debug the specified test groups. Do not use this option when running a full test-suite to generate a qualification report.
+ `update-idt`. Sets the response for the prompt to update IDT. `Y` as input stops the test execution if IDT detects there is a newer version. `N` as input continues the test execution.
+ `update-managed-policy`. `Y` as input stops the test execution if IDT detects that the user's managed policy isn’t updated. `N` as input continues the test execution.
For more information about `run-suite` options, use the `help` option:
```
devicetester_{{[linux | mac | win_x86-64]}} run-suite -h
```
------
#### [ IDT v2.3.0 and earlier ]
`help`
Lists information about the specified command.
`list-groups`
Lists the groups in a given test suite.
`list-suites`
Lists the available test suites.
`run-suite`
Runs a suite of tests on a pool of devices.
For more information about `run-suite` options, use the `help` option:
```
devicetester_{{[linux | mac | win_x86-64]}} run-suite -h
```
------