From 5cbe2931f64e16a44fc843e148325909fbe1511d Mon Sep 17 00:00:00 2001 From: "Josh V [Apple]" Date: Thu, 17 Feb 2022 05:46:21 -0800 Subject: [PATCH] Update readme with additional functionality. (#15160) --- .github/.wordlist.txt | 109 +++++- src/app/tests/suites/README.md | 359 ++++++++++++++++-- .../tests/suites/examples/Config_Example.yaml | 7 + .../examples/Config_Variables_Example.yaml | 31 ++ .../tests/suites/examples/PICS_Example.yaml | 15 + .../suites/examples/Response_Example.yaml | 8 + .../tests/suites/examples/TestGenExample.zapt | 8 + src/app/tests/suites/examples/TestPICS | 2 + .../tests/suites/examples/Test_Example.yaml | 36 ++ .../tests/suites/examples/Test_Example_1.yaml | 10 + .../tests/suites/examples/Test_Example_2.yaml | 10 + .../tests/suites/examples/Test_Example_3.yaml | 10 + .../suites/examples/gen_readme_example.sh | 29 ++ .../suites/examples/templates/templates.json | 16 + .../tests/suites/examples/templates/tests.js | 49 +++ src/controller/README.md | 5 + 16 files changed, 667 insertions(+), 37 deletions(-) create mode 100644 src/app/tests/suites/examples/Config_Example.yaml create mode 100644 src/app/tests/suites/examples/Config_Variables_Example.yaml create mode 100644 src/app/tests/suites/examples/PICS_Example.yaml create mode 100644 src/app/tests/suites/examples/Response_Example.yaml create mode 100644 src/app/tests/suites/examples/TestGenExample.zapt create mode 100644 src/app/tests/suites/examples/TestPICS create mode 100644 src/app/tests/suites/examples/Test_Example.yaml create mode 100644 src/app/tests/suites/examples/Test_Example_1.yaml create mode 100644 src/app/tests/suites/examples/Test_Example_2.yaml create mode 100644 src/app/tests/suites/examples/Test_Example_3.yaml create mode 100755 src/app/tests/suites/examples/gen_readme_example.sh create mode 100644 src/app/tests/suites/examples/templates/templates.json create mode 100644 src/app/tests/suites/examples/templates/tests.js diff --git a/.github/.wordlist.txt b/.github/.wordlist.txt index aac333fa389469..0a51f7a18f863f 100644 --- a/.github/.wordlist.txt +++ b/.github/.wordlist.txt @@ -16,6 +16,7 @@ abfb ABI ABIs ables +AccessControl accessor AccountLogin acdbc @@ -29,7 +30,9 @@ AddOrUpdateWiFiNetwork addr AddThreadNetwork adk +AdministratorCommissioning adoc +adr AdvAutonomous AdvManagedFlag AdvOnLink @@ -49,6 +52,8 @@ APIs apk AppConfig AppImpl +ApplianceControl +ApplianceIdentification ApplicationBasic ApplicationId ApplicationIdentifier @@ -70,9 +75,11 @@ ASAN asdk AssertionError ASYNC +atomics att attId attr +attrib attributeValue attrListName attrMask @@ -97,6 +104,7 @@ babaf backend backticks backtrace +BallastConfiguration BarrierControl BasicCHIPRegression baudrate @@ -105,6 +113,7 @@ BDX BDXDownloader BeagleBone befc +BinaryInputBasic bitbake bld BLE @@ -119,15 +128,20 @@ blocklist blockquote bluetoothd bluez +BooleanState bootable Bootloader BorderRouterAP BRD breakpoint bredr +BridgedActions BridgedDeviceBasic bridgedLightEndpoint bringup +BromateConcentrationMeasurement +BromodichloromethaneConcentrationMeasurement +BromoformConcentrationMeasurement bt btmgmt BTN @@ -143,6 +157,8 @@ cacerts CAfile cancelled capacitive +CarbonDioxideConcentrationMeasurement +CarbonMonoxideConcentrationMeasurement CatalogVendorId CBB cbd @@ -179,7 +195,12 @@ ChipMessageLayer CHIPOBLE CHIPProjectConfig CHIPTest +chiptests CHIPTool +ChloraminesConcentrationMeasurement +ChlorineConcentrationMeasurement +ChlorodibromomethaneConcentrationMeasurement +ChloroformConcentrationMeasurement chmod chrpath CIPD @@ -237,6 +258,7 @@ continuousHinting contrib controllee conv +CopperConcentrationMeasurement cortexa cp cpio @@ -281,6 +303,8 @@ DCONFIG debianutils DEDEDEDE deepnote +definedValue +DehumidificationControl DelayedActionTime delayedActionTimeSec delayQuery @@ -305,8 +329,10 @@ DeviceNetworkProvisioningDelegate DeviceNetworkProvisioningDelegateImpl DevicePairingDelegate deviceSoftwareVersionModel +DeviceTemperatureConfiguration DevKitC DevKitM +devtype df dfu DgDxsfHx @@ -315,6 +341,7 @@ DHCP DHCPC DHCPv dhrishi +DiagnosticLogs dialout diffstat diffsyms @@ -325,6 +352,7 @@ disambiguated discoverable DispatchEvent DispatchEventToApplication +DissolvedOxygenConcentrationMeasurement DISTRO Distutils DK @@ -380,6 +408,7 @@ EnableNetwork EnableWiFiNetwork EndpointId endpointName +endsWith eno entrypoint enum @@ -392,6 +421,8 @@ esptool eth EthernetNetworkDiagnostics ethernets +EthyleneConcentrationMeasurement +EthyleneOxideConcentrationMeasurement EvalCode EvalCodeWithName EvalFrameDefault @@ -407,6 +438,7 @@ extpanid FabricId fabricIdx factoryreset +FanControl fb fbb fbd @@ -415,6 +447,7 @@ FDDE fddead fde FECA +FecalColiformAndEColiConcentrationMeasurement feff ffaa ffeebaefa @@ -427,6 +460,8 @@ filepath fini FixedLabel flashdebug +FlowMeasurement +FluorideConcentrationMeasurement focusable forkpty formatOnSave @@ -455,7 +490,9 @@ GetDeviceId GetDeviceInfo GetDns GetIP +getManualTests getstarted +getTests GH gh ghp @@ -481,6 +518,7 @@ GroupKeyManagement gtk Gv gz +HaloaceticAcidsConcentrationMeasurement hardcoded hardknott hardwarever @@ -498,6 +536,11 @@ hostname href HTTPS HW +hwadr +HydrogenConcentrationMeasurement +HydrogenSulphideConcentrationMeasurement +IasAce +IasWd iaszone ibb ICA @@ -508,6 +551,7 @@ ifdef ifdefs IGMP ihex +IlluminanceMeasurement IM imager imagetool @@ -537,6 +581,7 @@ InvokeCommandRequests InvokeCommandResponse IoT ipaddr +ipadr ipp iptables iputils @@ -545,6 +590,9 @@ ipykernel ipynb IPython ISCAN +isHexString +isLowerCase +isUpperCase itemName iterable JDK @@ -573,6 +621,7 @@ LabelList launchable LAUNCHXL ldflags +LeadConcentrationMeasurement LEDs LevelControl LF @@ -608,6 +657,7 @@ LinuxOTAImageProcessor LinuxOTARequestorDriver LocalConfigDisabled localhost +LocalizationConfiguration localstatedir LockingState loopback @@ -627,6 +677,7 @@ Makefile makefiles MakeTpCall mandir +ManganeseConcentrationMeasurement ManualPairingCode ManualTest ManufacturingDate @@ -641,7 +692,9 @@ matterUTestLib maxApplicableSoftwareVersion MaxInterval MaxIntervalCeilingSeconds +maxLength MaxRtrAdvInterval +maxValue mbed MbedCommissioning MbedNewTarget @@ -663,6 +716,7 @@ memdf MemMonitoring menuconfig MeshCoP +MeterIdentification MfgDeviceCaCerts MfgSpecificPing mfrcacerts @@ -678,12 +732,15 @@ minApplicableSoftwareVersion Minicom MinInterval MinIntervalFloorSeconds +minLength MinRtrAdvInterval +minValue mkdir mlan MLD mmevk moal +ModeSelect modprobe Modustoolbox moveMode @@ -719,6 +776,8 @@ networkID networkname NewUDPEndPoint nfds +NitricOxideConcentrationMeasurement +NitrogenDioxideConcentrationMeasurement nl NLUnitTest NLUnitTests @@ -726,6 +785,7 @@ NodeId nongnu nordicsemi NotAvailable +notValue nRF nrfconnect nrfdks @@ -747,6 +807,7 @@ oneshot onnetwork OnOff OnOffClusterTest +OnOffSwitchConfiguration OnPlatformEvent OO openjdk @@ -776,11 +837,14 @@ OTARequesterImpl OTARequestor OTARequestorDriver OTARequestorSerialPort +OtaSoftwareUpdateProvider otasoftwareupdaterequestor otaURL OTBR otcli outgoingCommands +OxygenConcentrationMeasurement +OzoneConcentrationMeasurement PAA PacketBuffer PAI @@ -816,13 +880,19 @@ PlatformManager PlatformManagerImpl plt png +PollControl polymorphism POSIX PosixConfig postAttributeChangeCallback +PowerConfiguration +PowerProfile +PowerSource +PowerSourceConfiguration pre preprocessor Presetup +PressureMeasurement prj ProductID ProductLabel @@ -832,14 +902,18 @@ proto protobuf protos Prover -providerNodeId providerFabricIndex +providerNodeId +ProxyConfiguration +ProxyDiscovery +ProxyValid PRs PSCAN PSK PSoC PTR pts +PulseWidthModulation PumpConfigurationAndControl pwd PWM @@ -895,8 +969,8 @@ repo req Requestor Requestor's -Requestors RequestorCanConsent +Requestors responder retargeting reusability @@ -924,6 +998,7 @@ runtime rw RXD sandboxed +saveAs sbin scalability scalable @@ -956,6 +1031,7 @@ SetUpPINCode SetupQRCode sexualized SHA +ShadeConfiguration showDocumentation shubhamdp SIGINT @@ -973,6 +1049,7 @@ smoketest SMP socat socio +SodiumConcentrationMeasurement softap SoftDevice softmmu @@ -990,12 +1067,14 @@ SRV SSID startoffset StartScan +startsWith stderr stdout sterm storagepath str strcpy +struct su Subclassing subcommand @@ -1010,6 +1089,8 @@ SubscribeResponse SubscriptionId subtype sudo +SulfateConcentrationMeasurement +SulfurDioxideConcentrationMeasurement svg SVR SWD @@ -1023,6 +1104,7 @@ systemctl systemd systemdsystemunitdir systemduserunitdir +systime sysv TargetNavigator TBD @@ -1034,9 +1116,12 @@ TemperatureMeasurement testability TestArray TestCluster +TestConstraints TestEmptyString +TestGenExample TestMultiRead TESTPASSWD +TestPICS TESTSSID TestString TestStruct @@ -1047,12 +1132,18 @@ testws texinfo textboxes TFT +ThermostatUserInterfaceConfiguration ThIsIsNoTMyReAlGiThUbToKeNSoDoNoTtRy +ThreadNetworkDiagnostics threadOperationalDataset ThreadStackManager ThreadStackManagerImpl +ths Thunderboard +timedInteractionTimeoutMs +TimeFormatLocalization timeoutMs +TimeSynchronization TKIP tlsr TLV @@ -1065,7 +1156,9 @@ toolchain toolchains topologies tos +TotalColiformBacteriaConcentrationMeasurement totalTests +TotalTrihalomethanesConcentrationMeasurement trackAlloc trackFree transitionTime @@ -1079,6 +1172,7 @@ ttyACM ttyACMx ttymxc ttyUSB +TurbidityConcentrationMeasurement TXD txt UART @@ -1097,6 +1191,7 @@ uncommissioned unfocus Unicast UniFlash +UnitLocalization unpair unprovisioned untrusted @@ -1124,6 +1219,7 @@ VendorID VendorName vendorpayload venv +ver Verifier Verifiers VID @@ -1145,6 +1241,7 @@ whitespace whitespaces whl wic +WiFiNetworkDiagnostics WindowCovering WindowCoveringGoToLiftPercentage wlan @@ -1171,9 +1268,17 @@ xd xdeadbeefcafe xds xdsdfu +xEA +xEB +xEC xed xef xF +xFA +xFB +xFC +xFD +xFE xFF xFFF xFFFF diff --git a/src/app/tests/suites/README.md b/src/app/tests/suites/README.md index 060a4d23cd5012..62f441aeeca6fd 100644 --- a/src/app/tests/suites/README.md +++ b/src/app/tests/suites/README.md @@ -1,12 +1,36 @@ # CHIP Test Suites +- [CHIP Test Suites](#chip-test-suites) +- [Controllers](#controllers) +- [Automatic conversion process](#automatic-conversion-process) +- [List](#list) + - [chip_tests](#list-chiptests) + - [Property: test](#property-test) + - [Property: config](#property-config) + - [Property: {variable_name}](#property-variable_name) + - [chip_tests_items](#list-chip_tests_items) + - [Property: tests](#property-tests) + - [Property: arguments](#property-arguments) + - [Property: values](#property-values) + - [Property: response](#property-response) + - [Property: constraints](#property-constraints) + - [chip_tests_item_parameters](#list-chip_tests_item_parameters) + - [chip_tests_item_response_parameters](#list-chip_tests_item_response_parameters) + - [chip_tests_pics](#list-chip_tests_pics) +- [YAML Test Definition](#yaml-test-definition) +- [PICS Usage](#pics-usage) +- [Examples](#examples) + - [YAML Examples](#yaml-examples) + - [ZAP Example](#zap-example) +- [Index](#index) + This directory contains a set of tests describing interactions between nodes, and more specifically between a controller and a controllee. This test set is written in a high level language before being automatically converted into a language understandable by the different controllers. -## Controllers +# Controllers There are currently 4 implementations of the CHIP device controller. These different implementations share a common configuration file describing the @@ -16,6 +40,7 @@ supported functionalities in terms of clusters, commands and attributes: | Controllers | Testing | | ----------- | ------- | | POSIX CLI | y | +| Darwin CLI | y | | iOS | y | | Python | n | | Android | n | @@ -23,7 +48,7 @@ supported functionalities in terms of clusters, commands and attributes: For more information on the different implementations of the CHIP device controller, see [README.md](../../../controller/README.md) -## Automatic conversion process +# Automatic conversion process The process of automatic conversion of test files depends on the [ZAP](https://github.com/project-chip/zap) tool. @@ -34,6 +59,7 @@ translating the tests into an appropriate format. | Controllers | Template | | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | POSIX CLI | [examples/chip-tool/templates/partials/test_cluster.zapt](../../../../examples/chip-tool/templates/partials/test_cluster.zapt) | +| Darwin CLI | [examples/chip-tool-darwin/templates/partials/test_cluster.zapt](../../../../examples/chip-tool-darwin/templates/partials/test_cluster.zapt) | | iOS | [src/darwin/Framework/CHIP/templates/partials/test_cluster.zapt](../../../../src/darwin/Framework/CHIP/templates/partials/test_cluster.zapt) | | Python | | | Android | | @@ -43,7 +69,7 @@ These dedicated templates share a common test file with the content of the ZAP database built from the [definition files](../../zap-templates/zcl) of the specification. -## Lists +# Lists This common script exposes the result of the analysis in the form of multiple lists accessible from the dedicated template files. @@ -52,25 +78,36 @@ These lists contain elements of which certain properties are directly configurable through the source test file, but also additional properties added during the analysis. -### List: _{{chip\_tests}}_ +## List: _chip_tests_ -**{{chip_tests}}** takes as parameter a list of test files and returns an +**{{chip\_tests}}** takes as parameter a list of test files and returns an iterable list of objects. Each element of the list is an object with the following properties: -| Name | Description | -| ------ | ---------------------------------------------------------------------------------- | -| name | Name of the test set in human readable format | -| config | Default configuration that is inherited by each of the tests in this set | -| tests | The set of tests. It is possible to iterate over it using **{{chip\_test_items}}** | +#### Property: [_test_](./examples/Test_Example.yaml) + +| Name | Description | Required | +| ------ | ----------------------------------------------------------------------------------- | -------- | +| name | Name of the test set in human readable format | Yes | +| config | Default configuration that is inherited by each of the tests in this set | Yes | +| tests | The set of tests. It is possible to iterate over it using **{{chip\_test\_items}}** | Yes | + +#### Property: [_config_](#basic-yaml-config-example) + +| Name | Description | Required | +| --------------- | ------------------------------------------------------------------------------------------------ | -------- | +| cluster | Name of the cluster listed in [Cluster Names](#index) | No | +| endpoint | Endpoint Identifier that will be targeted by default by each of the tests in this set | No | +| identity | Name of the controller to perform tests with. alpha, beta, and gamma are the only ones supported | No | +| {variable_name} | Name of test variable to use within test. | No | -##### Property: _config_ +##### Property: [_{variable_name}_](./examples/Config_Variables_Example.yaml) -| Name | Description | -| -------- | ------------------------------------------------------------------------------------- | -| cluster | Name of the cluster that will be targeted by default by each of the tests in this set | -| endpoint | Endpoint Identifier that will be targeted by default by each of the tests in this set | +| Name | Description | +| --------------- | ------------------------------------------------ | +| {variable_name} | Name of test variable to use within test. | +| type | Macro type from [ZAP atomics](#zap-atomic-types) | Additionally, the object exhibits the following autogenerated properties: @@ -79,25 +116,67 @@ Additionally, the object exhibits the following autogenerated properties: | filename | Name of the source file from which the test set was built | | totalTests | Total number of tests contained in this set | -### List: _{{chip\_tests\_items}}_ +## List: _chip_tests_items_ -**{{chip\_tests\_items}}** can be used inside a **{{chip_tests}}** block and +**{{chip\_tests\_items}}** can be used inside a **{{chip\_tests}}** block and iterates over the test set. Each element of the list is an object with the following configurable properties: -| Name | Description | -| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| label | Test name | -| disabled | Allows to deactivate a test | -| command | Name of the command to execute. The command can be any of the commands available for the cluster, or a special command. | -| attribute | If the command is a special attribute command, then this property contains the name of the attribute targeted by the command. | -| optional | Allows you to specify that a test is optional. An optional test passes if the controllee does not support the requested command or if the command is supported, and the specified conditions are validated. | -| cluster | The name of the target cluster. _If not specified, the default configuration is used._ | -| endpoint | The identifier of the target endpoint. _If not specified, the default configuration is used._ | -| arguments | A list of arguments to pass to the command. It is possible to iterate over it using **{{chip\_test\_item_\parameters}}** | -| response | A list of expected results or result constraints. It is possible to iterate over it using **{{chip\_test\_item\_response\_parameters}}** | +#### Property: [_tests_](./examples/Test_Example.yaml) + +| Name | Description | Required | +| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | +| label | Test name | Yes | +| disabled | Allows to deactivate a test | No | +| command | Name of the command to execute. The command can be any of the commands available for the cluster, or a special command. | No | +| attribute | If the command is a special attribute command, then this property contains the name of the attribute targeted by the command. | No | +| optional | Allows you to specify that a test is optional. An optional test passes if the controllee does not support the requested command or if the command is supported, and the specified conditions are validated. | No | +| cluster | Name from [Cluster names](#index) . _If not specified, the default configuration is used._ | No | +| endpoint | The identifier of the target endpoint. _If not specified, the default configuration is used._ | No | +| arguments | A list of arguments to pass to the command. It is possible to iterate over it using **{{chip\_test\_item\_parameters}}** | No | +| response | A list of expected results or result constraints. It is possible to iterate over it using **{{chip\_test\_item\_response\_parameters}}** | No | +| PICS | Protocol Implementation Conformance Statement. A conditional flag that this determines whether a test step should run. | No | +| timedInteractionTimeoutMs | Sets a timeout for Writing to attribute and sending a command. | No | + +##### Property: [_arguments_](./examples/Test_Example.yaml) + +| Name | Description | Required | +| ------ | ------------------- | -------- | +| values | A list of arguments | Yes | + +##### Property: [_values_](./examples/Test_Example.yaml) + +| Name | Description | Required | +| ----- | ----------------------------------------------------- | -------- | +| name | The name of the argument to be used | No | +| value | The value of the argument to be used within test step | Yes | + +##### Property: [_response_](./examples/Test_Example.yaml) + +| Name | Description | Required | +| ----------- | ------------------------------------------------------------------------------------------------------------ | ---------------------- | +| values | A list of values to expect on response. See [Property: value](#property-values) | No (If other provided) | +| value | The values expected on the the response from the command | No (If other provided) | +| error | Error code that is expected from response | No (If other provided) | +| saveAs | Save a value to a variable name for later use. Value above required. [Example](./examples/Test_Example.yaml) | No | +| constraints | Constraints to check for on response from the command | No | + +##### Property: [_constraints_](../../../../src/app/tests/suites/TestConstraints.yaml) + +| Name | Description | Required | +| ----------- | ----------------------------------------------------------- | ---------------------- | +| minValue | Minimum value to expect from the command response. | No (If other provided) | +| maxValue | Maximum value to expect from the command response. | No (If other provided) | +| notValue | Validate the the value is not what is provided. | No (If other provided) | +| minLength | Minimum length of the response parameter. | No (If other provided) | +| maxLength | Maximum length of the string parameter. | No (If other provided) | +| startsWith | Condition is which will validate what a string starts with. | No (If other provided) | +| endsWith | Condition is which will validate what a string ends with. | No (If other provided) | +| isLowerCase | Validates if the char_string is lower case. | No (If other provided) | +| isUpperCase | Validates if the char_string is upper case. | No (If other provided) | +| isHexString | Checks whether the char_string is a hex string. | No (If other provided) | Additionally, the object exhibits the following autogenerated properties: @@ -105,10 +184,10 @@ Additionally, the object exhibits the following autogenerated properties: | ----- | ------------------ | | index | Overall test index | -### List: _{{chip\_tests\_item\_parameters}}_ +## List: _chip_tests_item_parameters_ -**{{chip\_tests\_item|_parameters}}** can be used inside a -**{{chip_test_items}}** block and iterates over the test arguments for the +**{{chip\_tests\_item\_parameters}}** can be used inside a +**{{chip\_test\_items}}** block and iterates over the test arguments for the target command. This object contains all the properties contained in the ZAP database related to @@ -116,11 +195,11 @@ the command or the attribute in the case of a special attribute command. It is increased by the value to be used contained in the test file. -### List: _{{chip\_tests\_item\_response\_parameters}}_ +## List: _chip_tests_item_response_parameters_ -**{{chip\_tests\_item|_response|_parameters}}** can be used inside a -**{{chip_test_items}}** block and iterates over the test response arguments for -the target command. +**{{chip\_tests\_item\_response\_parameters}}** can be used inside a +**{{chip\_test\_items}}** block and iterates over the test response arguments +for the target command. This object contains all the properties contained in the ZAP database related to the response or the attribute response in the case of a special attribute @@ -128,3 +207,213 @@ command. It is increased by the expected value or the constraints to be used contained in the test file. + +## List: _chip_tests_pics_ + +**{{chip\_tests\_pics}}** can be used to get the collection of all PICS for a +given test. + +## List: _chip_tests_config_ + +**{{chip\_tests\_config}}** can be used to get the collection of user defined +variables in the config. See [ZAP Tests Config](#examples) below + +This object contains {{name}} {{definedValue}} and {{type}}. +(chip_tests_config_has definedValue) can be used to determine if there is a +value set for a particular user defined variable. + +| Name | Description | +| ------------ | ------------------------------------- | +| name | The name of the user defined variable | +| type | [ZAP Atomic Types](#index) Macro | +| definedValue | The value of the user define variable | + +# YAML Test Definition + +YAML is used to generate tests into a programming language understood by +commissioners, controllers, or simulated devices. There is a define set of +keyword/values that are used to define test behavior. + +YAML is the high level language chosen to generate test against a controller or +a controllee. [Test Definition Example](#yaml-examples) + +Top level key to define a YAML test: [test](#property-test) + +## Location of Test Definitions + +- [Simulated README](../../../../docs/guides/simulated_device_linux.md) +- Simulated tests: + [tests.js](../../../../examples/placeholder/linux/apps/app1/tests.js) + +- chip-tool(darwin) tests: + [tests.js](../../../../examples/chip-tool-darwin/templates/tests.js) + +- chip-tool tests: + [tests.js](../../../../examples/chip-tool/templates/tests.js) + + ```javascript + // Manual test definitions. Does not run in CI. + function getManualTests(); + + // Test definition that run in CI. + function getTests(); + ``` + +# PICS Usage + +#### Required Files + +- [PICS Test YAML](./examples/PICS_Example.yaml) +- [TestPICS](./examples/TestPICS) + +#### Example PICS Command + +``` +chip-tool tests Test 1 --PICS TestPICS.txt +``` + +# Examples + +## YAML Examples + +- [Basic YAML Config Example](./examples/Config_Example.yaml) +- [YAML Response Example](./examples/Response_Example.yaml) +- [YAML Tests Example](./examples/Test_Example.yaml) +- [YAML Config Variables Example](./examples/Config_Variables_Example.yaml) + +## ZAP Example + +### Required Files + +- [ZAP Example](./examples/TestGenExample.zapt) +- [Test1](./examples/Test_Example_1.yaml) +- [Test2](./examples/Test_Example_2.yaml) +- [Test3](./examples/Test_Example_3.yaml) + +### Generate Example Script + +The following script will generate an output file TestGenExample.out in +src/app/tests/suites/examples/out. The directory and the file will be created. +This is a basic demonstration on how tests are generated. + +``` +src/app/tests/suites/examples/gen_readme_example.sh +``` + +# Index + +
Atomic Type Info

+ +| Name | Size | Macro | ID | Description | C type | +| ----------------- | ---- | ----------------- | ---- | ------------------------ | ---------- | +| no_data | 0 | NO_DATA | 0x00 | No data | uint8_t \* | +| boolean | 1 | BOOLEAN | 0x10 | Boolean | uint8_t | +| bitmap8 | 1 | BITMAP8 | 0x18 | 8-bit bitmap | uint8_t | +| bitmap16 | 2 | BITMAP16 | 0x19 | 16-bit bitmap | uint16_t | +| bitmap24 | 3 | BITMAP24 | 0x1A | 24-bit bitmap | uint32_t | +| bitmap32 | 4 | BITMAP32 | 0x1B | 32-bit bitmap | uint32_t | +| bitmap64 | 8 | BITMAP64 | 0x1F | 64-bit bitmap | uint8_t \* | +| int8u | 1 | INT8U | 0x20 | Unsigned 8-bit integer | uint8_t | +| int16u | 2 | INT16U | 0x21 | Unsigned 16-bit integer | uint16_t | +| int24u | 3 | INT24U | 0x22 | Unsigned 24-bit integer | uint32_t | +| int32u | 4 | INT32U | 0x23 | Unsigned 32-bit integer | uint32_t | +| int40u | 5 | INT40U | 0x24 | Unsigned 40-bit integer | uint8_t \* | +| int48u | 6 | INT48U | 0x25 | Unsigned 48-bit integer | uint8_t \* | +| int56u | 7 | INT56U | 0x26 | Unsigned 56-bit integer | uint8_t \* | +| int64u | 8 | INT64U | 0x27 | Unsigned 64-bit integer | uint8_t \* | +| int8s | 1 | INT8S | 0x28 | Signed 8-bit integer | int8_t | +| int16s | 2 | INT16S | 0x29 | Signed 16-bit integer | int16_t | +| int24s | 3 | INT24S | 0x2A | Signed 24-bit integer | int32_t | +| int32s | 4 | INT32S | 0x2B | Signed 32-bit integer | int32_t | +| int40s | 5 | INT40S | 0x2C | Signed 40-bit integer | int8_t \* | +| int48s | 6 | INT48S | 0x2D | Signed 48-bit integer | int8_t \* | +| int56s | 7 | INT56S | 0x2E | Signed 56-bit integer | int8_t \* | +| int64s | 8 | INT64S | 0x2F | Signed 64-bit integer | int8_t \* | +| enum8 | 1 | ENUM8 | 0x30 | 8-bit enumeration | uint8_t | +| enum16 | 2 | ENUM16 | 0x31 | 16-bit enumeration | uint16_t | +| single | 4 | SINGLE | 0x39 | Single precision | uint8_t \* | +| double | 8 | DOUBLE | 0x3A | Double precision | uint8_t \* | +| octet_string | | OCTET_STRING | 0x41 | Octet String | uint8_t \* | +| char_string | | CHAR_STRING | 0x42 | Character String | uint8_t \* | +| long_octet_string | | LONG_OCTET_STRING | 0x43 | Long Octet String | uint8_t \* | +| long_char_string | | LONG_CHAR_STRING | 0x44 | Long Character String | uint8_t \* | +| array | | ARRAY | 0x48 | List | uint8_t \* | +| struct | | STRUCT | 0x4C | Structure | uint8_t \* | +| tod | 4 | TOD | 0xE0 | Time of day | uint8_t \* | +| date | 4 | DATE | 0xE1 | Date | uint32_t | +| utc | 4 | UTC | 0xE2 | UTC Time | uint8_t \* | +| epoch_us | 8 | EPOCH_US | 0xE3 | Epoch Microseconds | uint8_t \* | +| epoch_s | 4 | EPOCH_S | 0xE4 | Epoch Seconds | uint8_t \* | +| systime_us | 8 | SYSTIME_US | 0xE5 | System Time Microseconds | uint8_t \* | +| percent | 1 | PERCENT | 0xE6 | Percentage units 1% | uint8_t \* | +| percent100ths | 2 | PERCENT100THS | 0xE7 | Percentage units 0.01% | uint8_t \* | +| cluster_id | 4 | CLUSTER_ID | 0xE8 | Cluster ID | uint16_t | +| attrib_id | 4 | ATTRIB_ID | 0xE9 | Attribute ID | uint8_t \* | +| field_id | 4 | FIELD_ID | 0xEA | Field ID | uint8_t \* | +| event_id | 4 | EVENT_ID | 0xEB | Event ID | uint8_t \* | +| command_id | 4 | COMMAND_ID | 0xEC | Command ID | uint8_t \* | +| action_id | 1 | ACTION_ID | 0xED | Action ID | uint8_t \* | +| trans_id | 4 | TRANS_ID | 0xEF | Transaction ID | uint8_t \* | +| node_id | 8 | NODE_ID | 0xF0 | Node ID | uint8_t \* | +| vendor_id | 2 | VENDOR_ID | 0xF1 | Vendor ID | uint8_t \* | +| devtype_id | 4 | DEVTYPE_ID | 0xF2 | Device Type ID | uint8_t \* | +| fabric_id | 8 | FABRIC_ID | 0xF3 | Fabric ID | uint8_t \* | +| group_id | 2 | GROUP_ID | 0xF4 | Group ID | uint8_t \* | +| status | 2 | STATUS | 0xF5 | Status Code | uint8_t \* | +| data_ver | 4 | DATA_VER | 0xF6 | Data Version | uint_ver_t | +| event_no | 8 | EVENT_NO | 0xF7 | Event Number | uint8_t \* | +| endpoint_no | 2 | ENDPOINT_NO | 0xF8 | Endpoint Number | uint8_t \* | +| fabric_idx | 1 | FABRIC_IDX | 0xF9 | Fabric Index | uint8_t \* | +| ipadr | | IPADR | 0xFA | IP Address | uint8_t \* | +| ipv4adr | 4 | IPV4ADR | 0xFB | IPv4 Address | uint8_t \* | +| ipv6adr | 16 | IPV6ADR | 0xFC | IPv6 Address | uint8_t \* | +| ipv6pre | | IPV6PRE | 0xFD | IPv6 Prefix | uint8_t \* | +| hwadr | | HWADR | 0xFE | Hardware Address | uint8_t \* | +| unknown | 0 | UNKNOWN | 0xFF | Unknown | uint8_t \* | + +

+ +
Cluster Names

+ +| | | | +| ------------------------------ | ---------------------------------------- | --------------------------------------------- | +| PowerConfiguration | AdministratorCommissioning | DissolvedOxygenConcentrationMeasurement | +| DeviceTemperatureConfiguration | OperationalCredentials | BromateConcentrationMeasurement | +| Identify | GroupKeyManagement | ChloraminesConcentrationMeasurement | +| Groups | FixedLabel | ChlorineConcentrationMeasurement | +| Scenes | UserLabel | FecalColiformAndEColiConcentrationMeasurement | +| OnOff | ProxyConfiguration | FluorideConcentrationMeasurement | +| OnOffSwitchConfiguration | ProxyDiscovery | HaloaceticAcidsConcentrationMeasurement | +| LevelControl | ProxyValid | TotalTrihalomethanesConcentrationMeasurement | +| Alarms | BooleanState | TotalColiformBacteriaConcentrationMeasurement | +| Time | ModeSelect | TurbidityConcentrationMeasurement | +| BinaryInputBasic | ShadeConfiguration | CopperConcentrationMeasurement | +| PowerProfile | DoorLock | LeadConcentrationMeasurement | +| ApplianceControl | WindowCovering | ManganeseConcentrationMeasurement | +| PulseWidthModulation | BarrierControl | SulfateConcentrationMeasurement | +| Descriptor | PumpConfigurationAndControl | BromodichloromethaneConcentrationMeasurement | +| Binding | Thermostat | BromoformConcentrationMeasurement | +| AccessControl | FanControl | ChlorodibromomethaneConcentrationMeasurement | +| PollControl | DehumidificationControl | ChloroformConcentrationMeasurement | +| BridgedActions | ThermostatUserInterfaceConfiguration | SodiumConcentrationMeasurement | +| Basic | ColorControl | IasZone | +| OtaSoftwareUpdateProvider | BallastConfiguration | IasAce | +| OtaSoftwareUpdateRequestor | IlluminanceMeasurement | IasWd | +| LocalizationConfiguration | TemperatureMeasurement | WakeOnLan | +| TimeFormatLocalization | PressureMeasurement | Channel | +| UnitLocalization | FlowMeasurement | TargetNavigator | +| PowerSourceConfiguration | RelativeHumidityMeasurement | MediaPlayback | +| PowerSource | OccupancySensing | MediaInput | +| GeneralCommissioning | CarbonMonoxideConcentrationMeasurement | LowPower | +| NetworkCommissioning | CarbonDioxideConcentrationMeasurement | KeypadInput | +| DiagnosticLogs | EthyleneConcentrationMeasurement | ContentLauncher | +| GeneralDiagnostics | EthyleneOxideConcentrationMeasurement | AudioOutput | +| SoftwareDiagnostics | HydrogenConcentrationMeasurement | ApplicationLauncher | +| ThreadNetworkDiagnostics | HydrogenSulphideConcentrationMeasurement | ApplicationBasic | +| WiFiNetworkDiagnostics | NitricOxideConcentrationMeasurement | AccountLogin | +| EthernetNetworkDiagnostics | NitrogenDioxideConcentrationMeasurement | TestCluster | +| TimeSynchronization | OxygenConcentrationMeasurement | Messaging | +| BridgedDeviceBasic | OzoneConcentrationMeasurement | ApplianceIdentification | +| Switch | SulfurDioxideConcentrationMeasurement | MeterIdentification | + +

diff --git a/src/app/tests/suites/examples/Config_Example.yaml b/src/app/tests/suites/examples/Config_Example.yaml new file mode 100644 index 00000000000000..3bcad39a2897a4 --- /dev/null +++ b/src/app/tests/suites/examples/Config_Example.yaml @@ -0,0 +1,7 @@ +config: + cluster: "ExampleCluster" + endpoint: 1 + identity: "beta" # Uses secondary commissioner + exampleVariable: # See Config variables example + type: INT16U + defaultValue: 110 diff --git a/src/app/tests/suites/examples/Config_Variables_Example.yaml b/src/app/tests/suites/examples/Config_Variables_Example.yaml new file mode 100644 index 00000000000000..9484ad9f4dac13 --- /dev/null +++ b/src/app/tests/suites/examples/Config_Variables_Example.yaml @@ -0,0 +1,31 @@ +config: + exampleVariable: + type: INT16U + defaultValue: 110 + coolVariables: + type: CHAR_STRING + defaultValue: "I am a super cool variable" + aBigNumber: + type: INT64U + defaultValue: 1.8446744e+19 + aBool: + type: BOOLEAN + defaultValue: false + +tests: + - label: "Examples Test Step 1" + cluster: "ExampleCluster" + command: "ExamplesCommand" + disabled: false # Disables the test step if true + arguments: # User variable as arguments + values: + - name: "exampleVariable" + value: exampleVariable + + - label: "Examples Test Step 2" + cluster: "ExampleCluster2" + command: "ExamplesCommand2" + response: # User variable as response value checks + values: + - name: "aBool" + value: aBool diff --git a/src/app/tests/suites/examples/PICS_Example.yaml b/src/app/tests/suites/examples/PICS_Example.yaml new file mode 100644 index 00000000000000..cd567cc1e557d1 --- /dev/null +++ b/src/app/tests/suites/examples/PICS_Example.yaml @@ -0,0 +1,15 @@ +tests: + - label: "Examples Test Step 1" + cluster: "ExampleCluster" + command: "writeAttribute" + PICS: WILL_NOT_RUN + + - label: "Examples Test Step 2" + cluster: "ExampleCluster" + command: "readAttribute" + PICS: WILL_RUN + + - label: "Examples Test Step 3" + cluster: "ExampleCluster" + command: "ExamplesCommand" + PICS: WILL_NOT_RUN || WILL_RUN # Conditional will run diff --git a/src/app/tests/suites/examples/Response_Example.yaml b/src/app/tests/suites/examples/Response_Example.yaml new file mode 100644 index 00000000000000..5ea5523b81c6dd --- /dev/null +++ b/src/app/tests/suites/examples/Response_Example.yaml @@ -0,0 +1,8 @@ +tests: + - label: "Examples Test Step 1" + cluster: "ExampleCluster" + command: "ExamplesCommand" + response: # Validates the response variables of the commands + values: + - name: "exampleResponseVariable" + value: 1 diff --git a/src/app/tests/suites/examples/TestGenExample.zapt b/src/app/tests/suites/examples/TestGenExample.zapt new file mode 100644 index 00000000000000..c6db5d473bf558 --- /dev/null +++ b/src/app/tests/suites/examples/TestGenExample.zapt @@ -0,0 +1,8 @@ +{{#chip_tests (getTests)}} +{{#chip_tests_config}} +"Argument Name {{name}}" +"Argument Type {{type}}" +"Argument Type {{defaultValue}}" + +{{/chip_tests_config}} +{{/chip_tests}} diff --git a/src/app/tests/suites/examples/TestPICS b/src/app/tests/suites/examples/TestPICS new file mode 100644 index 00000000000000..1ccc088f671da9 --- /dev/null +++ b/src/app/tests/suites/examples/TestPICS @@ -0,0 +1,2 @@ +WILL_NOT_RUN=0 +WILL_RUN=1 diff --git a/src/app/tests/suites/examples/Test_Example.yaml b/src/app/tests/suites/examples/Test_Example.yaml new file mode 100644 index 00000000000000..03641c43aa480b --- /dev/null +++ b/src/app/tests/suites/examples/Test_Example.yaml @@ -0,0 +1,36 @@ +tests: + - label: "Examples Test Step 1" + cluster: "ExampleCluster" + command: "writeAttribute" + attribute: "exampleAttribute" + arguments: + value: 255 + + - label: "Examples Test Step 2" + cluster: "ExampleCluster" + command: "readAttribute" + attribute: "exampleAttribute" + response: # Validates the response variables of the commands + value: 255 + + - label: "Examples Test Step 3" + cluster: "ExampleCluster" + command: "ExamplesCommand" + response: # Validates the response variables of the commands + saveAs: nameOfSaveVariable + value: 0 + values: + - name: "exampleResponseVariable" + value: 1 + timedInteractionTimeoutMs: 10000 + PICS: RUN_ONLY_IF_ENABLED + arguments: + values: + - name: "arg1" + value: 0 + - name: "arg2" + value: { Key1: 1, Key2: 2 } + - name: "stringExamples" + value: "Hello World" + - name: "fromSaveAs" + value: nameOfSaveVariable diff --git a/src/app/tests/suites/examples/Test_Example_1.yaml b/src/app/tests/suites/examples/Test_Example_1.yaml new file mode 100644 index 00000000000000..fd8994ec43d9c3 --- /dev/null +++ b/src/app/tests/suites/examples/Test_Example_1.yaml @@ -0,0 +1,10 @@ +config: + cluster: "Basic" + endpoint: 0 + testOneVariable: + type: INT16U + defaultValue: 1 +tests: + - label: "Examples Test Step 1" + cluster: "LogCommands" + command: "Log" diff --git a/src/app/tests/suites/examples/Test_Example_2.yaml b/src/app/tests/suites/examples/Test_Example_2.yaml new file mode 100644 index 00000000000000..6d23a57d0266ad --- /dev/null +++ b/src/app/tests/suites/examples/Test_Example_2.yaml @@ -0,0 +1,10 @@ +config: + cluster: "Basic" + endpoint: 0 + testTwoVariable: + type: INT16U + defaultValue: 2 +tests: + - label: "Examples Test Step 1" + cluster: "LogCommands" + command: "Log" diff --git a/src/app/tests/suites/examples/Test_Example_3.yaml b/src/app/tests/suites/examples/Test_Example_3.yaml new file mode 100644 index 00000000000000..3ebfe6ea322d73 --- /dev/null +++ b/src/app/tests/suites/examples/Test_Example_3.yaml @@ -0,0 +1,10 @@ +config: + cluster: "Basic" + endpoint: 0 + testThreeVariable: + type: INT16U + defaultValue: 3 +tests: + - label: "Examples Test Step 1" + cluster: "LogCommands" + command: "Log" diff --git a/src/app/tests/suites/examples/gen_readme_example.sh b/src/app/tests/suites/examples/gen_readme_example.sh new file mode 100755 index 00000000000000..f85cebaba095c8 --- /dev/null +++ b/src/app/tests/suites/examples/gen_readme_example.sh @@ -0,0 +1,29 @@ +#!/usr/bin/env bash + +# +# Copyright (c) 2022 Project CHIP Authors +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# + +CHIP_ROOT="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" &>/dev/null && pwd)"/../../../../.. +echo "$CHIP_ROOT" +INPUT_ZAP="$CHIP_ROOT/src/controller/data_model/controller-clusters.zap" +INPUT_TEMPLATE="$CHIP_ROOT/src/app/tests/suites/examples/templates/templates.json" +OUTPUT_DIR="$CHIP_ROOT/src/app/tests/suites/examples/out" + +source "$CHIP_ROOT/scripts/activate.sh" + +mkdir -p "$OUTPUT_DIR" + +"$CHIP_ROOT"/scripts/tools/zap/generate.py "$INPUT_ZAP" -t "$INPUT_TEMPLATE" -o "$OUTPUT_DIR" diff --git a/src/app/tests/suites/examples/templates/templates.json b/src/app/tests/suites/examples/templates/templates.json new file mode 100644 index 00000000000000..6c7f81544b1e89 --- /dev/null +++ b/src/app/tests/suites/examples/templates/templates.json @@ -0,0 +1,16 @@ +{ + "name": "CHIP README Templates", + "version": "chip-v1", + "helpers": [ + "../../../../zap-templates/common/ClusterTestGeneration.js", + "tests.js" + ], + + "templates": [ + { + "path": "../TestGenExample.zapt", + "name": "Test Generate Example", + "output": "TestGenExample.out" + } + ] +} diff --git a/src/app/tests/suites/examples/templates/tests.js b/src/app/tests/suites/examples/templates/tests.js new file mode 100644 index 00000000000000..2328879f061283 --- /dev/null +++ b/src/app/tests/suites/examples/templates/tests.js @@ -0,0 +1,49 @@ +/* + * + * Copyright (c) 2022 Project CHIP Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +function getManualTests() +{ + const ExampleManualCataCategory = [ + 'examples/Test_Example', + ]; + + const tests = [ + ExampleManualCataCategory, // + + ]; + return tests.flat(1); +} + +function getTests() +{ + const TestExample = [ + 'examples/Test_Example_1', + 'examples/Test_Example_2', + 'examples/Test_Example_3', + ]; + + const tests = [ + TestExample, // + ]; + return tests.flat(1); +} + +// +// Module exports +// +exports.getTests = getTests; +exports.getManualTests = getManualTests; diff --git a/src/controller/README.md b/src/controller/README.md index 035aa3579be3ef..88df3136bd61e0 100644 --- a/src/controller/README.md +++ b/src/controller/README.md @@ -18,6 +18,11 @@ The Android chip-tool is located in [../android/CHIPTool](../android/CHIPTool). The POSIX CLI chip-tool is located in [../../examples/chip-tool](../../examples/chip-tool). +### Darwin CLI + +The POSIX CLI chip-tool is located in +[../../examples/chip-tool-darwin](../../examples/chip-tool). + ### Python The Python chip-device-ctrl is located in