Update documentation

This adds some instructions to build test widget using SDK
and basic instruction on how to test natively on your host
as well as on a target board.

Change-Id: I077fda253336883bec3cd0101e61467565d679ff
Signed-off-by: Romain Forlot <romain.forlot@iot.bzh>

4 files changed, 109 insertions, 19 deletions

diff --git a/docs/0_Installation.md b/docs/0_Installation.md
index e81c718..f02fa88 100644
--- a/docs/0_Installation.md
+++ b/docs/0_Installation.md
@@ -34,4 +34,32 @@ cd afb-test
 mkdir build
 cd build
 cmake .. && make
-```
\ No newline at end of file
+```
+
+## Test natively on your host
+
+If you want to use the **afb-test** binding natively on your host, you have to
+install it. Then *pkg-config* tool can find the **afb-test.pc** and you can
+use **afm-test** launcher:
+
+```bash
+sudo make install
+# Eventually set PKG_CONFIG_PATH environment variable if not installed in the
+# system directory
+export PKG_CONFIG_PATH=<path-to-pkgconfig-dir>:${PKG_CONFIG_PATH}
+# The same for the PATH environment variable where afm-test has been installed
+export PATH=<path-to-afm-test-dir>:${PATH}
+```
+
+Then you can test other binding using the **afm-test** launcher. Example here,
+with another binding project using **app-templates** submodule or the
+**cmake-apps-module** CMake module:
+
+> **Note** CMake module is the new way to use **app-templates**
+
+```bash
+cd build
+cmake ..
+make
+afm-test package package-test
+```
diff --git a/docs/WriteYourTests/0_ProjectTree.md b/docs/WriteYourTests/0_ProjectTree.md
index 850487c..1905d21 100644
--- a/docs/WriteYourTests/0_ProjectTree.md
+++ b/docs/WriteYourTests/0_ProjectTree.md
@@ -6,7 +6,7 @@
 
 "test"
    +-- etc
-   |   +-- aft-aftest-self.json
+   |   +-- aft-yourbinding.json
    |   +-- CMakeLists.txt
    +-- fixture
    |   +-- a-script.sh
@@ -24,20 +24,19 @@
 To integrate tests in your project, create a **test** subfolder at your project
 root directory and fulfill it with appropriate files like shown as above.
 
-To make it quick you'll have to write your tests using lua language and store it
-in the **tests** (with an "s") folder (as shown above) and change *aft-aftest-self.json* or make a new .json
-file to be able to launch your tests. Note that if you make a new json file,
-its name has to start with "aft-" followed by the binder's name. (e.g.
-aft-low-can for the low-level-can-service)
+To make it simple you'll have to write your tests using lua language and store it
+in the **tests** folder (as shown above) and create a JSON configuration file
+*aft-yourbinding.json* to be able to launch your tests. You'll see in the next
+section how to write a proper configuration file.
 
-*aft-aftest-self.json* is a conguration file. You'll see in the next section
-how to write a proper configuration file.
+> **Note** that if you create a new json file, its name has to start with "aft-"
+> followed by the binder's name. (e.g. aft-low-can for the low-level-can-service)
 
 ## Integration with CMake using App-templates
 
 To make the link between your test files, config files, data files
-and the test binding,
-you will have to integrate them with CMake using the App-templates.
+and the test binding, you will have to integrate them with CMake using the
+App-templates.
 
 First you will have to create your CMake target using **PROJECT_TARGET_ADD**
 with your target name as parameter, it will include the target to
@@ -91,9 +90,9 @@ And about test dedicated **LABELS**:
 > **TIP** you should use the prefix _afb-_ with your **BINDING* targets which
 > stand for **Application Framework Binding**.
 
