docs/4_APIs_and_Services/4.4_AGL_Test_Framework/1_Write_the_tests/Write_the_tests.md

   1 ---
   2 edit_link: ''
   3 title: Write the tests
   4 origin_url: >-
   5   https://git.automotivelinux.org/apps/app-afb-test/plain/docs/1_Write_the_tests.md?h=master
   6 ---
   7
   8 <!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/apis_services/master/app-afb-test-developer-guides-api-services-book.yml -->
   9
  10 # Write the tests
  11
  12 ## Create the test tree
  13
  14 At the root of your project, create a test-dedicated directory that holds
  15 all your test materials. A classic test tree looks like the following:
  16
  17 ```tree
  18  test
  19  ├── CMakeLists.txt
  20  └── afb-test
  21      ├── CMakeLists.txt
  22      ├── etc
  23      │   ├── CMakeLists.txt
  24      │   └── aft-agl-middlename.json
  25      ├── fixtures
  26      │   ├── CMakeLists.txt
  27      │   ├── helper.sh
  28      │   ├── data
  29      │   └── plugin.lua
  30      └── tests
  31          ├── CMakeLists.txt
  32          ├── test01.lua
  33          ├── test02.lua
  34          └── test03.lua
  35  ...
  36 ```
  37
  38 Here is a description of each subdirectory purpose:
  39
  40 - *etc*`: Holds the test binding configuration in a JSON file.
  41 - *fixtures*: contains all external needed files to run your tests.
  42   This subdirectory is primarily used to inject data or a plugin
  43   with the mock-up APIs code in a LUA or C plugin.
  44 - *tests*: Contains only the tests written in LUA for your binding.
  45
  46 ## Create your configuration file
  47
  48 The configuration file describes your test API and how it launches the tests.
  49 A test binding does not provide verbs.
  50 This configuration describes the API verb(s) and mocked-up APIs.
  51 Following are the `key` descriptions for the configuration file:
  52
  53 ### `metadata` section
  54
  55 - `uid`: A simple label useful for debugging.
  56 - `version` (optional): The test's version.
  57 - `info` (optional): Provides information about the test.
  58 - `api`: The name your test binding takes.
  59   Formerly, the name was the test API name prefixed with `aft`
  60   (i.e. `aft-<tested-api-name>`).
  61 - `require`: The tested API's name. This key ensure that the tested API is
  62   correctly launched and initialized so the test binding can test it.
  63
  64 ### `testVerb` section
  65
  66 - `uid`: The verb name.
  67 - `info` (optional): Provides information about the verb.
  68 - `action`: A special string indicating the function to trigger when the verb is
  69   called. The verb is always the same about the test binding.
  70 - `args` Contains the following:
  71   - `trace`: The name of the tested API you are testing. `trace` is
  72    needed to allow the test binding trace the tested API and retrieve through
  73    the binder's monitoring feature `calls` and `events`.
  74   - `files`: A string or an array of strings of the LUA files with your tests.
  75    Only provide the file name.  Do not provide the path.
  76
  77 ### `mapis` (mocked up API), section
  78
  79 - `uid`: The mocked up API's name
  80 - `info` (optional): Provides information on the mock-up API.
  81 - `libs`: The LUA script or C plugin file name.
  82
  83 #### `verbs` section
  84
  85 Describes the implemented mocked up API verbs. Each verb maps to a function
  86 name that is executed when the verb is called.
  87
  88 - `uid`: The verb's name.
  89 - `info` (optional): Provides information on the verb.
  90 - `action`: A URI string that points to a C plugin or LUA script's function that
  91   is executes when the verb is called. The format of the action URI is:
  92  `<lua|plugin|api>`://`<C plugin's name|api's name|lua script name>`#`<function|verb's name>`
  93
  94 #### `events` section.
  95
  96 Allows you to trigger a function when a described event is received.
  97 The trigger can be for any event on which you need to apply modifications.
  98 You do not have to enumerate each possible event that the mocked up API can
  99 generate.  You could avoid this section if you do not want to execute a function
 100 when an event is received.
 101
 102 - `uid`: The event's name (e.g. `<api>/<event-name>`)
 103 - `info` (optional): Provides information about the event.
 104 - `action`: A URI string that points to a C plugin or LUA script's function that
 105   is executed when an event is received. The format of the action URI is:
 106   `<lua|plugin|api>`://`<C plugin's name|api's name|lua script name>`#`<function|verb's name>`.
 107   The action `lua://AFT#_evt_catcher_` is the default `afb-test` events listener.
 108
 109 ### Configuration examples
 110
 111 Here is a simple example:
 112
 113 ```json
 114 {
 115     "id": "http://iot.bzh/download/public/schema/json/ctl-schema.json#",
 116     "$schema": "http://iot.bzh/download/public/schema/json/ctl-schema.json#",
 117     "metadata": {
 118         "uid": "Hello_Test",
 119         "version": "1.0",
 120         "api": "aft-example",
 121         "info": "Binding made to test other bindings",
 122         "require": [
 123             "hello"
 124         ]
 125     },
 126     "testVerb": {
 127         "uid": "testing-hello",
 128         "info": "Launch the tests against hello api",
 129         "action": "lua://AFT#_launch_test",
 130         "args": {
 131             "trace": "hello",
 132             "files": ["aftTest.lua","helloworld.lua"]
 133         }
 134     }
 135 }
 136 ```
 137
 138 Following is another example that uses a mocked up `low-can` API:
 139
 140 ```json
 141 {
 142     "id": "http://iot.bzh/download/public/schema/json/ctl-schema.json#",
 143     "$schema": "http://iot.bzh/download/public/schema/json/ctl-schema.json#",
 144     "metadata": {
 145         "uid": "Other_Tests",
 146         "version": "1.0",
 147         "api": "aft-example",
 148         "info": "Binding made to test other bindings",
 149         "require": [
 150             "tested-api"
 151         ]
 152     },
 153     "testVerb": {
 154         "uid": "Complete",
 155         "info": "Launch all the tests",
 156         "action": "lua://AFT#_launch_test",
 157         "args": {
 158             "trace": "low-can",
 159             "files": [ "aftTest.lua", "mapis-tests.lua" ]
 160         }
 161     },
 162     "mapis": [{
 163         "uid": "low-can",
 164         "info": "Faked low-can API",
 165         "libs": "mapi_low-can.lua",
 166         "verbs": [
 167             {
 168                 "uid": "subscribe",
 169                 "info": "Subscribe to CAN signals events",
 170                 "action": "lua://low-can#_subscribe"
 171             },
 172             {...},
 173             {
 174                 "uid": "write",
 175                 "info": "Write a CAN messages to the CAN bus.",
 176                 "action": "lua://low-can#_write"
 177             }
 178         ],
 179         "events": [{
 180             "uid": "low-can/diagnostic_messages",
 181             "action": "lua://AFT#_evt_catcher_"
 182         },{
 183             "uid": "low-can/messages_engine_speed",
 184             "action": "lua://AFT#_evt_catcher_"
 185         },{
 186             "uid": "low-can/messages_vehicle_speed",
 187             "action": "lua://AFT#_evt_catcher_"
 188         }]
 189     }]
 190 }
 191 ```
 192
 193 ## The LUA test files
 194
 195 The test framework uses the LUA language to describe the tests.
 196
 197 You must be aware of two things when you write tests using
 198 this framework: *test* and *assertions* functions.
 199
 200 - *Assertions* functions test an atomic operation result.
 201   (ie: `1+1 = 2`).
 202 - *Test* functions represent a test. These functions represent a set of one
 203   or more *assertions* that must all succeed in order to valid the test.
 204
 205 The framework comes with several *test* and *assertion* functions that
 206 allow verb calls and received events to be tested. Use these provided
 207 *test* functions as a start.  If you
 208 need more functions, use the ones that call a callback. If the test is more complex or
 209 more comprehensive then *describe* your test function using *assert* functions.
 210 Following is an example.
 211
 212 See the test framework functions [References](Reference/0_BindingTestFunctions.html) for a
 213 comprehensive list of available *tests* and *assertions* functions.
 214
 215 ### Tests example
 216
 217 ```lua
 218     function _callback(responseJ)
 219     _AFT.assertStrContains(responseJ.response, "Some String")
 220     end
 221
 222     function _callbackError(responseJ)
 223     _AFT.assertStrContains(responseJ.request.info, "Ping Binder Daemon fails")
 224     end
 225
 226     function _callbackEvent(eventName, eventData)
 227     _AFT.assertEquals(eventData, {data = { key = 'weird others data', another_key = 123.456 }})
 228     end
 229
 230     _AFT.addEventToMonitor("hello/anEvent")
 231     _AFT.addEventToMonitor("hello/anotherEvent", _callbackEvent)
 232
 233     _AFT.testVerbStatusSuccess('testPingSuccess','hello', 'ping', {})
 234     _AFT.testVerbResponseEquals('testPingSuccess','hello', 'ping', {}, "Some String")
 235     _AFT.testVerbResponseEquals('testPingSuccess','hello', 'ping', {}, "Unexpected String")
 236     _AFT.testVerbCb('testPingSuccess','hello', 'ping', {}, _callback)
 237     _AFT.testVerbStatusError('testPingError', 'hello', 'pingfail', {})
 238     _AFT.testVerbResponseEqualsError('testPingError', 'hello', 'pingfail', {}, "Ping Binder Daemon fails")
 239     _AFT.testVerbResponseEqualsError('testPingError', 'hello', 'pingfail', {}, "Ping Binder Daemon succeed")
 240     _AFT.testVerbCbError('testPingError', 'hello', 'pingfail', {}, _callbackError)
 241
 242     _AFT.testVerbStatusSuccess('testEventAdd', 'hello', 'eventadd', {tag = 'event', name = 'anEvent'})
 243     _AFT.testVerbStatusSuccess('testEventSub', 'hello', 'eventsub', {tag = 'event'})
 244     _AFT.testVerbStatusSuccess('testEventPush', 'hello', 'eventpush', {tag = 'event', data = { key = 'some data', another_key = 123}})
 245
 246     _AFT.testVerbStatusSuccess('testEventAdd', 'hello', 'eventadd', {tag = 'evt', name = 'anotherEvent'})
 247     _AFT.testVerbStatusSuccess('testEventSub', 'hello', 'eventsub', {tag = 'evt'})
 248     _AFT.testVerbStatusSuccess('testEventPush', 'hello', 'eventpush', {tag = 'evt', data = { key = 'weird others data', another_key = 123.456}})
 249
 250     _AFT.testVerbStatusSuccess('testGenerateWarning', 'hello', 'verbose', {level = 4, message = 'My Warning message!'})
 251
 252     _AFT.testEvtGrpReceived("TestEventGroupReceived",{"hello/anEvent","hello/anotherEvent"},300000)
 253     _AFT.testEvtGrpNotReceived("TestEventGroupNotReceived",{"hello/anEvent","hello/anotherEvent"},300000)
 254
 255     _AFT.testEvtReceived("testEvent", "hello/anEvent",300000)
 256     _AFT.testEvtReceived("testEventCb", "hello/anotherEvent",300000)
 257
 258     _AFT.describe("myTestLabel", function()
 259       _AFT.assertEquals(false, false)
 260     end)
 261 ```