-You will find in depth explanations about it [here](http://docs.automotivelinux.org/docs/devguides/en/dev/reference/sdk-devkit/docs/part-2/2_4-Use-app-templates.html#targets-properties).
+You will find in further description about it [here](http://docs.automotivelinux.org/docs/devguides/en/dev/reference/sdk-devkit/docs/part-2/2_4-Use-app-templates.html#targets-properties).
 
-Here is an example of a proper CMake file:
+Here is an example of a proper CMake file to include your LUA test files:
 
 ```CMake
 PROJECT_TARGET_ADD(test-files)
@@ -105,4 +104,69 @@ PROJECT_TARGET_ADD(test-files)
     LABELS "TEST-DATA"
     OUTPUT_NAME ${TARGET_NAME}
     )
-```
\ No newline at end of file
+```
+
+## Build the test widget
+
+### Using CMake Apps module or app-templates
+
+> **Note** the CMake module is the new way to use **app-templates**
+
+To launch tests on a target board, you need to build a test widget. Using the
+SDK, you only have to set the variable *BUILD_TEST_WGT=TRUE* when configuring
+the project.
+
+Example from another project than **afb-test**:
+
+```bash
+mkdir build
+cd build
+cmake -DBUILD_TEST_WGT=TRUE ..
+make
+make widget
+```
+
+### Without using CMake Apps module or app-templates
+
+Like you'd build a regular widget create a directory where you'll put your tests
+materials: LUA tests, configuration and fixture files.
+
+Then create in that directory a **bin** directory where you'll put this
+[script](https://gerrit.automotivelinux.org/gerrit/gitweb?p=apps/app-templates.git;a=blob_plain;f=test-widget/launcher.sh.in;h=005c43357db3daa71b66d95d2486cd13f5cee482;hb=refs/heads/master) and name it **launcher**. To finish, you'll also need a
+widget configuration file. You can use the example provided [here](https://gerrit.automotivelinux.org/gerrit/gitweb?p=apps/app-templates.git;a=blob_plain;f=test-widget/test-config.xml.in;hb=refs/heads/master) and edit it
+to fit your needs by replacing the variables surrounded by **@** characters.
+
+Example from another project than **afb-test**:
+
+```bash
+cd build
+BUILDDIR="$(pwd)"
+mkdir -p package-test/bin
+cd package-test
+wget https://gerrit.automotivelinux.org/gerrit/gitweb?p=apps/app-templates.git;a=blob_plain;f=test-widget/launcher.sh.in;h=005c43357db3daa71b66d95d2486cd13f5cee482;hb=refs/heads/master -O bin/launcher
+wget https://gerrit.automotivelinux.org/gerrit/gitweb?p=apps/app-templates.git;a=blob_plain;f=test-widget/test-config.xml.in;hb=refs/heads/master -O config.xml
+vim config.xml
+```
+
+Then once your widget content directory is complete, use **wgtpkg-pack** utility
+to create the test widget.
+
+```bash
+cd ${BUILDDIR}
+wgtpkg-pack -f -o <project_name>-test.wgt package-test
+```
+
+## Run the test widget on the target
+
+Once built you can send the wgt file to your target board and launch the tests
+using **afm-test** as follow:
+
+```bash
+afm-test <path-to-your-test.wgt>
+```
+
+**afm-test** installs the test wgt file, then runs it and uninstalls it.
+
+> **CAUTION**: Be cautious to not specify a regular widget's app, else it will
+> be uninstalled at the end of the operation. So, if it was an important
+> service/binding, others bindings or apps relying on it won't work.
diff --git a/docs/WriteYourTests/1_BindingConfiguration.md b/docs/WriteYourTests/1_BindingConfiguration.md
index 90b7e8d..2bd31c5 100644
--- a/docs/WriteYourTests/1_BindingConfiguration.md
+++ b/docs/WriteYourTests/1_BindingConfiguration.md
@@ -1,4 +1,4 @@
-# Binding configuration
+# Test configuration
 
 The file `aft-test.json` contains the controller binding configuration. Here,
 you have to change or define the *files* key in the *args* object of the
@@ -109,4 +109,4 @@ and another example which tests the low-can api:
         }]
     }]
 }
-```
\ No newline at end of file
+```
diff --git a/docs/WriteYourTests/2_LUATestFiles.md b/docs/WriteYourTests/2_LUATestFiles.md
index 377b8f2..05752dd 100644
--- a/docs/WriteYourTests/2_LUATestFiles.md
+++ b/docs/WriteYourTests/2_LUATestFiles.md
@@ -1,7 +1,5 @@
 # LUA Test files
 
-First, ensure that you put your LUA tests files in the `lua.d` directory.
-
 You have two differents things to take in account when you'll write your tests
 using this framework: *test* and *assertions*.
 
@@ -14,4 +12,4 @@ several *assertions* which are all needed to succeed to valid the test.
 The framework came with several *test* and *assertion* functions to simply be
 able to test verb calls and events receiving. Use the simple one as often as
 possible and if you need more use the one that calls a callback. Specifying a
-callback let you add assertions and enrich the test.
\ No newline at end of file
+callback let you add assertions and enrich the test.